# Aither ADK — Full Documentation

> Build AI agent fleets with any LLM backend. Local GPU inference via vLLM, CPU/Mac via Ollama, cloud via Elysium. Register agents on the Aitherium network. OpenAI-compatible API. MCP bridge for 200+ tools.

## Installation

```bash
pip install awdk
```

Requirements: Python 3.10+, no native dependencies. Optional: Ollama for local inference, Docker for vLLM GPU containers.

## Architecture

```
Your Code
    |
    v
AitherAgent ──> LLMRouter (auto-detects backend)
    |               |
    |         ┌─────┼──────────────┐─────────────┐
    |         v     v              v             v
    |      vLLM   Ollama    OpenAI/Anthropic   Elysium
    |    (GPU)   (CPU/Mac)   (cloud API)     (Aitherium)
    |
    ├──> @tool functions (your custom tools)
    ├──> Graph Memory (SQLite, persistent)
    ├──> MCP Bridge (mcp.aitherium.com, 200+ tools)
    └──> Fleet (multi-agent delegation)
```

## LLM Backend Selection

The LLMRouter auto-detects backends in priority order:

1. **vLLM** — Checks ports 8200-8203 and 8000 for running vLLM containers
2. **Ollama** — Checks localhost:11434
3. **Elysium Gateway** — If `AITHER_API_KEY` env var is set
4. **Anthropic** — If `ANTHROPIC_API_KEY` env var is set
5. **OpenAI** — If `OPENAI_API_KEY` env var is set

Override explicitly:

```python
from adk import LLMRouter

# Force Ollama
router = LLMRouter(provider="ollama")

# Force OpenAI-compatible (vLLM, LM Studio, etc.)
router = LLMRouter(provider="openai", base_url="http://localhost:8000/v1")

# Force Anthropic
router = LLMRouter(provider="anthropic", api_key="sk-ant-...")

# Force Elysium cloud
router = LLMRouter(provider="gateway", api_key="aither_sk_live_...")
```

### Effort-Based Model Selection

```python
response = await agent.chat("Complex reasoning task", effort=8)
# effort 1-3 → small model
# effort 4-6 → orchestrator model
# effort 7-10 → reasoning model
```

Default model mapping per backend:

| Backend | Small (1-3) | Medium (4-6) | Large (7-10) |
|---------|-------------|-------------|--------------|
| Ollama | llama3.2:3b | nemotron-orchestrator-8b | deepseek-r1:14b |
| Elysium | aither-small | aither-orchestrator | aither-reasoning |
| OpenAI | gpt-4o-mini | gpt-4o | o1 |
| Anthropic | claude-haiku-4-5 | claude-sonnet-4-6 | claude-opus-4-6 |

## Agent Creation

### Basic Agent

```python
from adk import AitherAgent

agent = AitherAgent("my-agent")
response = await agent.chat("Hello!")
print(response.content)    # str
print(response.tokens)     # token usage dict
```

### Agent with Identity

```python
agent = AitherAgent("my-agent", identity="lyra")
# Uses lyra's system prompt, personality, and expertise
```

Available identities: aither, lyra, demiurge, hydra, athena, apollo, prometheus, atlas, viviane, scribe, iris, tania, hermes, sentinel, nexus, forge.

### Agent with Custom Tools

```python
from adk import AitherAgent, tool

@tool
def search_database(query: str, limit: int = 10) -> str:
    """Search the product database."""
    results = db.search(query, limit=limit)
    return json.dumps(results)

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email."""
    mailer.send(to=to, subject=subject, body=body)
    return f"Email sent to {to}"

agent = AitherAgent("support-bot", tools=[search_database, send_email])
response = await agent.chat("Find laptops under $500 and email the results to sales@co.com")
```

### Agent with Inline Tools

```python
agent = AitherAgent("my-agent")

@agent.tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return requests.get(f"https://wttr.in/{city}?format=j1").text

response = await agent.chat("What's the weather in Tokyo?")
```

## Fleet Mode — Multi-Agent

