Metadata-Version: 2.4
Name: agenttrail-sdk
Version: 0.1.0
Summary: AgentTrail Python SDK — observability for agentic AI systems
Project-URL: Homepage, https://github.com/agenttrail/agenttrail-python
Project-URL: Documentation, https://github.com/agenttrail/agenttrail-python#readme
Project-URL: Repository, https://github.com/agenttrail/agenttrail-python
Project-URL: Changelog, https://github.com/agenttrail/agenttrail-python/releases
Author: AgentTrail
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,langchain,langgraph,llm,observability,opentelemetry,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.25.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: openai>=1.0.0
Description-Content-Type: text/markdown

# AgentTrail Python SDK

Client library for **tracing agent and LLM workloads**: it records **spans** and sends them to **your** ingestion endpoint (`POST {base_url}/v1/spans`). It does **not** include a server, database, or UI—only instrumentation and export.

## Install (PyPI)

```bash
pip install agenttrail-sdk
```

LangGraph, OpenAI, and Anthropic clients are **dependencies of this package**—customers install once; new framework support ships in **new SDK releases**, not separate extras.

**Developers** can use [uv](https://docs.astral.sh/uv/) with this repo: see [`pyproject.toml`](pyproject.toml) and [`uv.lock`](uv.lock).

## Quick usage

Set **`base_url`** to your span ingestion service, or set the environment variable **`AGENTTRAIL_BASE_URL`** (default if both omitted: `http://127.0.0.1:8080`).

```python
from agenttrail import init, shutdown

init(
    api_key="your-api-key",
    project="my-agent",
    base_url="https://ingest.example.com",
)
try:
    ...  # app / agents
finally:
    shutdown()
```

By default, `init()` **auto-instruments** LangGraph (`invoke` / `ainvoke` / `stream` / `astream`), OpenAI `chat.completions.create`, and Anthropic `messages.create`. Use `auto_instrument=False` to disable.

## Docs

Links use the GitHub repository so they work from **PyPI** and from this checkout.

| Doc | Purpose |
|-----|---------|
| [QUICKSTART](https://github.com/agenttrail/agenttrail-python/blob/main/docs/QUICKSTART.md) | Examples (LangGraph, OpenAI, Anthropic, manual spans) |
| [CONNECTOR_SPEC](https://github.com/agenttrail/agenttrail-python/blob/main/docs/CONNECTOR_SPEC.md) | Building third-party connectors |
| [TESTING](https://github.com/agenttrail/agenttrail-python/blob/main/docs/TESTING.md) | Automated checks and manual smoke tests |
| [PUBLISHING](https://github.com/agenttrail/agenttrail-python/blob/main/docs/PUBLISHING.md) | **PyPI release** (`uv build`, `uv publish`) |
| [SDK_Plan](https://github.com/agenttrail/agenttrail-python/blob/main/docs/SDK_Plan.md) | Internal roadmap / program context |

## Development

```bash
cd /path/to/repo   # repository root containing pyproject.toml
uv sync
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
```

## License

Apache License 2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
