MonkAI Trace - Python SDK

Official Python client for MonkAI - Monitor, analyze, and optimize your AI agents.

📖 REST API reference: trace-docs.monkai.com.br — interactive ReDoc with curl/Node/Python samples per endpoint (also at bemonkai.github.io/monkai-trace) · Migration guide · API changelog · OpenAPI spec · Postman collection

Features

• Upload conversation records with full token segmentation
• Track 4 token types: input, output, process, memory
• Async support via AsyncMonkAIClient (aiohttp-based)
• Retry with exponential backoff on transient failures
• Batch processing with automatic chunking
• Upload from JSON files (supports your existing data)
• Session management with automatic cleanup and configurable timeouts
• Data export - Query records/logs with filters, export to JSON or CSV
• Structured logging via Python logging module
• HTTP REST API - Language-agnostic tracing for any runtime
• Framework Integrations:
  • MonkAI Agent - Native framework with automatic tracking
  • LangChain - Full callback handler support (v0.2+)
  • OpenAI Agents - RunHooks integration
  • Python Logging - Standard logging handler with custom_object metadata
• Coding Assistant Integrations:
  • Claude Code - Parse CLI session logs from ~/.claude/
  • Cline - Parse VS Code extension task history (also Cursor, Windsurf)
  • OpenClaw - Parse personal AI assistant session transcripts
  • GitHub Copilot - Chat history, org usage API, CSV imports

Installation

pip install monkai-trace

For framework integrations:

# MonkAI Agent (Native Framework)
pip install monkai-trace monkai-agent

# LangChain
pip install monkai-trace langchain

# OpenAI Agents
pip install monkai-trace openai-agents-python

Quick Start

Basic Usage

from monkai_trace import MonkAIClient

client = MonkAIClient(tracer_token="tk_your_token")

client.upload_record(
    namespace="customer-support",
    agent="support-bot",
    messages=[
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I help?"}
    ],
    input_tokens=5,
    output_tokens=10,
    process_tokens=100,
    memory_tokens=20
)

Async Client

from monkai_trace import AsyncMonkAIClient

async def main():
    client = AsyncMonkAIClient(tracer_token="tk_your_token")
    await client.upload_record(
        namespace="my-agent",
        agent="assistant",
        messages=[{"role": "user", "content": "Hello"}],
        input_tokens=5,
        output_tokens=10
    )
    await client.close()

OpenAI Agents Integration

from agents import Agent, WebSearchTool
from monkai_trace.integrations.openai_agents import MonkAIRunHooks

hooks = MonkAIRunHooks(
    tracer_token="tk_your_token",
    namespace="my-agent",
    batch_size=1
)

agent = Agent(
    name="Assistant",
    instructions="You are helpful",
    tools=[WebSearchTool()]
)

hooks.set_user_id("user_abc123")
hooks.set_user_name("João Silva")
hooks.set_user_channel("whatsapp")

result = await MonkAIRunHooks.run_with_tracking(agent, "Hello!", hooks)

LangChain Integration

from langchain.agents import initialize_agent, load_tools
from langchain.llms import OpenAI
from monkai_trace.integrations.langchain import MonkAICallbackHandler

handler = MonkAICallbackHandler(
    tracer_token="tk_your_token",
    namespace="my-agents"
)

llm = OpenAI(temperature=0)
tools = load_tools(["serpapi"], llm=llm)
agent = initialize_agent(tools, llm, callbacks=[handler])
agent.run("What is the weather in Tokyo?")

MonkAI Agent Framework

from monkai_agent import Agent
from monkai_trace.integrations.monkai_agent import MonkAIAgentHooks

hooks = MonkAIAgentHooks(
    tracer_token="tk_your_token",
    namespace="my-namespace"
)

agent = Agent(
    name="Support Bot",
    instructions="You are a helpful assistant",
    hooks=hooks
)

result = agent.run("Help me with my order")

Claude Code Integration

from monkai_trace import ClaudeCodeTracer

tracer = ClaudeCodeTracer(tracer_token="tk_your_token", namespace="dev-productivity")

# Upload all Claude Code sessions
tracer.upload_all_projects()

# Or a specific project
tracer.upload_project("~/.claude/projects/-Users-me-myproject/")

Auto-trace every Claude Code session

Register a one-time hook and every session is uploaded automatically when it ends — no manual command, visible in the MonkAI Hub Monitoring view:

pip install monkai-trace

# Export your tracer token (from MyAgents in the Hub) in your shell profile:
export MONKAI_TRACE_TOKEN="tk_your_token"
export MONKAI_TRACE_NAMESPACE="claude-code"   # optional, this is the default

