> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Aleph Alpha (tracing)

> Trace official Aleph Alpha Python SDK calls with Respan auto-instrumentation.

[Aleph Alpha](https://aleph-alpha.com/) provides enterprise AI models and APIs for chat, text generation, embeddings, evaluation, and explanation workflows. Respan instruments the official Aleph Alpha Python SDK so each model call is exported as a trace with prompts, completions, token usage, model metadata, tool definitions, and latency.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Aleph Alpha gateway setup](/docs/gateway/aleph-alpha) to route Aleph Alpha model calls through the Respan gateway.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/aleph-alpha)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-aleph-alpha aleph-alpha-client
```

#### Set environment variables

```bash
export ALEPH_ALPHA_API_KEY="YOUR_ALEPH_ALPHA_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`ALEPH_ALPHA_API_KEY` is used for Aleph Alpha requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python
import os

from aleph_alpha_client import ChatRequest, Client, Message
from aleph_alpha_client.chat import Role
from respan import Respan
from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor

respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])

response = client.chat(
    request=ChatRequest(
        model="pharia-1-chat",
        messages=[
            Message(role=Role.User, content="Say hello in one sentence."),
        ],
    ),
    model="pharia-1-chat",
)
print(response.message.content)
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your auto-instrumented Aleph Alpha spans with prompts, completions, model names, token usage, and latency.

## Covered calls

The Aleph Alpha instrumentor patches `aleph_alpha_client.Client` and `AsyncClient` calls for:

* `chat` and `complete`
* `complete_with_streaming` and `chat_with_streaming`
* `embed`, `embeddings`, `semantic_embed`, `batch_semantic_embed`, and `instructable_embed`
* `evaluate` and `explain`

Embedding spans capture the input and a vector summary without storing raw vector values.

## Configuration

| Parameter             | Type           | Default | Description                                                              |
| --------------------- | -------------- | ------- | ------------------------------------------------------------------------ |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                                  |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                                 |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate, such as `AlephAlphaInstrumentor()`. |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                               |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                                  |
| `environment`         | `str \| None`  | `None`  | Environment tag, such as `"production"`.                                 |

## Attributes

### In Respan()

Set defaults at initialization. These apply to all spans.

```python
from respan import Respan
from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor

respan = Respan(
    instrumentations=[AlephAlphaInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "aleph-alpha-api", "version": "1.0.0"},
)
```

### With propagate_attributes

Override attributes per request using a context scope.

```python
import os

from aleph_alpha_client import ChatRequest, Client, Message
from aleph_alpha_client.chat import Role
from respan import Respan, propagate_attributes
from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor

respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])

def handle_request(user_id: str, question: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = client.chat(
            request=ChatRequest(
                model="pharia-1-chat",
                messages=[Message(role=Role.User, content=question)],
            ),
            model="pharia-1-chat",
        )
        print(response.message.content)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |

## Decorators (optional)

Decorators are not required. Aleph Alpha SDK calls are auto-traced after the instrumentor is activated. Use `@workflow` and `@task` when you want to group related calls into named workflows.

```python
import os

from aleph_alpha_client import Client, CompletionRequest, Prompt
from respan import Respan, task, workflow
from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor

respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])

@task(name="draft_completion")
def draft(prompt: str) -> str:
    response = client.complete(
        request=CompletionRequest(prompt=Prompt.from_text(prompt), maximum_tokens=100),
        model="pharia-1-chat",
    )
    return response.completions[0].completion

@workflow(name="aleph_alpha_content_pipeline")
def pipeline(topic: str):
    print(draft(f"Write a concise summary about {topic}."))

pipeline("SDK tracing")
```