Spaces:
Sleeping
Sleeping
| # CLAUDE.md | |
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |
| ## Project Overview | |
| Multi-agent AI system that generates SWOT analyses for publicly-traded companies using a self-correcting workflow. Python/FastAPI backend with TypeScript/React frontend. | |
| **Live Demo:** https://huggingface.co/spaces/vn6295337/Instant-SWOT-Agent | |
| ## Common Commands | |
| ### Backend (Python) | |
| ```bash | |
| make api # Run FastAPI server (port 7860) | |
| make test # Run pytest tests | |
| make lint # Run flake8 and pylint | |
| make format # Format with black | |
| make coverage # Run tests with coverage | |
| make analyze TICKER=AAPL # CLI analysis for a ticker | |
| ``` | |
| ### Frontend (TypeScript/React) | |
| ```bash | |
| cd frontend | |
| npm run dev # Vite dev server (port 5173) | |
| npm run build # Production build | |
| npm run lint # ESLint | |
| npm test # Vitest unit tests | |
| npm run test:e2e # Playwright E2E tests | |
| npm run storybook # Component docs (port 6006) | |
| ``` | |
| ### Full Stack | |
| ```bash | |
| make frontend # Run both backend and React frontend | |
| ``` | |
| ## Architecture | |
| ``` | |
| User Input → Researcher → [6 MCP Servers] → Raw Data | |
| ↓ | |
| Raw Data → Analyst → SWOT Draft → Critic → Score | |
| ↓ | |
| Score < 7 → Editor → Revised Draft → Critic | |
| Score ≥ 7 or 3 revisions → Final Output | |
| ``` | |
| **Agent Workflow (LangGraph):** | |
| 1. **Researcher** - Gathers data from MCP servers (fundamentals, volatility, macro, valuation, news, sentiment) | |
| 2. **Analyst** - Generates SWOT draft based on strategy focus | |
| 3. **Critic** - Scores output 1-10 with rubric-based evaluation | |
| 4. **Editor** - Revises based on critique (loops until score ≥ 7 or 3 revisions) | |
| **Key Files:** | |
| - `src/workflow/graph.py` - LangGraph workflow definition | |
| - `src/nodes/` - Agent implementations (researcher, analyzer, critic, editor) | |
| - `src/api/app.py` - FastAPI application | |
| - `src/state.py` - TypedDict for workflow state | |
| - `frontend/src/App.tsx` - Main React component | |
| ## API Endpoints | |
| - `POST /analyze` - Start SWOT analysis (returns workflow_id) | |
| - `GET /workflow/{id}/status` - Progress and metrics | |
| - `GET /workflow/{id}/result` - Final results | |
| - `GET /api/stocks/search?q=` - Stock ticker search | |
| - `GET /health` - Health check | |
| ## Environment Variables | |
| Required (at least one LLM provider): | |
| - `GROQ_API_KEY` - Primary LLM (Llama 3.1 8B) | |
| - `GEMINI_API_KEY` - Fallback | |
| - `OPENROUTER_API_KEY` - Fallback | |
| Data sources: | |
| - `TAVILY_API_KEY` - Web search | |
| - `FRED_API_KEY` - Macro data | |
| - `FINNHUB_API_KEY` - Sentiment/ratings | |
| ## Tech Stack | |
| **Backend:** Python 3.11+, FastAPI, LangGraph, LangChain, Pydantic | |
| **Frontend:** React 18, TypeScript, Vite, Tailwind CSS, Radix UI, React Query | |
| **Testing:** pytest (backend), Vitest + Playwright (frontend) | |