Metadata-Version: 2.4
Name: capybara-sdk
Version: 0.1.0
Summary: Emit OpenTelemetry traces to a local capybara trace debugger.
Project-URL: Homepage, https://github.com/tonquoc0407/capybara
Author: capybara
License-Expression: MIT
Keywords: agents,llm,observability,opentelemetry,tracing
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openai>=1.50; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# capybara-sdk

Emit OpenTelemetry `gen_ai.*` traces to a local [capybara](https://github.com/tonquoc0407/capybara)
trace debugger. Import name is `capybara`.

```bash
pip install capybara-sdk
```

```python
import capybara
from pydantic import BaseModel

capybara.init()  # export to a local capybara on 127.0.0.1:4318


class Price(BaseModel):
    price: float
    currency: str


capybara.schema("lookup_price", Price)  # declared beats learned


@capybara.trace(tool="lookup_price")
def lookup_price(sku: str) -> dict:
    return {"price": 42.0, "currency": "USD"}
```

`init()` reuses a `TracerProvider` you already configured, so OpenInference or
OpenLLMetry instrumentors covering OpenAI, Anthropic, or LangChain keep working;
capybara only adds an OTLP exporter and the schema processor.

`@capybara.trace` wraps un-instrumented functions. A bare `@capybara.trace`
records a tool span named after the function; `kind="agent"` or `kind="llm"`
records other span kinds. `capybara.schema(tool, model)` attaches a Pydantic
model's JSON Schema to that tool's spans so capybara reports contract drift on
the first violating call.

Sync and async functions are both supported.

`capybara.replay` is invoked by the binary, not by you: pressing `r` in the TUI
re-executes the recorded process, serving the recorded model responses and tool
outputs so nothing touches the network. A call that is not in the recording
stops the replay instead of running live; only model calls made after an edited
value has been served are allowed to diverge.
