1 line
62 KiB
JSON
1 line
62 KiB
JSON
{"repo": "ajay-v11/radar-backend", "files": {"docs/README.md": {"dc749146028cab88c19d858a587f408dae52f607": {"t": 1785746452.2074451, "n": 7916, "h": "ec8f3c6c2bad30d5", "c": "# Documentation\n\n## Overview\n\nTwo-phase workflow with LangGraph agents for analyzing company visibility across AI models.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n| Document | Description |\n| ---------------------------------------------------------------- | ------------------------------------------ |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design, data flow, caching strategy |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | API reference with examples |\n| [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) | LLM provider setup |\n| [API_STREAMING_STRUCTURE.md](./API_STREAMING_STRUCTURE.md) | SSE streaming format |\n| [CSV_EXPORT.md](./CSV_EXPORT.md) | CSV export feature |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent (LangGraph - 9 nodes)\n\nPhase 2: Visibility Analysis\n └─> Visibility Orchestrator (7 nodes with looping)\n ├─> Query Generator (per category)\n ├─> AI Model Tester (parallel)\n └─> Scorer Analyzer (hybrid matching)\n```\n\n### Key Features\n\n- **LangGraph Workflows**: Modular, observable agent workflows\n- **Slug-Based Caching**: Simple route-level caching (24hr TTL)\n- **Hybrid Matching**: Exact + semantic via ChromaDB\n- **Category-Based Batching**: Progressive results per category\n- **SSE Streaming**: Real-time progress updates\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\"company_url\": \"https://hellofresh.com\"}'\n# Returns: slug_id (e.g., \"company_abc123\")\n```\n\n### Phase 2: Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_slug_id\": \"company_abc123\",\n \"num_queries\": 20,\n \"models\": [\"llama\", \"gemini\"]\n }'\n# Returns: SSE stream with visibility_score, model_scores, category_breakdown\n```\n\n## Performance\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ---------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n\n**Cost Optimization**: 70% savings with 4-level caching\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Model Name |\n| -------- | ---------- | -------- | ------------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-5-haiku-20241022 |\n| Llama | Groq | **FREE** | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | **FREE** | deepseek-chat-v3 |\n\n## Dynamic Industry Classification\n\nNo hardcoded industries - LLM generates specific classifications (e.g., \"AI-Powered Meal Kit Delivery\" not \"food_services\")\n\n## Caching Strategy\n\n### Slug-Based Caching\n\n| Phase | Slug Format | TTL |\n| ------- | ------------------------------------------------- | ---- |\n| Phase 1 | `company_{hash(url + region)}` | 24hr |\n| Phase 2 | `visibility_{hash(url + queries + models + llm)}` | 24hr |\n\n**Cache Behavior:**\n\n- Same params → Instant results (10-50ms)\n- Different params → New analysis, new slug_id\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# LLM Provider\nINDUSTRY_ANALYSIS_PROVIDER=claude # claude, gemini, llama, openai\nQUERY_GENERATION_PROVIDER=claude\n\n# API Keys (at least one required)\nANTHROPIC_API_KEY=sk-ant-... # Claude\nGROK_API_KEY=gsk_... # Llama (FREE)\nGEMINI_API_KEY=... # Gemini\nFIRECRAWL_API_KEY=... # Required\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\nSee [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) for details.\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Project Structure\n\n```\n.\n├── agents/ # LangGraph agents\n│ ├── industry_detection_agent/ # Agent 1\n│ ├── query_generator_agent/ # Agent 2\n│ ├── ai_model_tester_agent/ # Agent 3\n│ ├── scorer_analyzer_agent/ # Agent 4\n│ └── visibility_orchestrator/ # Orchestrator\n├── src/\n│ ├── app.py # FastAPI app\n│ ├── routes/ # API routes\n│ └── controllers/ # Business logic\n├── config/ # Configuration\n├── storage/ # RAG store\n├── models/ # Data models\n├── tests/ # Tests\n└── docs/ # Documentation\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](./ARCHITECTURE.md) - System design\n- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - API reference\n- [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) - LLM setup\n- [AGENTS.md](../AGENTS.md) - Agent workflows\n"}, "14a21d7e770a482d0d45c1f4afbe0d5e4354918a": {"t": 1785764398.8921347, "n": 7916, "h": "ec8f3c6c2bad30d5", "c": "# Documentation\n\n## Overview\n\nTwo-phase workflow with LangGraph agents for analyzing company visibility across AI models.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n| Document | Description |\n| ---------------------------------------------------------------- | ------------------------------------------ |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design, data flow, caching strategy |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | API reference with examples |\n| [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) | LLM provider setup |\n| [API_STREAMING_STRUCTURE.md](./API_STREAMING_STRUCTURE.md) | SSE streaming format |\n| [CSV_EXPORT.md](./CSV_EXPORT.md) | CSV export feature |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent (LangGraph - 9 nodes)\n\nPhase 2: Visibility Analysis\n └─> Visibility Orchestrator (7 nodes with looping)\n ├─> Query Generator (per category)\n ├─> AI Model Tester (parallel)\n └─> Scorer Analyzer (hybrid matching)\n```\n\n### Key Features\n\n- **LangGraph Workflows**: Modular, observable agent workflows\n- **Slug-Based Caching**: Simple route-level caching (24hr TTL)\n- **Hybrid Matching**: Exact + semantic via ChromaDB\n- **Category-Based Batching**: Progressive results per category\n- **SSE Streaming**: Real-time progress updates\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\"company_url\": \"https://hellofresh.com\"}'\n# Returns: slug_id (e.g., \"company_abc123\")\n```\n\n### Phase 2: Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_slug_id\": \"company_abc123\",\n \"num_queries\": 20,\n \"models\": [\"llama\", \"gemini\"]\n }'\n# Returns: SSE stream with visibility_score, model_scores, category_breakdown\n```\n\n## Performance\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ---------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n\n**Cost Optimization**: 70% savings with 4-level caching\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Model Name |\n| -------- | ---------- | -------- | ------------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-5-haiku-20241022 |\n| Llama | Groq | **FREE** | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | **FREE** | deepseek-chat-v3 |\n\n## Dynamic Industry Classification\n\nNo hardcoded industries - LLM generates specific classifications (e.g., \"AI-Powered Meal Kit Delivery\" not \"food_services\")\n\n## Caching Strategy\n\n### Slug-Based Caching\n\n| Phase | Slug Format | TTL |\n| ------- | ------------------------------------------------- | ---- |\n| Phase 1 | `company_{hash(url + region)}` | 24hr |\n| Phase 2 | `visibility_{hash(url + queries + models + llm)}` | 24hr |\n\n**Cache Behavior:**\n\n- Same params → Instant results (10-50ms)\n- Different params → New analysis, new slug_id\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# LLM Provider\nINDUSTRY_ANALYSIS_PROVIDER=claude # claude, gemini, llama, openai\nQUERY_GENERATION_PROVIDER=claude\n\n# API Keys (at least one required)\nANTHROPIC_API_KEY=sk-ant-... # Claude\nGROK_API_KEY=gsk_... # Llama (FREE)\nGEMINI_API_KEY=... # Gemini\nFIRECRAWL_API_KEY=... # Required\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\nSee [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) for details.\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Project Structure\n\n```\n.\n├── agents/ # LangGraph agents\n│ ├── industry_detection_agent/ # Agent 1\n│ ├── query_generator_agent/ # Agent 2\n│ ├── ai_model_tester_agent/ # Agent 3\n│ ├── scorer_analyzer_agent/ # Agent 4\n│ └── visibility_orchestrator/ # Orchestrator\n├── src/\n│ ├── app.py # FastAPI app\n│ ├── routes/ # API routes\n│ └── controllers/ # Business logic\n├── config/ # Configuration\n├── storage/ # RAG store\n├── models/ # Data models\n├── tests/ # Tests\n└── docs/ # Documentation\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](./ARCHITECTURE.md) - System design\n- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - API reference\n- [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) - LLM setup\n- [AGENTS.md](../AGENTS.md) - Agent workflows\n"}, "08484a071e35ab3ce1ca02067b8ffc8ef3352aaf": {"t": 1785764400.2727685, "n": 7916, "h": "cc38fd24c579a99e", "c": "# Documentation\n\n## Overview\n\nTwo-phase workflow with LangGraph agents for analyzing company visibility across AI models.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n| Document | Description |\n| ---------------------------------------------------------------- | ------------------------------------------ |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design, data flow, caching strategy |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | API reference with examples |\n| [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) | LLM provider setup |\n| [API_STREAMING_STRUCTURE.md](./API_STREAMING_STRUCTURE.md) | SSE streaming format |\n| [CSV_EXPORT.md](./CSV_EXPORT.md) | CSV export feature |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent (LangGraph - 9 nodes)\n\nPhase 2: Visibility Analysis\n └─> Visibility Orchestrator (7 nodes with looping)\n ├─> Query Generator (per category)\n ├─> AI Model Tester (parallel)\n └─> Scorer Analyzer (hybrid matching)\n```\n\n### Key Features\n\n- **LangGraph Workflows**: Modular, observable agent workflows\n- **Slug-Based Caching**: Simple route-level caching (24hr TTL)\n- **Hybrid Matching**: Exact + semantic via ChromaDB\n- **Category-Based Batching**: Progressive results per category\n- **SSE Streaming**: Real-time progress updates\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\"company_url\": \"https://hellofresh.com\"}'\n# Returns: slug_id (e.g., \"company_abc123\")\n```\n\n### Phase 2: Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_slug_id\": \"company_abc123\",\n \"num_queries\": 20,\n \"models\": [\"llama\", \"gemini\"]\n }'\n# Returns: SSE stream with visibility_score, model_scores, category_breakdown\n```\n\n## Performance\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ---------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n\n**Cost Optimization**: 70% savings with 4-level caching\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Model Name |\n| -------- | ---------- | -------- | ------------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-5-haiku-20241022 |\n| Llama | Groq | **FREE** | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | **FREE** | deepseek-chat-v3 |\n\n## Dynamic Industry Classification\n\nNo hardcoded industries - LLM generates specific classifications (e.g., \"AI-Powered Meal Kit Delivery\" not \"food_services\")\n\n## Caching Strategy\n\n### Slug-Based Caching\n\n| Phase | Slug Format | TTL |\n| ------- | ------------------------------------------------- | ---- |\n| Phase 1 | `company_{hash(url + region)}` | 24hr |\n| Phase 2 | `visibility_{hash(url + queries + models + llm)}` | 24hr |\n\n**Cache Behavior:**\n\n- Same params → Instant results (10-50ms)\n- Different params → New analysis, new slug_id\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# LLM Provider\nINDUSTRY_ANALYSIS_PROVIDER=openai # claude, gemini, llama, openai\nQUERY_GENERATION_PROVIDER=claude\n\n# API Keys (at least one required)\nANTHROPIC_API_KEY=sk-ant-... # Claude\nGROK_API_KEY=gsk_... # Llama (FREE)\nGEMINI_API_KEY=... # Gemini\nFIRECRAWL_API_KEY=... # Required\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\nSee [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) for details.\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Project Structure\n\n```\n.\n├── agents/ # LangGraph agents\n│ ├── industry_detection_agent/ # Agent 1\n│ ├── query_generator_agent/ # Agent 2\n│ ├── ai_model_tester_agent/ # Agent 3\n│ ├── scorer_analyzer_agent/ # Agent 4\n│ └── visibility_orchestrator/ # Orchestrator\n├── src/\n│ ├── app.py # FastAPI app\n│ ├── routes/ # API routes\n│ └── controllers/ # Business logic\n├── config/ # Configuration\n├── storage/ # RAG store\n├── models/ # Data models\n├── tests/ # Tests\n└── docs/ # Documentation\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](./ARCHITECTURE.md) - System design\n- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - API reference\n- [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) - LLM setup\n- [AGENTS.md](../AGENTS.md) - Agent workflows\n"}, "696616b5f38eb2e7b38884974a9d2940dd80cc02": {"t": 1785764402.498573, "n": 7916, "h": "ec8f3c6c2bad30d5", "c": "# Documentation\n\n## Overview\n\nTwo-phase workflow with LangGraph agents for analyzing company visibility across AI models.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n| Document | Description |\n| ---------------------------------------------------------------- | ------------------------------------------ |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design, data flow, caching strategy |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | API reference with examples |\n| [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) | LLM provider setup |\n| [API_STREAMING_STRUCTURE.md](./API_STREAMING_STRUCTURE.md) | SSE streaming format |\n| [CSV_EXPORT.md](./CSV_EXPORT.md) | CSV export feature |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent (LangGraph - 9 nodes)\n\nPhase 2: Visibility Analysis\n └─> Visibility Orchestrator (7 nodes with looping)\n ├─> Query Generator (per category)\n ├─> AI Model Tester (parallel)\n └─> Scorer Analyzer (hybrid matching)\n```\n\n### Key Features\n\n- **LangGraph Workflows**: Modular, observable agent workflows\n- **Slug-Based Caching**: Simple route-level caching (24hr TTL)\n- **Hybrid Matching**: Exact + semantic via ChromaDB\n- **Category-Based Batching**: Progressive results per category\n- **SSE Streaming**: Real-time progress updates\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\"company_url\": \"https://hellofresh.com\"}'\n# Returns: slug_id (e.g., \"company_abc123\")\n```\n\n### Phase 2: Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_slug_id\": \"company_abc123\",\n \"num_queries\": 20,\n \"models\": [\"llama\", \"gemini\"]\n }'\n# Returns: SSE stream with visibility_score, model_scores, category_breakdown\n```\n\n## Performance\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ---------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n\n**Cost Optimization**: 70% savings with 4-level caching\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Model Name |\n| -------- | ---------- | -------- | ------------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-5-haiku-20241022 |\n| Llama | Groq | **FREE** | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | **FREE** | deepseek-chat-v3 |\n\n## Dynamic Industry Classification\n\nNo hardcoded industries - LLM generates specific classifications (e.g., \"AI-Powered Meal Kit Delivery\" not \"food_services\")\n\n## Caching Strategy\n\n### Slug-Based Caching\n\n| Phase | Slug Format | TTL |\n| ------- | ------------------------------------------------- | ---- |\n| Phase 1 | `company_{hash(url + region)}` | 24hr |\n| Phase 2 | `visibility_{hash(url + queries + models + llm)}` | 24hr |\n\n**Cache Behavior:**\n\n- Same params → Instant results (10-50ms)\n- Different params → New analysis, new slug_id\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# LLM Provider\nINDUSTRY_ANALYSIS_PROVIDER=claude # claude, gemini, llama, openai\nQUERY_GENERATION_PROVIDER=claude\n\n# API Keys (at least one required)\nANTHROPIC_API_KEY=sk-ant-... # Claude\nGROK_API_KEY=gsk_... # Llama (FREE)\nGEMINI_API_KEY=... # Gemini\nFIRECRAWL_API_KEY=... # Required\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\nSee [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) for details.\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Project Structure\n\n```\n.\n├── agents/ # LangGraph agents\n│ ├── industry_detection_agent/ # Agent 1\n│ ├── query_generator_agent/ # Agent 2\n│ ├── ai_model_tester_agent/ # Agent 3\n│ ├── scorer_analyzer_agent/ # Agent 4\n│ └── visibility_orchestrator/ # Orchestrator\n├── src/\n│ ├── app.py # FastAPI app\n│ ├── routes/ # API routes\n│ └── controllers/ # Business logic\n├── config/ # Configuration\n├── storage/ # RAG store\n├── models/ # Data models\n├── tests/ # Tests\n└── docs/ # Documentation\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](./ARCHITECTURE.md) - System design\n- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - API reference\n- [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) - LLM setup\n- [AGENTS.md](../AGENTS.md) - Agent workflows\n"}, "ce8075e3e5c7702d116f23b4d2f13541676f924b": {"t": 1785764404.0283706, "n": 7940, "h": "bc33ba83d5f705ae", "c": "# Documentation\n\n## Overview\n\nTwo-phase workflow with LangGraph agents for analyzing company visibility across AI models.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n| Document | Description |\n| ---------------------------------------------------------------- | ------------------------------------------ |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | System design, data flow, caching strategy |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | API reference with examples |\n| [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) | LLM provider setup |\n| [API_STREAMING_STRUCTURE.md](./API_STREAMING_STRUCTURE.md) | SSE streaming format |\n| [CSV_EXPORT.md](./CSV_EXPORT.md) | CSV export feature |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent (LangGraph - 9 nodes)\n\nPhase 2: Visibility Analysis\n └─> Visibility Orchestrator (LangGraph - 7 nodes)\n ├─> Query Generator (per category)\n ├─> AI Model Tester (parallel)\n └─> Scorer Analyzer (hybrid matching)\n```\n\n### Key Features\n\n- **LangGraph Workflows**: Modular, observable agent workflows\n- **4-Level Caching**: Scraping (24hr), Industry (24hr), Queries (24hr), Responses (1hr)\n- **Hybrid Matching**: Exact + semantic via ChromaDB\n- **Category-Based Batching**: Progressive results per category\n- **SSE Streaming**: Real-time progress updates\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\"company_url\": \"https://hellofresh.com\"}'\n# Returns: slug_id (e.g., \"company_abc123\")\n```\n\n### Phase 2: Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_slug_id\": \"company_abc123\",\n \"num_queries\": 20,\n \"models\": [\"llama\", \"gemini\"]\n }'\n# Returns: SSE stream with visibility_score, model_scores, category_breakdown\n```\n\n## Performance\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ---------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n\n**Cost Optimization**: 70% savings with 4-level caching\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Model Name |\n| -------- | ---------- | -------- | ------------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-5-haiku-20241022 |\n| Llama | Groq | **FREE** | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | **FREE** | deepseek-chat-v3 |\n\n## Dynamic Industry Classification\n\nNo hardcoded industries - LLM generates specific classifications (e.g., \"AI-Powered Meal Kit Delivery\" not \"food_services\")\n\n## Caching Strategy\n\n### Slug-Based Caching\n\n| Phase | Slug Format | TTL |\n| ------- | ------------------------------------------------- | ---- |\n| Phase 1 | `company_{hash(url + region)}` | 24hr |\n| Phase 2 | `visibility_{hash(url + queries + models + llm)}` | 24hr |\n\n**Cache Behavior:**\n\n- Same params → Instant results (10-50ms)\n- Different params → New analysis, new slug_id\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# LLM Provider\nINDUSTRY_ANALYSIS_PROVIDER=claude # claude, gemini, llama, openai\nQUERY_GENERATION_PROVIDER=claude\n\n# API Keys (at least one required)\nANTHROPIC_API_KEY=sk-ant-... # Claude\nGROK_API_KEY=gsk_... # Llama (FREE)\nGEMINI_API_KEY=... # Gemini\nFIRECRAWL_API_KEY=... # Required\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\nSee [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) for details.\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Project Structure\n\n```\n.\n├── agents/ # LangGraph agents\n│ ├── industry_detection_agent/ # Agent 1\n│ ├── query_generator_agent/ # Agent 2\n│ ├── ai_model_tester_agent/ # Agent 3\n│ ├── scorer_analyzer_agent/ # Agent 4\n│ └── visibility_orchestrator/ # Orchestrator\n├── src/\n│ ├── app.py # FastAPI app\n│ ├── routes/ # API routes\n│ └── controllers/ # Business logic\n├── config/ # Configuration\n├── storage/ # RAG store\n├── models/ # Data models\n├── tests/ # Tests\n└── docs/ # Documentation\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](./ARCHITECTURE.md) - System design\n- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - API reference\n- [LLM_PROVIDER_CONFIGURATION.md](./LLM_PROVIDER_CONFIGURATION.md) - LLM setup\n- [AGENTS.md](../AGENTS.md) - Agent workflows\n"}, "be42922d14fff1152755a35fe7e81caa26f7b0b7": {"t": 1785764405.9646382, "n": 10577, "h": "c481ae6868b689b8", "c": "# AI Visibility Scoring System - Documentation\n\n## Overview\n\nThe AI Visibility Scoring System analyzes how frequently companies are mentioned by AI models when users search for industry-related queries. The system uses a two-phase workflow with intelligent multi-level caching to provide fast, accurate visibility scores.\n\n## Quick Start\n\n### 1. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis starts:\n\n- **ChromaDB** on port 8001 (vector database)\n- **Redis** on port 6379 (cache)\n\n### 2. Configure Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-...\nFIRECRAWL_API_KEY=...\n\n# Optional (for additional AI models)\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n```\n\n### 3. Run Server\n\n```bash\npython run_server.py\n```\n\nOr with auto-reload:\n\n```bash\nuvicorn src.app:app --reload\n```\n\n### 4. Access API\n\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n## Documentation Structure\n\n### Core Documentation\n\n| Document | Description |\n| -------------------------------------- | ----------------------------------------------------------- |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | High-level system architecture, data flow, technology stack |\n| [ORCHESTRATION.md](./ORCHESTRATION.md) | Workflow orchestration, agent coordination, flow diagrams |\n| [API_ENDPOINTS.md](./API_ENDPOINTS.md) | Complete API reference with examples |\n\n### Agent Documentation\n\n| Agent | Document | Purpose |\n| ------- | ---------------------------------------------------------- | ------------------------------------------------------------ |\n| Agent 1 | [AGENT_INDUSTRY_DETECTOR.md](./AGENT_INDUSTRY_DETECTOR.md) | Web scraping, industry classification, competitor extraction |\n| Agent 2 | [AGENT_QUERY_GENERATOR.md](./AGENT_QUERY_GENERATOR.md) | Industry-specific query generation with LLM |\n| Agent 3 | [AGENT_AI_MODEL_TESTER.md](./AGENT_AI_MODEL_TESTER.md) | Testing queries across multiple AI models |\n| Agent 4 | [AGENT_SCORER_ANALYZER.md](./AGENT_SCORER_ANALYZER.md) | Hybrid mention detection and visibility scoring |\n\n## System Architecture\n\n### Two-Phase Workflow\n\n```\nPhase 1: Company Analysis\n └─> Industry Detector Agent\n └─> Output: Company profile with competitors\n\nPhase 2: Complete Visibility Flow\n ├─> Industry Detector (reuses Phase 1 cache)\n ├─> Query Generator\n ├─> AI Model Tester (parallel batches)\n └─> Scorer Analyzer\n └─> Output: Visibility score + detailed report\n```\n\n### Key Features\n\n- **Multi-Level Caching**: 4 cache layers (industry, queries, responses, complete flow)\n- **Smart Caching**: Granular cache keys for optimal reuse\n- **Hybrid Matching**: Exact + semantic mention detection\n- **Parallel Processing**: Batch testing for efficiency\n- **Streaming Updates**: Real-time progress via SSE\n\n## API Usage\n\n### Phase 1: Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze/company \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_url\": \"https://hellofresh.com\",\n \"company_name\": \"HelloFresh\"\n }'\n```\n\n**Response (cached)**:\n\n```json\n{\n \"cached\": true,\n \"data\": {\n \"industry\": \"food_services\",\n \"company_name\": \"HelloFresh\",\n \"competitors\": [\"Blue Apron\", \"Home Chef\", \"Sun Basket\"],\n \"company_description\": \"...\",\n \"company_summary\": \"...\"\n }\n}\n```\n\n### Phase 2: Complete Visibility Analysis\n\n```bash\ncurl -X POST http://localhost:8000/analyze/visibility \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_url\": \"https://hellofresh.com\",\n \"num_queries\": 20,\n \"models\": [\"chatgpt\", \"gemini\"],\n \"llm_provider\": \"gemini\",\n \"batch_size\": 5\n }'\n```\n\n**Response**: Server-Sent Events stream with real-time progress\n\n## Performance\n\n### Latency\n\n| Scenario | Phase 1 | Phase 2 | Total |\n| ------------- | ------- | ------- | -------- |\n| Cold cache | 5-10s | 30-60s | 35-70s |\n| Warm cache | 10-50ms | 10-50ms | 20-100ms |\n| Partial cache | 2-3s | 15-40s | 17-43s |\n\n### Cost Optimization\n\n- **Without caching**: ~$0.10-0.50 per analysis\n- **With caching**: ~$0.03-0.15 per analysis (70% savings)\n\n## Technology Stack\n\n- **Backend**: FastAPI (Python 3.11+)\n- **LLMs**: OpenAI (gpt-4-mini), Gemini, Claude, Llama\n- **Vector DB**: ChromaDB (semantic search)\n- **Cache**: Redis (multi-level caching)\n- **Web Scraping**: Firecrawl (markdown extraction)\n- **Embeddings**: OpenAI text-embedding-ada-002\n\n## Supported AI Models\n\n| Model | Provider | Cost | Notes |\n| -------- | ---------- | -------- | --------------------- |\n| ChatGPT | OpenAI | Low | gpt-3.5-turbo |\n| Gemini | Google | Very Low | gemini-2.5-flash-lite |\n| Claude | Anthropic | Low | claude-3-haiku |\n| Llama | Groq | Free | llama-3.1-8b-instant |\n| Grok | OpenRouter | Low | grok-4.1-fast |\n| DeepSeek | OpenRouter | Free | deepseek-chat-v3 |\n\n## Supported Industries\n\n1. **technology**: Software, SaaS, AI, cloud, apps, IT services\n2. **retail**: E-commerce, stores, fashion, consumer goods\n3. **healthcare**: Medical services, pharmaceuticals, biotech\n4. **finance**: Banking, fintech, payments, insurance\n5. **food_services**: Restaurants, meal delivery, catering\n6. **other**: Default fallback category\n\n## Caching Strategy\n\n### Cache Layers\n\n| Layer | Key | TTL | Purpose |\n| ----------------- | ---------------------------- | ---- | ------------------------ |\n| Industry Analysis | `company_url` | 24hr | Complete company profile |\n| Queries | `url+industry+count` | 24hr | Generated queries |\n| Model Responses | `query+model` | 1hr | Individual AI responses |\n| Complete Flow | `url+queries+models+weights` | 24hr | Final aggregated results |\n\n### Cache Behavior\n\n**Same everything** → Instant cached results (~10-50ms)\n**Only models changed** → Reuses queries, re-runs tests\n**Only num_queries changed** → Reuses industry, regenerates queries\n**Query weights changed** → Re-runs everything (future feature)\n\n## Database Setup\n\n### ChromaDB (Vector Store)\n\n```bash\n# Runs on port 8001\ndocker-compose up chromadb -d\n\n# Test connection\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Collections**:\n\n- `companies`: Company profiles with embeddings\n- `competitors`: Competitor data with rich metadata\n\n### Redis (Cache)\n\n```bash\n# Runs on port 6379\ndocker-compose up redis -d\n\n# Test connection\nredis-cli ping # Should return PONG\n```\n\n## Testing\n\n### Run All Tests\n\n```bash\npytest tests/ -v\n```\n\n### Test Individual Agents\n\n```bash\npytest tests/agents/test_industry_detector.py -v\npytest tests/agents/test_query_generator.py -v\npytest tests/agents/test_ai_model_tester.py -v\npytest tests/agents/test_scorer_analyzer.py -v\n```\n\n### Integration Tests\n\n```bash\npytest tests/integration/ -v\n```\n\n## Troubleshooting\n\n### ChromaDB Not Connecting\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n### Redis Not Connecting\n\n```bash\ndocker-compose logs redis\nredis-cli ping\n```\n\n### Low Visibility Score\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n- Ensure company name is correct\n\n### Industry Detected as \"other\"\n\n- Check Firecrawl API key is configured\n- Verify website is accessible\n- Provide company_description to skip scraping\n- Review scraped content in logs\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# AI Models\nOPENAI_API_KEY=sk-...\nGEMINI_API_KEY=...\nANTHROPIC_API_KEY=...\nGROK_API_KEY=...\nOPEN_ROUTER_API_KEY=...\n\n# Web Scraping\nFIRECRAWL_API_KEY=...\n\n# Databases\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\n### Settings\n\nEdit `config/settings.py` to customize:\n\n```python\n# Model selection\nINDUSTRY_ANALYSIS_MODEL = \"gpt-4-mini\"\nCHATGPT_MODEL = \"gpt-3.5-turbo\"\nGEMINI_MODEL = \"gemini-2.5-flash-lite\"\n\n# Query generation\nMIN_QUERIES = 20\nMAX_QUERIES = 100\nDEFAULT_NUM_QUERIES = 20\n\n# Caching\nQUERY_CACHE_TTL = 86400 # 24 hours\nSCRAPE_CACHE_TTL = 86400 # 24 hours\n```\n\n## Monitoring\n\n### Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\n### Logs\n\nCheck logs for cache performance:\n\n```\n[INFO] Cache HIT for industry analysis: https://...\n[INFO] Cache HIT for queries: https://... (20 queries)\n[INFO] Cache MISS for complete flow: https://...\n```\n\n### Metrics\n\nTrack in production:\n\n- Cache hit rates (should be >70%)\n- API latency per agent\n- Error rates per model\n- Cost per request\n\n## Development\n\n### Project Structure\n\n```\n.\n├── agents/ # Agent implementations\n│ ├── industry_detector.py\n│ ├── query_generator.py\n│ ├── ai_model_tester.py\n│ └── scorer_analyzer.py\n├── src/\n│ ├── app.py # FastAPI application\n│ └── routes/\n│ ├── health_routes.py\n│ └── analysis_routes.py\n├── config/\n│ ├── settings.py # Configuration\n│ └── database.py # Database connections\n├── utils/ # Utilities\n│ ├── competitor_matcher.py\n│ └── vector_store.py\n├── storage/\n│ └── rag_store.py # Query templates\n├── models/\n│ └── schemas.py # Data models\n├── tests/ # Test suite\n└── docs/ # Documentation\n```\n\n### Adding a New AI Model\n\n1. Add API key to `.env`\n2. Add model config to `config/settings.py`\n3. Implement query function in `agents/ai_model_tester.py`\n4. Update model list in documentation\n\n### Adding a New Industry\n\n1. Add industry to `VALID_INDUSTRIES` in `agents/industry_detector.py`\n2. Add keywords to `INDUSTRY_KEYWORDS`\n3. Add categories to `INDUSTRY_CATEGORIES` in `agents/query_generator.py`\n4. Update documentation\n\n## Support\n\n### Common Issues\n\n- [Troubleshooting Guide](./ARCHITECTURE.md#error-handling)\n- [Agent-Specific Issues](./AGENT_INDUSTRY_DETECTOR.md#common-issues)\n- [API Errors](./API_ENDPOINTS.md#error-handling)\n\n### Documentation\n\n- [Architecture Overview](./ARCHITECTURE.md)\n- [Workflow Orchestration](./ORCHESTRATION.md)\n- [API Reference](./API_ENDPOINTS.md)\n- [Agent Details](./AGENT_INDUSTRY_DETECTOR.md)\n\n## License\n\n[Your License Here]\n\n## Contributing\n\n[Your Contributing Guidelines Here]\n"}, "91aafcf662f74aacd09900232bdea595d2946259": {"t": 1785764408.3909202, "n": 9132, "h": "527978ba5ae7ae1f", "c": "# AI Visibility Scoring System - Documentation\n\n## Quick Start\n\n1. **Start services**: `docker-compose up -d`\n\n - ChromaDB on port 8001\n - Redis on port 6379\n\n2. **Run server**: `python run_server.py` or `uvicorn main:app --reload`\n\n - Databases initialize automatically on startup\n - Check logs for connection status:\n - ✅ ChromaDB: Connected\n - ✅ Redis: Connected\n - ✅ RAGStore initialized with 6 industry templates\n\n3. **API docs**: http://localhost:8000/docs\n\n**Optional**: Test database connections manually with `python scripts/init_databases.py`\n\n### Startup Process\n\nThe server automatically:\n\n1. Initializes RAG Store with query templates\n2. Tests ChromaDB connection and creates collections\n3. Tests Redis connection\n4. Logs status of all services\n5. Continues even if databases are unavailable (with warnings)\n\n## System Architecture\n\nFour agents work sequentially to analyze company visibility:\n\n```\nInput → Industry Detector → Query Generator → AI Model Tester → Scorer Analyzer → Output\n```\n\n### Workflow State\n\nThe workflow state is passed between agents and accumulates data:\n\n```python\n{\n # Input (provided by user)\n \"company_url\": str,\n \"company_name\": str, # Optional\n \"company_description\": str, # Optional\n \"models\": List[str], # Optional, defaults to [\"chatgpt\", \"gemini\"]\n\n # Added by Industry Detector\n \"industry\": str, # Detected category\n \"company_summary\": str, # AI-generated summary\n \"scraped_content\": str, # Raw website content\n \"competitors\": List[str], # Competitor names\n \"competitors_data\": List[Dict], # Rich competitor metadata\n\n # Added by Query Generator\n \"queries\": List[str], # 20 generated queries\n\n # Added by AI Model Tester\n \"model_responses\": Dict[str, List[str]], # {model: [responses]}\n\n # Added by Scorer Analyzer\n \"visibility_score\": float, # 0-100 score\n \"analysis_report\": Dict, # Detailed results with competitor mentions\n\n # Error tracking (all agents)\n \"errors\": List[str] # Non-blocking errors\n}\n```\n\n## Agents\n\n### 1. Industry Detector (`agents/industry_detector.py`)\n\n**Purpose**: Classifies companies into industries using Firecrawl scraping + OpenAI GPT-4o-mini analysis\n\n**Industries**: technology, retail, healthcare, finance, food_services, other\n\n**Process**:\n\n1. Scrapes company website with Firecrawl (markdown format)\n2. Analyzes content with OpenAI to extract:\n - Company name, description, and summary\n - Industry classification\n - 3-5 main competitors with rich metadata (description, products, positioning)\n3. Stores in ChromaDB with embeddings for semantic search\n\n**Features**:\n\n- Redis caching (24hr TTL) - 90% faster on repeated URLs\n- Retry logic (2 attempts for scraping and AI analysis)\n- Stores company + competitors in ChromaDB with rich embeddings\n- Token-optimized (5k chars vs 10k)\n- Fallback to keyword matching if AI analysis fails\n\n### 2. Query Generator (`agents/query_generator.py`)\n\n**Purpose**: Generates 20 industry-specific queries from RAG templates\n\n**Process**:\n\n1. Fetch templates from RAG Store by industry\n2. Randomly sample 20 unique templates\n3. 30% chance to customize with company name for comparison queries\n\n### 3. AI Model Tester (`agents/ai_model_tester.py`)\n\n**Purpose**: Executes queries against AI models\n\n**Supported Models** (cost-optimized):\n\n- ChatGPT (gpt-3.5-turbo)\n- Claude (claude-3-haiku)\n- Gemini (gemini-2.5-flash-lite)\n- Llama (llama-3.1-8b-instant via Groq - FREE)\n- Mistral (mistral-7b-instruct via OpenRouter)\n- Qwen (qwen-2-7b-instruct via OpenRouter)\n\n**Features**:\n\n- Redis caching for responses (1hr TTL)\n- Retry logic (2 attempts per query)\n- Rate limiting (60 calls/min per model)\n- Graceful error handling\n- 70% cost reduction with caching\n\n### 4. Scorer Analyzer (`agents/scorer_analyzer.py`)\n\n**Purpose**: Calculates visibility score and generates report\n\n**Scoring**: `(total_mentions / (queries × models)) × 100`\n\n**Mention Detection** (Hybrid Approach):\n\n1. **Exact String Matching**: Fast, high-precision company name search\n2. **Semantic Matching**: RAG-based competitor detection using ChromaDB\n - Catches variations: \"meal kit service\" → HelloFresh\n - Similarity threshold: 0.70\n - Rich embeddings: name + description + products + positioning\n\n**Features**:\n\n- Hybrid exact + semantic matching for best accuracy\n- Competitor mention tracking per model\n- Per-model breakdown with competitor context\n- Sample mentions with query and competitor info\n- Graceful fallback if semantic search unavailable\n\n## Databases\n\n### ChromaDB (Vector Store)\n\n- **Port**: 8001\n- **Collections**: companies, competitors\n- **Usage**: Semantic competitor matching, company embeddings\n\n### Redis (Cache)\n\n- **Port**: 6379\n- **Usage**: Scrape cache (24hr), model responses (1hr), rate limiting\n\n## Configuration\n\n### Environment Variables (`.env`)\n\n```bash\n# AI Models (at least OPENAI_API_KEY required)\nOPENAI_API_KEY=sk-... # Required for industry analysis\nANTHROPIC_API_KEY=sk-ant-... # Optional\nGEMINI_API_KEY=... # Optional\nGROK_API_KEY=gsk_... # Optional (Groq - FREE)\nOPEN_ROUTER_API_KEY=sk-or-... # Optional\n\n# Firecrawl (required for web scraping)\nFIRECRAWL_API_KEY=...\n\n# Databases (auto-initialized on startup)\nCHROMA_HOST=localhost\nCHROMA_PORT=8001\nREDIS_HOST=localhost\nREDIS_PORT=6379\n```\n\n## API Usage\n\n### Analyze Company\n\n```bash\ncurl -X POST http://localhost:8000/analyze \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_url\": \"https://hellofresh.com\",\n \"company_name\": \"HelloFresh\",\n \"company_description\": \"Meal kit delivery service\",\n \"models\": [\"chatgpt\", \"gemini\"]\n }'\n```\n\n### Response Format\n\n```json\n{\n \"job_id\": \"uuid\",\n \"status\": \"completed\",\n \"industry\": \"food_services\",\n \"visibility_score\": 75.5,\n \"total_queries\": 20,\n \"total_mentions\": 30,\n \"model_results\": {\n \"chatgpt\": {\n \"mentions\": 16,\n \"mention_rate\": 0.8,\n \"sample_mentions\": [\"Query: '...' → mentioned\"]\n }\n }\n}\n```\n\n## Performance\n\n### Without Caching\n\n- 20 queries × 2 models = 40 API calls\n- ~30-60 seconds per analysis\n\n### With Caching\n\n- First run: 40 API calls\n- Subsequent: ~12 API calls (70% cache hit)\n- ~10-20 seconds per analysis\n- 70% cost reduction\n\n## Competitor Matching\n\nUses semantic embeddings (ChromaDB + OpenAI) with similarity threshold: 0.70 to catch variations:\n\n- \"German sportswear brand\" → Adidas\n- \"premium meal kits\" → Blue Apron\n- \"budget delivery\" → EveryPlate\n- \"meal kit service\" → HelloFresh\n\n**Rich embeddings** include: name, description, products, positioning\n\n**How it works**:\n\n1. Industry Detector extracts competitors from website analysis\n2. Competitors stored in ChromaDB with rich metadata embeddings\n3. Scorer Analyzer uses semantic search to detect mentions in AI responses\n4. Tracks which competitors appear alongside company in responses\n\n## Testing\n\n```bash\n# Unit tests\npython -m pytest tests/\n\n# Integration test\npython test_complete_integration.py\n\n# RAG competitor matching\npython test_rag_competitor_matching.py\n```\n\n## Troubleshooting\n\n**ChromaDB not connecting?**\n\n```bash\ndocker-compose logs chromadb\ncurl http://localhost:8001/api/v1/heartbeat\n```\n\n**Redis not connecting?**\n\n```bash\nredis-cli ping # Should return PONG\n```\n\n**Low visibility score?**\n\n- Check generated queries are relevant\n- Verify API keys are valid\n- Review error logs for API failures\n\n**Industry detected as \"other\"?**\n\n- Check Firecrawl API key is configured\n- Verify website is accessible and has content\n- Check logs for scraping errors\n- System falls back to keyword matching if scraping fails\n\n---\n\n## System Features Summary\n\n### Performance Optimizations\n\n- **Redis Caching**: 70% cost reduction on model responses (1hr TTL)\n- **Scrape Caching**: 90% faster on repeated URLs (24hr TTL)\n- **Rate Limiting**: 60 calls/min per model to avoid throttling\n- **Token Optimization**: 5k char limit on scraped content\n\n### Accuracy Improvements\n\n- **Hybrid Mention Detection**: Exact + semantic matching\n- **Rich Embeddings**: Competitors stored with description, products, positioning\n- **Semantic Search**: Catches variations like \"meal kit service\" → HelloFresh\n- **Competitor Tracking**: Monitors which competitors appear in responses\n\n### Reliability Features\n\n- **Automatic Retry**: 2 attempts for scraping and API calls\n- **Graceful Degradation**: Falls back to keyword matching if AI fails\n- **Non-Blocking Errors**: Workflow continues even with partial failures\n- **Auto-Initialization**: Databases initialize on server startup\n\n### Cost Efficiency\n\n- **Optimized Models**: gpt-3.5-turbo, claude-haiku, gemini-flash-lite\n- **Free Options**: Llama via Groq (free tier)\n- **Caching Strategy**: Reduces API calls by 70%\n- **Token Limits**: 500 tokens per response\n\n### Extensibility\n\n- **Modular Agents**: Easy to add new agents or modify existing ones\n- **Pluggable Models**: Simple to add new AI models\n- **Industry Templates**: 25+ queries per industry, easy to extend\n- **Vector Store**: Ready for advanced semantic features\n"}}}} |