Metadata-Version: 2.4
Name: aos-sdk
Version: 0.1.0
Summary: Python SDK for AOS (Agentic Operating System) - Machine-native agent runtime
Author-email: Agenticverz <dev@xuniverz.com>
Maintainer-email: Agenticverz <dev@xuniverz.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/xuniverz/agenticverz
Project-URL: Documentation, https://github.com/xuniverz/agenticverz#readme
Project-URL: Repository, https://github.com/xuniverz/agenticverz
Project-URL: Issues, https://github.com/xuniverz/agenticverz/issues
Project-URL: Changelog, https://github.com/xuniverz/agenticverz/blob/main/CHANGELOG.md
Keywords: aos,agent,agentic,sdk,machine-native,runtime,llm,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: requires-python

# AOS SDK for Python

The official Python SDK for AOS (Agentic Operating System) - the most predictable, reliable, deterministic SDK for building machine-native agents.

## Installation

```bash
pip install aos-sdk
```

## Quick Start

```python
from aos_sdk import AOSClient

# Initialize client
client = AOSClient(
    api_key="your-api-key",
    base_url="http://localhost:8000"
)

# Check available capabilities
caps = client.get_capabilities()
print(f"Budget remaining: {caps['budget_remaining_cents']}c")
print(f"Available skills: {caps['skills_available']}")

# Simulate before executing
result = client.simulate([
    {"skill": "http_call", "params": {"url": "https://api.example.com"}},
    {"skill": "llm_invoke", "params": {"prompt": "Summarize the response"}}
])

if result["feasible"]:
    print(f"Plan is feasible! Estimated cost: {result['estimated_cost_cents']}c")
else:
    print(f"Plan not feasible: {result['reason']}")
```

## Machine-Native Features

AOS is designed for agents to operate efficiently, not humans to babysit:

- **Queryable execution context** - Not log parsing
- **Capability contracts** - Not just tool lists
- **Structured outcomes** - Never throws exceptions
- **Failure as data** - Navigable, not opaque
- **Pre-execution simulation** - Know before you run

## API Reference

### AOSClient

```python
client = AOSClient(
    api_key="...",           # Optional, uses AOS_API_KEY env var
    base_url="http://...",   # Default: http://127.0.0.1:8000
    timeout=30               # Request timeout in seconds
)
```

### Machine-Native APIs

```python
# Simulate a plan before execution
result = client.simulate(plan=[...], budget_cents=1000)

# Query runtime state
budget = client.query("remaining_budget_cents")
attempts = client.query("what_did_i_try_already", run_id="...")

# List and describe skills
skills = client.list_skills()
skill = client.describe_skill("http_call")

# Get capabilities
caps = client.get_capabilities()
```

### Agent Workflow APIs

```python
# Create agent and execute goal
agent_id = client.create_agent("my-agent")
run_id = client.post_goal(agent_id, "Check the weather in London")
result = client.poll_run(agent_id, run_id, timeout=30)

# Memory recall
memories = client.recall(agent_id, "weather queries", k=5)
```

## CLI

The SDK includes a command-line interface:

```bash
# Check version
aos version

# Check server health
aos health

# Show capabilities
aos capabilities

# List skills
aos skills

# Describe a skill
aos skill http_call

# Simulate a plan
aos simulate '[{"skill": "http_call", "params": {"url": "https://example.com"}}]'
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AOS_API_KEY` | API key for authentication | (none) |
| `AOS_BASE_URL` | Base URL for AOS server | `http://127.0.0.1:8000` |

## Requirements

- Python 3.8+
- `requests` or `httpx` (both supported)

## License

MIT License - see LICENSE file for details.
