> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhara.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Company name is Akhara AI (never Rubric AI). Keep lowercase rubric/rubrics only when meaning grading criteria.
> Expert Review (docs path talent/) is enterprise BYO experts for audit and review: invite customer specialists; do not pitch Akhara recruiting or a public expert career portal. RLHF and domain writing are secondary work types.
> Prefer concrete API examples against public hosts: Environments eval API https://agi.akhara.ai, Control plane PDP https://api.akhara.dev, Evaluation https://app.akhara.ai / https://api.akhara.ai, Expert Review portal https://talent.akhara.ai.
> Do not invent a public hostname for private orchestrators or env API internals.
> Do not confuse control-plane latches with Environments confirmation latches.
> Environments SDK/API examples: curl against https://agi.akhara.ai. Evaluation SDK: from akhara import Akhara and AKHARA_API_KEY.
> Start with /llms.txt for the docs index and OpenAPI links; fetch individual pages as .md exports.

# Python SDK

> Complete reference for the Akhara Python SDK.

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install akhara
  ```

  ```bash poetry theme={null}
  poetry add akhara
  ```

  ```bash conda theme={null}
  conda install -c conda-forge akhara
  ```
</CodeGroup>

**Requirements:** Python 3.8+

## Quick Start

```python theme={null}
from akhara import Akhara

# Initialize client
client = Akhara(api_key="gr_live_xxxxxxxx")

# Or use environment variable AKHARA_API_KEY
client = Akhara()

# Log a call
client.calls.log(
    project="my-project",
    transcript=[...],
    ai_decision={...}
)

# Run an evaluation
evaluation = client.evaluations.create(
    name="Weekly Review",
    project="proj_abc123",
    dataset="ds_xyz789",
    evaluators=[{"type": "triage_accuracy"}]
)
```

## Configuration

### Client Options

```python theme={null}
client = Akhara(
    api_key="gr_live_xxxxxxxx",     # API key (or use AKHARA_API_KEY env var)
    base_url="https://api.akhara.ai", # Custom endpoint
    timeout=30.0,                     # Request timeout in seconds
    max_retries=3,                    # Retry failed requests
    http_client=None                  # Custom httpx client
)
```

### Environment Variables

| Variable           | Description                                     |
| ------------------ | ----------------------------------------------- |
| `AKHARA_API_KEY`   | API key for authentication                      |
| `AKHARA_BASE_URL`  | Custom API endpoint                             |
| `AKHARA_TIMEOUT`   | Default timeout                                 |
| `AKHARA_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) |

## Core Resources

### Calls

Log and manage voice call data:

```python theme={null}
# Log a call
call = client.calls.log(
    project="patient-triage",
    audio_url="https://storage.example.com/call.wav",
    transcript=[
        {"speaker": "agent", "text": "How can I help?", "start": 0.0, "end": 1.5},
        {"speaker": "patient", "text": "I have chest pain", "start": 2.0, "end": 4.0}
    ],
    ai_decision={
        "triage_level": "urgent",
        "extracted_symptoms": ["chest_pain"]
    },
    metadata={
        "call_id": "call_12345",
        "duration_seconds": 180
    }
)
print(f"Logged: {call.id}")

# Retrieve a call
call = client.calls.get("call_abc123")

# List calls with filters
calls = client.calls.list(
    project="patient-triage",
    created_after="2024-01-01",
    status="pending_review",
    limit=50
)
```

### Notes

Log clinical documentation:

```python theme={null}
# Log a clinical note
note = client.notes.log(
    project="visit-summarizer",
    input_text="Patient presents with...",
    output={
        "soap_note": {
            "subjective": "...",
            "objective": "...",
            "assessment": "...",
            "plan": "..."
        },
        "icd_codes": ["E11.9"]
    },
    expected={
        "icd_codes": ["E11.65"]
    }
)
```

### Imaging

Log medical imaging AI outputs:

```python theme={null}
# Log imaging analysis
study = client.imaging.log(
    project="chest-xray-analyzer",
    study_uid="1.2.840.113619.2.55...",
    dicom_metadata={
        "modality": "CR",
        "body_part": "CHEST"
    },
    ai_analysis={
        "findings": [...],
        "impression": "..."
    }
)
```

### Datasets

Manage datasets for evaluation:

