{"id":44608243,"url":"https://github.com/sauravbhattacharya001/agentlens","last_synced_at":"2026-04-25T03:52:25.362Z","repository":{"id":338341145,"uuid":"1157547892","full_name":"sauravbhattacharya001/agentlens","owner":"sauravbhattacharya001","description":"AgentLens — Observability and Explainability for AI Agents","archived":false,"fork":false,"pushed_at":"2026-04-10T13:35:44.000Z","size":1595,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-10T15:25:47.474Z","etag":null,"topics":["agent-framework","ai-agents","ai-observability","ai-safety","cost-tracking","dashboard","debugging","devtools","explainability","langchain","llm","llm-tools","monitoring","observability","openai","prompt-engineering","python-sdk","token-tracking","tracing"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sauravbhattacharya001.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T00:18:13.000Z","updated_at":"2026-04-10T09:32:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sauravbhattacharya001/agentlens","commit_stats":null,"previous_names":["sauravbhattacharya001/agentlens"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/sauravbhattacharya001/agentlens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2Fagentlens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2Fagentlens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2Fagentlens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2Fagentlens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sauravbhattacharya001","download_url":"https://codeload.github.com/sauravbhattacharya001/agentlens/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sauravbhattacharya001%2Fagentlens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31872055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","ai-agents","ai-observability","ai-safety","cost-tracking","dashboard","debugging","devtools","explainability","langchain","llm","llm-tools","monitoring","observability","openai","prompt-engineering","python-sdk","token-tracking","tracing"],"created_at":"2026-02-14T11:25:50.654Z","updated_at":"2026-04-16T05:06:27.750Z","avatar_url":"https://github.com/sauravbhattacharya001.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔍 AgentLens\n\n**Observability and Explainability for AI Agents**\n\n*Datadog meets Chain-of-Thought — for autonomous agents*\n\n[![CI](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/ci.yml/badge.svg)](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/codeql.yml/badge.svg)](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/codeql.yml)\n[![Coverage](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/coverage.yml/badge.svg)](https://github.com/sauravbhattacharya001/agentlens/actions/workflows/coverage.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/agentlens?logo=pypi\u0026logoColor=white)](https://pypi.org/project/agentlens/)\n[![npm version](https://img.shields.io/npm/v/agentlens-backend?logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/agentlens-backend)\n[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python\u0026logoColor=white)](https://python.org)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![GitHub repo size](https://img.shields.io/github/repo-size/sauravbhattacharya001/agentlens)](https://github.com/sauravbhattacharya001/agentlens)\n[![GitHub last commit](https://img.shields.io/github/last-commit/sauravbhattacharya001/agentlens)](https://github.com/sauravbhattacharya001/agentlens/commits)\n[![GitHub issues](https://img.shields.io/github/issues/sauravbhattacharya001/agentlens)](https://github.com/sauravbhattacharya001/agentlens/issues)\n[![GitHub stars](https://img.shields.io/github/stars/sauravbhattacharya001/agentlens?style=social)](https://github.com/sauravbhattacharya001/agentlens)\n\n[Getting Started](#-getting-started) · [Features](#-features) · [SDK Reference](#-sdk-reference) · [Dashboard](#-dashboard) · [Architecture](#-architecture) · [Contributing](#-contributing) · [📖 Full Docs](https://sauravbhattacharya001.github.io/agentlens/) · [🎯 Live Demo](https://sauravbhattacharya001.github.io/agentlens/demo/)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 What is AgentLens?\n\nAgentLens gives you full visibility into what your AI agents are doing, why they're doing it, and how much it costs. As AI agents become more autonomous — making decisions, calling tools, chaining actions — you need to **see inside the black box**.\n\nAgentLens provides:\n- **Session-level tracing** for every agent run\n- **Token and cost tracking** across models and calls\n- **Decision traces** capturing *why* an agent made each choice\n- **Human-readable explanations** of agent behavior\n- **A real-time dashboard** to monitor everything visually\n\n## 🤔 Why AgentLens?\n\n| | LangSmith | Helicone | Weights \u0026 Biases | **AgentLens** |\n|---|:---:|:---:|:---:|:---:|\n| Self-hosted | ❌ | ❌ | ❌ | ✅ |\n| Zero external dependencies | ❌ | ❌ | ❌ | ✅ |\n| Decision-level explainability | ❌ | ❌ | ❌ | ✅ |\n| Built-in anomaly detection | ❌ | ❌ | ❌ | ✅ |\n| Session comparison \u0026 diff | ❌ | ❌ | ❌ | ✅ |\n| Cost forecasting | ❌ | Partial | ❌ | ✅ |\n| No vendor lock-in | ❌ | ❌ | ❌ | ✅ |\n| Free \u0026 open source | ❌ | Partial | ❌ | ✅ |\n\nAgentLens runs entirely on your infrastructure — SQLite for storage, no cloud dependencies, no data leaving your network.\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 📊 **Session Tracking** | Group agent actions into sessions with full execution traces |\n| 🛠️ **Tool Call Capture** | Record every tool invocation with inputs, outputs, and duration |\n| 💰 **Token Usage** | Track token consumption and costs across models |\n| 🧠 **Decision Traces** | Capture the reasoning behind each agent decision |\n| 📈 **Visual Timeline** | Interactive timeline view of agent actions in the dashboard |\n| 💡 **Explainability** | Generate human-readable summaries of agent behavior |\n| 🎨 **Decorators** | Zero-config instrumentation with Python decorators |\n| 📈 **Analytics Dashboard** | Aggregate stats, model usage, hourly activity heatmap, sessions-over-time |\n| ⚖️ **Session Comparison** | Compare two sessions side-by-side — token deltas, event breakdowns, tool usage diffs |\n| 💲 **Cost Estimation** | Configurable model pricing, per-session/event cost tracking, cost breakdown dashboard |\n| 🔔 **Alert Rules** | Configurable alert rules with metric thresholds and event triggers |\n| 🏷️ **Session Tags** | Tag sessions for filtering, organization, and retention exemption |\n| 📝 **Annotations** | Timestamped notes on sessions and events for auditing |\n| 🗄️ **Data Retention** | Configurable retention policies with auto-purge and exempt tags |\n| 🔍 **Event Search** | Rich filtering across sessions — by type, model, tokens, duration |\n| 🔬 **Anomaly Detection** | Z-score statistical analysis to detect latency spikes, token surges, error bursts |\n| 🏥 **Health Scoring** | Grade sessions A–F based on error rates, latency, tool failures |\n| 💸 **Cost Budgets** | Per-agent and global spending limits with real-time tracking, warnings, and overage detection |\n| 📖 **Session Narratives** | Auto-generate human-readable summaries of agent session behavior |\n| 🏆 **Agent Scorecards** | Per-agent performance grading with composite scores and letter grades |\n| 🔮 **Cost Forecasting** | Budget projections with what-if simulator and model breakdown |\n| 📊 **Token Heatmap** | Calendar-style visualization of token consumption patterns |\n| ⏱️ **Trace Waterfall** | Interactive Gantt-style event visualization for session traces |\n| 🔄 **Session Diff** | Side-by-side visual comparison of two agent sessions |\n| ❌ **Error Analytics** | Error grouping by type, agent, and model with trend analysis |\n| 🎯 **Command Center** | Unified activity feed aggregating alerts, anomalies, budget warnings, and health signals |\n| 📋 **SLA Compliance** | Track SLA targets with compliance rings, violation alerts, and history |\n\n## 🏗️ Architecture\n\n```\n┌──────────────┐     HTTP POST      ┌──────────────────┐     SQLite      ┌──────────┐\n│  Your Agent  │ ──────────────────► │  AgentLens API   │ ──────────────► │    DB    │\n│  + SDK       │    /events          │  (Express.js)    │                 └──────────┘\n└──────────────┘                     └────────┬─────────┘\n                                              │ REST API\n                                     ┌────────┴─────────┐\n                                     │    Dashboard      │\n                                     │  (HTML/CSS/JS)    │\n                                     └──────────────────┘\n```\n\n| Component | Directory | Tech Stack |\n|-----------|-----------|------------|\n| **Python SDK** | `sdk/` | Python 3.9+, Pydantic, httpx |\n| **Backend API** | `backend/` | Node.js, Express, better-sqlite3 |\n| **Dashboard** | `dashboard/` | Vanilla HTML/CSS/JS (no build step) |\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- **Python 3.9+** (for the SDK)\n- **Node.js 18+** (for the backend)\n- **npm** (comes with Node.js)\n\n### 1. Clone the repo\n\n```bash\ngit clone https://github.com/sauravbhattacharya001/agentlens.git\ncd agentlens\n```\n\n### 2. Start the Backend\n\n```bash\ncd backend\nnpm install\nnode seed.js      # Load demo data (optional)\nnode server.js    # Starts on http://localhost:3000\n```\n\nThe dashboard is served automatically at [http://localhost:3000](http://localhost:3000).\n\n### 3. Install the Python SDK\n\n```bash\npip install agentlens\n```\n\nOr install from source for development:\n\n```bash\ncd sdk\npip install -e .\n```\n\n### 4. Use the CLI\n\nAfter installing the SDK, you get the `agentlens` command:\n\n```bash\n# Check backend connectivity\nagentlens status\n\n# List recent sessions\nagentlens sessions --limit 10\n\n# View cost breakdown for a session\nagentlens costs \u003csession_id\u003e\n\n# Search events by type or model\nagentlens events --type llm_call --model gpt-4\n\n# Export a session to JSON or CSV\nagentlens export \u003csession_id\u003e --format csv -o report.csv\n\n# Health score for a session (A–F grading)\nagentlens health \u003csession_id\u003e\n\n# Compare two sessions side-by-side\nagentlens compare \u003csession_a\u003e \u003csession_b\u003e\n\n# View aggregate analytics\nagentlens analytics\n\n# List recent alerts\nagentlens alerts\n\n# Generate incident postmortem for a session\nagentlens postmortem \u003csession_id\u003e\n\n# List sessions eligible for postmortem analysis\nagentlens postmortem --candidates --min-errors 3\n\n# Live session leaderboard\nagentlens top\n\n# Live-follow session events\nagentlens tail \u003csession_id\u003e\n\n# Generate time-range summary report\nagentlens report --from 2024-01-01 --to 2024-01-31\n\n# Generate interactive HTML flamegraph for a session\nagentlens flamegraph \u003csession_id\u003e -o profile.html --open\n\n# Print flamegraph statistics without generating HTML\nagentlens flamegraph \u003csession_id\u003e --stats\n\n# Generate self-contained HTML dashboard with interactive charts\nagentlens dashboard --limit 200 -o dashboard.html --open\n\n# Evaluate sessions against SLA policies\nagentlens sla --policy production --limit 100\n\n# Custom SLA targets with verbose output\nagentlens sla --latency 2000 --error-rate 5 --token-budget 8000 --slo 95 --verbose\n\n# SLA compliance as JSON for CI/CD pipelines\nagentlens sla --policy production --json\n```\n\nConfigure via environment variables:\n```bash\nexport AGENTLENS_ENDPOINT=http://localhost:3000\nexport AGENTLENS_API_KEY=your-key\n```\n\nOr pass `--endpoint` and `--api-key` flags to any command.\n\n### 5. Instrument Your Agent\n\n```python\nimport agentlens\n\n# Initialize the SDK\nagentlens.init(api_key=\"your-key\", endpoint=\"http://localhost:3000\")\n\n# Start a tracking session\nsession = agentlens.start_session(agent_name=\"my-agent\")\n\n# Track events manually\nagentlens.track(\n    event_type=\"llm_call\",\n    input_data={\"prompt\": \"What is 2+2?\"},\n    output_data={\"response\": \"4\"},\n    model=\"gpt-4\",\n    tokens_in=12,\n    tokens_out=3,\n    reasoning=\"Simple arithmetic question, answered directly\",\n)\n\n# Get a human-readable explanation\nprint(agentlens.explain())\n\n# End the session\nagentlens.end_session()\n```\n\n### 5. Run the Demo\n\n```bash\ncd sdk/examples\npython mock_agent.py\n# Then open http://localhost:3000 to see the results\n```\n\n## 📖 SDK Reference\n\n### Initialization\n\n```python\nimport agentlens\n\n# Connect to your AgentLens backend\ntracker = agentlens.init(\n    api_key=\"your-key\",           # API key for authentication\n    endpoint=\"http://localhost:3000\"  # Backend URL\n)\n```\n\n### Session Management\n\n```python\n# Start a session\nsession = agentlens.start_session(\n    agent_name=\"my-agent\",        # Name of the agent\n    metadata={\"env\": \"prod\"}      # Optional metadata\n)\n\n# End the session (flushes all pending events)\nagentlens.end_session()\n```\n\n### Manual Event Tracking\n\n```python\nevent = agentlens.track(\n    event_type=\"llm_call\",        # Event type: llm_call, tool_call, generic\n    input_data={\"prompt\": \"...\"},  # Input to the operation\n    output_data={\"text\": \"...\"},   # Output from the operation\n    model=\"gpt-4\",                # Model used (if applicable)\n    tokens_in=100,                # Input tokens\n    tokens_out=50,                # Output tokens\n    reasoning=\"...\",              # Why the agent made this decision\n    tool_name=\"search\",           # Tool name (for tool calls)\n    tool_input={\"query\": \"...\"},  # Tool input\n    tool_output={\"results\": []},  # Tool output\n    duration_ms=1500.0,           # Execution duration in ms\n)\n```\n\n### Decorators (Zero-Config)\n\n```python\nfrom agentlens import track_agent, track_tool_call\n\n@track_agent(model=\"gpt-4\")\ndef my_agent(prompt):\n    \"\"\"Automatically tracked — captures input, output, and timing.\"\"\"\n    return call_llm(prompt)\n\n@track_tool_call(tool_name=\"web_search\")\ndef search(query):\n    \"\"\"Automatically tracked — captures tool input/output.\"\"\"\n    return do_search(query)\n```\n\n### Explainability\n\n```python\n# Get a human-readable explanation of agent behavior\nexplanation = agentlens.explain()\nprint(explanation)\n# Output: \"The agent received a question about arithmetic.\n#          It called GPT-4 which responded with '4'.\n#          Total tokens used: 15 (12 in, 3 out).\"\n```\n\n### Session Comparison\n\n```python\n# Compare two sessions side-by-side\nresult = agentlens.compare_sessions(\n    session_a=\"abc123\",\n    session_b=\"def456\",\n)\n\n# Result includes metrics, deltas, and shared breakdowns\nprint(f\"Token delta: {result['deltas']['total_tokens']['percent']}%\")\nprint(f\"Session A events: {result['session_a']['event_count']}\")\nprint(f\"Session B events: {result['session_b']['event_count']}\")\nprint(f\"Shared tools: {result['shared']['tools']}\")\n```\n\n### Cost Estimation\n\n```python\n# Get cost breakdown for the current session\ncosts = agentlens.get_costs()\nprint(f\"Total cost: ${costs['total_cost']:.4f}\")\nprint(f\"Input cost: ${costs['total_input_cost']:.4f}\")\nprint(f\"Output cost: ${costs['total_output_cost']:.4f}\")\n\n# Per-model breakdown\nfor model, mc in costs['model_costs'].items():\n    print(f\"  {model}: ${mc['total_cost']:.4f} ({mc['calls']} calls)\")\n\n# View/update model pricing (per 1M tokens, USD)\npricing = agentlens.get_pricing()\nprint(pricing['pricing'])  # Current pricing config\n\n# Set custom pricing\nagentlens.set_pricing({\n    \"my-custom-model\": {\n        \"input_cost_per_1m\": 5.00,\n        \"output_cost_per_1m\": 15.00,\n    }\n})\n```\n\n### Event Search\n\n```python\n# Search events with rich filtering\nresults = tracker.search_events(\n    q=\"error\",                    # Full-text search\n    event_type=\"tool_call\",       # Filter by type\n    model=\"gpt-4\",               # Filter by model\n    min_tokens=100,               # Minimum token count\n    has_tools=True,               # Only events with tool calls\n    after=\"2024-01-01T00:00:00Z\", # Date range\n    limit=50,                     # Max results\n)\nfor event in results[\"events\"]:\n    print(f\"{event['event_type']}: {event.get('model', 'N/A')}\")\n```\n\n### Session Tags\n\n```python\n# Add tags to the current session\ntracker.add_tags([\"production\", \"v2.0\", \"critical\"])\n\n# Remove specific tags\ntracker.remove_tags([\"v2.0\"])\n\n# Get tags for a session\ntags = tracker.get_tags()\n\n# List all tags across sessions\nall_tags = tracker.list_all_tags()\n\n# Find sessions by tag\nsessions = tracker.list_sessions_by_tag(\"production\")\n```\n\n### Annotations\n\n```python\n# Annotate a session with timestamped notes\ntracker.annotate(\n    \"Latency spike detected at step 5\",\n    annotation_type=\"warning\",\n    author=\"monitoring-bot\",\n)\ntracker.annotate(\n    \"Reached goal state\",\n    annotation_type=\"milestone\",\n)\n\n# Retrieve annotations\nannotations = tracker.get_annotations(annotation_type=\"warning\")\nfor ann in annotations[\"annotations\"]:\n    print(f\"[{ann['type']}] {ann['text']}\")\n\n# Update or delete annotations\ntracker.update_annotation(\"ann-id-123\", text=\"Updated note\")\ntracker.delete_annotation(\"ann-id-456\")\n```\n\n### Alert Rules\n\n```python\n# Create an alert rule\ntracker.create_alert_rule(\n    name=\"High Error Rate\",\n    metric=\"error_rate\",\n    condition=\"gt\",\n    threshold=0.1,\n    description=\"Fires when error rate exceeds 10%\",\n)\n\n# List and evaluate rules\nrules = tracker.list_alert_rules()\nalerts = tracker.evaluate_alerts()  # Check all rules against recent data\nalert_events = tracker.get_alert_events(limit=20)\n```\n\n### Anomaly Detection\n\n```python\nfrom agentlens import AnomalyDetector, AnomalyDetectorConfig\n\nconfig = AnomalyDetectorConfig(\n    warning_threshold=2.0,   # 2σ = warning\n    critical_threshold=3.0,  # 3σ = critical\n)\ndetector = AnomalyDetector(config)\n\n# Analyze a session for anomalies\nreport = detector.analyze(session_events)\nprint(f\"Found {len(report.anomalies)} anomalies\")\nfor anomaly in report.anomalies:\n    print(f\"  [{anomaly.severity.value}] {anomaly.kind.value}: {anomaly.description}\")\n```\n\n### Health Scoring\n\n```python\nfrom agentlens import HealthScorer, HealthThresholds\n\nscorer = HealthScorer()\nreport = scorer.score(session_events)\n\nprint(f\"Overall: {report.overall_grade.value} ({report.overall_score:.0f}/100)\")\nfor metric in report.metrics:\n    print(f\"  {metric.name}: {metric.grade.value} ({metric.score:.0f}/100)\")\n```\n\n### Data Retention\n\n```python\n# Configure retention policy\ntracker.set_retention_config(\n    max_age_days=30,              # Delete sessions older than 30 days\n    max_sessions=10000,           # Keep max 10k sessions\n    exempt_tags=[\"production\"],   # Never delete production sessions\n    auto_purge=True,              # Enable automatic cleanup\n)\n\n# Preview what would be purged\npreview = tracker.purge(dry_run=True)\nprint(preview[\"message\"])\n\n# Actually purge\nresult = tracker.purge()\nprint(f\"Purged {result['purged_sessions']} sessions\")\n```\n\n### Data Models\n\n| Model | Description |\n|-------|-------------|\n| `AgentEvent` | A single observable event (LLM call, tool use, decision) |\n| `ToolCall` | A tool/function invocation with input and output |\n| `DecisionTrace` | The reasoning behind an agent's decision |\n| `Session` | A collection of events for one agent run |\n| `AlertRule` | A configurable alert rule with metric and threshold |\n| `Anomaly` | A detected statistical anomaly in session metrics |\n| `HealthReport` | Graded health assessment of a session (A–F) |\n\n## 📊 Dashboard\n\nThe dashboard provides a real-time view of your agent sessions:\n\n- **Sessions List** — Filter by status (active, completed, error)\n- **Session Comparison** — Select two sessions and compare side-by-side with visual diffs\n- **Analytics Overview** — Click 📈 Analytics to see aggregate stats, model usage, hourly activity, and top agents\n- **Timeline View** — Interactive timeline of every event in a session\n- **Token Charts** — Per-event and cumulative token usage visualization\n- **Explain Tab** — Human-readable behavior summaries\n- **Costs Tab** — Per-event and per-model cost breakdowns, cumulative cost chart, configurable model pricing\n- **Cost Forecast** — Budget projections with what-if simulator and model breakdown\n- **Agent Scorecards** — Per-agent performance grading with composite scores, letter grades, and sparkline trends\n- **Token Heatmap** — Calendar-style visualization of daily token consumption\n- **Trace Waterfall** — Gantt-style visualization of event timing within a session\n- **Session Diff Viewer** — Side-by-side comparison of two sessions with event-level diffs\n- **Error Analytics** — Error grouping by type, agent, and model with trends\n- **SLA Compliance** — Compliance rings, violation alerts, and history charts\n\nThe dashboard is a lightweight HTML/CSS/JS app served directly by the backend — no build step required.\n\n## 🔌 API Endpoints\n\nThe backend exposes a comprehensive REST API with **80+ endpoints** across 16 route groups:\n\n| Route Group | Endpoints | Description |\n|-------------|-----------|-------------|\n| **Sessions** | 8 | CRUD, search, explain, export, compare |\n| **Events** | 1 | Batch event ingestion (up to 500/call) |\n| **Analytics** | 4 | Aggregate stats, performance, heatmaps, cache |\n| **Pricing \u0026 Costs** | 4 | Model pricing config, per-session cost calculation |\n| **Alerts** | 8 | Alert rules CRUD, evaluation, acknowledgment |\n| **Webhooks** | 6 | Webhook CRUD, test delivery, delivery history |\n| **Correlations** | 10 | Correlation rules, groups, event correlations |\n| **Correlation Scheduler** | 6 | SSE stream, schedule management, scheduler control |\n| **Tags** | 5 | Session tagging, tag-based filtering |\n| **Bookmarks** | 4 | Session bookmarking |\n| **Annotations** | 5 | Timestamped notes on sessions and events |\n| **Baselines** | 5 | Agent performance baselines and drift detection |\n| **Error Analysis** | 5 | Error grouping by type, agent, model with trends |\n| **Dependencies** | 5 | Service dependency graph, co-occurrence, critical paths |\n| **Leaderboard** | 1 | Agent performance ranking |\n| **Postmortem** | 2 | Incident report generation and candidate listing |\n| **Retention** | 4 | Retention config, stats, manual purge |\n| **Health** | 1 | Health check |\n\n\u003e 📖 **Full API reference with request/response examples:** [docs/API.md](docs/API.md)\n\n## 🛠️ Tech Stack\n\n- **Python SDK**: Pydantic for data validation, httpx for async HTTP\n- **Backend**: Express.js with better-sqlite3 for zero-config persistence\n- **Dashboard**: Vanilla JS with Canvas-based charts (no framework dependencies)\n- **Database**: SQLite (embedded, no external DB setup needed)\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. Fork the repo\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests: `cd sdk \u0026\u0026 pytest`\n5. Commit (`git commit -m 'Add amazing feature'`)\n6. Push (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Setup\n\n```bash\n# Backend (with auto-reload)\ncd backend \u0026\u0026 npm install \u0026\u0026 node server.js\n\n# SDK (editable install with dev deps)\ncd sdk \u0026\u0026 pip install -e \".[dev]\"\n\n# Run SDK tests\ncd sdk \u0026\u0026 pytest\n```\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built by [Saurav Bhattacharya](https://github.com/sauravbhattacharya001)**\n\n*Because if you can't see what your agents are doing, you can't trust them.*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsauravbhattacharya001%2Fagentlens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsauravbhattacharya001%2Fagentlens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsauravbhattacharya001%2Fagentlens/lists"}