gati 0.0.3

Local-first observability for AI agents. Track LLM calls, tool usage, and agent state.

GATI SDK (Public Beta)

Local-First Intelligent Observability Platform for AI Agents

GATI is a comprehensive observability platform that helps you understand, debug, and optimize your AI agents. Track every LLM call, tool usage, and state change with only 2 lines of code.

Quick Start (2 Steps)

# 1. Install
pip install gati

# 2. Start local services (optional - for dashboard)
gati start

That's it! No authentication required. Start tracking immediately.

---

⭐ Stay Updated

Star this repository to get notified about new framework integrations and updates!

We're actively working on adding support for more AI frameworks in the coming weeks. If you'd like to request a specific framework, please fill out the framework request form in the Support section below.

---

Features

• Zero-Code Instrumentation - Automatic tracking for LangChain and LangGraph
• Local-First - All trace data stays on your machine
• Real-Time Cost Tracking - Monitor LLM API costs and token usage
• Visual Dashboard - React interface for exploring traces
• AI Assistant Integration - Query traces using GitHub Copilot via MCP (just run gati mcp)
• Privacy-Focused - All development traces stored locally; only anonymous usage metrics are collected
• Instant Setup - No authentication barriers, just install and go

---

Installation & Setup

1. Install the SDK

pip install gati

2. Start Local Services (Optional)

Only needed if you want to view the dashboard or use MCP integration:

# Start backend and dashboard as local processes
gati start

# Services will be available at:
# - Backend:   http://localhost:8000
# - Dashboard: http://localhost:3000

Custom ports:

# Use command-line arguments
gati start --backend-port 8080 --dashboard-port 3001

# Or set environment variables
export GATI_BACKEND_PORT=8080
export GATI_DASHBOARD_PORT=3001
gati start

Stop services when done:

gati stop

3. Use the SDK

from gati import observe

# Initialize once at the start of your application
observe.init(name="my_agent")

# Your existing LangChain/LangGraph code works automatically!
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4")
response = llm.invoke("Hello!")  # ← Automatically tracked!

---

Usage Examples

LangChain (Auto-instrumentation)

from gati import observe
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate

# Initialize - that's it! No authentication needed
observe.init(name="my_agent")

# All LangChain calls are automatically tracked
llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
chain = prompt | llm

# Automatically tracked with full telemetry
result = chain.invoke({"topic": "programming"})

LangGraph (Auto-instrumentation)

from gati import observe
from langgraph.graph import StateGraph

observe.init(name="my_research_agent")

# Your LangGraph code is automatically instrumented
graph = StateGraph(AgentState)
graph.add_node("agent", call_model)
graph.add_node("action", call_tool)
# ... rest of your graph
app = graph.compile()  # Automatically wrapped!

result = app.invoke(initial_state)

Custom Code (Decorators)

from gati import observe
from gati.decorators import track_agent, track_tool

observe.init(name="my_agent")

@track_agent(name="ResearchAgent")
def my_agent(query: str):
    result = research(query)
    return process(result)

@track_tool(name="web_search")
def research(query: str):
    # Your tool logic here
    return results

---

View Your Traces

Local Dashboard

Open your browser to http://localhost:3000 to see:

• All agent runs with full execution traces
• LLM calls with prompts, responses, and token usage
• Tool invocations with inputs and outputs
• Cost tracking and performance metrics
• Search and filter capabilities
• Timeline visualization

All data is stored locally in SQLite - nothing leaves your machine except anonymous usage metrics.

Metrics Dashboard

Track aggregate metrics across all your agents during development. Navigate to the Metrics page in the dashboard to view:

The metrics dashboard provides:

• Summary Cards: Total agents, runs, events, costs, and averages
• Cost Timeline: Daily cost trends with cumulative totals over time
• Token Usage Timeline: Input/output token consumption patterns
• Agent Comparison: Side-by-side comparison of runs, costs, and token usage per agent
• Top Agents: Rankings by cost and number of runs
• Date Range Filtering: View metrics for the last 7, 14, 30, 60, or 90 days