```python
from adk.fleet import load_fleet

fleet = load_fleet(agent_names=["aither", "lyra", "demiurge", "hydra"])
orchestrator = fleet.get_orchestrator()  # "aither" by default

# The orchestrator can delegate to other agents via ask_agent tool
response = await orchestrator.chat("Review the auth module for security issues")
# aither may delegate to hydra (review specialist)
```

### From YAML

```yaml
# fleet.yaml
name: my-fleet
orchestrator: aither
agents:
  - name: aither
    identity: aither
  - name: coder
    identity: demiurge
    tools: [file_io, shell]
  - name: reviewer
    identity: hydra
```

```bash
aither-serve --fleet fleet.yaml --port 8080
```

### CLI

```bash
# Single agent
aither-serve --identity aither --port 8080

# Multi-agent fleet
aither-serve --agents aither,lyra,demiurge,hydra --port 8080
```

## Elysium — Cloud Inference

Elysium connects your local ADK agent to Aitherium's cloud inference pipeline. Your agent logic runs locally; LLM calls route through Aitherium's GPU cluster.

### Step 1: Register

```python
from adk.elysium import Elysium

ely = Elysium()
result = await ely.register(email="you@example.com", password="your-password")
# Returns: {"user_id": "...", "message": "Check email for verification"}
```

Or register via API:

```bash
curl -X POST https://gateway.aitherium.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

### Step 2: Login

```python
result = await ely.login(email="you@example.com", password="your-password")
# Returns: {"token": "eyJ...", "expires_at": 1234567890}
```

Or use an ACTA API key (from https://demo.aitherium.com):

```bash
export AITHER_API_KEY=aither_sk_live_your_key_here
```

### Step 3: Connect

```python
from adk import AitherAgent
from adk.elysium import Elysium

# Auto-connects using AITHER_API_KEY env var
ely = await Elysium.connect()

# Or explicit
ely = await Elysium.connect(api_key="aither_sk_live_...")
```

### Step 4: Create Agent with Cloud Inference

```python
# Option A: Pass router at creation
agent = AitherAgent("my-agent", llm=ely.router)

# Option B: Attach to existing agent
agent = AitherAgent("my-agent")
await ely.attach(agent)  # replaces agent.llm with Elysium router

# Now all chat() calls go through Aitherium cloud
response = await agent.chat("Hello from the cloud!")
```

### Register Your Agent on the Network

```python
# Make your agent discoverable by other Aitherium users
await ely.register_agent(
    agent_name="my-support-bot",
    capabilities=["customer-support", "billing", "technical"],
    description="AI support agent for Acme Corp",
)

# Find other agents
agents = await ely.discover_agents(capability="code-review")

# List your registered agents
my_agents = await ely.my_agents()
```

### Available Models

```python
models = await ely.models()
# Returns OpenAI-compatible model list
```

| Model | Backend | Min Tier | Cost (tokens/1K) | Context |
|-------|---------|----------|-------------------|---------|
| aither-small | Ollama | free | 1 | 8K |
| aither-orchestrator | vLLM | pro | 3 | 32K |
| aither-reasoning | vLLM | enterprise | 10 | 32K |
| aither-vision | vLLM | enterprise | 8 | 16K |
| aither-coding | vLLM | enterprise | 5 | 32K |

### Pricing

| Plan | Price | Tokens/Month | Models |
|------|-------|-------------|--------|
| Starter | Free | 2,500 | aither-small |
| Creator | $9/mo | 25,000 | + aither-orchestrator |
| Professional | $29/mo | 100,000 | + all models |
| Business | $79/mo | 500,000 | + all models |
| Enterprise | Custom | Unlimited | + custom fine-tunes |

## Inference API (Direct)

If you don't use the ADK, you can hit the inference API directly with any OpenAI-compatible client:

```bash
# Chat completion
curl -X POST https://mcp.aitherium.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer aither_sk_live_YOUR_KEY" \
  -d '{
    "model": "aither-orchestrator",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# List models
