spyglass-ai 0.1.9

A client library for shipping telemetry to the Spyglass AI platform

Spyglass SDK

The Spyglass SDK provides client code for shipping telemetry data to the Spyglass AI platform

Installation

pip install spyglass-ai

Configuration

Set the following environment variables to configure the SDK:

Required

• SPYGLASS_API_KEY: Your Spyglass API key
• SPYGLASS_DEPLOYMENT_ID: Unique identifier for your deployment
  • Note: Used for both service.name and deployment.id attributes

Optional

• SPYGLASS_OTEL_EXPORTER_OTLP_ENDPOINT: Custom endpoint for development

Example Configuration

export SPYGLASS_API_KEY="your-api-key"
export SPYGLASS_DEPLOYMENT_ID="user-service-v1.2.0"  # Required - used for both service.name and deployment.id

Note: SPYGLASS_DEPLOYMENT_ID is required and will be used for both the OpenTelemetry service.name and deployment.id resource attributes. This ensures consistency and simplifies dashboard queries.

Usage

Basic Function Tracing

Use the @spyglass_trace decorator to automatically trace function calls:

from spyglass_ai import spyglass_trace

@spyglass_trace()
def calculate_total(price, tax_rate):
    return price * (1 + tax_rate)

# Usage
result = calculate_total(100, 0.08)  # This call will be traced

You can also provide a custom span name:

@spyglass_trace(name="payment_processing")
def process_payment(amount, card_info):
    # Payment processing logic
    return {"status": "success", "transaction_id": "tx_123"}

Agent Observability (sessions & span kinds)

Group related spans into an agent run with a session id, and tag spans by kind (chain, llm, tool, retriever) so the Spyglass UI can render waterfalls and session views.

from spyglass_ai import spyglass_trace, session, SPAN_KIND_TOOL

with session("user-123-run-1"):
    @spyglass_trace(kind=SPAN_KIND_TOOL)
    def lookup_docs(query: str):
        return []

    lookup_docs("refund policy")

OpenAI and MCP wrappers set llm / tool kinds automatically and attach session.id when a session context is active. OpenAI spans also include an estimated gen_ai.usage.cost_usd from token usage.

OpenAI Integration

Wrap your OpenAI client to automatically trace API calls:

from openai import OpenAI
from spyglass_ai import spyglass_openai

# Create your OpenAI client
client = OpenAI(api_key="your-api-key")

# Wrap it with Spyglass tracing
client = spyglass_openai(client)

# Now all chat completions will be traced
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=100
)

Complete Example

from openai import OpenAI
from spyglass_ai import spyglass_trace, spyglass_openai

# Set up OpenAI client with tracing
client = OpenAI(api_key="your-api-key")
client = spyglass_openai(client)

@spyglass_trace(name="ai_conversation")
def have_conversation(user_message):
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": user_message}],
        max_tokens=150
    )
    return response.choices[0].message.content

# This will create traces for both the function and the OpenAI API call
answer = have_conversation("What is the capital of France?")
print(answer)

What Gets Traced

Function Tracing (@spyglass_trace)

• Function name, module, and qualified name
• Input arguments (excluding self and cls)
• Return values
• Execution time
• Any exceptions that occur

OpenAI Integration (spyglass_openai)

• Model used
• Number of messages
• Request parameters (max_tokens, temperature, etc.)
• Token usage (prompt, completion, total)
• Response model
• Any API errors

Development

Install Dependencies

uv sync --extra test

Run All Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_trace.py -v