README.md

---
title: Template Final Assignment
emoji: 🕵🏻‍♂️
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
---

# LangGraph Multi-Agent System with Langfuse v3 Observability

A sophisticated multi-agent system built with LangGraph that follows best practices for state management, tracing, and iterative workflows. Features comprehensive Langfuse v3 observability with OpenTelemetry integration.

## Architecture Overview

The system implements an iterative research/code loop with specialized agents:

```
User Query → Lead Agent → Research Agent → Code Agent → Lead Agent (loop) → Answer Formatter → Final Answer
```

## Key Features

- **🤖 Multi-Agent Workflow**: Specialized agents for research, computation, and formatting
- **📊 Langfuse v3 Observability**: Complete tracing with OTEL integration and predictable span naming
- **🔄 Iterative Processing**: Intelligent routing between research and computational tasks
- **🎯 GAIA Compliance**: Exact-match answer formatting for benchmark evaluation
- **💾 Memory System**: Vector store integration for learning and caching
- **🛠️ Tool Integration**: Web search, Wikipedia, ArXiv, calculations, and code execution

## Quick Start

### Environment Setup

Create an `env.local` file with required API keys:

```bash
# LLM API
GROQ_API_KEY=your_groq_api_key

# Search Tools
TAVILY_API_KEY=your_tavily_api_key

# Observability (Langfuse v3)
LANGFUSE_PUBLIC_KEY=your_langfuse_public_key
LANGFUSE_SECRET_KEY=your_langfuse_secret_key
LANGFUSE_HOST=https://cloud.langfuse.com

# Memory (Optional)
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_KEY=your_supabase_service_key
```

### Running the System

**Important**: Use `uv run` for proper dependency management:

```bash
# Run the multi-agent system test
uv run python test_new_multi_agent_system.py

# Test Langfuse v3 observability
uv run python test_observability.py

# Run the main application
uv run python app.py
```

### Basic Usage

```python
import asyncio
from langgraph_agent_system import run_agent_system

async def main():
    result = await run_agent_system(
        query="What is the capital of Maharashtra?",
        user_id="user_123",
        session_id="session_456"
    )
    print(f"Answer: {result}")

asyncio.run(main())
```

## Observability Dashboard

After running queries, check your traces at: **https://cloud.langfuse.com**

The system provides:
- 🎯 **Predictable Span Naming**: `agent/<role>`, `tool/<name>`, `llm/<model>`
- 🔗 **Session Tracking**: User and session continuity across conversations  
- 📈 **Cost & Latency Metrics**: Automatic aggregation by span type
- 🌐 **OTEL Integration**: Automatic trace correlation across services

## Deployment

### For Hugging Face Spaces

To generate a `requirements.txt` file compatible with **Python 3.10** for deployment:

```bash
uv pip compile pyproject.toml --python 3.10 -o requirements.txt

# Remove Windows-specific packages
# Linux / macOS (bash)
sed -i '/^pywin32==/d' requirements.txt

# Windows (PowerShell)
(Get-Content requirements.txt) -notmatch '^pywin32==' | Set-Content requirements.txt
```

### Environment Variables for Production

Set these in your deployment environment:
- `GROQ_API_KEY` - Required for LLM inference
- `TAVILY_API_KEY` - Required for web search
- `LANGFUSE_PUBLIC_KEY` - Required for observability
- `LANGFUSE_SECRET_KEY` - Required for observability
- `LANGFUSE_HOST` - Langfuse endpoint (default: https://cloud.langfuse.com)

## Documentation

For detailed architecture, configuration, and usage instructions, see:
- **[Multi-Agent System Guide](README_MULTI_AGENT_SYSTEM.md)** - Complete system documentation
- **[Supabase Setup](README_SUPABASE.md)** - Memory system configuration

## Configuration Reference

Check out the Hugging Face Spaces configuration reference at https://huggingface.co/docs/hub/spaces-config-reference