README
¶
pig-sdk (Python)
Python SDK for building pig subprocess extensions.
This SDK is a language bridge into the same extension API that upstream
pi exposes to TypeScript extensions: the wire protocol, register payload,
tool/command/event semantics, request/response and host-call shapes are
identical to the Go SDK (extensions/sdk) and the Rust SDK (extensions/sdk-rs).
See docs/extension-api-parity.md for the host API parity matrix and
docs/extension-runtime-cells.md for how factory extensions are packed
into generated runner subprocesses.
Breaking changes in 0.3.0
Host-backed Context getters raise HostCallError on a host failure or a reply that lacks its field, and never return an empty value. get_session_name, get_session_file and get_leaf_id return None when absent, and get_branch and get_entries raise a failed session-log subscription. timeout options accept a float. Context.exec(..., max_buffer=...) caps stdout and stderr together; past it the command is terminated and ExecResult.truncated is true, and a command that ignores SIGTERM is killed five seconds later. See the migration tables in docs/site/docs/extensions.md.
Status
maturity: production bridge
runtime: subprocess (no in-process, no WASM)
wire: current Pig subprocess contract (no independent version)
host APIs implemented:
full host-call bridge matching the Go SDK method set
declaration kinds implemented:
tools
commands
event handlers
shortcuts
flags
providers
message renderers
widgets / widget_push
The Python SDK is a first-class bridge into the same subprocess protocol as Go and Rust. When a new host API is added, update all SDKs and the parity matrix in the same change.
Pi helper exports
The helpers Pi exports to extensions keep their names in snake case and behave like Pi's, which the conformance suite checks against Pi's own code:
import os
import pathlib
import pig_sdk
def summarize(text: str) -> str:
# Pi's truncateTail keeps the end of command output; the limits default to Pi's 2000 lines and 50KB.
output = pig_sdk.truncate_tail(text)
if not output.truncated:
return output.content
return f"{output.content}\n[showing {pig_sdk.format_size(output.output_bytes)} of {pig_sdk.format_size(output.total_bytes)}]"
def save_note(text: str) -> None:
# Pi's withFileMutationQueue: parallel tool calls on one file run one at a time, in call order.
notes = os.path.join(pig_sdk.get_agent_dir(), "notes.txt")
pig_sdk.with_file_mutation_queue(notes, lambda: pathlib.Path(notes).write_text(text))
tui.get_select_page_index(keybindings, data, selected_index, item_count, page_size) is Pi's getSelectPageIndex: the clamped index a tui.select.pageUp (-1) or tui.select.pageDown (+1) key moves a select list to (0 for an empty list), or None for any other key. A ctx.custom component, an EditorComponent and a TuiAltScreen component may have captures_viewport_input (a bool attribute, property or method; Pi's capturesViewportInput): each ui.custom.render and ui.editor.render frame carries capturesViewportInput: true while it is true (a change alone sends a frame), and a tui.alt component's caps report the member and answer the host's capturesViewportInput callback with its current value. ctx.exec(..., max_buffer=n) sends options.maxBuffer and ExecResult.truncated reports an overflow.
is_tool_call_event_type(name, event) is Pi's isToolCallEventType (the tool name must match exactly). get_package_dir() and get_shell_config(custom_shell_path=None) are Pi's getPackageDir() and getShellConfig(). Pi's pure pi-ai helpers are in pig_sdk too (string_enum, clamp_thinking_level, get_supported_thinking_levels, calculate_cost, content_text, normalize_context, get_current_system_prompt, is_context_overflow, is_retryable_assistant_error, env_api_key_auth, create_assistant_message_event_stream and the rest of pi_ai_helpers.py), over the dicts the wire carries. ctx.set_working_message("") shows an empty working label and ctx.set_working_message(None) restores the default one, as in Pi; set_hidden_thinking_label follows the same rule. truncate_head, truncate_tail, truncate_line and format_size are Pi's truncateHead, truncateTail, truncateLine and formatSize; byte limits count UTF-8 bytes and truncate_line counts UTF-16 units like a JavaScript string. get_agent_dir, get_config_dir_name and get_version are Pi's getAgentDir(), CONFIG_DIR_NAME and VERSION; they raise HostInfoUnavailable, never return a made-up path, when the process was not started by a PiG host. ctx.get_editor_component() returns the factory this extension installed with ctx.set_editor_component, or None. Pi's getEditorComponent returns the factory installed by any extension, so one extension can wrap another's editor; PiG returns only the calling extension's own factory.
ctx.set_status(key, "") sets an empty status text, as Pi's setStatus(key, "") does (RPC mode writes it); ctx.clear_status(key) is Pi's setStatus(key, undefined). ctx.input(title, placeholder=None) and ctx.editor(title, prefill=None) leave the placeholder or prefill unset (RPC mode writes no such member); an empty string is written as "".
Authoring a factory extension
import pig_sdk
def new_extension() -> pig_sdk.Extension:
ext = pig_sdk.Extension("my-py-ext")
def hello(ctx: pig_sdk.Context, args: dict) -> dict:
ctx.notify(f"hello, {args.get('name', 'world')}")
return {"content": "ok"}
ext.tool("hello", "Say hello", {"type": "object"}, hello)
return ext
if __name__ == "__main__":
new_extension().run()
Optional packing override:
kind: Extension
metadata:
name: my-py-ext
spec:
runtime:
language: python
isolation: shared-ok
entrypoint:
mode: factory
package: my_py_ext
factory: new_extension
Two or more factory-style Python extensions with isolation: shared-ok
are automatically packed into a single generated runner subprocess by
PlanCells (see docs/extension-runtime-cells.md).
The upstream 0.99.1 extension API
Extension and Context carry the extension API that upstream 0.99.1 added. Names follow the SDK convention (registerMcpServer is register_mcp_server); dicts keep upstream's key names (extensionPath, thinkingLevel, structuredContent of an outcome).
| upstream | Python |
|---|---|
registerMcpServer, unregisterMcpServer |
register_mcp_server(name, config), unregister_mcp_server(name) on Extension and Context. The host validates the config and the name's owner and raises HostCallError. |
getMcpServers |
ctx.get_mcp_servers(), answered from the state the host replicates and from the replies of registration calls, applied in the order the host sent them. |
registerVirtualModel, unregisterVirtualModel |
register_virtual_model(VirtualModel(provider=..., id=..., name=..., route=route)), unregister_virtual_model(provider, id). route(ctx, request) returns {"model": {"provider", "id"}, "thinkingLevel", "state"?}; a state that is absent or None keeps the current state, as upstream's undefined does. request["signal"] is its cancellation. |
getSettings |
ctx.get_settings(). It raises RuntimeError until the host has sent the settings. |
ToolDefinition.outputSchema, exposure, namespace, annotations, defaultActive, prepareLoadout |
ToolDefinition(output_schema=..., exposure=..., namespace=..., annotations=..., default_active=..., prepare_loadout=hook). hook(loadout) gets a ToolLoadout and returns {"descriptions": ..., "hiddenDeclarations": ...} or None. |
structuredContent, isError of a tool result |
keys structured_content and is_error of the dict a tool returns. |
ctx.tools, ctx.executeTool(name, args, options) |
ctx.tools and ctx.execute_tool(name, args, ExecuteToolOptions(signal=..., on_update=...)), available while a tool runs. The outcome is upstream's AgentToolCallOutcome as a dict; tool failures come back with isError true. signal defaults to the calling tool's cancellation; a given signal replaces it, so cancelling the calling tool leaves the nested call running (upstream options.signal ?? signal). on_update runs on the calling thread, in order, before the call returns. |
provider_stream_event, mcp_servers_change |
EVENT_PROVIDER_STREAM_EVENT, EVENT_MCP_SERVERS_CHANGE with on_event. Tool events carry parentToolCallId. |
pi.events |
ext.events and ctx.events: on(channel, handler) -> unsubscribe and emit(channel, data). Payloads cross as JSON. A handler is handler(ctx, data) and may call emit. The unsubscribe function never raises; a host refusal is printed to stderr. |
A registration made while the factory runs is queued and applied when the host accepts the extension; a failing factory leaves none behind. Extension.replaceable is not an extension API: only the resource loader sets it for an inline extension.
Threading and cancellation
The SDK uses one reader thread plus one worker thread per in-flight
request. Host calls from a handler block on a single shared write lock
and use the reader thread to deliver call_result envelopes.
Each handler receives a Context exposing cooperative cancellation:
def slow_tool(ctx, args):
for chunk in stream():
if ctx.is_cancelled():
return {"content": "", "is_error": True}
Cancellation is cooperative; a handler that never checks it will run until the process exits or shuts down.
is_cancelled() reports the handler's own request. Pi's ctx.signal is the
signal of the run in progress, so it is ctx.signal: one ProviderSignal for
the whole run that is set when the run aborts, even while a handler is still in
flight, and None while no run is active (a command or session_start while
idle). Use it for work owned by the current turn:
def on_turn_start(event, ctx):
signal = ctx.signal
if signal is not None:
signal.subscribe(stop_background_work)
Waiting for a run you started
ctx.send_message(..., trigger_turn=True) marks the session busy, and ctx.is_idle() stays busy until the code that sent the message yields, as Pi's does until its handler reaches its first await. Python has no await in a handler, so the SDK has explicit helpers: ctx.yield_now() tells the host this handler yields, and ctx.sleep(seconds) yields and then blocks the thread. A handler that waits for the run it started must use one of them:
ctx.send_message("note", "go", True, True)
while not ctx.is_idle():
ctx.sleep(0.01)
A raw time.sleep keeps the hold until the handler returns, so such a poll would read busy for as long as the handler runs.
Terminal strings
on_terminal_input receives strings with the same UTF-16 units as Pi. A high or low surrogate can arrive without its partner. Python str retains that unit, and the SDK's JSON encoder sends it as a standard \u escape. Return it directly in TerminalInputResult(data=...). Do not encode it to UTF-8 yourself or replace it with U+FFFD. Callback order and cancellation are unchanged.
Development
cd extensions/sdk-py
uv run python -m ast pig_sdk/__init__.py >/dev/null
uv run pytest
From the repository root, make test-sdk-py runs the same suite in a cached venv with the hash-locked dev dependencies in requirements-dev.txt; make check and CI's ci-sdk shard include it. After changing the dev dependency group, regenerate the lock with the command at the top of requirements-dev.txt.
License
MIT: see LICENSE.
Child agent sessions
ctx.create_agent_session(CreateAgentSessionOptions(...)) is Pi's createAgentSession: a child agent session over the host's model runtime that the extension prompts (prompt, steer, follow_up), observes (subscribe), aborts (abort) and disposes (dispose), with custom_tools served by this extension. Calls block as Pi's Promises resolve; the session ends with the connection. See Child agent sessions.
Documentation
¶
Overview ¶
Package pysdk carries the Python extension SDK sources so an installed pig can stage a buildable copy to disk. See extensions/sdk/bundle.go for the rationale; this is the Python analogue. The Python SDK is not a Go package, so this small Go file colocated with it provides the embed. Staging writes these files under <config-root>/state/pigsdk/sdk-py-<hash16>, a directory per build named for their content hash, so packed Python cells resolve the SDK on a clean host (findPythonSDKRoot's staged-source strategy).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Source embed.FS
Source holds the bundle's files, without test files.
Functions ¶
func BundledFiles ¶
func BundledFiles() []string
BundledFiles lists the embedded files, relative to the SDK root, in a stable order. Paths use forward slashes; a stager recreates subdirectories. A name under .gz/ is the gzip of the file the stager writes under the rest of the name, without .gz.
pig_sdk/__init__.py imports pig_sdk.tui at load, so the subpackage is staged with the package.
Types ¶
This section is empty.