Metadata-Version: 2.4
Name: hestiaos
Version: 0.1.0
Summary: HestiaOS SDK — Domain Interface for the HestiaOS platform
Author: HestiaOS Team
License-Expression: MIT
Project-URL: Homepage, https://hestiaos.local
Project-URL: Source, https://gitlab.com/hestiaos/hestiaos
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: typer>=0.12.0
Dynamic: license-file

# 🏠 HestiaOS SDK

**Python SDK for the HestiaOS platform** — deterministic governance, multi-agent orchestration, and local-first AI execution.

[![PyPI version](https://img.shields.io/pypi/v/hestiaos)](https://pypi.org/project/hestiaos/)
[![Python Versions](https://img.shields.io/pypi/pyversions/hestiaos)](https://pypi.org/project/hestiaos/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install hestiaos
```

Requires Python 3.11+.

---

## Quickstart

### Python Client

```python
from hestiaos import Client

client = Client(base_url="http://localhost:8000")

# Run a command through the governance pipeline
result = client.run("create a report")
print(result.result)      # "processed: create a report"
print(result.trace_id)    # "abc-123-def"
print(result.mode)        # "ALLOW"

# Check system health
status = client.system.status()
print(status.status)      # "healthy"

# Retrieve a governance trace
trace = client.governance.trace("abc-123-def")
```

### CLI

```bash
# Run a command
hestiaos run "create a report"

# Check server health
hestiaos health

# Retrieve a trace
hestiaos trace abc-123-def

# JSON output (pipe to jq)
hestiaos run "hello" --json | jq

# Custom server URL
hestiaos --base-url http://localhost:8000 health
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `hestiaos run <text>` | Execute a command through the governance pipeline |
| `hestiaos trace <id>` | Retrieve a governance trace by ID |
| `hestiaos health` | Check server health status |

| Global Option | Description |
|---------------|-------------|
| `--base-url, -u` | API base URL (default: `http://localhost:8000`) |
| `--api-key, -k` | API key for authentication |
| `--json, -j` | Output as raw JSON |

---

## API

### `Client(base_url, api_key=None)`

| Method | Returns | Description |
|--------|---------|-------------|
| `client.run(input_text)` | `RunResponse` | Execute through governance pipeline |
| `client.governance.trace(trace_id)` | `dict \| None` | Retrieve governance trace |
| `client.governance.explain(command_type, command_input)` | `dict` | Explain a governance decision |
| `client.system.status()` | `SystemStatus` | Server health status |

### Models

- **`RunResponse`**: `result`, `trace_id`, `output`, `mode`, `budget`, `latency_ms`
- **`TraceResponse`**: `trace_id`, `decision`, `violations`, `latency_ms`
- **`HealthResponse`**: `status`, `version`, `uptime_seconds`
- **`GovernanceBlock`**: Raised when governance blocks execution

---

## Development

```bash
# Clone and install
git clone <repo-url> && cd hestiaos
python -m venv venv && source venv/bin/activate
pip install -e .

# Run tests
pytest tests/test_sdk_client.py tests/test_cli.py -v
```

---

## License

MIT — see [LICENSE](LICENSE).