Access the metrics dashboard at http://localhost:3000/metrics or click the "Metrics" link in the navigation bar.

---

MCP Server Integration for VS Code

Query your agent traces directly from GitHub Copilot Chat using natural language.

What is MCP?

The Model Context Protocol (MCP) allows AI assistants like GitHub Copilot to access your local trace data and answer questions about your agent's behavior.

Setup (2 commands)

1. Start the GATI services:

   gati start
   

2. Run the MCP setup command:

   gati mcp
   

   This automatically:

   • Builds the MCP server if needed
   • Creates .vscode/mcp.json in your workspace
   • Configures the connection to your local backend

3. Reload VS Code:

   • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
   • Type "Developer: Reload Window"
   • Hit Enter

4. Start querying your traces!

   Open GitHub Copilot Agent Chat and try:

   • show me all agent runs in gati
   • what was the average cost today?
   • find runs with errors
   • compare the last 3 runs
   • which agent used the most tokens? Try the above commands preferably using a claude model

MCP Server Features

The GATI MCP server provides these tools:

• list_agents - List all tracked agents
• get_agent_stats - Get statistics for a specific agent
• get_run_details - Get detailed information about a run
• query_events - Query events with filters
• get_recent_runs - Get recent agent runs
• search_runs - Search runs by criteria
• get_cost_summary - Get cost breakdown
• compare_runs - Compare multiple runs

All MCP queries read from your local database - no data is sent externally.

---

Privacy & Data Collection

What Stays Local (100%)

All development traces remain on your machine:

• LLM prompts and completions
• Tool inputs and outputs
• Agent execution traces
• API keys and credentials
• Your code and business logic
• Cost and token usage details

Storage: Local SQLite database at ~/.gati/data/gati.db

Anonymous Usage Metrics

By using GATI SDK, anonymous usage metrics are automatically collected:

What is collected:

• Installation ID (anonymous UUID - no personal info)
• SDK version (e.g., "0.1.1")
• Framework detection (e.g., "langchain", "langgraph")
• Event counts (daily and lifetime)
• Agent counts (how many agents tracked)
• MCP query counts
• Timestamp

What is NOT collected:

• LLM prompts or completions
• Tool inputs or outputs
• API keys or credentials
• Your code or business logic
• IP addresses or device information
• Any personally identifiable information

Telemetry endpoint: https://gati-mvp-telemetry.vercel.app/api/metrics

Opt-out anytime:

# Disable telemetry in your code
observe.init(name="my_agent", telemetry=False)

However, total number of anonymous MCP queries will always be counted. Why we collect metrics:

• Understand which frameworks are popular
• Track SDK adoption and usage patterns
• Improve reliability and performance
• Prioritize features and bug fixes

Transparency: All telemetry code is open source and readable in gati/core/telemetry.py.

---

CLI Commands

# Start local services (backend, dashboard, mcp-server)
gati start                          # Run in background (detached mode)
gati start -f                       # Run in foreground with logs visible
gati start --backend-port 8080      # Custom backend port
gati start --dashboard-port 3001    # Custom dashboard port

# MCP Server Setup for VS Code
gati mcp                            # Set up MCP server (creates .vscode/mcp.json)
gati mcp --force                    # Overwrite existing configuration

# Stop services
gati stop                           # Stop all services

# Check status
gati status                         # Show running services

# View logs
gati logs                           # Show all logs
gati logs -f                        # Follow logs (live tail)
gati logs -f backend                # Follow specific service logs

# Help
gati --help                         # Show all commands

---

Configuration

Environment Variables

# Service ports (for gati start command)
export GATI_BACKEND_PORT=8080          # Backend port (default: 8000)
export GATI_DASHBOARD_PORT=3001        # Dashboard port (default: 3000)

# SDK configuration
export GATI_BACKEND_URL=http://localhost:8000  # Backend URL (default: http://localhost:8000)
export GATI_BATCH_SIZE=10                      # Batch size for event sending (default: 10)
export GATI_FLUSH_INTERVAL=1.0                 # Flush interval in seconds (default: 1.0)

