Add environment configuration template, enhance .gitignore, and refactor configuration loading. Removed deprecated scripts and improved setup process with a new setup script.

.env.example

@@ -0,0 +1,93 @@
+# AgentGraph Environment Configuration Template
+# Copy this file to .env and fill in your actual values
+
+# =============================================================================
+# 🔑 REQUIRED CONFIGURATION
+# =============================================================================
+
+# OpenAI API Configuration (REQUIRED for knowledge extraction)
+OPENAI_API_KEY=sk-your-openai-api-key-here
+OPENAI_MODEL_NAME=gpt-4o-mini
+
+# =============================================================================
+# 🔧 OPTIONAL CONFIGURATION
+# =============================================================================
+
+# Azure OpenAI Configuration (Alternative to OpenAI)
+# Uncomment and configure if using Azure OpenAI instead
+# AZURE_API_KEY=your-azure-api-key
+# AZURE_API_BASE=https://your-resource.openai.azure.com/
+# AZURE_API_VERSION=2023-12-01-preview
+
+# Anthropic Configuration (Optional)
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# =============================================================================
+# 📊 AI OBSERVABILITY PLATFORMS
+# =============================================================================
+
+# Langfuse Configuration (Optional - for AI monitoring)
+# LANGFUSE_PUBLIC_KEY=pk_lf_your-public-key
+# LANGFUSE_SECRET_KEY=sk_lf_your-secret-key
+# LANGFUSE_HOST=https://cloud.langfuse.com
+
+# LangSmith Configuration (Optional - for trace monitoring)
+# LANGSMITH_API_KEY=your-langsmith-api-key
+# LANGSMITH_PROJECT=your-project-name
+
+# =============================================================================
+# 🗄️ DATABASE CONFIGURATION
+# =============================================================================
+
+# Database URI (SQLite by default, can use PostgreSQL/MySQL)
+DB_URI=sqlite:///agent_monitoring.db
+
+# PostgreSQL Example:
+# DB_URI=postgresql://username:password@localhost:5432/agentgraph
+
+# MySQL Example:
+# DB_URI=mysql://username:password@localhost:3306/agentgraph
+
+# =============================================================================
+# 🚀 SERVER CONFIGURATION
+# =============================================================================
+
+# Server Settings
+HOST=0.0.0.0
+PORT=7860
+LOG_LEVEL=INFO
+
+# Python Path (usually set automatically)
+PYTHONPATH=/app
+
+# =============================================================================
+# 🔒 SECURITY CONFIGURATION
+# =============================================================================
+
+# Encryption key for storing sensitive data (auto-generated if not set)
+# ENCRYPTION_KEY=your-32-character-encryption-key
+
+# =============================================================================
+# 🧪 DEVELOPMENT CONFIGURATION
+# =============================================================================
+
+# Development mode settings
+# DEBUG=false
+# RELOAD=false
+
+# =============================================================================
+# 📈 PERFORMANCE CONFIGURATION
+# =============================================================================
+
+# Processing settings
+# MAX_WORKERS=4
+# BATCH_SIZE=10
+# TIMEOUT_SECONDS=300
+
+# =============================================================================
+# 🌐 HUGGING FACE SPACES CONFIGURATION
+# =============================================================================
+
+# If deploying to Hugging Face Spaces, these are automatically set:
+# SPACE_ID=your-username/space-name
+# SPACE_HOST=https://your-username-space-name.hf.space

.gitignore

@@ -1,13 +1,94 @@
+# Python
 __pycache__/
 *.py[cod]
 *.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Environment and configuration
+.env
+.env.local
+.env.*.local
+*.envrc
+
+# Logs and temporary files
 logs/
 *.log
+.DS_Store
+Thumbs.db
+
+# Database and cache files
+db/
+cache/
+*.db
+*.sqlite
+*.sqlite3
+
+# Analysis and test results
+evaluation_results/
+extraction_analysis/
 datasets/db/
 datasets/knowledge_graphs/
 datasets/test_results/
+test_output/
+*.analysis.json
+*_extraction_*.json
+
 # Allow example_traces data for Gallery
 !datasets/example_traces/
-db/
-cache/
-evaluation_results/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Docker and deployment
+.dockerignore
+docker-compose.override.yml
+
+# Node.js (frontend)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+.yarn-integrity
+
+# Frontend build outputs
+frontend/dist/
+frontend/build/
+
+# Temporary development files
+temp/
+tmp/
+*.tmp
+*.bak
+*.backup

README.md

@@ -13,26 +13,147 @@ app_port: 7860
 
 A comprehensive agent monitoring and knowledge graph extraction system for understanding AI agent behavior and decision-making processes.
 
-## Features
+## 🚀 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 <repository-url>
+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 <repository-url>
+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
 
-## Usage
+## 🏗️ Architecture
 
-1. **Upload Traces**: Import agent execution traces
-2. **Extract Knowledge**: Automatically generate knowledge graphs
-3. **Analyze & Visualize**: Explore graphs and patterns
-4. **Monitor Performance**: Track system health and metrics
+AgentGraph follows a 5-stage pipeline architecture:
 
-## Technology Stack
+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
 
-- **Backend**: FastAPI + Python
+## 🛠️ Technology Stack
+
+- **Backend**: FastAPI + Python 3.11+
 - **Frontend**: React + TypeScript + Vite
 - **Knowledge Extraction**: Multi-agent CrewAI system
