gati 0.0.3
Local-first observability for AI agents. Track LLM calls, tool usage, and agent state.
License: MIT
Requires Python: >=3.9
Keywords: ai, agents, llm, observability, tracing, langchain, langgraph, monitoring, dashboard

# 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)

```bash
# 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](#-support) 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

```bash
pip install gati
```

### 2. Start Local Services (Optional)

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

```bash
# Start backend and dashboard as local processes
gati start

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

**Custom ports:**
```bash
# 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:**
```bash
gati stop
```

### 3. Use the SDK

```python
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)

```python
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)

```python
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)

```python
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

![GATI dashboard showing a full execution trace](./reference_trace.png)

### Local Dashboard

Open your browser to [http://localhost:3000](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:

![GATI metrics dashboard showing aggregate agent metrics](./metrics_dashboard.png)

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](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**:
   ```bash
   gati start
   ```

2. **Run the MCP setup command**:
   ```bash
   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:**
```python
# 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

```bash
# 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

```bash
# 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

```python
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

```python
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:

```python
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

```python
# 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

```bash
# 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**:
   ```bash
   gati status  # Should show backend and mcp-server running
   ```

2. **Verify configuration exists**:
   ```bash
   cat .vscode/mcp.json  # Should show the MCP server config
   ```

3. **Rebuild MCP configuration**:
   ```bash
   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**:
   ```bash
   curl http://localhost:8000/health
   # Should return: {"status":"healthy","version":"1.0.0"}
   ```

### Telemetry Issues

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

---

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 📚 Documentation

- [SDK Documentation](sdk/README.md)
- [Backend API Reference](backend/README.md)
- [Dashboard Guide](dashboard/README.md)
- [MCP Server Setup](mcp-server/README.md)

---

## 💬 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.


---