orchard-sdk 0.1.1

Python client SDK for the Orchard Flow REST API

orchard-sdk

Python client SDK for the Orchard Flow REST API.

Call Groves, list providers, and trigger webhooks from any Python application. Supports both sync and async usage.

Install

pip install orchard-sdk

Or with test dependencies:

pip install "orchard-sdk[test]"

Quick Start

from orchard_sdk import OrchardClient

# Connect to an Orchard Flow API server
client = OrchardClient(
    base_url="http://localhost:8000",
    api_key="of_your_api_key_here",
)

# Run a Grove
result = client.run_grove("my_grove", soil={"key": "value"}, seed=42)
print(result["harvest"])

# List available providers
providers = client.list_providers()
print(providers)

# Check server health
if client.is_healthy():
    print("Server is online")

Async Usage

import asyncio
from orchard_sdk import OrchardClient

async def main():
    async with OrchardClient(
        base_url="http://localhost:8000",
        api_key="of_your_api_key_here",
    ) as client:
        # Run a Grove asynchronously
        result = await client.async_run_grove("my_grove", soil={"key": "value"})
        print(result)

        # List providers asynchronously
        providers = await client.async_list_providers()
        print(providers)

asyncio.run(main())

Trigger Webhooks

client = OrchardClient(base_url="http://localhost:8000", api_key="of_xxx")
result = client.trigger_webhook("my_grove", event="file.uploaded", data={"path": "/tmp/file.mp4"})

Error Handling

from orchard_sdk import OrchardClient
from orchard_sdk.errors import (
    OrchardNotFoundError,
    OrchardAuthenticationError,
    OrchardServerError,
    OrchardConnectionError,
    OrchardTimeoutError,
)

client = OrchardClient(base_url="http://localhost:8000", api_key="of_xxx")

try:
    result = client.run_grove("missing_grove")
except OrchardNotFoundError:
    print("Grove not found")
except OrchardAuthenticationError:
    print("Check your API key")
except OrchardConnectionError:
    print("Server is unreachable")
except OrchardTimeoutError:
    print("Request timed out")

API Reference

OrchardClient

Method	Description
run_grove(name, soil, seed)	Execute a Grove and return results
run_grove_model(name, soil, seed)	Same but returns typed GroveRunResponse
list_providers()	List all registered providers
trigger_webhook(name, event, data)	Trigger a Grove via webhook
is_healthy()	Check server connectivity

Async variants (prefixed async_) available for all methods.

Requirements

• Python 3.11+
• httpx >= 0.27
• pydantic >= 2.0

Development

git clone https://github.com/MegistusAI/orchard-flow
cd orchard/sdks/python
pip install -e ".[test]"
pytest tests/

License

MIT