Metadata-Version: 2.4
Name: orchard-sdk
Version: 0.1.1
Summary: Python client SDK for the Orchard Flow REST API
Project-URL: Homepage, https://github.com/MegistusAI/orchard-flow
Project-URL: Source, https://github.com/MegistusAI/orchard-flow
Project-URL: Tracker, https://github.com/MegistusAI/orchard-flow/issues
Project-URL: Documentation, https://megistusai.github.io/orchard-flow
Author: Tumi Maape
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Requires-Dist: respx>=0.20; extra == 'test'
Description-Content-Type: text/markdown

# orchard-sdk

Python client SDK for the [Orchard Flow](https://orchard-flow.dev) REST API.

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

## Install

```bash
pip install orchard-sdk
```

Or with test dependencies:

```bash
pip install "orchard-sdk[test]"
```

## Quick Start

```python
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

```python
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

```python
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

```python
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

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

## License

MIT
