Metadata-Version: 2.4
Name: catalyst-tracing
Version: 0.0.2
Summary: First-party OpenInference-shaped tracing for Python LLM and agent applications on Catalyst by Inference.net.
Project-URL: Homepage, https://inference.net
Keywords: agents,ai,catalyst,inference,llm,observability,openinference,opentelemetry,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.28.0
Requires-Dist: opentelemetry-exporter-otlp-proto-common>=1.28.0
Requires-Dist: opentelemetry-sdk>=1.28.0
Requires-Dist: protobuf>=5.0.0
Requires-Dist: requests>=2.32.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: claude-agent-sdk
Requires-Dist: claude-agent-sdk>=0.0.1; extra == 'claude-agent-sdk'
Provides-Extra: langchain
Requires-Dist: langchain>=0.3.0; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.6.0; extra == 'langgraph'
Provides-Extra: langsmith
Requires-Dist: langsmith>=0.3.15; extra == 'langsmith'
Provides-Extra: openai
Requires-Dist: openai>=1.54.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.5; extra == 'openai-agents'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai>=0.0.50; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# catalyst-tracing

First-party OpenInference-shaped tracing for Python LLM and agent applications
running on Catalyst by Inference.net.

`catalyst-tracing` gives you one Python package for instrumenting common model
SDKs, agent frameworks, and custom agent work. It emits OpenTelemetry spans with
OpenInference-compatible attributes over OTLP/HTTP so Catalyst can display model
calls, tool calls, prompts, responses, token usage, and parent-child agent flows.

This package is currently in beta. APIs may change before `1.0`, but the package
name and import path are intended to remain stable.

## Install

Install the base tracing runtime:

```bash
pip install catalyst-tracing
```

Install only the integrations your application uses:

```bash
pip install 'catalyst-tracing[openai]'
pip install 'catalyst-tracing[anthropic]'
pip install 'catalyst-tracing[langchain]'
pip install 'catalyst-tracing[langgraph]'
pip install 'catalyst-tracing[langsmith]'
pip install 'catalyst-tracing[openai-agents]'
pip install 'catalyst-tracing[claude-agent-sdk]'
pip install 'catalyst-tracing[pydantic-ai]'
```

You can combine extras:

```bash
pip install 'catalyst-tracing[openai,anthropic,langchain]'
```

## Quick Start

Set your Catalyst endpoint and token:

```bash
export CATALYST_OTLP_ENDPOINT="https://your-catalyst-otlp-endpoint"
export CATALYST_OTLP_TOKEN="your-token"
export CATALYST_SERVICE_NAME="checkout-agent"
```

Initialize tracing before creating SDK clients:

```python
from catalyst_tracing import setup
from openai import OpenAI

tracing = setup()

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Summarize this order."}],
)

tracing.shutdown()
```

The OpenAI call is captured as an OpenInference-shaped LLM span and exported to
Catalyst through OTLP/HTTP.

## What It Instruments

| Integration | Install extra | What is captured |
|---|---|---|
| OpenAI | `openai` | Chat Completions, Responses, sync clients, and async clients |
| Anthropic | `anthropic` | Messages API calls, sync clients, and async clients |
| LangChain | `langchain` | Callback-manager driven chain, model, tool, and retriever spans |
| LangGraph | `langgraph` | Graph and node spans through the LangChain callback path |
| LangSmith | `langsmith` | LangSmith OpenTelemetry spans bridged into the Catalyst provider |
| OpenAI Agents | `openai-agents` | Agent runs plus nested OpenAI model spans |
| Claude Agent SDK | `claude-agent-sdk` | `query()` calls and yielded agent messages |
| Pydantic AI | `pydantic-ai` | Pydantic AI's native OpenTelemetry instrumentation |

The base package includes the tracing runtime. Extras install the upstream SDKs
themselves so you can keep production environments narrow.

## Public API

Most applications only need `setup()`:

```python
from catalyst_tracing import setup

tracing = setup(
    service_name="support-agent",
    service_version="0.4.0",
)
```

`setup()` returns a `CatalystTracing` handle with:

