# Aitherium Integration: Vellum Workflow Step

Use this template to add Aitherium delegation as a step in your Vellum workflows.

## Prerequisites

1. An Aitherium API key (register at `POST https://gateway.aitherium.com/v1/billing/register`)
2. Vellum account with workflow access

## HTTP Request Step Configuration

In your Vellum workflow, add an **HTTP Request** step with these settings:

### Connection

| Field | Value |
|-------|-------|
| Method | POST |
| URL | `https://mcp.aitherium.com/v1/chat/completions` |
| Content-Type | application/json |
| Authorization | Bearer {{aither_api_key}} |

### Request Body

```json
{
  "model": "{{model_selection}}",
  "messages": [
    {
      "role": "system",
      "content": "{{system_prompt}}"
    },
    {
      "role": "user",
      "content": "{{user_task}}"
    }
  ],
  "max_tokens": {{max_tokens}},
  "temperature": {{temperature}}
}
```

### Variable Mapping

| Vellum Variable | Type | Default | Description |
|-----------------|------|---------|-------------|
| `aither_api_key` | Secret | — | Your aither_sk_live_... key |
| `model_selection` | String | aither-orchestrator | Model to use |
| `system_prompt` | String | "Complete the task thoroughly." | Agent system prompt |
| `user_task` | String | — | The task from previous workflow step |
| `max_tokens` | Number | 4096 | Maximum response length |
| `temperature` | Number | 0.3 | Response creativity (0.0-1.0) |

### Output Parsing

Extract the response from the JSON:

| Output Variable | JSON Path | Type |
|-----------------|-----------|------|
| `aither_response` | `$.choices[0].message.content` | String |
| `tokens_used` | `$.usage.total_tokens` | Number |
| `model_used` | `$.model` | String |

## Checkpoint-Compatible Delegation

Vellum's checkpoint system works naturally with Aitherium. Configure the HTTP step as a checkpoint so:

1. If the workflow pauses, the Aitherium response is preserved
2. If the workflow resumes, it picks up from the saved response
3. No duplicate API calls on resume

### Checkpoint Configuration

```
Step: aither_delegation
Type: HTTP Request
Checkpoint: enabled
Retry on failure: true
Max retries: 2
Retry delay: 5s
Timeout: 120s
```

## Workflow Templates

### Template 1: Code Review Pipeline

```
[Input: code_to_review]
    ↓
[Aither Delegation]
  model: aither-orchestrator
  system: "You are Hydra, the code review guardian. Return JSON: {issues: [{severity, line, description, fix}], summary: string, score: number}"
  user: "Review this code:\n\n{{code_to_review}}"
    ↓
[Parse JSON Response]
  Extract: issues, summary, score
    ↓
[Conditional]
  If score < 0.7 → [Flag for human review]
  If score >= 0.7 → [Approve]
```

### Template 2: Research + Synthesis

```
[Input: research_topic]
    ↓
[Aither Delegation - Research]
  model: aither-reasoning
  system: "You are Lyra. Research this topic deeply. Return structured findings."
  user: "{{research_topic}}"
    ↓ (checkpoint)
[Aither Delegation - Synthesis]
  model: aither-orchestrator
  system: "Synthesize these research findings into an executive summary."
  user: "Findings:\n{{research_response}}\n\nCreate a 3-paragraph executive summary."
    ↓
[Output: executive_summary]
```

### Template 3: Security Audit

```
[Input: artifact]
    ↓
[Aither Delegation]
  model: aither-orchestrator
  system: "You are Athena, the security oracle. Analyze for OWASP Top 10, injection vectors, auth issues, data exposure. Return JSON: {vulnerabilities: [{id, severity, category, description, remediation}], risk_score: number}"
  user: "Security audit:\n\n{{artifact}}"
    ↓
[Parse Response]
    ↓
[Conditional: risk_score > 7]
  → [Alert: Critical security issues found]
  → [Continue pipeline]
```

## Error Handling

Configure these error handlers on the HTTP step:

| HTTP Status | Action | Description |
|-------------|--------|-------------|
| 200 | Continue | Success |
| 401 | Fail workflow | Invalid API key |
| 402 | Fail with message | Insufficient balance |
| 429 | Retry (backoff) | Rate limited |
| 500-599 | Retry (2x) | Server error |
| Timeout | Retry (1x) | Request took too long |

## Model Selection Logic

Add a **Code Step** before the HTTP request to auto-select the model:

```python
def select_model(task_type: str, complexity: str) -> str:
    if task_type == "code" and complexity == "high":
        return "aither-coding"
    elif complexity == "high":
        return "aither-reasoning"
    elif task_type in ("quick", "summary", "classify"):
        return "aither-small"
    else:
        return "aither-orchestrator"
```

## Cost Estimation

Before making calls, estimate cost:

```
POST https://gateway.aitherium.com/v1/external/estimate
Body: {"tool": "chat", "effort": 5, "plan": "free"}
```