# Aitherium Integration: Hermes Tool Definition

Use this template to add Aitherium as a delegation target in Hermes agent workflows.

## Prerequisites

1. An Aitherium API key (register at `POST https://gateway.aitherium.com/v1/billing/register`)
2. Hermes installed and configured

## Tool Definition

Add this to your Hermes tool configuration:

```json
{
  "type": "function",
  "function": {
    "name": "aither_delegate",
    "description": "Delegate a complex task to Aitherium's specialized AI agents. Use for deep reasoning, code review, security analysis, multi-step planning, or any task requiring persistent memory and multi-agent orchestration. Returns a detailed response from the most appropriate specialist agent.",
    "parameters": {
      "type": "object",
      "properties": {
        "task": {
          "type": "string",
          "description": "The task to delegate. Be specific about what you need: code review, security analysis, research, planning, debugging, etc."
        },
        "model": {
          "type": "string",
          "enum": ["aither-small", "aither-orchestrator", "aither-reasoning", "aither-coding", "aither-vision"],
          "default": "aither-orchestrator",
          "description": "Which model to use. small=fast/cheap, orchestrator=balanced, reasoning=deep analysis, coding=code tasks, vision=images"
        },
        "persona": {
          "type": "string",
          "enum": ["aither", "demiurge", "hydra", "athena", "lyra", "apollo", "scribe"],
          "description": "Optional specialist persona. hydra=code review, athena=security, lyra=creative research, apollo=performance, demiurge=code generation, scribe=documentation"
        },
        "context": {
          "type": "string",
          "description": "Additional context for the task (code, docs, error logs, etc.)"
        },
        "max_tokens": {
          "type": "integer",
          "default": 4096,
          "description": "Maximum response length"
        }
      },
      "required": ["task"]
    }
  }
}
```

## Implementation

The tool executor should make this HTTP call:

```python
import httpx

AITHER_API_KEY = "aither_sk_live_..."  # From environment
AITHER_BASE_URL = "https://mcp.aitherium.com/v1"

async def aither_delegate(task: str, model: str = "aither-orchestrator",
                          persona: str | None = None, context: str | None = None,
                          max_tokens: int = 4096) -> str:
    """Delegate a task to Aitherium."""
    system = "You are a specialized AI agent. Complete the task thoroughly and return structured results."
    if persona:
        persona_prompts = {
            "hydra": "You are Hydra, the code review guardian. Review from every angle: correctness, security, performance, maintainability.",
            "athena": "You are Athena, the security oracle. Analyze for vulnerabilities, attack vectors, and security best practices.",
            "lyra": "You are Lyra, the creative research agent. Explore deeply, synthesize connections, and present insights.",
            "apollo": "You are Apollo, the performance optimizer. Identify bottlenecks, measure impact, and suggest optimizations.",
            "demiurge": "You are Demiurge, the code architect. Write clean, efficient, well-structured code.",
            "scribe": "You are Scribe, the documentation sage. Create clear, comprehensive documentation.",
        }
        system = persona_prompts.get(persona, system)

    user_msg = task
    if context:
        user_msg = f"{task}\n\nContext:\n{context}"

    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"{AITHER_BASE_URL}/chat/completions",
            headers={
                "Authorization": f"Bearer {AITHER_API_KEY}",
                "Content-Type": "application/json",
            },
            json={
                "model": model,
                "messages": [
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_msg},
                ],
                "max_tokens": max_tokens,
                "temperature": 0.3,
            },
            timeout=120.0,
        )
        resp.raise_for_status()
        return resp.json()["choices"][0]["message"]["content"]
```

## Streaming Integration (SSE)

For streaming responses, use the streaming endpoint:

```python
async def aither_delegate_stream(task: str, model: str = "aither-orchestrator", **kwargs):
    """Stream a response from Aitherium."""
    async with httpx.AsyncClient() as client:
        async with client.stream(
            "POST",
            f"{AITHER_BASE_URL}/chat/completions",
            headers={
                "Authorization": f"Bearer {AITHER_API_KEY}",
                "Content-Type": "application/json",
            },
            json={
                "model": model,
                "messages": [{"role": "user", "content": task}],
                "stream": True,
                **kwargs,
            },
            timeout=120.0,
        ) as resp:
            async for line in resp.aiter_lines():
                if line.startswith("data: ") and line != "data: [DONE]":
                    chunk = json.loads(line[6:])
                    delta = chunk["choices"][0].get("delta", {})
                    if "content" in delta:
                        yield delta["content"]
```

## Effort Mapping

Map Hermes reasoning depth to Aitherium models:

| Hermes Self-Eval Score | Aitherium Model | Rationale |
|------------------------|-----------------|-----------|
| Low confidence (< 0.4) | aither-reasoning | Needs deep analysis |
| Medium (0.4 - 0.7) | aither-orchestrator | Standard delegation |
| High confidence (> 0.7) | aither-small | Quick confirmation |
| Code-specific | aither-coding | Specialized for code |

## Example Workflow

```
Hermes Agent → encounters complex code review task
  → self-eval: "I'm not confident about security implications" (score: 0.35)
  → calls aither_delegate(task="Review for SQL injection...", model="aither-reasoning", persona="athena")
  → receives detailed security analysis
  → incorporates findings into its response
```

## Cost Tracking

```python
# Check balance before expensive operations
resp = httpx.get(
    "https://gateway.aitherium.com/v1/billing/balance",
    headers={"Authorization": f"Bearer {AITHER_API_KEY}"}
)
balance = resp.json()["balance"]
```