curl https://mcp.aitherium.com/v1/models
```

Works with any OpenAI SDK:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://mcp.aitherium.com/v1",
    api_key="aither_sk_live_YOUR_KEY",
)

response = client.chat.completions.create(
    model="aither-orchestrator",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

## MCP Bridge

Connect to mcp.aitherium.com for 200+ tools (memory, search, code analysis, etc.):

```python
from adk import connect_mcp

bridge = await connect_mcp(api_key="aither_sk_live_...")
tools = await bridge.list_tools()
result = await bridge.call_tool("think", {"problem": "Design a caching strategy"})
```

## Graph Memory

Persistent memory with semantic search:

```python
from adk import GraphMemory

memory = GraphMemory("my-agent-memory")
await memory.remember("User prefers Python over JavaScript", category="preference")
results = await memory.query("What languages does the user prefer?")
```

## Preflight Health Check

Before starting operations, agents should run a preflight check:

```python
from adk.elysium import Elysium

ely = Elysium(api_key="aither_sk_live_...")
status = await ely.preflight()

if status["ready"]:
    print("All systems go!")
else:
    for name, check in status["checks"].items():
        if not check["ok"]:
            print(f"FAIL: {name} — {check.get('error', check)}")
```

Returns:

```json
{
  "ready": true,
  "checks": {
    "gateway_reachable": {"ok": true, "status_code": 200},
    "inference_reachable": {"ok": true, "status_code": 200},
    "auth_valid": {"ok": true},
    "balance": {"ok": true, "balance": 2500, "plan": "explorer"},
    "models": {"ok": true, "total": 5, "accessible": ["aither-small"]},
    "agents": {"ok": true, "count": 1, "names": ["my-agent"]}
  }
}
```

Individual health checks:

```python
# Gateway only
healthy = await ely.health()

# List models I can access
models = await ely.models()

# My registered agents
agents = await ely.my_agents()
```

## Gateway API Reference

### Authentication

- `POST /v1/auth/register` — Register account. Body: `{"email": "...", "password": "..."}`
- `POST /v1/auth/login` — Login. Body: `{"email": "...", "password": "..."}`
- `POST /v1/auth/verify` — Verify email. Body: `{"email": "...", "token": "..."}`

### Inference

- `POST /v1/chat/completions` — OpenAI-compatible chat. Auth: Bearer token.
- `GET /v1/models` — List available models (public, tier-filtered when authenticated)

### Agent Registry

- `POST /v1/agents/register` — Register agent. Auth required.
- `GET /v1/agents/discover` — Discover agents. Params: `capability`, `limit`.
- `GET /v1/agents/mine` — List your registered agents. Auth required.
- `DELETE /v1/agents/{id}` — Unregister agent. Auth required, owner-only.

### Billing

- `POST /v1/billing/register` — Get ACTA API key. Body: `{"email": "..."}`
- `GET /v1/billing/balance` — Check token balance. Auth required.
- `POST /v1/billing/keys/refresh` — Rotate API key. Auth required.

### Telemetry

- `POST /v1/telemetry` — Submit node telemetry. Auth required.

### Bug Reports

- `POST /v1/bugs` — Submit bug report. Auth optional.
- `GET /v1/bugs/{id}` — Check bug status.

### Health

- `GET /health` — Gateway health check.

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `AITHER_API_KEY` | ACTA API key for Elysium | `aither_sk_live_abc123` |
| `AITHER_GATEWAY_URL` | Gateway URL override | `https://gateway.aitherium.com` |
| `AITHER_INFERENCE_URL` | Inference URL override | `https://mcp.aitherium.com/v1` |
| `ANTHROPIC_API_KEY` | Anthropic direct API | `sk-ant-...` |
| `OPENAI_API_KEY` | OpenAI direct API | `sk-...` |
| `OPENAI_BASE_URL` | OpenAI base URL override | `http://localhost:8000/v1` |

## Links

- PyPI: https://pypi.org/project/awdk/
- GitHub: https://github.com/Aitherium/aither
- Demo & Pricing: https://demo.aitherium.com
- MCP Tools: https://demo.aitherium.com/llms.txt
- Gateway Health: https://gateway.aitherium.com/health