Skip to main content

Installation

pip install fallom anthropic

Quick Start

Import order matters! Initialize Fallom before importing Anthropic.
import os

# Import and initialize Fallom FIRST
import fallom
fallom.init(api_key=os.environ["FALLOM_API_KEY"])

# NOW import Anthropic
from anthropic import Anthropic
client = Anthropic()

# Set session context (config_key, session_id, customer_id)
fallom.trace.set_session("my-app", "session-123", customer_id="user-456")

# Use as normal - automatically traced!
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.content[0].text)

With System Prompt

import fallom
fallom.init(api_key="your-fallom-api-key")

from anthropic import Anthropic
client = Anthropic()

fallom.trace.set_session("my-agent", "session-123")

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant who speaks like a pirate.",
    messages=[{"role": "user", "content": "Tell me about the weather."}]
)

Streaming

import fallom
fallom.init(api_key="your-fallom-api-key")

from anthropic import Anthropic
client = Anthropic()

fallom.trace.set_session("my-agent", "session-123")

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a poem."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="")

Model A/B Testing

import fallom
from fallom import models

fallom.init(api_key="your-fallom-api-key")

from anthropic import Anthropic
client = Anthropic()

# Get assigned model
model_id = models.get("my-experiment", "session-123", fallback="claude-sonnet-4-20250514")

fallom.trace.set_session("my-experiment", "session-123")

response = client.messages.create(
    model=model_id,
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

What Gets Traced

FieldDescription
Modelclaude-sonnet-4-20250514, etc.
DurationTotal request time (ms)
TokensInput, output tokens
CostCalculated from token usage
PromptsSystem + user messages
CompletionsModel response
SessionYour config key + session ID

Next Steps