Python SDK

Install with Python 3.13 or newer:

pip install orchetree

The SDK registers code-defined resources and synchronizes their metadata to a running Orchetree backend. The decorated Python function is not used as the remote node executor; tree execution still uses the node prompts, policies, connectors, and resolved AI connection in Orchetree.

Register a tool

import orchetree


@orchetree.tool(
    name="Search",
    description="Search an approved source.",
    schema={
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
)
def search(query: str) -> str:
    return query

name, description, and schema are required. The schema is stored with an SDK tool connector and should be valid JSON Schema for the tool input.

Register a node

@orchetree.node(
    tree="Research",
    capability="retrieval",
    business_prompt="Find evidence relevant to the question.",
    system_prompt="Use only the supplied sources.",
    execution_prompt="Return concise findings with source identifiers.",
    output_prompt='Return {"findings": [...]} as JSON.',
)
def retrieve(inputs: dict) -> dict:
    return inputs

Node options:

Option	Required	Purpose
`tree`	yes	Name of the tree that owns the node
`capability`	yes	Capability label shown in the editor
`business_prompt`	no	Business-owned goal and domain instructions
`system_prompt`	no	System-level model instructions
`execution_prompt`	no	Runtime procedure and constraints
`examples`	no	Few-shot examples
`output_prompt`	no	Expected output shape or formatting

The function name becomes the display name by replacing underscores and title-casing the result.

Synchronize

orchetree sync --url http://localhost:8000 --project-id 1 --dir .
orchetree watch --url http://localhost:8000 --project-id 1 --dir .

You can also synchronize from Python:

summary = orchetree.sync(
    url="http://localhost:8000",
    project_id=1,
    directory="./agents",
)

print(summary["created"], summary["updated"], summary["deactivated"])

sync() imports Python files under directory, performs a backend health check, and returns synced, created, updated, and deactivated counts. Set ORCHETREE_URL to avoid passing the URL each time.

watch() monitors Python files recursively and synchronizes after changes. It requires the optional watcher dependency:

pip install watchdog

CLI

Command	Purpose
`orchetree init`	Scaffold a Python SDK project
`orchetree init --docker`	Include Docker startup files
`orchetree sync`	Perform one synchronization
`orchetree watch`	Synchronize continuously during development

Both synchronization commands accept --url, --project-id, and --dir.

Synchronization rules

A stable source ID is derived from the absolute file path, function name, and tree name for nodes.
Repeating a synchronization updates the same SDK-managed resource instead of creating a duplicate.
Removing a definition marks its existing resource sdk_inactive; sync does not hard-delete it.
Prompt blocks edited in the Orchetree interface are preserved when SDK-managed structure is synchronized again.
Files must be importable from the selected directory, including all of their Python dependencies.

The public package exports node, tool, sync, and watch.

See Creating nodes, AI connections, and Runs and traces.