Metadata-Version: 2.5
Name: zhanla
Version: 0.2.0
Summary: Trace an agent for Zhanla: OpenTelemetry spans for its requests, model calls and tool calls, sent to a Zhanla eval run or to production.
Project-URL: Homepage, https://zhanla.vercel.app
Requires-Python: >=3.10
Requires-Dist: openinference-instrumentation-anthropic
Requires-Dist: openinference-instrumentation-crewai; python_version < '3.13'
Requires-Dist: openinference-instrumentation-langchain
Requires-Dist: openinference-instrumentation-litellm
Requires-Dist: openinference-instrumentation-llama-index
Requires-Dist: openinference-instrumentation-openai
Requires-Dist: openinference-instrumentation-openai-agents
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
Requires-Dist: opentelemetry-sdk>=1.27
Provides-Extra: test
Requires-Dist: anthropic>=0.40; extra == 'test'
Requires-Dist: fastapi>=0.110; extra == 'test'
Requires-Dist: langchain-openai>=0.3; extra == 'test'
Requires-Dist: openai>=1; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: uvicorn>=0.29; extra == 'test'
Description-Content-Type: text/markdown

# zhanla

Trace an LLM agent for [Zhanla](https://zhanla.vercel.app): OpenTelemetry spans for each request, its model calls and its tool calls, sent to the Zhanla eval run that started the process or, in production, to your organization.

```sh
pip install zhanla
```

```python
import zhanla

zhanla.init(agent="<your agent's id in Zhanla>")

@zhanla.observe  # the function that handles one request: its call is the root of the trajectory
def answer(question):
    ...  # your agent: OpenAI, Anthropic, LangChain, LlamaIndex, LiteLLM, CrewAI and the OpenAI Agents SDK are traced on their own
```

Zhanla offers to write this for you when it sets your agent up, as a diff you accept.

> Versions before 0.2.0 of this name on PyPI were an earlier Zhanla command-line tool, unrelated to this SDK.

## Where spans go

- **An eval run.** Zhanla starts your agent with `ZHANLA_TRACE_ENDPOINT` and `ZHANLA_TRACE_ITEM` set; nothing to configure.
- **Production.** Set `ZHANLA_API_KEY` to an SDK key made on your organization's settings page (`ZHANLA_INGEST_URL` overrides where they go).
- **Neither.** Tracing is off, with one line on stderr. The SDK never writes to stdout and never stops your agent: a failed export is said once on stderr.

Spans waiting to be sent go as the process exits (`atexit`); a server that stops on a signal calls `zhanla.flush()` first. A process that calls `os._exit` loses them.

## What is traced

`init` instruments the libraries your environment has and returns their names. When a framework (LangChain, LlamaIndex, CrewAI) calls a client it covers, the call is recorded once, by the framework; calls you make on the client yourself are kept.

By hand:

| | |
|---|---|
| `@zhanla.observe` / `@zhanla.observe(name=...)` | a span per call (sync or async) with its arguments and result |
| `with zhanla.span(name, kind=None):` | a span of its own; `kind="subagent"` or `"skill"` says what it is |
| `zhanla.generation(model, input).end(output, input_tokens, output_tokens, thinking, thinking_tokens)` | a model call |
| `zhanla.tool(name, arguments, mcp=None, kind=None).end(result)` | a tool call |
| `set_session_id`, `set_user_id`, `set_tags`, `set_metadata` | stamped on every span started after, for this request |

`zhanla.init(agent, mask=...)`: `mask` runs on every input and output before anything leaves the process; what it returns is what is sent.

## Serverless functions and named libraries

```python
zhanla.init(agent="<id>", instrument={"openai": openai})  # instrument these, and raise if one cannot be
```

On AWS Lambda, Vercel, Netlify, Google Cloud Functions and Run, and Azure Functions, the outermost `observe` sends its request's spans as it ends, before it returns, so a frozen function loses nothing; `serverless=True` turns this on elsewhere, `False` turns it off.

## Servers

A request Zhanla sends to a server you run carries `baggage: zhanla.item=<id>`, so one server serves every eval item:

```python
app.add_middleware(zhanla.ASGIMiddleware)          # FastAPI, Starlette
app.wsgi_app = zhanla.WSGIMiddleware(app.wsgi_app) # Flask
```

Requires Python 3.10 or later.
