Skip to main content

Installation

Install the Observatory Python SDK using pip:
pip install contextcompany
For LiteLLM integration, install with optional dependencies:
pip install contextcompany[litellm]

Authentication

Set your API key as an environment variable:
export TCC_API_KEY=your_api_key_here
Alternatively, pass the api_key parameter directly to any function:
from contextcompany import run

r = run(api_key="your_api_key_here")

Quick Start

Here’s a basic example of tracking an AI agent run:
from contextcompany import run

# Create a new run
r = run()

# Set prompt and response
r.prompt(user_prompt="What is the weather in San Francisco?")
r.response("The weather in San Francisco is 65°F and sunny.")

# End the run
r.end()

Core Concepts

Runs

A run represents a single execution of your AI agent. Use the run() function to create and track runs.

Steps

A step represents an individual LLM call within a run. Steps track prompts, responses, token usage, and costs.
from contextcompany import run

r = run()
s = r.step()

s.prompt("Analyze this data...")
s.response("Based on the analysis...")
s.tokens(prompt_uncached=100, completion=50)
s.end()

r.prompt(user_prompt="User query")
r.response("Final response")
r.end()

Tool Calls

A tool call represents a function or tool invocation during a run:
from contextcompany import run

r = run()
tc = r.tool_call(tool_name="get_weather")

tc.args({"location": "San Francisco"})
tc.result({"temperature": 65, "condition": "sunny"})
tc.end()

r.prompt(user_prompt="What's the weather?")
r.response("It's 65°F and sunny.")
r.end()

API Reference

run()

Create and track AI agent runs

step()

Track individual LLM calls

tool_call()

Monitor tool and function invocations

LiteLLM

Auto-instrument LiteLLM completions

Environment Variables

TCC_API_KEY
string
required
Your Observatory API key
TCC_URL
string
Custom Observatory endpoint URL (defaults to production)
TCC_DEBUG
string
Set to “1” to enable debug logging

Python Version Support

The SDK supports Python 3.9 and above:
  • Python 3.9
  • Python 3.10
  • Python 3.11
  • Python 3.12
  • Python 3.13

Source Code

The Python SDK is open source and available on GitHub.

Build docs developers (and LLMs) love