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

1 import os
2 
3 from aleph_alpha_client import ChatRequest, Client, Message
4 from aleph_alpha_client.chat import Role
5 from respan import Respan
6 from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor
7 
8 respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
9 client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])
10 
11 response = client.chat(
12     request=ChatRequest(
13         model="pharia-1-chat",
14         messages=[
15             Message(role=Role.User, content="Say hello in one sentence."),
16         ],
17     ),
18     model="pharia-1-chat",
19 )
20 print(response.message.content)
21 respan.flush()

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.

1 from respan import Respan
2 from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor
3 
4 respan = Respan(
5     instrumentations=[AlephAlphaInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "aleph-alpha-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override attributes per request using a context scope.

1 import os
2 
3 from aleph_alpha_client import ChatRequest, Client, Message
4 from aleph_alpha_client.chat import Role
5 from respan import Respan, propagate_attributes
6 from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor
7 
8 respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
9 client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])
10 
11 def handle_request(user_id: str, question: str):
12     with propagate_attributes(
13         customer_identifier=user_id,
14         thread_identifier="conv_abc_123",
15         metadata={"plan": "pro"},
16     ):
17         response = client.chat(
18             request=ChatRequest(
19                 model="pharia-1-chat",
20                 messages=[Message(role=Role.User, content=question)],
21             ),
22             model="pharia-1-chat",
23         )
24         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.

1 import os
2 
3 from aleph_alpha_client import Client, CompletionRequest, Prompt
4 from respan import Respan, task, workflow
5 from respan_instrumentation_aleph_alpha import AlephAlphaInstrumentor
6 
7 respan = Respan(instrumentations=[AlephAlphaInstrumentor()])
8 client = Client(token=os.environ["ALEPH_ALPHA_API_KEY"])
9 
10 @task(name="draft_completion")
11 def draft(prompt: str) -> str:
12     response = client.complete(
13         request=CompletionRequest(prompt=Prompt.from_text(prompt), maximum_tokens=100),
14         model="pharia-1-chat",
15     )
16     return response.completions[0].completion
17 
18 @workflow(name="aleph_alpha_content_pipeline")
19 def pipeline(topic: str):
20     print(draft(f"Write a concise summary about {topic}."))
21 
22 pipeline("SDK tracing")
23 respan.flush()