monkai-trace 0.2.16

Official Python SDK for MonkAI - Track and analyze your AI agent conversations

MonkAI Trace - Python SDK

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

Features

• 📤 Upload conversation records with full token segmentation
• 📊 Track 4 token types: input, output, process, memory (always present in API)
• 📁 Upload from JSON files (supports your existing data)
• 🔄 Batch processing with automatic chunking and improved error handling
• 🛡️ Graceful optional dependencies - Import without dependencies, error only on use
• 🌐 HTTP REST API - Language-agnostic tracing for any runtime (Deno, Go, Node.js, etc.)
• 📥 Data Export - Query records/logs with filters and export to JSON or CSV
• 🔌 Framework Integrations:
  • ✅ MonkAI Agent - Native framework with automatic tracking
  • ✅ LangChain - Full callback handler support (v0.2+)
  • ✅ OpenAI Agents - RunHooks integration (updated for latest API)
  • ✅ Python Logging - Standard logging handler with custom_object metadata

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

LangChain Integration

Automatically track LangChain agents:

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

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

# Add to your agent
llm = OpenAI(temperature=0)
tools = load_tools(["serpapi"], llm=llm)
agent = initialize_agent(tools, llm, callbacks=[handler])

# Automatically tracked!
agent.run("What is the weather in Tokyo?")

Basic Usage

from monkai_trace import MonkAIClient

# Initialize client
client = MonkAIClient(tracer_token="tk_your_token")

# Upload a conversation
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
)

MonkAI Agent Framework (Native)

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

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

# Create agent with automatic tracking
agent = Agent(
    name="Support Bot",
    instructions="You are a helpful assistant",
    hooks=hooks
)

# Run agent - automatically tracked!
result = agent.run("Help me with my order")

OpenAI Agents Integration

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

# Create tracking hooks (batch_size=1 recommended for real-time monitoring)
hooks = MonkAIRunHooks(
    tracer_token="tk_your_token",
    namespace="my-agent",
    batch_size=1  # v0.2.10+: Upload immediately
)

# Create agent with web search
agent = Agent(
    name="Assistant",
    instructions="You are helpful",
    tools=[WebSearchTool()]
)

# Set user identification (v0.2.12+)
hooks.set_user_id("user_abc123")         # Unique ID for session tracking
hooks.set_user_name("João Silva")        # Display name in dashboard
hooks.set_user_channel("whatsapp")       # Communication channel

# ✅ RECOMMENDED: Use run_with_tracking() for internal tools capture
result = await MonkAIRunHooks.run_with_tracking(agent, "Hello!", hooks)
# Captures: user message, web_search_call with sources, assistant response

# Dashboard shows:
# - "👤 João Silva" instead of "👤 Usuário" in messages
# - Filter by user name in monitoring panel

HTTP REST API (Language-Agnostic)

For non-Python runtimes or when you prefer direct HTTP calls:

import requests

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

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

# Trace LLM call
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.

Upload from JSON Files

# Upload conversation records
client.upload_records_from_json("records.json")

# Upload logs
client.upload_logs_from_json("logs.json", namespace="my-agent")

Query & Export Data

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

# Export all records to JSON file
client.export_records(
    namespace="customer-support",
    output_file="conversations.json"
)

# Export logs as CSV
client.export_logs(
    namespace="my-agent",
    level="error",
    format="csv",
    output_file="errors.csv"
)

See Data Export Guide for complete documentation.

📚 Practical Examples

Learn by example! Check out our comprehensive examples:

Session Management

• Basic Sessions - Automatic session creation and timeout
• Multi-User - WhatsApp bot with concurrent users
• Custom Timeouts - Configure for your use case

OpenAI Agents

• Basic Integration - Get started quickly
• Multi-Agent - Advanced handoff patterns

HTTP REST API

• Basic Usage - Direct API calls without SDK
• Async Client - High-performance async tracing
• OpenAI + HTTP - Trace OpenAI calls via REST

Data Export

• Query & Export - Query records/logs and export to JSON/CSV

See examples/README.md for full list and use case guide.

---

Session Management

MonkAI automatically manages user sessions with configurable timeouts:

• Default timeout: 2 minutes of inactivity
• Automatic session renewal: Active conversations continue in same session
• Multi-user support: Each user gets isolated sessions
• WhatsApp integration: Use user_whatsapp or user_id for user identification

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

See Session Management Guide for details.

Token Segmentation

MonkAI helps you understand your LLM costs by tracking 4 token types:

• Input: User queries and prompts
• Output: Agent responses and completions
• Process: System prompts, instructions, tool definitions
• Memory: Conversation history and context

client.upload_record(
    namespace="analytics",
    agent="data-agent",
    messages={"role": "user", "content": "Analyze this"},
    input_tokens=15,      # User query
    output_tokens=200,    # Agent response
    process_tokens=500,   # System prompt + tools
    memory_tokens=100     # Previous conversation
)

Documentation

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

Examples

See the examples/ directory for:

• monkai_agent_example.py - MonkAI Agent framework integration
• langchain_example.py - LangChain integration
• langchain_conversational.py - LangChain with memory
• openai_agents_example.py - OpenAI Agents integration
• multi_agent_handoff.py - Multi-agent tracking
• logging_example.py - Python logging integration (scripts)
• service_logging_example.py - Python logging for long-running services
• send_json_files.py - Upload from JSON files
• http_rest_basic.py - HTTP REST API basic usage ⭐ NEW
• http_rest_async.py - Async HTTP REST client ⭐ NEW
• http_rest_openai.py - OpenAI + HTTP REST tracing ⭐ NEW
• export_data.py - Query and export data to JSON/CSV ⭐ NEW

Development

# Clone repository
git clone https://github.com/monkai/monkai-trace-python
cd monkai-trace-python

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy monkai_trace

Requirements

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

License

MIT License - see LICENSE file.

Support

• Documentation
• GitHub Issues
• Discord Community

Contributing

Contributions welcome! Please read our Contributing Guide first.