README.md

---
title: AgentGraph
emoji: 🕸️
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false
license: mit
app_port: 7860
hf_oauth: true
# HF automatically includes 'openid profile', we add specific scopes we need
hf_oauth_scopes:
  - read-repos
hf_oauth_expiration_minutes: 480
---

# 🕸️ AgentGraph

A comprehensive agent monitoring and knowledge graph extraction system for understanding AI agent behavior and decision-making processes.

## 🚀 Quick Start

### Option 1: Automated Setup (Recommended)

The easiest way to get started is using our setup script:

```bash
# 1. Clone the repository
git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
cd AgentGraph

# 2. Run the setup script
./setup.sh
```

The script will:

- Guide you through environment configuration
- Prompt for your OpenAI API key
- Choose between Docker or local development setup
- Automatically handle all dependencies and services

### Option 2: Manual Docker Setup

If you prefer manual control:

```bash
# 1. Clone and setup environment
git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
cd AgentGraph
cp .env.example .env
# Edit .env and add your OpenAI API key

# 2. Build and run with Docker
docker build -t agentgraph .
docker run -d --name agentgraph-app -p 7860:7860 --env-file .env agentgraph

# 3. Access the application
open http://localhost:7860
```

### Option 3: Local Development

For development work:

```bash
# 1. Setup environment
cp .env.example .env
# Edit .env with your API keys

# 2. Quick setup (installs dependencies and starts development server)
python main.py --first-run

# Or step by step:
python main.py --setup        # Set up environment
python main.py --init-db      # Initialize database
python main.py --dev          # Start development servers
```

## 🔧 Configuration

### Required Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key (required for knowledge extraction)

### Optional Environment Variables

- `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`: For AI monitoring integration
- `OPENAI_MODEL_NAME`: Model to use (default: gpt-4o-mini)
- `DB_URI`: Database connection string (default: SQLite)

See `.env.example` for all available configuration options.

## 📋 Features

- 📊 **Real-time Agent Monitoring**: Track agent behavior and performance metrics
- 🕸️ **Knowledge Graph Extraction**: Extract and visualize knowledge graphs from agent traces
- 📈 **Interactive Dashboards**: Comprehensive monitoring and analytics interface
- 🔄 **Trace Analysis**: Analyze agent execution flows and decision patterns
- 🎨 **Graph Visualization**: Beautiful interactive knowledge graph visualizations
- 🔬 **Causal Analysis**: Advanced causal inference and component analysis
- 🧪 **Perturbation Testing**: Security and robustness evaluation
- 🔗 **Platform Integration**: Connect to LangSmith, Langfuse, and other monitoring platforms

## 🏗️ Architecture

AgentGraph follows a 5-stage pipeline architecture:

1. **Input Processing**: Trace upload, analysis, and chunking
2. **Knowledge Extraction**: Multi-agent CrewAI-based extraction
3. **Prompt Reconstruction**: Template extraction and context resolution
4. **Perturbation Testing**: Robustness and security evaluation
5. **Causal Analysis**: Causal inference and relationship analysis

## 🛠️ Technology Stack

- **Backend**: FastAPI + Python 3.11+
- **Frontend**: React + TypeScript + Vite
- **Knowledge Extraction**: Multi-agent CrewAI system
- **Visualization**: Cytoscape, D3.js, React Force Graph
- **AI Integration**: OpenAI, LiteLLM, Langfuse, LangSmith
- **Database**: SQLAlchemy (SQLite/PostgreSQL/MySQL)
- **Deployment**: Docker, Hugging Face Spaces ready

## 📖 Usage

1. **Upload Traces**: Import agent execution traces in various formats
2. **Configure Processing**: Choose extraction methods and parameters
3. **Extract Knowledge**: Automatically generate knowledge graphs
4. **Analyze & Visualize**: Explore graphs, relationships, and patterns
5. **Test Robustness**: Run perturbation tests and security evaluations
6. **Causal Analysis**: Understand causal relationships and component influences

## 🐛 Troubleshooting

### Environment Variable Issues

If you see "Invalid API key" errors:

```bash
# Check your configuration
python -c "from utils.config import debug_config; debug_config()"

# Restart Docker container after updating .env
docker restart agentgraph-app
```

### Common Issues

- **Missing Dependencies**: Run `python main.py --first-run` for automatic setup
- **Port Conflicts**: Change the port with `--port 8080`
- **API Key Problems**: Ensure your `.env` file has the correct format (no quotes or extra spaces)

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for AI agent research and monitoring.