hestiaos 0.1.0

HestiaOS SDK — Domain Interface for the HestiaOS platform

🏠 HestiaOS SDK

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

---

Installation

pip install hestiaos

Requires Python 3.11+.

---

Quickstart

Python Client

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

# 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

# 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.