Metadata-Version: 2.4
Name: cmpnd-observe
Version: 0.0.2
Summary: DSPy observability SDK for cmpnd-track
Project-URL: Homepage, https://cmpnd.io
Project-URL: Documentation, https://docs.cmpnd.io
Project-URL: Repository, https://github.com/cmpnd-ai/cmpnd-sdk
Author-email: cmpnd <hello@cmpnd.io>
License: MIT
Keywords: dspy,llm,observability,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: dspy>=3.1.3
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: xxhash>=3.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# cmpnd

DSPy observability SDK for cmpnd Obsersve.

Automatically trace your DSPy programs with one line of code.

## Installation

```bash
pip install cmpnd-observe
```

## Quick Start

```python
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

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

```python
import cmpnd

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

### Configuration options

```python
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

```python
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

```python
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:

```python
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