# Register the SessionEnd hook in ~/.claude/settings.json (idempotent):
monkai-trace install-hook

The hook runs monkai-trace claude-hook, which reads the session transcript path from Claude Code and uploads it. It never raises, so a trace failure can never break your Claude Code session. Remove it anytime with monkai-trace uninstall-hook.

Auto-trace Codex and Grok CLI sessions

The same hook works for the Codex CLI and the Grok CLI:

monkai-trace install-hook --assistant codex   # ~/.codex/hooks.json
monkai-trace install-hook --assistant grok    # ~/.grok/hooks/monkai-trace.json

Each finished turn is uploaded with source codex / grok and namespace codex / grok (or MONKAI_TRACE_NAMESPACE), plus model, tool calls and the repo/branch it ran in. Codex tokens are exact; Grok logs no input/output split, so its tokens are an estimate (metadata.tokens_estimated: true). Codex asks you to trust a new hook before running it. Remove with monkai-trace uninstall-hook --assistant codex|grok. See docs/coding_assistants_integration.md.

The transcript is uploaded once, when the session ends (SessionEnd). If you resume a session and end it again, it is re-uploaded in full.

🔒 Protect your token file. When the token is resolved from a file (MONKAI_TRACE_TOKEN_FILE, default ~/.monkai_trace_token) instead of the MONKAI_TRACE_TOKEN env var, restrict it so other users on the machine can't read your tracer token — it authenticates all of your trace traffic:

chmod 600 ~/.monkai_trace_token

Cline Integration

from monkai_trace import ClineTracer

tracer = ClineTracer(tracer_token="tk_your_token", namespace="dev-productivity")

# Auto-detects VS Code, Cursor, or Windsurf
tracer.upload_all_tasks()

OpenClaw Integration

from monkai_trace import OpenClawTracer

tracer = OpenClawTracer(tracer_token="tk_your_token", namespace="dev-productivity")

# Upload all sessions from ~/.openclaw/
tracer.upload_all_sessions()

GitHub Copilot Integration

from monkai_trace import CopilotTracer

tracer = CopilotTracer(tracer_token="tk_your_token", namespace="dev-productivity")

# Local chat history
tracer.upload_chat_history()

# Org usage API (Business/Enterprise)
tracer.upload_org_usage(github_token="ghp_xxx", org="MyOrg")

# CSV import
tracer.upload_from_csv("copilot_export.csv")

Upload from JSON Files

client.upload_records_from_json("records.json")
client.upload_logs_from_json("logs.json", namespace="my-agent")

Query & Export Data

result = client.query_records(
    namespace="customer-support",
    agent="Support Bot",
    start_date="2025-01-01",
    limit=50
)

client.export_records(
    namespace="customer-support",
    output_file="conversations.json"
)

client.export_logs(
    namespace="my-agent",
    level="error",
    format="csv",
    output_file="errors.csv"
)

HTTP REST API (Language-Agnostic)

For non-Python runtimes or direct HTTP calls:

import requests

MONKAI_API = "https://lpvbvnqrozlwalnkvrgk.supabase.co/functions/v1/monkai-api"
TOKEN = "tk_your_token"

session = requests.post(
    f"{MONKAI_API}/sessions/create",
    headers={"tracer_token": TOKEN, "Content-Type": "application/json"},
    json={"namespace": "my-agent", "user_id": "user123"}
).json()

requests.post(
    f"{MONKAI_API}/traces/llm",
    headers={"tracer_token": TOKEN, "Content-Type": "application/json"},
    json={
        "session_id": session["session_id"],
        "model": "gpt-4",
        "input": {"messages": [{"role": "user", "content": "Hello"}]},
        "output": {"content": "Hi!", "usage": {"prompt_tokens": 5, "completion_tokens": 3}}
    }
)

See HTTP REST API Guide for complete documentation.

Session Management

MonkAI automatically manages user sessions with configurable timeouts:

• Default timeout: 2 minutes of inactivity
• Automatic cleanup: Background thread removes expired sessions
• Multi-user support: Each user gets isolated sessions
• Persistent sessions: Optional file-backed session storage with LRU caching

hooks = MonkAIRunHooks(
    tracer_token="tk_your_token",
    namespace="support",
    inactivity_timeout=120
)
hooks.set_user_id("customer-12345")

See Session Management Guide for details.

Token Segmentation

Track 4 token types to understand LLM costs:

client.upload_record(
    namespace="analytics",
    agent="data-agent",
    messages={"role": "user", "content": "Analyze this"},
    input_tokens=15,
    output_tokens=200,
    process_tokens=500,
    memory_tokens=100
)