| Attribute | Purpose |
|---|---|
| `provider` | OpenTelemetry `TracerProvider` configured for Catalyst export |
| `tracer` | Tracer for manual spans |
| `install_results` | Per-integration install results |
| `shutdown()` | Flush and close tracing before process exit |

You can also import integration installers directly:

```python
from catalyst_tracing import setup
from catalyst_tracing.openai import install_openai

tracing = setup(auto_instrument=False)
install_openai(tracing.provider)
```

Available entry-point modules:

| Import | Export |
|---|---|
| `catalyst_tracing.openai` | `install_openai` |
| `catalyst_tracing.anthropic` | `install_anthropic` |
| `catalyst_tracing.langchain` | `install_langchain` |
| `catalyst_tracing.langgraph` | `install_langgraph` |
| `catalyst_tracing.langsmith` | `install_langsmith` |
| `catalyst_tracing.openai_agents` | `install_openai_agents` |
| `catalyst_tracing.claude_agent_sdk` | `install_claude_agent_sdk` |
| `catalyst_tracing.pydantic_ai` | `install_pydantic_ai` |

## Manual Agent Spans

Use `agent_span()` when work does not go through a supported SDK, such as a CLI
subprocess, custom router, planner, evaluator, or tool executor.

```python
from catalyst_tracing import agent_span, setup

tracing = setup()

with agent_span(tracing.tracer, name="RefundReviewAgent", system="internal") as span:
    span.set_input("Review refund request #1842")
    decision = run_refund_review()
    span.set_output(decision.summary)
    span.record_tokens(prompt=820, completion=160)

tracing.shutdown()
```

Any child spans created inside the context automatically parent under the agent
span through standard OpenTelemetry context propagation.

## Configuration

You can configure tracing with keyword arguments or environment variables.

| Option | Environment variable | Default |
|---|---|---|
| `endpoint` | `CATALYST_OTLP_ENDPOINT` | `http://localhost:8799` |
| `token` | `CATALYST_OTLP_TOKEN` | unset |
| `service_name` | `CATALYST_SERVICE_NAME` | generated `catalyst-app-*` name |
| `service_version` | `CATALYST_SERVICE_VERSION` | `0.0.1` |
| `debug` | `CATALYST_DEBUG` | `false` |
| `batching` | none | `"batch"` |

Legacy `OTLP_ENDPOINT`, `OTLP_INGEST_TOKEN`, and `SERVICE_NAME` variables are
also accepted for compatibility.

## Span Shape

Spans use OpenInference-style semantic attributes so LLM-aware viewers can
understand them without custom adapters:

| Attribute family | Examples |
|---|---|
| Span kind | `openinference.span.kind` |
| Inputs and outputs | `input.value`, `output.value` |
| Messages | `llm.input_messages.*`, `llm.output_messages.*` |
| Model metadata | `llm.model_name`, `llm.invocation_parameters` |
| Token counts | `llm.token_count.prompt`, `llm.token_count.completion`, `llm.token_count.total` |
| Provider/system | `gen_ai.system` |

Constants are exported for custom spans:

```python
from catalyst_tracing import Attr, SpanKindValues

span.set_attribute(Attr.SPAN_KIND, SpanKindValues.LLM.value)
span.set_attribute(Attr.MODEL_NAME, "gpt-4o-mini")
```

## Error Handling

The package raises typed errors for misuse and returns structured install
results for optional integrations:

```python
from catalyst_tracing import CatalystTracingError, InvalidTracerProviderError
from catalyst_tracing.openai import install_openai

try:
    result = install_openai(provider)
except InvalidTracerProviderError as exc:
    print(exc.code)
except CatalystTracingError:
    raise
```

Each installer returns an `InstrumentResult` with:

| Field | Meaning |
|---|---|
| `name` | Integration name |
| `installed` | Whether instrumentation was installed |
| `code` | Stable status code such as `INSTALLED` or `SDK_NOT_INSTALLED` |
| `reason` | Human-readable detail when installation is skipped |

## Package Names

The primary package is `catalyst-tracing` and the primary import path is
`catalyst_tracing`.

Inference also publishes `inference-catalyst-tracing` as a company-qualified
install name. It depends on this package and re-exports the same public API from
the `inference_catalyst_tracing` import path.