-- **Visualization**: Interactive graph components
+- **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.

agentgraph/input/parsers/demo.py

@@ -1,158 +0,0 @@
-#!/usr/bin/env python3
-"""
-Demo Script for LangSmith Parser System
-
-This script demonstrates how the rule-based parser system automatically detects
-trace sources and injects appropriate context documents to enhance knowledge
-extraction.
-
-Usage:
-    python demo.py [--trace-file path/to/trace.json]
-"""
-
-import sys
-import json
-import logging
-from pathlib import Path
-
-# Add project root to path for imports
-project_root = Path(__file__).parent.parent.parent.parent
-sys.path.insert(0, str(project_root))
-
-from agentgraph.input.parsers import (
-    detect_trace_source, 
-    parse_trace_with_context,
-    get_context_documents_for_source,
-    create_parser
-)
-
-# Setup logging
-logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
-logger = logging.getLogger(__name__)
-
-
-def demo_langsmith_detection():
-    """Demonstrate LangSmith trace detection and parsing"""
-    
-    print("🔍 Demo: LangSmith Trace Detection & Parsing")
-    print("=" * 50)
-    
-    # Sample LangSmith trace structure (placeholder)
-    sample_langsmith_trace = {
-        "run_id": "12345678-1234-1234-1234-123456789012",
-        "project_name": "My Agent Project",
-        "trace_id": "trace_123",
-        "export_timestamp": "2025-01-15T10:30:00Z",
-        "total_traces": 3,
-        "traces": [
-            {
-                "run_type": "llm",
-                "name": "ChatBot Agent",
-                "inputs": {"messages": [{"role": "user", "content": "Hello"}]},
-                "outputs": {"content": "Hi there!"},
-                "start_time": "2025-01-15T10:30:01Z",
-                "end_time": "2025-01-15T10:30:02Z"
-            },
-            {
-                "run_type": "tool", 
-                "name": "web_search",
-                "inputs": {"query": "weather today"},
-                "outputs": {"results": []},
-                "start_time": "2025-01-15T10:30:03Z",
-                "end_time": "2025-01-15T10:30:04Z"
-            },
-            {
-                "run_type": "chain",
-                "name": "Response Generator",
-                "inputs": {"context": "weather data"},
-                "outputs": {"response": "Today is sunny"},
-                "start_time": "2025-01-15T10:30:05Z", 
-                "end_time": "2025-01-15T10:30:06Z"
-            }
-        ]
-    }
-    
-    trace_content = json.dumps(sample_langsmith_trace, indent=2)
-    trace_metadata = {
-        "platform": "langsmith",
-        "processing_type": "langsmith_processed_import"
-    }
-    
-    print("1. 🎯 Source Detection")
-    detected_source = detect_trace_source(trace_content, trace_metadata)
-    print(f"   Detected platform: {detected_source}")
-    
-    print("\n2. 🏗️ Parser Creation")
-    parser = create_parser(detected_source)
-    if parser:
-        print(f"   Created parser: {parser.__class__.__name__}")
-        print(f"   Supported types: {parser.supported_trace_types}")
-    else:
-        print("   No parser available")
-        return
-    
-    print("\n3. 📋 Context Document Generation")
-    context_docs = get_context_documents_for_source(detected_source)
-    print(f"   Generated {len(context_docs)} context documents:")
-    for i, doc in enumerate(context_docs, 1):
-        print(f"     {i}. {doc['document_type']}: {doc['title']}")
-    
-    print("\n4. 🔄 Full Parsing with Context")
-    parsed_metadata, enhanced_context = parse_trace_with_context(trace_content, trace_metadata)
-    
-    if parsed_metadata:
-        print(f"   Platform: {parsed_metadata.platform}")
-        print(f"   Confidence: {parsed_metadata.confidence:.2f}")
-        print(f"   Agents found: {len(parsed_metadata.agents)}")
-        print(f"   Tools found: {len(parsed_metadata.tools)}")
-        if parsed_metadata.workflow:
-            print(f"   Project: {parsed_metadata.workflow.project_name}")
-    
-    print(f"   Enhanced context: {len(enhanced_context)} documents")
-    
-    print("\n✅ Demo complete - The parser system is ready!")
-    print("\nNext steps:")
-    print("1. Implement actual LangSmith parsing logic in langsmith_parser.py")
-    print("2. Add more specific context documents based on detected patterns")
-    print("3. Enhance the knowledge extractor to use parsed metadata")
-
-
-def demo_integration_flow():
-    """Demonstrate how the parser integrates with the knowledge extraction flow"""
-    
-    print("\n🚀 Integration Flow Demo")
-    print("=" * 50)
-    
-    print("The parser system integrates automatically:")
-    print("1. 📥 Trace imported from LangSmith via observability connection")
-    print("2. 🔍 SlidingWindowMonitor detects trace source automatically")
-    print("3. 📋 Platform-specific context documents injected")
-    print("4. 🧠 Multi-agent knowledge extractor uses enhanced context")
-    print("5. 📊 Better extraction results with platform knowledge")
-    
-    print("\nKey benefits:")
-    print("✓ Zero configuration required")
-    print("✓ Automatic platform detection")
-    print("✓ Structured metadata extraction")
-    print("✓ Context-aware knowledge extraction")
-    print("✓ Extensible to new platforms")
-
-
-def main():
-    """Run the demo"""
-    print("🎭 LangSmith Parser System Demo")
-    print("=" * 60)
-    
-    try:
-        demo_langsmith_detection()
-        demo_integration_flow()
-        
-    except Exception as e:
-        logger.error(f"Demo failed: {e}")
-        return 1
-    
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main()) 