Examples

See the examples/ directory:

See examples/README.md for the full guide.

Documentation

• Quick Start Guide
• HTTP REST API Guide
• Data Export Guide
• Session Management Guide
• Coding Assistants Integration ⭐ NEW
• MonkAI Agent Integration
• LangChain Integration
• OpenAI Agents Integration
• Logging Integration
• JSON Upload Guide
• API Reference

Development

git clone https://github.com/BeMonkAI/monkai-trace.git
cd monkai-trace

pip install -e ".[dev]"

pytest tests/ -x -q

Requirements

• Python 3.8+
• requests >= 2.32.2
• pydantic >= 2.0.0
• aiohttp (optional, for AsyncMonkAIClient)
• monkai-agent (optional, for MonkAI Agent integration)
• langchain (optional, for LangChain integration)
• openai-agents-python (optional, for OpenAI Agents integration)

Changelog

v0.7.0

• Incremental upload (per-session offsets) — ClaudeCodeTracer.upload_session_incremental() uploads only the turns not sent before, persisting an offset per session_id under ~/.monkai_trace/ (override with MONKAI_TRACE_STATE_DIR). The hook now uses it, so a session can fire on every Claude Code Stop (near-realtime) without duplicating, and resumed SessionEnd is safe too.
• monkai-trace install-hook is robust — registers an absolute, resolvable command (shutil.which / python -m monkai_trace.cli) so the hook runs even when monkai-trace is not on the hook runner's PATH. New --token-file (bakes MONKAI_TRACE_TOKEN_FILE) and --event Stop; warns at install if no token is resolvable yet.
• Token from file — resolve_token() falls back to MONKAI_TRACE_TOKEN_FILE (default ~/.monkai_trace_token) when MONKAI_TRACE_TOKEN is unset, so the hook does not depend on the shell profile being sourced.
• monkai-trace watch <dir> / ClaudeCodeTracer.watch() — poll a project directory and upload incrementally, for environments without a hook.

v0.6.1

• Security: redact PII inside tool_calls — tool-call arguments (file paths, emails, free-text) are now anonymized by the baseline anonymizer. Previously the tool_calls field bypassed redaction entirely.
• Messages with content: null (tool-only assistant turns, tool messages) no longer emit a spurious "PII may be transmitted unredacted" warning; the warning is reserved for genuinely unexpected content types.

v0.6.0

• New: monkai-trace CLI with a Claude Code auto-trace hook
  • monkai-trace install-hook registers a SessionEnd hook in ~/.claude/settings.json so every session uploads automatically
  • monkai-trace claude-hook reads the hook payload from stdin and uploads (never raises — a trace failure can't break your session)
  • monkai-trace uninstall-hook, upload-session, upload-project for manual control
  • Config via MONKAI_TRACE_TOKEN / MONKAI_TRACE_NAMESPACE / MONKAI_TRACE_BASE_URL
  • ClaudeCodeTracer and run_hook now exported from monkai_trace.integrations

v0.3.0

• New: Coding Assistant Integrations
  • ClaudeCodeTracer — Parse Claude Code CLI session logs from ~/.claude/
  • ClineTracer — Parse Cline VS Code extension task history (VS Code, Cursor, Windsurf)
  • OpenClawTracer — Parse OpenClaw personal AI assistant transcripts from ~/.openclaw/
  • CopilotTracer — Track GitHub Copilot via Chat history, org usage API, and CSV imports
• New: source field on ConversationRecord to identify data origin (claude-code, cline, openclaw, copilot)
• New: TokenUsage.from_anthropic_usage() — Parse Anthropic API usage dicts with cache token support
• Added 4 examples and comprehensive documentation guide

v0.2.18

• Updated README and project URLs
• Synchronized repository metadata

v0.2.17

• Security: Patched requests dependency (CVE fix, now >= 2.32.2)
• Security: Added .env files to .gitignore
• Security: Replaced bare except: with specific exception handling
• Reliability: Added retry with exponential backoff on all HTTP requests
• Reliability: Added CI test gate before PyPI publish
• Usability: Unified async client (base URL, auth headers, endpoints)
• Usability: Exported AsyncMonkAIClient from package __init__
• Usability: Fixed TokenUsage.total_tokens auto-calculation
• Scalability: Automatic session cleanup via background thread
• Scalability: Microsecond-precision session IDs to prevent collisions
• Quality: Migrated all print() calls to logging module

License

MIT License - see LICENSE file.

Support

• Documentation
• GitHub Issues

Contributing

Contributions welcome! Please read our Contributing Guide first.