peekai 0.1.3

Lightweight, local-first observability and debugging for Python AI agents.

No cloud. No API keys. No dashboards to sign up for.
Drop it in, call peekai.init(), and see exactly what your agent is doing —
every LLM call, every tool use, every token spent.

Why PeekAI?

Building AI agents is hard. Debugging them is harder. Tools like LangSmith or Weights & Biases require you to send your data to their cloud, create accounts, and wire up pipelines before you can see a single trace.

PeekAI is different:

Install

pip install peekai

# With OpenAI support
pip install "peekai[openai]"

# With Anthropic support
pip install "peekai[anthropic]"

# With the web dashboard
pip install "peekai[ui]"

# With everything
pip install "peekai[all]"

Quickstart

import peekai
from openai import OpenAI

# One line to instrument everything
peekai.init()

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is 2 + 2?"}],
)

print(response.choices[0].message.content)

Then inspect your traces:

peekai list                  # recent traces
peekai view <trace-id>       # full span waterfall
peekai stats                 # token + cost totals
peekai ui                    # launch the web dashboard

How it works — peekai.init() monkey-patches the SDK clients at startup. No changes to your existing API calls are needed.

Multi-Agent Support

Decorate your agents and tools — PeekAI automatically builds the parent/child span tree:

import peekai
from openai import OpenAI

peekai.init()
client = OpenAI()


@peekai.agent("researcher")
def researcher_agent(topic: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"Research: {topic}"}],
    )
    return response.choices[0].message.content


@peekai.agent("writer")
def writer_agent(research: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"Summarise: {research}"}],
    )
    return response.choices[0].message.content


@peekai.tool("format_output")
def format_output(text: str) -> str:
    return f"📝 {text}"


@peekai.trace("multi_agent_pipeline")
def run():
    research = researcher_agent("the James Webb Space Telescope")
    summary = writer_agent(research)
    return format_output(summary)


run()

Visualize the agent flow in the terminal:

peekai map <trace-id>

  trace: multi_agent_pipeline  ✓ ok  3.6s  236 tokens  $0.000222

  └── 🧠 researcher  [agent]  ✓ ok  2.3s
      └── 🤖 openai/gpt-4o  [llm]  ✓ ok  2.3s  102 tok  $0.000115
  └── 🧠 writer  [agent]  ✓ ok  1.3s
      └── 🤖 openai/gpt-4o  [llm]  ✓ ok  1.3s  134 tok  $0.000107
  └── 🔧 format_output  [tool]  ✓ ok  0ms

Trace Replay

Re-run any past trace — swap the model, inject a different tool response, see what would have changed:

# Replay with the same model
peekai replay <trace-id>

# Swap to a different model
peekai replay <trace-id> --model gpt-4o

# Swap to Anthropic
peekai replay <trace-id> --model claude-3-5-sonnet-20241022

# Inject a modified tool response
peekai replay <trace-id> --tool search="different search result"

The replay is saved as a new trace and shown side by side in the UI with token/cost deltas.

CLI Reference

All commands accept short trace IDs — the first 8 characters are enough.

Web Dashboard

peekai ui

Opens at http://localhost:8501 with four pages:

• Dashboard — KPIs, cost over time, per-model breakdown
• Traces — filterable list with status, tokens, cost
• Trace View — span waterfall with duration bars, input/output tabs, error highlighting
• Replay — run a replay with model swap, side-by-side comparison

Decorators

peekai.init() options

peekai.init(
    db_path="./my_traces.db",  # default: ~/.peekai/peekai.db
    openai=True,               # patch OpenAI SDK (default True)
    anthropic=True,            # patch Anthropic SDK (default True)
    litellm=True,              # patch LiteLLM (default True)
    capture_content=True,      # store raw prompts/responses (default True)
                               # set False to keep only tokens/costs/timings
)

Traces are stored locally at ~/.peekai/peekai.db by default. You can open it directly with any SQLite viewer, back it up, or wipe it with peekai clear.

⚠️ Traces contain sensitive data — prompts, completions, and tool-call arguments can include API keys, credentials, PII, and proprietary content. A few precautions:

• Add ~/.peekai/ to your ~/.gitignore so traces are never committed.
• Use peekai clear to wipe the database when you no longer need the history.
• Pass capture_content=False to store only timing, token counts, and costs without any raw content.
• On POSIX systems (Linux/macOS) PeekAI sets the trace directory to 0700 and the database to 0600 automatically. On Windows filesystem permissions are not enforced.

Supported SDKs

Development

# Clone and install
git clone https://github.com/oussamaKH63/peekai
cd peekai
uv sync --extra all  # includes openai, anthropic, litellm, ui

# Run tests
uv run pytest tests/ -v

# Run the demos
uv run python examples/demo_agent.py
uv run python examples/demo_multi_agent.py

# Launch the UI
uv run peekai ui

Contributing

# Install dev dependencies
uv sync --extra dev

# Run linter
uv run ruff check src/

# Run type checker
uv run mypy src/

# Run tests
uv run pytest tests/ -v

PRs and issues are welcome. See CONTRIBUTING.md for more detail.

License

MIT © Oussema Khorchani