Mirascope (tracing)

Mirascope is a Python toolkit for building LLM applications with a unified model API, structured outputs, streaming, and typed tools. respan-instrumentation-mirascope traces Mirascope 2.x model operations as canonical Respan chat spans and toolkit execution as tool spans.

Synchronous and asynchronous calls are supported. Streaming spans stay open until the underlying stream is consumed, so their timing, output, usage, and iterator errors describe the complete stream.

Setup

$
pip install respan-ai respan-instrumentation-mirascope "mirascope[openai]"

$
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

1
from mirascope import llm
2
from respan import Respan
3
from respan_instrumentation_mirascope import MirascopeInstrumentor
4
5
respan = Respan(
6
    app_name="mirascope-support-agent",
7
    instrumentations=[MirascopeInstrumentor()],
8
)
9
model = llm.Model("openai/gpt-4o-mini")
10
11
try:
12
    response = model.call("Explain distributed tracing in one sentence.")
13
    print(response.text())
14
finally:
15
    respan.shutdown()

Supported operations

Model calls include prompts, completions, tool definitions and calls, model and provider identifiers, and token usage when the provider response supplies them. Errors are re-raised unchanged after the span records OpenTelemetry error status, status_code, and error.message.

Stream model output

The stream span finishes when text_stream() is exhausted:

1
from mirascope import llm
2
3
model = llm.Model("openai/gpt-4o-mini")
4
response = model.stream("Count from one to three.")
5
6
for text in response.text_stream():
7
    print(text, end="")

For an asynchronous stream, await stream_async() and consume its text stream with async for:

1
from mirascope import llm
2
3
4
async def stream_answer() -> str:
5
    model = llm.Model("openai/gpt-4o-mini")
6
    response = await model.stream_async("Count from four to six.")
7
    parts = []
8
    async for text in response.text_stream():
9
        parts.append(text)
10
    return "".join(parts)

Trace tool execution

Tools passed to a model call are captured on the chat span. When Mirascope executes a returned tool call, the execution becomes a child tool span.

1
import math
2
3
from mirascope import llm
4
5
6
@llm.tool
7
def square_root(number: float) -> float:
8
    """Calculate the square root of a number."""
9
    return math.sqrt(number)
10
11
12
model = llm.Model("openai/gpt-4o-mini")
13
response = model.call(
14
    "Use the tool to calculate the square root of 144.",
15
    tools=[square_root],
16
)
17
results = response.execute_tools() if response.tool_calls else []
18
print(results)

Configuration

Disable content capture

1
from respan import Respan
2
from respan_instrumentation_mirascope import MirascopeInstrumentor
3
4
respan = Respan(
5
    instrumentations=[MirascopeInstrumentor(capture_content=False)],
6
)

With capture disabled, messages, tool definitions, arguments, and model outputs are omitted. Provider, model, usage, timing, status, and exception type remain available.

Add trace context

1
from respan import Respan
2
3
with Respan.propagate_attributes(
4
    customer_identifier="user_123",
5
    thread_identifier="conversation_abc",
6
    trace_group_identifier="mirascope_support_workflow",
7
    metadata={"plan": "pro"},
8
):
9
    response = model.call("Draft a concise answer to this support request.")

Do not combine this adapter with mirascope.ops.instrument_llm() unless you intentionally want two independent telemetry pipelines for each operation.