pisama-auto 0.2.0

Zero-code auto-instrumentation for LLM applications with Pisama failure detection

pisama-auto

Zero-code auto-instrumentation for LLM applications. Add Pisama failure detection with one line.

Requires Python 3.10 or newer. Python 3.10 through 3.13 are tested.

Quick Start

pip install "pisama[auto]"

pisama[auto] is the recommended install because it keeps the CLI, local detectors, and auto-instrumentation on one compatible dependency path. pip install pisama-auto remains supported for applications that only need the instrumentation layer.

import pisama_auto
pisama_auto.init()  # traces locally; set PISAMA_API_KEY to export to Pisama

# All subsequent LLM calls are automatically traced
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
# This call is automatically traced and sent to Pisama if export is configured.

Supported Libraries

Library	Status	What's Traced
anthropic	GA	messages.create(), messages.stream()
openai	GA	chat.completions.create()

Package lifecycle

pisama-auto is a maintained implementation package. Its public API remains supported, but it is not a separate product entry point. New users should install pisama[auto]. Existing direct installations continue to work.

How It Works

1. pisama_auto.init() sets up an OpenTelemetry tracer that exports to Pisama
2. It then patches supported LLM libraries to emit spans with gen_ai.* semantic conventions
3. Pisama's detection engine analyzes the traces for 50 failure modes
4. Results appear in your Pisama dashboard

Configuration

pisama_auto.init(
    api_key="ps_...",                    # or set PISAMA_API_KEY env var
    endpoint="https://your-instance/api/v1/traces/ingest",  # or PISAMA_ENDPOINT env var
    service_name="my-agent",             # OTEL service name
    auto_patch=True,                     # auto-patch all detected libraries
)

With an API key and no explicit endpoint, spans go to the Pisama platform (api.pisama.ai). The exporter exchanges the API key for a short-lived token automatically. Without an API key, traces are generated locally but not exported. Set PISAMA_ENDPOINT to target a self-hosted instance or a custom OTLP collector instead.

Selective Patching

import pisama_auto
pisama_auto.init(auto_patch=False)  # don't auto-patch

from pisama_auto.patches import patch
patch("anthropic")  # only patch anthropic