In Code Configuration

from gati import observe

observe.init(
    name="my_agent",
    backend_url="http://localhost:8000",  # Custom backend
    batch_size=20,                        # Larger batches
    flush_interval=2.0,                   # Flush every 2 seconds
    telemetry=False,                      # Disable telemetry
)

---

Architecture

Flow at a glance

1. Your code

   • from gati import observe → observe.init(name="my_agent")
   • LangChain/LangGraph/custom code emits events to http://localhost:8000/api/events.

2. Local services (gati start)

   • Backend (FastAPI, :8000): receives events, persists them, exposes REST/WebSocket APIs.
   • Dashboard (React, :3000): visualizes traces by calling the backend.
   • MCP server (TypeScript): read-only layer on top of the same database for Claude/Copilot.

3. Storage footprint

   • SQLite DB stored at ~/.gati/data/gati.db.
   • Telemetry counters stored at ~/.gati/metrics.json.
   • All services run as local processes (no Docker required).

4. Telemetry (optional & anonymous)

   • Only installation UUID, SDK version, framework flags, and aggregate counts are sent to https://gati-mvp-telemetry.vercel.app/api/metrics.
   • No prompts, completions, API keys, or business logic leave your machine.

---

Custom Event Tracking

from gati import observe
from gati.core.event import Event

observe.init(name="my_agent")

# Create custom events
event = Event(
    event_type="custom_metric",
    data={"metric_name": "cache_hit_rate", "value": 0.85}
)

observe.track_event(event)

Framework-Specific Callbacks

If auto-instrumentation doesn't work:

from gati import observe

observe.init(name="my_agent")

# LangChain: Pass callbacks manually
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    callbacks=observe.get_callbacks()
)

---

Troubleshooting

SDK Not Tracking Events

# Check if backend is running
import requests
requests.get("http://localhost:8000/health")
# Should return: {"status": "healthy"}

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

Services Not Starting

# Check if ports are available
lsof -i :8000  # Check backend port
lsof -i :3000  # Check dashboard port

# View logs for errors
gati logs

# Check service status
gati status

# Restart services
gati stop
gati start

Dashboard Not Showing Data

1. Verify backend is running: curl http://localhost:8000/health
2. Check browser console for errors (F12)
3. Verify events are being sent: Check gati logs backend
4. Restart services: gati stop && gati start

MCP Server Not Showing in VS Code

1. Ensure services are running:

   gati status  # Should show backend and mcp-server running
   

2. Verify configuration exists:

   cat .vscode/mcp.json  # Should show the MCP server config
   

3. Rebuild MCP configuration:

   gati mcp --force  # Overwrite and recreate config
   

4. Reload VS Code completely:

   • Press Cmd+Shift+P → "Developer: Reload Window"
   • Or restart VS Code

5. Check VS Code Output:

   • View → Output
   • Select "MCP" from the dropdown
   • Look for GATI server initialization messages

6. Verify backend connection:

   curl http://localhost:8000/health
   # Should return: {"status":"healthy","version":"1.0.0"}
   

Telemetry Issues

# Disable telemetry if causing issues
observe.init(name="my_agent", telemetry=False)

---

📝 License

MIT License - see LICENSE file for details.

---

📚 Documentation

• SDK Documentation
• Backend API Reference
• Dashboard Guide
• MCP Server Setup

---

💬 Support

Need help or have questions? Fill out this 2-minute Google form and we'll get back to you within 48 hours: https://docs.google.com/forms/d/e/1FAIpQLSfGTXR1iyeSWfKGXOa7xhyjEW08gowEFwvgukI_v90qQ3Qpjg/viewform?usp=dialog

Framework Requests: We're adding support for more AI frameworks in the coming weeks! If you'd like to request a specific framework (e.g., AutoGen, CrewAI, Semantic Kernel, etc.), please mention it in the support form above.

---