Aleph Alpha (tracing)

Aleph Alpha 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 and grab an API key.

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

Use Respan Gateway

See Aleph Alpha gateway setup to route Aleph Alpha model calls through the Respan gateway.

Example projects

Python examples

Setup

Install packages

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

Set environment variables

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

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 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.

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.

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.

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")