cmpnd

DSPy observability SDK for cmpnd Obsersve.

Automatically trace your DSPy programs with one line of code.

Installation

pip install cmpnd-observe

Quick Start

import cmpnd

# Configure with your API key
cmpnd.configure(api_key="ct_xxx", project="my-project")

# Enable automatic DSPy instrumentation
cmpnd.auto_instrument()

# Your DSPy code is now automatically traced!
import dspy

lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)

cot = dspy.ChainOfThought("question -> answer")
result = cot(question="What is DSPy?")
# Trace is automatically sent to cmpnd-track

Configuration

Using environment variables

export CMPND_API_KEY="ct_your_api_key"
export CMPND_ENDPOINT="https://observe.cmpnd.ai"  # optional

import cmpnd

cmpnd.configure()  # Reads from environment
cmpnd.auto_instrument()

Configuration options

cmpnd.configure(
    api_key="ct_xxx",                # Required: API key
    endpoint="https://observe.cmpnd.ai", # Optional: Backend URL
    project="my-project",            # Optional: Project name
    batch_size=100,                  # Optional: Batch size for export
    flush_interval_seconds=5.0,      # Optional: Flush interval
    capture_inputs=True,             # Optional: Capture function inputs
    capture_outputs=True,            # Optional: Capture function outputs
    default_tags={"env": "prod"},    # Optional: Tags for all traces
)

Custom Spans

Add custom spans to trace non-DSPy code:

Using the decorator

from cmpnd import trace, SpanType

@trace(name="fetch_documents", span_type=SpanType.RETRIEVE)
def fetch_documents(query: str) -> list[str]:
    # Your retrieval logic
    return documents

Using the context manager

from cmpnd import start_span, SpanType

def run_pipeline(query: str):
    with start_span("vector_search", span_type=SpanType.RETRIEVE) as span:
        span.set_attribute("index", "my-faiss-index")
        docs = search(query)
        span.set_outputs({"doc_count": len(docs)})

    return generate(query, docs)

What Gets Traced

The SDK automatically captures:

Module Execution

• Module type (Predict, ChainOfThought, ReAct, etc.)
• Signature name and instructions
• Input/output field names
• Demo count

LM Calls

• Model name and provider
• Token usage (prompt, completion, total)
• Request/response content

Adapters

• Format and parse operations
• Input/output transformations

Tools

• Tool name and description
• Invocation inputs/outputs

Evaluations

• Evaluation scores
• Program being evaluated

Span Types

Available span types for categorization:

• SpanType.MODULE - Generic DSPy module
• SpanType.PREDICT - Predict module
• SpanType.CHAIN_OF_THOUGHT - ChainOfThought module
• SpanType.REACT - ReAct agent
• SpanType.RETRIEVE - Retrieval operations
• SpanType.LM_CALL - Language model calls
• SpanType.ADAPTER_FORMAT - Adapter formatting
• SpanType.ADAPTER_PARSE - Adapter parsing
• SpanType.TOOL - Tool invocations
• SpanType.EVALUATION - Evaluation runs

API Reference

cmpnd.configure()

Initialize the SDK with your API key and options.

cmpnd.auto_instrument()

Automatically register the callback with DSPy.

cmpnd.CmpndCallback

The callback class for manual registration:

import dspy
import cmpnd

cmpnd.configure(api_key="ct_xxx")
dspy.configure(callbacks=[cmpnd.CmpndCallback()])

cmpnd.trace()

Decorator for custom traced functions.

cmpnd.start_span()

Context manager for custom spans.

cmpnd.get_current_trace()

Get the current trace (if any).

cmpnd.get_current_span()

Get the current span (if any).

cmpnd.shutdown_exporter()

Gracefully shutdown the background exporter.

License

MIT