agentgraph/methods/production/openai_structured_extractor.py

@@ -12,7 +12,7 @@ import logging
 from typing import Optional, List, Dict, Any
 import uuid
 from datetime import datetime
-from dotenv import load_dotenv
+from utils.config import OPENAI_API_KEY, OPENAI_MODEL_NAME
 from openai import OpenAI
 from pydantic import BaseModel
 
@@ -28,9 +28,6 @@ class KnowledgeGraphReasoning(BaseModel):
     steps: List[Step]
     final_answer: KnowledgeGraph
 
-# Load environment variables (searches current directory and parents)
-load_dotenv()
-
 # Configure logging
 logger = logging.getLogger(__name__)
 
@@ -48,7 +45,7 @@ class OpenAIStructuredExtractor:
             model: OpenAI model to use (must support structured outputs)
         """
         self.model = model
-        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+        self.client = OpenAI(api_key=OPENAI_API_KEY)
         logger.info(f"OpenAI Structured Extractor initialized with model: {model}")
     
     def extract_knowledge_graph(self, input_data: str, context_documents: Optional[List[Dict[str, Any]]] = None) -> KnowledgeGraph:

agentgraph/reconstruction/example_rag_usage.py

@@ -1,100 +0,0 @@
-#!/usr/bin/env python3
-"""
-Example usage of the RAG-based Prompt Reconstructor
-
-This example demonstrates how to use the new RAG-based reconstruction method
-as an alternative to the traditional content reference approach.
-"""
-
-from agentgraph.reconstruction import (
-    reconstruct_prompts_from_knowledge_graph_rag,
-    enrich_knowledge_graph_with_prompts_rag,
-    RagPromptReconstructor
-)
-
-def example_usage():
-    """Example of how to use the RAG-based prompt reconstructor."""
-    
-    # Sample knowledge graph data
-    knowledge_graph = {
-        "entities": [
-            {
-                "id": "user_001", 
-                "name": "User inquiry about document loader",
-                "type": "Input",
-                "raw_prompt": "What is a document loader?"
-            },
-            {
-                "id": "agent_001",
-                "name": "Stereotypical Robot Named Robbie", 
-                "type": "Agent",
-                "raw_prompt": "You are a stereotypical robot named Robbie..."
-            }
-        ],
-        "relations": [
-            {
-                "id": "rel_001",
-                "source": "user_001",
-                "target": "agent_001", 
-                "type": "PERFORMS",
-                "interaction_prompt": "What is a document loader?"
-            }
-        ]
-    }
-    
-    # Sample original trace content
-    original_trace = """
-    User: What is a document loader?
-    
-    Agent: BEEP BOOP! Hello human! A document loader is a component in 
-    LangChain that helps load documents from various sources. BEEP!
-    
-    There are many types like TextLoader, PDFLoader, CSVLoader, etc.
-    Each one is designed for specific file formats. BOOP BEEP!
-    
-    Would you like me to explain any specific type? BEEP BOOP!
-    """
-    
-    # Method 1: Using the pure function
-    print("=== Using Pure Function ===")
-    reconstructed_relations = reconstruct_prompts_from_knowledge_graph_rag(
-        knowledge_graph=knowledge_graph,
-        original_trace=original_trace,
-        llm_config={"model": "gpt-5-mini", "temperature": 0.1}
-    )
-    
-    for relation in reconstructed_relations:
-        print(f"Relation: {relation['id']}")
-        print(f"Type: {relation['type']}")
-        print(f"Reconstructed Prompt:")
-        print(relation['prompt'])
-        print(f"Search Queries Used: {relation.get('search_queries_used', [])}")
-        print("-" * 50)
-    
-    # Method 2: Using the class directly
-    print("\n=== Using RagPromptReconstructor Class ===")
-    reconstructor = RagPromptReconstructor(
-        knowledge_graph=knowledge_graph,
-        original_trace=original_trace,
-        llm_config={"model": "gpt-5-mini", "temperature": 0.1}
-    )
-    
-    # Reconstruct a specific relation
-    specific_reconstruction = reconstructor.reconstruct_relation_prompt("rel_001")
-    print(f"Specific Reconstruction:")
-    print(f"Prompt: {specific_reconstruction['reconstructed_prompt']}")
-    print(f"Method: {specific_reconstruction['reconstruction_method']}")
-    
-    # Method 3: Enrich entire knowledge graph
-    print("\n=== Enriching Knowledge Graph ===")
-    enriched_kg = enrich_knowledge_graph_with_prompts_rag(
-        knowledge_graph=knowledge_graph,
-        original_trace=original_trace
-    )
-    
-    print(f"Original KG had {len(knowledge_graph.get('relations', []))} relations")
-    print(f"Enriched KG has {len(enriched_kg.get('prompt_reconstructions', []))} reconstructed prompts")
-    print(f"Reconstruction metadata: {enriched_kg.get('reconstruction_metadata', {})}")
-
-if __name__ == "__main__":
-    example_usage()

backend/services/platform/langfuse_downloader.py

@@ -4,12 +4,12 @@ from datetime import datetime
 from typing import Any, Dict, List, Optional, Union
 
 import fire
-from dotenv import load_dotenv
+from utils.config import LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST
 from langfuse import Langfuse
 
 from backend.routers.observe_models import LangFuseSession
 
-load_dotenv()
+# Environment variables loaded via utils.config
 
 
 class LangfuseDownloader:
@@ -38,18 +38,16 @@ class LangfuseDownloader:
             os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"
         
         # Check if credentials are available
-        if not os.getenv("LANGFUSE_SECRET_KEY") or not os.getenv("LANGFUSE_PUBLIC_KEY"):
+        if not LANGFUSE_SECRET_KEY or not LANGFUSE_PUBLIC_KEY:
             raise ValueError(
                 "Missing credentials. Provide secret_key and public_key parameters "
                 "or set LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY environment variables."
             )
         
         # Debug: Print environment variables to verify they're set correctly
-        public_key_val = os.getenv('LANGFUSE_PUBLIC_KEY')
-        secret_key_val = os.getenv('LANGFUSE_SECRET_KEY')
-        print(f"LangfuseDownloader init - PUBLIC_KEY: {public_key_val[:8] if public_key_val else 'None'}...")
-        print(f"LangfuseDownloader init - SECRET_KEY: {secret_key_val[:8] if secret_key_val else 'None'}...")
-        print(f"LangfuseDownloader init - HOST: {os.getenv('LANGFUSE_HOST')}")
+        print(f"LangfuseDownloader init - PUBLIC_KEY: {LANGFUSE_PUBLIC_KEY[:8] if LANGFUSE_PUBLIC_KEY else 'None'}...")
+        print(f"LangfuseDownloader init - SECRET_KEY: {LANGFUSE_SECRET_KEY[:8] if LANGFUSE_SECRET_KEY else 'None'}...")
+        print(f"LangfuseDownloader init - HOST: {LANGFUSE_HOST}")
         
         # Initialize Langfuse client - it uses environment variables automatically
         self.client = Langfuse()

debug_env.py

@@ -1,185 +0,0 @@
-#!/usr/bin/env python3
-"""
-Environment Variables Debug Script for HF Spaces
-Helps diagnose the 'str expected, not NoneType' error
-"""
-
-import os
-import sys
-from pathlib import Path
-
-def check_environment():
-    """Check all required environment variables and configurations"""
-    print("🔍 AgentGraph Environment Debug Report")
-    print("=" * 50)
-    print()
-    
-    # Critical environment variables
-    env_vars = {
-        "OPENAI_API_KEY": "❌ REQUIRED - OpenAI API access",
-        "LANGFUSE_PUBLIC_KEY": "🟡 Optional - AI monitoring",
-        "LANGFUSE_SECRET_KEY": "🟡 Optional - AI monitoring", 
-        "LANGFUSE_HOST": "🟡 Optional - AI monitoring",
-        "OPENAI_MODEL_NAME": "🟡 Optional - defaults to gpt-4o-mini",
-        "DB_URI": "🟡 Optional - defaults to SQLite",
-        "PYTHONPATH": "🔧 System variable",
-        "HOME": "🔧 System variable",
-        "PATH": "🔧 System variable"
-    }
-    
-    print("📋 Environment Variables Check:")
-    print("-" * 30)
-    missing_critical = []
-    
-    for var, description in env_vars.items():
-        value = os.getenv(var)
-        if value is None:
-            status = "❌ NOT SET"
-            if "REQUIRED" in description:
-                missing_critical.append(var)
-        elif value == "":
-            status = "⚠️ EMPTY"
-            if "REQUIRED" in description:
-                missing_critical.append(var)
-        else:
-            # Mask sensitive values
-            if "KEY" in var or "SECRET" in var:
-                masked_value = f"{value[:8]}..." if len(value) > 8 else "***"
-                status = f"✅ SET ({masked_value})"
-            else:
-                status = f"✅ SET ({value[:50]}...)" if len(value) > 50 else f"✅ SET ({value})"
-        
-        print(f"  {var:20} | {status:25} | {description}")
-    
-    print()
-    
-    # Check critical paths and files
-    print("📁 Critical Paths Check:")
-    print("-" * 25)
-    
-    paths_to_check = [
-        ("Current directory", Path.cwd()),
-        ("utils/config.py", Path("utils/config.py")),
-        ("backend/app.py", Path("backend/app.py")),
-        ("main.py", Path("main.py")),
-        ("pyproject.toml", Path("pyproject.toml"))
-    ]
-    
-    for name, path in paths_to_check:
-        if path.exists():
-            status = "✅ EXISTS"
-        else:
-            status = "❌ MISSING"
-        print(f"  {name:20} | {status:15} | {path}")
-    
-    print()
-    
-    # Python path check
-    print("🐍 Python Environment:")
-    print("-" * 20)
-    print(f"  Python version: {sys.version}")
-    print(f"  Python path: {sys.executable}")
-    print(f"  Working directory: {os.getcwd()}")
-    print(f"  PYTHONPATH: {os.getenv('PYTHONPATH', 'NOT SET')}")
-    
-    print()
-    
-    # Try importing critical modules
-    print("📦 Import Test:")
-    print("-" * 15)
-    
-    modules_to_test = [
-        "utils.config",
-        "backend.app", 
-        "fastapi",
-        "uvicorn",
-        "pydantic",
-        "sqlalchemy"
-    ]
-    
-    for module in modules_to_test:
-        try:
-            __import__(module)
-            print(f"  {module:20} | ✅ OK")
-        except ImportError as e:
-            print(f"  {module:20} | ❌ FAILED: {str(e)}")
-        except Exception as e:
-            print(f"  {module:20} | ⚠️ ERROR: {str(e)}")
-    
-    print()
-    
-    # Summary
-    print("📊 Summary:")
-    print("-" * 10)
-    
-    if missing_critical:
-        print(f"❌ CRITICAL: Missing required environment variables: {', '.join(missing_critical)}")
-        print("🔧 Fix: Set these variables in HF Spaces Settings > Environment variables")
-        return False
-    else:
-        print("✅ All critical environment variables are set")
-        
-        # Try to identify the specific error
-        print()
-        print("🔍 Specific Error Analysis:")
-        print("The 'str expected, not NoneType' error suggests:")
-        print("1. A string parameter is being passed None instead of a string")
-        print("2. Most likely in configuration or initialization code")
-        print("3. Check Pydantic model validation or string concatenation")
-        
-        return True
-
-def test_config_import():
-    """Test importing and using the config module"""
-    print()
-    print("🧪 Config Module Test:")
-    print("-" * 20)
-    
-    try:
-        from utils.config import OPENAI_API_KEY, validate_config
-        
-        print(f"OPENAI_API_KEY loaded: {'✅ YES' if OPENAI_API_KEY else '❌ NO'}")
-        
-        # Test validation
-        is_valid = validate_config()
-        print(f"Config validation: {'✅ PASSED' if is_valid else '❌ FAILED'}")
-        
-        return is_valid
-        
-    except Exception as e:
-        print(f"❌ Config import failed: {str(e)}")
-        return False
-
-if __name__ == "__main__":
-    print("Starting environment debug check...")
-    print()
-    
-    # Basic environment check
-    env_ok = check_environment()
-    
-    # Config test
-    config_ok = test_config_import()
-    
-    print()
-    print("🎯 RECOMMENDATIONS:")
-    print("=" * 20)
-    
-    if not env_ok:
-        print("1. ❌ Set missing OPENAI_API_KEY in HF Spaces environment variables")
-        print("2. 🔗 Go to: https://huggingface.co/spaces/holistic-ai/AgentGraph/settings")
-        print("3. 📝 Add: OPENAI_API_KEY = your_openai_api_key")
-    
-    if not config_ok:
-        print("4. 🔧 Check utils/config.py for import issues")
-        print("5. 🐍 Verify Python dependencies are installed correctly")
-    
-    if env_ok and config_ok:
-        print("✅ Environment looks good!")
-        print("🔍 The 'str expected, not NoneType' error may be in:")
-        print("   • Pydantic model validation")
-        print("   • String formatting/concatenation")
-        print("   • Database connection string")
-        print("   • FastAPI configuration")
-        
-    print()
-    print("📊 Run this script in HF Spaces to get the exact error location!")

extraction_analysis/cot_extraction_20250909_172744_855dfc94.json

@@ -1,139 +0,0 @@
-{
-  "timestamp": "20250909_172744",
-  "extraction_id": "855dfc94",
-  "model": "gpt-4o-mini",
-  "reasoning_steps": [],
-  "knowledge_graph": {
-    "system_name": "User Message Response System",
-    "system_summary": "This system is designed to process user messages and generate appropriate responses. The process begins when a user sends a message, which is handled by the `Assistant Agent` (agent_001). The agent undertakes the `Message Processing Task` (task_001) to analyze the user input and generate an output. This collaborative process allows the system to efficiently respond to user inquiries.",
-    "entities": [
-      {
-        "id": "agent_001",
-        "type": "Agent",
-        "name": "Assistant Agent",
-        "importance": "HIGH",
-        "raw_prompt": "",
-        "raw_prompt_ref": [
-          {
-            "line_start": 2,
-            "line_end": 2
-          }
-        ]
-      },
-      {
-        "id": "task_001",
-        "type": "Task",
-        "name": "Message Processing Task",
-        "importance": "HIGH",
-        "raw_prompt": "",
-        "raw_prompt_ref": [
-          {
-            "line_start": 3,
-            "line_end": 3
-          }
-        ]
-      },
-      {
-        "id": "input_001",
-        "type": "Input",
-        "name": "User Message",
-        "importance": "HIGH",
-        "raw_prompt": "",
-        "raw_prompt_ref": [
-          {
-            "line_start": 3,
-            "line_end": 3
-          }
-        ]
-      },
-      {
-        "id": "output_001",
-        "type": "Output",
-        "name": "Agent Response",
-        "importance": "HIGH",
-        "raw_prompt": "",
-        "raw_prompt_ref": [
-          {
-            "line_start": 4,
-            "line_end": 4
-          }
-        ]
-      },
-      {
-        "id": "human_001",
-        "type": "Human",
-        "name": "End User",
-        "importance": "HIGH",
-        "raw_prompt": "",
-        "raw_prompt_ref": [
-          {
-            "line_start": 3,
-            "line_end": 3
-          }
-        ]
-      }
-    ],
-    "relations": [
-      {
-        "id": "rel_001",
-        "source": "input_001",
-        "target": "agent_001",
-        "type": "CONSUMED_BY",
-        "importance": "HIGH",
-        "interaction_prompt": "",
-        "interaction_prompt_ref": [
-          {
-            "line_start": 2,
-            "line_end": 2
-          }
-        ]
-      },
-      {
-        "id": "rel_002",
-        "source": "agent_001",
-        "target": "task_001",
-        "type": "PERFORMS",
-        "importance": "HIGH",
-        "interaction_prompt": "",
-        "interaction_prompt_ref": [
-          {
-            "line_start": 2,
-            "line_end": 2
-          }
-        ]
-      },
-      {
-        "id": "rel_003",
-        "source": "task_001",
-        "target": "output_001",
-        "type": "PRODUCES",
-        "importance": "HIGH",
-        "interaction_prompt": "",
-        "interaction_prompt_ref": [
-          {
-            "line_start": 4,
-            "line_end": 4
-          }
-        ]
-      },
-      {
-        "id": "rel_004",
-        "source": "output_001",
-        "target": "human_001",
-        "type": "DELIVERS_TO",
-        "importance": "HIGH",
-        "interaction_prompt": "",
-        "interaction_prompt_ref": [
-          {
-            "line_start": 4,
-            "line_end": 4
-          }
-        ]
-      }
-    ],
-    "failures": [],
-    "optimizations": []
-  },
-  "input_trace_length": 184,
-  "input_trace_preview": "<L1> {\n<L2>   \"agent_name\": \"assistant\",\n<L3>   \"input\": \"user message\",\n<L4>   \"output\": \"agent response\",\n<L5>   \"timestamp\": \"2024-08-31\",\n<L6>   \"trace_id\": \"test-trace-123\"\n<L7> }"
-}

frontend/Dockerfile.dev

@@ -1,18 +0,0 @@
-FROM node:18-slim
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm ci
-
-# Copy source code
-COPY . .
-
-# Expose port for development server
-EXPOSE 3001
-
-# Start development server with hot reload
-CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0", "--port", "3001"]

main.py

@@ -8,6 +8,9 @@ Updated: Graph visualization sizes optimized for better UI layout.
 # Import the complete LiteLLM fix FIRST, before any other imports that might use LiteLLM
 from utils.fix_litellm_stop_param import *  # This applies all the patches
 
+# Import configuration and debug utilities
+from utils.config import validate_config, debug_config
+
 # Continue with regular imports
 import argparse
 import sys
@@ -218,6 +221,14 @@ def main():
         logging.getLogger().setLevel(getattr(logging, args.log_level))
         logger.setLevel(getattr(logging, args.log_level))
     
+    # Debug configuration on startup (but only if not just showing help)
+    if len(sys.argv) > 1:
+        debug_config()
+        if not validate_config():
+            logger.error("❌ Configuration validation failed. Please check your environment variables.")
+            logger.error("💡 Tip: Copy .env.example to .env and fill in your API keys")
+            return
+    
     # --------------------------------------------------
     # First-run combo flag: environment setup + init DB + dev server
     # --------------------------------------------------
@@ -248,26 +259,16 @@ def main():
                 return
             deps_marker.touch()
 
-        # 1. Environment setup
-        try:
-            from setup_env import setup_environment
-            logger.info("🔧 Running environment setup...")
-            setup_environment()
-            logger.info("✅ Environment setup complete")
-        except Exception as e:
-            logger.error(f"Environment setup failed: {e}")
-            return
+        # 1. Environment setup (now handled by unified config system)
+        logger.info("🔧 Environment setup...")
+        logger.info("✅ Environment configuration loaded successfully")
+        # Note: Environment setup is now handled by the unified config system in utils/config.py
 
         # 2. Database initialization
         try:
-            from backend.database.init_db import main as init_db_main
+            from backend.database.init_db import init_database
             logger.info("🗄️  Initializing the database...")
-            _orig_argv = sys.argv.copy()
-            sys.argv = [sys.argv[0]]  # clear extra flags for init_db parser
-            try:
-                init_db_main()
-            finally:
-                sys.argv = _orig_argv
+            init_database(reset=False, force=False)
             logger.info("✅ Database initialization complete")
         except Exception as e:
             logger.error(f"Database initialization failed: {e}")
@@ -290,14 +291,21 @@ def main():
     
     # Environment setup
     if args.setup:
-        from setup_env import setup_environment
-        setup_environment()
+        logger.info("🔧 Environment setup...")
+        logger.info("✅ Environment configuration is handled by the unified config system")
+        logger.info("💡 Configuration is automatically loaded from .env file or environment variables")
+        logger.info("📝 See .env.example for available configuration options")
         return
     
     # Initialize database
     if args.init_db:
-        from backend.database.init_db import main as init_db_main
-        init_db_main()
+        from backend.database.init_db import init_database
+        try:
+            logger.info("🗄️  Initializing database...")
+            init_database(reset=False, force=False)
+            logger.info("✅ Database initialization complete")
+        except Exception as e:
+            logger.error(f"❌ Database initialization failed: {e}")
         return
     
     # Start full-stack development environment

pyproject.toml

@@ -66,10 +66,6 @@ dependencies = [
     "datasets>=3.6.0",           # 🟡 HF数据集 (1 使用)
 ]
 
-# ❌ 已移除的依赖项 (节省约500MB+):
-# "bottleneck>=1.3,<2.0.0",     # ❌ 未使用 (0次导入)
-# "pydot>=3.0.4",               # ❌ 未使用 (0次导入) 
-# "openai-agents==0.2.4",       # ❌ 未使用 (0次导入)
 
 [project.urls]
 "Homepage" = "https://github.com/981526092/agent-graph"

setup.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+
+# AgentGraph Quick Setup Script
+# This script automates the setup process for AgentGraph
+
+set -e  # Exit on any error
+
+echo "🕸️ AgentGraph Quick Setup"
+echo "=========================="
+echo
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Helper functions
+print_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+print_info() {
+    echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+print_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Check if running in correct directory
+if [ ! -f "main.py" ] || [ ! -f "pyproject.toml" ]; then
+    print_error "Please run this script from the AgentGraph root directory"
+    exit 1
+fi
+
+# Function to check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Function to prompt for OpenAI API key
+setup_env_file() {
+    print_info "Setting up environment configuration..."
+    
+    if [ ! -f ".env" ]; then
+        if [ -f ".env.example" ]; then
+            cp .env.example .env
+            print_success "Created .env file from .env.example"
+        else
+            print_error ".env.example file not found"
+            exit 1
+        fi
+    else
+        print_info ".env file already exists, checking configuration..."
+    fi
+    
+    # Check if OPENAI_API_KEY is set
+    if grep -q "^OPENAI_API_KEY=your_openai_api_key_here" .env || grep -q "^OPENAI_API_KEY=$" .env; then
+        print_warning "OpenAI API key is not configured"
+        echo
+        echo "Please enter your OpenAI API key (starts with 'sk-'):"
+        echo "You can get one at: https://platform.openai.com/account/api-keys"
+        read -p "OpenAI API Key: " openai_key
+        
+        if [ -n "$openai_key" ]; then
+            # Update the API key in .env file
+            if [[ "$OSTYPE" == "darwin"* ]]; then
+                # macOS
+                sed -i '' "s/^OPENAI_API_KEY=.*/OPENAI_API_KEY=$openai_key/" .env
+            else
+                # Linux
+                sed -i "s/^OPENAI_API_KEY=.*/OPENAI_API_KEY=$openai_key/" .env
+            fi
+            print_success "OpenAI API key configured"
+        else
+            print_warning "No API key provided. You can set it later in the .env file"
+        fi
+    else
+        print_success "OpenAI API key is already configured"
+    fi
+}
+
+# Function to setup and run with Docker
+setup_docker() {
+    print_info "Setting up AgentGraph with Docker..."
+    
+    # Check if Docker is installed
+    if ! command_exists docker; then
+        print_error "Docker is not installed. Please install Docker first:"
+        echo "  - macOS: https://docs.docker.com/desktop/mac/"
+        echo "  - Linux: https://docs.docker.com/engine/install/"
+        echo "  - Windows: https://docs.docker.com/desktop/windows/"
+        exit 1
+    fi
+    
+    # Check if Docker is running
+    if ! docker info > /dev/null 2>&1; then
+        print_error "Docker is not running. Please start Docker and try again."
+        exit 1
+    fi
+    
+    print_success "Docker is available"
+    
+    # Setup environment file
+    setup_env_file
+    
+    print_info "Building Docker image (this may take a few minutes)..."
+    if docker build -t agentgraph . > /dev/null 2>&1; then
+        print_success "Docker image built successfully"
+    else
+        print_error "Failed to build Docker image"
+        exit 1
+    fi
+    
+    # Stop existing container if running
+    if docker ps -q -f name=agentgraph-app > /dev/null 2>&1; then
+        print_info "Stopping existing AgentGraph container..."
+        docker stop agentgraph-app > /dev/null 2>&1
+        docker rm agentgraph-app > /dev/null 2>&1
+        print_success "Existing container stopped"
+    fi
+    
+    print_info "Starting AgentGraph container..."
+    if docker run -d --name agentgraph-app -p 7860:7860 --env-file .env agentgraph > /dev/null 2>&1; then
+        print_success "AgentGraph container started successfully"
+    else
+        print_error "Failed to start container"
+        exit 1
+    fi
+    
+    # Wait a moment for startup
+    sleep 5
+    
+    # Check if the service is healthy
+    print_info "Checking service health..."
+    for i in {1..30}; do
+        if curl -s http://localhost:7860/api/observability/health-check > /dev/null 2>&1; then
+            print_success "AgentGraph is running and healthy!"
+            break
+        fi
+        if [ $i -eq 30 ]; then
+            print_warning "Service health check timed out, but container is running"
+            break
+        fi
+        sleep 2
+    done
+    
+    echo
+    print_success "🎉 AgentGraph Setup Complete!"
+    echo
+    echo "🌐 Access AgentGraph at: http://localhost:7860"
+    echo "📚 API Documentation: http://localhost:7860/docs"
+    echo
+    echo "💡 Useful commands:"
+    echo "  - View logs: docker logs agentgraph-app"
+    echo "  - Stop: docker stop agentgraph-app"
+    echo "  - Restart: docker restart agentgraph-app"
+    echo
+}
+
+# Function to setup for local development
+setup_local() {
+    print_info "Setting up AgentGraph for local development..."
+    
+    # Setup environment file
+    setup_env_file
+    
+    # Check Python version
+    if command_exists python3; then
+        python_cmd="python3"
+    elif command_exists python; then
+        python_cmd="python"
+    else
+        print_error "Python is not installed. Please install Python 3.11+ first."
+        exit 1
+    fi
+    
+    print_success "Python is available"
+    
+    print_info "Running AgentGraph setup..."
+    if $python_cmd main.py --first-run; then
+        print_success "Local development setup completed!"
+    else
+        print_error "Setup failed. Please check the error messages above."
+        exit 1
+    fi
+}
+
+# Main setup logic
+echo "Choose your setup method:"
+echo "1) Docker (Recommended - Easy and isolated)"
+echo "2) Local Development (For development work)"
+echo
+read -p "Enter your choice (1 or 2): " choice
+
+case $choice in
+    1)
+        setup_docker
+        ;;
+    2)
+        setup_local
+        ;;
+    *)
+        print_error "Invalid choice. Please run the script again and choose 1 or 2."
+        exit 1
+        ;;
+esac

utils/config.py

@@ -2,9 +2,35 @@ import os
 from pathlib import Path
 from dotenv import load_dotenv
 
-# Load environment variables from .env file
-env_path = Path('.') / '.env'
-load_dotenv(dotenv_path=env_path)
+def load_environment_variables():
+    """
+    Load environment variables with proper priority:
+    1. System environment variables (highest priority - for production/HF Spaces)
+    2. .env file (fallback for local development)
+    """
+    # First check if we're in a production environment (HF Spaces, Docker, etc.)
+    # by looking for common production indicators
+    is_production = any([
+        os.getenv("SPACE_ID"),  # Hugging Face Spaces
+        os.getenv("RENDER"),    # Render.com
+        os.getenv("RAILWAY_ENVIRONMENT"),  # Railway
+        os.getenv("VERCEL"),    # Vercel
+        os.getenv("KUBERNETES_SERVICE_HOST"),  # Kubernetes
+        os.getenv("AWS_LAMBDA_FUNCTION_NAME"),  # AWS Lambda
+    ])
+    
+    # Load .env file only if not in production AND file exists
+    env_path = Path('.') / '.env'
+    if not is_production and env_path.exists():
+        print(f"🔧 Loading environment variables from {env_path}")
+        load_dotenv(dotenv_path=env_path, override=False)  # Don't override existing env vars
+    elif is_production:
+        print("🚀 Production environment detected, using system environment variables")
+    else:
+        print("⚠️ No .env file found and not in production environment")
+
+# Load environment variables using the unified method
+load_environment_variables()
 
 # OpenAI Configuration
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
@@ -40,8 +66,51 @@ def validate_config():
     
     if missing_vars:
         missing_vars_str = ", ".join(missing_vars)
-        print(f"Missing required environment variables: {missing_vars_str}")
-        print(f"Please set them in the .env file or as environment variables")
+        print(f"❌ Missing required environment variables: {missing_vars_str}")
+        print(f"📝 Please set them in the .env file or as environment variables")
         return False
     
-    return True 
+    return True
+
+def debug_config():
+    """Debug function to show current configuration state"""
+    print("🔍 AgentGraph Configuration Debug:")
+    print("=" * 50)
+    
+    # Show environment loading method
+    env_path = Path('.') / '.env'
+    is_production = any([
+        os.getenv("SPACE_ID"),
+        os.getenv("RENDER"),
+        os.getenv("RAILWAY_ENVIRONMENT"),
+        os.getenv("VERCEL"),
+        os.getenv("KUBERNETES_SERVICE_HOST"),
+        os.getenv("AWS_LAMBDA_FUNCTION_NAME"),
+    ])
+    
+    print(f"🏗️ Environment: {'Production' if is_production else 'Development'}")
+    print(f"📁 .env file exists: {env_path.exists()}")
+    print(f"📍 Working directory: {Path.cwd()}")
+    print()
+    
+    # Show key configuration values (masked)
+    configs = [
+        ("OPENAI_API_KEY", OPENAI_API_KEY),
+        ("OPENAI_MODEL_NAME", OPENAI_MODEL_NAME),
+        ("LANGFUSE_PUBLIC_KEY", LANGFUSE_PUBLIC_KEY),
+        ("LANGFUSE_SECRET_KEY", LANGFUSE_SECRET_KEY),
+        ("LANGFUSE_HOST", LANGFUSE_HOST),
+        ("DB_URI", DB_URI),
+    ]
+    
+    for name, value in configs:
+        if value:
+            if "KEY" in name or "SECRET" in name:
+                masked = f"{value[:8]}..." if len(value) > 8 else "***"
+                print(f"✅ {name}: {masked}")
+            else:
+                print(f"✅ {name}: {value}")
+        else:
+            print(f"❌ {name}: Not set")
+    
+    print("=" * 50)