```python theme={null}
# Create a dataset
dataset = client.datasets.create(
    name="triage-test-set-v2",
    description="Gold standard triage cases",
    project="patient-triage"
)

# Add samples
client.datasets.add_samples(
    dataset_id=dataset.id,
    samples=[
        {
            "input": {"transcript": "..."},
            "expected": {"triage_level": "urgent"}
        }
    ]
)

# List datasets
datasets = client.datasets.list(project="patient-triage")
```

### Evaluations

Run and manage evaluations:

```python theme={null}
# Create evaluation
evaluation = client.evaluations.create(
    name="Weekly Triage Review",
    project="proj_abc123",
    dataset="ds_xyz789",
    evaluators=[
        {
            "type": "triage_accuracy",
            "config": {
                "severity_weights": {"under_triage": 5.0}
            }
        }
    ]
)

# Check status
evaluation = client.evaluations.get(evaluation.id)
print(f"Status: {evaluation.status}")
print(f"Progress: {evaluation.progress.completed}/{evaluation.progress.total}")

# Get results
results = client.evaluations.get_results(evaluation.id)
for evaluator in results.evaluators:
    print(f"{evaluator.name}: {evaluator.score}%")

# List evaluations
evaluations = client.evaluations.list(project="proj_abc123")

# Compare evaluations
comparison = client.evaluations.compare([
    "eval_week1", "eval_week2", "eval_week3"
])
```

## Async Support

The SDK provides async versions of all methods:

```python theme={null}
import asyncio
from akhara import AsyncAkhara

async def main():
    client = AsyncAkhara()
    
    # Async logging
    call = await client.calls.log(
        project="my-project",
        transcript=[...],
        ai_decision={...}
    )
    
    # Async evaluation
    evaluation = await client.evaluations.create(
        name="Async Eval",
        project="proj_abc123",
        dataset="ds_xyz789",
        evaluators=[{"type": "triage_accuracy"}]
    )
    
    # Wait for completion
    while True:
        evaluation = await client.evaluations.get(evaluation.id)
        if evaluation.status in ["completed", "failed"]:
            break
        await asyncio.sleep(5)

asyncio.run(main())
```

## Error Handling

```python theme={null}
from akhara import Akhara
from akhara.exceptions import (
    RubricException,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    NotFoundError
)

client = Akhara()

try:
    evaluation = client.evaluations.get("eval_nonexistent")
except NotFoundError as e:
    print(f"Evaluation not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after} seconds")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
    print(f"Field: {e.param}")
except RubricException as e:
    print(f"Akhara error: {e.message}")
```

## Pagination

```python theme={null}
# Manual pagination
page = client.calls.list(project="my-project", limit=100)
all_calls = list(page.data)

while page.has_more:
    page = client.calls.list(
        project="my-project",
        limit=100,
        after=page.data[-1].id
    )
    all_calls.extend(page.data)

# Auto-pagination iterator
for call in client.calls.list_auto(project="my-project"):
    process(call)
```

## Webhooks

```python theme={null}
# Register a webhook
webhook = client.webhooks.create(
    url="https://your-app.com/webhooks/akhara",
    events=["evaluation.completed", "review.submitted"],
    secret="your_webhook_secret"
)

# Verify webhook signature (in your endpoint)
from akhara.webhooks import verify_signature

@app.post("/webhooks/akhara")
def handle_webhook(request):
    signature = request.headers.get("X-Akhara-Signature")
    payload = request.body
    
    if verify_signature(payload, signature, webhook_secret):
        event = json.loads(payload)
        # Handle event
```

## Type Hints

The SDK is fully typed for IDE support:

```python theme={null}
from akhara import Akhara
from akhara.types import (
    Call,
    Evaluation,
    EvaluationStatus,
    EvaluatorConfig,
    TriageLevel
)

client = Akhara()

def process_call(call: Call) -> None:
    if call.ai_decision.triage_level == TriageLevel.EMERGENT:
        alert_team(call)

evaluation: Evaluation = client.evaluations.get("eval_123")
if evaluation.status == EvaluationStatus.COMPLETED:
    print(f"Score: {evaluation.results.overall_score}")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/evaluation/api-reference/introduction">
    Complete REST API documentation
  </Card>

  <Card title="Observability" icon="eye" href="/evaluation/docs/getting-started/observability">
    Start logging your AI outputs
  </Card>
</CardGroup>