Metadata-Version: 2.4
Name: spyllm
Version: 0.3.2
Summary: Framework-agnostic agent observability & LLM tracing. Supports OpenAI, Anthropic, CrewAI, AutoGen, LangGraph, and OpenTelemetry.
Project-URL: Homepage, https://spyllm.dev
Project-URL: Documentation, https://spyllm.dev/docs
Project-URL: Repository, https://github.com/Yemnis/spyllm
Project-URL: Bug Tracker, https://github.com/Yemnis/spyllm/issues
Project-URL: Dashboard, https://spyllm.dev/app
License-Expression: LicenseRef-Proprietary
Keywords: agents,anthropic,llm,observability,openai,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: wrapt>=1.14.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
Description-Content-Type: text/markdown

# SpyLLM Python SDK

[![PyPI Version](https://img.shields.io/pypi/v/spyllm?style=flat-square&label=pypi)](https://pypi.org/project/spyllm/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/spyllm?style=flat-square)](https://pypi.org/project/spyllm/)
[![Python](https://img.shields.io/pypi/pyversions/spyllm?style=flat-square)](https://pypi.org/project/spyllm/)
[![GitHub Stars](https://img.shields.io/github/stars/Yemnis/spyllm?style=flat-square&logo=github)](https://github.com/Yemnis/spyllm)

Framework-agnostic agent observability and automatic LLM tracing. Works with OpenAI, Anthropic, CrewAI, AutoGen, LangGraph, and any OpenTelemetry-instrumented framework.

> **See it in action** — [view a live trace on the dashboard](https://spyllm.dev/app)

## Prerequisites

You need a **free SpyLLM account** and an **API key** to use this SDK.

1. **Sign up** at [spyllm.dev/sign-up](https://spyllm.dev/sign-up)
2. Go to **Settings → API Keys** and click **Create API Key**
3. Copy the key — it is only shown once

## Install

```bash
pip install spyllm
```

With provider extras:

```bash
pip install spyllm[openai]       # OpenAI
pip install spyllm[anthropic]    # Anthropic
pip install spyllm[otel]         # OpenTelemetry export
```

## Quick Start

```python
import spyllm

spyllm.init(api_key="sk-...")

# That's it. Every OpenAI and Anthropic call is now automatically traced.
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
# Prompt, response, tokens, cost, and latency are captured automatically.
```

Open the [dashboard](https://spyllm.dev/app) to see traces as they arrive.

## Agent Observability

Wrap multi-agent workflows with `agent_span()` to automatically link every nested LLM call into a trace DAG. Nested spans inherit `trace_id` and set `parent_span_id` automatically — no manual ID threading needed.

```python
import spyllm
from openai import OpenAI

spyllm.init(api_key="sk-...")
client = OpenAI()

with spyllm.agent_span("orchestrator", role="orchestrator"):
    plan = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Plan the research task"}],
    )

    with spyllm.agent_span("researcher", role="worker"):
        research = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Research quantum computing"}],
        )

    with spyllm.agent_span("writer", role="worker"):
        report = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Write the report"}],
        )

# All spans share the same trace_id.
# Open the dashboard to see the full agent topology as an interactive DAG.
```

### Async Support

The async variant works identically with `asyncio`, which most agent frameworks use:

```python
async with spyllm.async_agent_span("planner", role="planner") as ctx:
    print(ctx.trace_id)       # auto-generated
    print(ctx.span_id)        # unique per span
    print(ctx.parent_span_id) # from outer span, if any
```

### Reading Span Context

Access the current span anywhere in your code:

```python
ctx = spyllm.get_current_span()
if ctx:
    print(f"Currently inside: {ctx.agent_name} (trace={ctx.trace_id})")
```

### Span Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `str` | required | Human-readable agent name |
| `role` | `str` | `"worker"` | Agent role for topology grouping |
| `operation` | `str` | `"invoke_agent"` | One of: `invoke_agent`, `create_agent`, `execute_tool`, `chat` |
| `trace_id` | `str` | auto-inherited | Override trace ID |
| `framework` | `str` | `None` | Framework identifier: `crewai`, `autogen`, `langgraph`, `custom` |
| `input_source` | `str` | `None` | What triggered this span: `user`, `agent:planner`, `tool:search` |

## Framework Adapters

One line of code gives you full agent topology for supported frameworks. Adapters use OpenTelemetry instrumentation libraries when available, with lightweight monkey-patch fallbacks.

### CrewAI

```python
import spyllm

spyllm.init(api_key="sk-...")
spyllm.adapters.instrument_crewai()

from crewai import Agent, Task, Crew
# All CrewAI agent/task/tool spans are captured automatically.
```

### Any OTel-Instrumented Framework (Zero SDK Code)

Point any framework's OpenTelemetry exporter at SpyLLM:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.spyllm.dev
export OTEL_EXPORTER_OTLP_HEADERS="X-API-Key=sk-your-key"
```

This works with CrewAI (`opentelemetry-instrumentation-crewai`), LangGraph (`LANGSMITH_OTEL_ENABLED=true`), AutoGen, PydanticAI, and any framework that emits `gen_ai.*` semantic convention spans.

## What Gets Captured

Every LLM call automatically records:

- **Prompt** — full message history sent to the model
- **Response** — the model's output
- **Token count** — input + output tokens
- **Cost** — estimated USD cost based on model pricing
- **Latency** — wall-clock time for the API call
- **Tool calls** — if the model invoked tools/functions
- **Errors** — failed calls with the exception message

With agent spans enabled, you also get:

- **Trace ID** — groups all spans in a workflow execution
- **Span ID / Parent Span ID** — builds the parent-child DAG
- **Agent Role** — orchestrator, worker, planner, etc.
- **Operation Name** — invoke_agent, execute_tool, chat, create_agent
- **Framework** — crewai, autogen, langgraph, custom
- **Agent Topology** — interactive DAG visualization in the dashboard

## Supported Providers

| Provider   | Auto-instrumented |
|------------|-------------------|
| OpenAI     | Yes               |
| Anthropic  | Yes               |

## Supported Agent Frameworks

| Framework  | Integration |
|------------|-------------|
| CrewAI     | Adapter (`spyllm.adapters.instrument_crewai()`) or OTel |
| AutoGen    | OTel env vars |
| LangGraph  | OTel env vars |
| PydanticAI | OTel env vars |
| Custom     | `agent_span()` context manager |

## Advanced Usage

### Manual Tracing

```python
from spyllm import SpyLLMClient

client = SpyLLMClient(api_key="sk-...", base_url="https://api.spyllm.dev")
client.trace(
    agent_name="my-agent",
    prompt="What is 2+2?",
    response="4",
    token_count=15,
    cost_usd=0.001,
)
```

### Decorator

```python
from spyllm import agent_trace, init

init(api_key="sk-...")

@agent_trace("my-pipeline")
def run_pipeline(query: str) -> str:
    # your code here
    return result
```

### Disable Auto-instrumentation

```python
spyllm.init(api_key="sk-...", instrument=False)
```

## Documentation

- [Quickstart guide](https://spyllm.dev/docs)
- [API reference](https://spyllm.dev/docs)

## Changelog

See [GitHub Releases](https://github.com/Yemnis/spyllm/releases) for a full changelog.

## License

Proprietary — Copyright SpyLLM. All rights reserved.
