Metadata-Version: 2.4
Name: orloj-sdk
Version: 0.1.0
Summary: Official Python SDK for the Orloj multi-agent orchestration platform
Project-URL: Homepage, https://orloj.dev
Project-URL: Documentation, https://docs.orloj.dev
Project-URL: Repository, https://github.com/OrlojHQ/orloj-python-sdk
Project-URL: Issues, https://github.com/OrlojHQ/orloj-python-sdk/issues
Author: Orloj HQ
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: typing-extensions>=4.8
Provides-Extra: dev
Requires-Dist: coverage>=7; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# orloj — Official Python SDK

Typed Python client for the [Orloj](https://orloj.dev) v1 REST API: synchronous and asynchronous usage (`httpx`), Pydantic v2 models, SSE watch streams, and cursor-based pagination.

## Requirements

- Python 3.10+

## Install

From [PyPI](https://pypi.org/project/orloj-sdk/):

```bash
pip install orloj-sdk
```

Install with `pip install orloj-sdk`, then import the `orloj_sdk` package (`from orloj_sdk import OrlojClient`).

From a git checkout:

```bash
pip install -e ".[dev]"
```

## Configuration

The client reads defaults from the environment (same order as `orlojctl`):

| Setting   | Constructor  | Environment (first wins)                |
| --------- | ------------ | --------------------------------------- |
| API token | `api_token=` | `ORLOJCTL_API_TOKEN`, `ORLOJ_API_TOKEN` |
| Base URL  | `base_url=`  | `ORLOJCTL_SERVER`, `ORLOJ_SERVER`       |

If unset, the base URL defaults to `http://127.0.0.1:8080` and the namespace defaults to `default`.

## Quickstart

```python
from orloj_sdk import OrlojClient

client = OrlojClient(api_token="your-token")
who = client.auth.whoami()
print(who.authenticated, who.username)

for agent in client.agents.list_all():
    print(agent.metadata.name)
```

### Async

```python
from orloj_sdk import AsyncOrlojClient

async with AsyncOrlojClient(api_token="your-token") as client:
    page = await client.agents.list(limit=20)
```

## Examples

Runnable scripts (require a running Orloj API):

| Script                           | Description                              |
| -------------------------------- | ---------------------------------------- |
| `examples/quickstart.py`         | `whoami` and list agents                 |
| `examples/watch_tasks.py`        | SSE watch on a task until completion     |
| `examples/multi_agent_system.py` | Create an `AgentSystem` with a graph     |
| `examples/async_example.py`      | `AsyncOrlojClient` with `asyncio.gather` |

```bash
export ORLOJ_API_TOKEN=...
python examples/quickstart.py
```

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks, and pull request expectations.

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
ruff check src/orloj_sdk tests examples
ruff format src/orloj_sdk tests examples
mypy src/orloj_sdk
pytest --cov=orloj_sdk
```

## License

Apache-2.0
