{"id":50864293,"url":"https://github.com/gsaini/financial-research-analyst-agent","last_synced_at":"2026-06-14T23:34:34.749Z","repository":{"id":336381539,"uuid":"1128657977","full_name":"gsaini/financial-research-analyst-agent","owner":"gsaini","description":"The Financial Research Analyst Agent is a hierarchical multi-agent system that provides comprehensive stock analysis by coordinating 11 specialized AI agents, 20+ analysis tools, a RAG knowledge pipeline, and a multi-provider data layer — all accessible through a Streamlit web app, REST API, and CLI.","archived":false,"fork":false,"pushed_at":"2026-05-13T04:40:55.000Z","size":1124,"stargazers_count":24,"open_issues_count":0,"forks_count":10,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T23:34:32.136Z","etag":null,"topics":["docker","fastapi","kubernetes","langchain","numpy","ollama","pandas","postgresql","python","redis"],"latest_commit_sha":null,"homepage":"https://financial-agents-ai.streamlit.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gsaini.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-06T01:04:55.000Z","updated_at":"2026-06-14T14:26:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gsaini/financial-research-analyst-agent","commit_stats":null,"previous_names":["gsaini/financial-research-analyst-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gsaini/financial-research-analyst-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsaini%2Ffinancial-research-analyst-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsaini%2Ffinancial-research-analyst-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsaini%2Ffinancial-research-analyst-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsaini%2Ffinancial-research-analyst-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gsaini","download_url":"https://codeload.github.com/gsaini/financial-research-analyst-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsaini%2Ffinancial-research-analyst-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34342089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","kubernetes","langchain","numpy","ollama","pandas","postgresql","python","redis"],"created_at":"2026-06-14T23:34:34.045Z","updated_at":"2026-06-14T23:34:34.729Z","avatar_url":"https://github.com/gsaini.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏦 Financial Research Analyst Agent\n\n\u003cdiv align=\"center\"\u003e\n\n![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n![LangChain](https://img.shields.io/badge/LangChain-1C3C3C?style=for-the-badge\u0026logo=langchain\u0026logoColor=white)\n![Ollama](https://img.shields.io/badge/Ollama-000000?style=for-the-badge\u0026logo=ollama\u0026logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=for-the-badge\u0026logo=fastapi\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Kubernetes](https://img.shields.io/badge/Kubernetes-326CE5?style=for-the-badge\u0026logo=kubernetes\u0026logoColor=white)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white)\n![Redis](https://img.shields.io/badge/Redis-DC382D?style=for-the-badge\u0026logo=redis\u0026logoColor=white)\n![Pandas](https://img.shields.io/badge/Pandas-150458?style=for-the-badge\u0026logo=pandas\u0026logoColor=white)\n![NumPy](https://img.shields.io/badge/NumPy-013243?style=for-the-badge\u0026logo=numpy\u0026logoColor=white)\n\n**An AI-powered autonomous agent that automates financial data analysis and generates investment insights using LangChain, Python, and multi-agent orchestration.**\n\n[Features](#-features) • [Architecture](#-architecture) • [Installation](#-installation) • [Usage](#-usage) • [API Reference](#-api-reference) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n\n- [Overview](#-overview)\n- [Case Study Details](#-case-study-details)\n- [Features](#-features)\n- [Architecture](#-architecture)\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [Usage](#-usage)\n- [Interactive API Documentation](#-interactive-api-documentation)\n- [API Reference](#-api-reference)\n- [Agent Capabilities](#-agent-capabilities)\n- [Sample Analysis](#-sample-analysis)\n- [Testing](#-testing)\n- [Deployment](#-deployment)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## 🎯 Overview\n\nThe **Financial Research Analyst Agent** is an end-to-end AI solution designed to automate financial data analysis and insight generation. Built with LangChain and Python, this agent leverages multiple specialized sub-agents to:\n\n- 📊 **Analyze financial data** from multiple sources\n- 📈 **Generate investment insights** with detailed reasoning\n- 🔍 **Perform market research** autonomously\n- 📑 **Create comprehensive reports** with actionable recommendations\n- ⚡ **Enhance decision-making speed** through automation\n\n---\n\n## 📚 Case Study Details\n\n| Attribute      | Description                                                                                                                                    |\n| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Objective**  | Leverage AI agent capabilities to automate data analysis and insight generation, enhancing the speed and quality of investment decision-making |\n| **Domain**     | Finance, Investment Analysis, Automation                                                                                                       |\n| **Skills**     | AI Agents, Data Analysis, Investment Decision-Making, LangChain, Python                                                                        |\n| **Complexity** | Advanced                                                                                                                                       |\n| **Duration**   | 4-6 weeks implementation                                                                                                                       |\n\n### Problem Statement\n\nTraditional financial research is:\n\n- **Time-consuming**: Analysts spend 60-80% of time on data gathering\n- **Error-prone**: Manual analysis leads to inconsistencies\n- **Limited in scope**: Human capacity limits coverage\n- **Reactive**: Difficulty in real-time market monitoring\n\n### Solution\n\nThis AI agent system addresses these challenges by:\n\n1. **Automating data collection** from multiple financial APIs\n2. **Performing real-time analysis** using advanced NLP and ML\n3. **Generating actionable insights** with confidence scores\n4. **Creating structured reports** for decision-makers\n\n---\n\n## ✨ Features\n\n### Core Capabilities\n\n| Feature                            | Description                                                             |\n| ---------------------------------- | ----------------------------------------------------------------------- |\n| 🤖 **Multi-Agent Architecture**    | Specialized agents for different analysis tasks                         |\n| 📊 **Real-time Data Analysis**     | Live market data processing and analysis                                |\n| 📈 **Technical Analysis**          | Automated chart pattern and indicator analysis                          |\n| 📰 **News Sentiment Analysis**     | AI-powered sentiment scoring (FinBERT/VADER), trends \u0026 volume tracking  |\n| 🎯 **Thematic Investing Analysis** | Group stocks by investment themes (AI, EV, Green Energy, etc.)          |\n| 👥 **Peer Group Comparison**       | Compare stocks against industry peers with real-time metrics            |\n| 🚀 **Market Disruption Analysis**  | Identify disruptors and companies at risk of disruption                 |\n| 📅 **Quarterly Earnings Analysis** | Track EPS surprises, beat/miss patterns, and earnings quality           |\n| 📉 **Performance Tracking**        | Multi-horizon returns, benchmark comparison \u0026 drawdown analysis         |\n| 📅 **Event-Driven Performance**    | Post-earnings price reactions, ±5 day windows, and surprise correlation |\n| 🔄 **Backtesting Engine**          | Simulate trading strategies against historical data with trade logs     |\n| 🔍 **Key Observations**            | Cross-dimensional insights, confluences, anomalies \u0026 ranked signals     |\n| 👤 **Insider \u0026 Institutional**     | Track insider transactions, institutional holdings \u0026 smart money score  |\n| 📊 **Options Flow Analysis**       | Put/Call ratios, implied volatility skew, max pain \u0026 unusual activity   |\n| 📑 **Report Generation**           | PDF \u0026 Excel reports with executive summary, deep dive templates         |\n| 🧠 **RAG Document Intelligence**   | Ingest \u0026 query SEC filings (10-K, 10-Q, 8-K) and earnings transcripts  |\n| 🔄 **ReAct Multi-Step Reasoning**  | Agents think step-by-step with few-shot examples and confidence scoring |\n| 🗃️ **Multi-Provider Data**         | YFinance + FMP + Alpha Vantage with automatic fallback \u0026 validation     |\n| 💡 **LLM-Powered Insights**        | Cross-dimensional synthesis with contradiction detection \u0026 historical context |\n| 🌍 **Macro Economic Data**         | FRED API: Fed funds, CPI, GDP, unemployment, treasury yields           |\n| 💬 **Social Media Sentiment**      | Reddit (WSB, r/stocks, r/investing) sentiment + composite scoring      |\n| 💰 **DCF Valuation Model**         | WACC/CAPM, 3-scenario DCF, 5x5 sensitivity matrix, margin of safety   |\n| 🤖 **ML Price Forecasting**        | GradientBoosting 30/60/90-day targets with confidence intervals        |\n| 🔎 **Anomaly Detection**           | Z-score volume/price anomalies, gap events, regime change detection    |\n| 📐 **Portfolio Optimization**      | Markowitz mean-variance, efficient frontier, risk-parity allocation    |\n| 📊 **Benchmark Comparison**        | Alpha, beta, tracking error, information ratio, return attribution     |\n| 🎲 **Monte Carlo Simulation**      | 10K-path GBM for VaR/CVaR, target price probability, portfolio risk   |\n| 🧬 **Factor Modeling**             | Fama-French style decomposition (market, size, value, momentum, quality) |\n| 🏷️ **Brinson Attribution**         | Allocation, selection \u0026 interaction effects at sector level            |\n| 🧮 **Tax-Loss Harvesting**         | Identify harvestable losses, replacement securities, wash sale warnings |\n| 🧪 **Strategy Optimization**       | Genetic algorithm parameter tuning with overfitting detection          |\n| 🔗 **Supply Chain Analysis**       | Map suppliers, customers, competitors with correlation risk scoring    |\n| 🔔 **Real-Time Alerts**            | Price/volume/RSI/52-week alerts with WebSocket push notifications      |\n| 📬 **Scheduled Reports**           | Daily/weekly/monthly digests with SMTP email or disk delivery          |\n| 🌓 **Dark/Light Theme**            | Toggle between Bloomberg-dark and light color modes                    |\n| 📱 **Mobile-Responsive UI**        | Responsive breakpoints at 768px and 480px                              |\n| 🔒 **API Security**                | API key auth, rate limiting, input sanitization (SQL/XSS/injection)    |\n| 💾 **Persistence Layer**           | SQLAlchemy ORM: watchlists, portfolios, analysis history               |\n| 🌐 **API Integration**             | REST API + WebSocket for external system integration                   |\n| 📖 **Interactive API Docs**        | Swagger UI \u0026 ReDoc with OpenAPI 3.0 specification                       |\n| 📱 **Web Dashboard**               | 13-page interactive visualization dashboard                            |\n\n### Agent Types\n\n| # | Agent | Key Capabilities |\n|---|-------|-----------------|\n| 1 | **Data Collector** | Multi-provider data gathering (YFinance, FMP, Alpha Vantage) with auto-fallback |\n| 2 | **Technical Analyst** | RSI, MACD, Bollinger, patterns + ML price forecasting + anomaly/regime detection |\n| 3 | **Fundamental Analyst** | Valuation, DCF (3-scenario), peer comparison, SEC filings via RAG, macro context |\n| 4 | **Sentiment Analyst** | News + Reddit social sentiment, analyst ratings, earnings transcript tone |\n| 5 | **Risk Analyst** | VaR/CVaR, Monte Carlo (10K paths), beta, drawdown, rate environment context |\n| 6 | **Thematic Analyst** | Investment themes (AI, EV, Green Energy), momentum \u0026 health scoring |\n| 7 | **Disruption Analyst** | R\u0026D intensity, disruption scoring, disruptor vs at-risk classification |\n| 8 | **Earnings Analyst** | EPS surprises, beat/miss patterns, earnings quality scoring |\n| 9 | **Performance Analyst** | Multi-horizon returns, benchmark comparison, Sharpe/Sortino/Beta |\n| 10 | **Report Generator** | PDF \u0026 Excel reports, executive summaries, multi-agent insight aggregation |\n| 11 | **Orchestrator** | Cross-agent conflict detection, RAG document ingestion, confidence scoring |\n\n---\n\n## 🏗 Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────────────────┐\n│                          FINANCIAL RESEARCH ANALYST AGENT                        │\n├──────────────────────────────────────────────────────────────────────────────────┤\n│                                                                                  │\n│  ┌────────────────────────────────────────────────────────────────────────────┐  │\n│  │                          ORCHESTRATOR AGENT                                │  │\n│  │  • Task Planning \u0026 Decomposition  • Agent Coordination  • Aggregation     │  │\n│  └────────────────────────────────────────────────────────────────────────────┘  │\n│                                       │                                          │\n│           ┌───────────────┬───────────┼───────────┬───────────────┐              │\n│           │               │           │           │               │              │\n│  ┌────────▼───────┐ ┌─────▼─────┐ ┌───▼───┐ ┌────▼────┐ ┌────────▼───────┐     │\n│  │ DATA COLLECTOR │ │ TECHNICAL │ │ FUNDA │ │ SENTI-  │ │ RISK           │     │\n│  │ AGENT          │ │ ANALYST   │ │ MENTAL│ │ MENT    │ │ ANALYST AGENT  │     │\n│  │                │ │ AGENT     │ │ AGENT │ │ AGENT   │ │                │     │\n│  │ • YFinance     │ │ • RSI     │ │ • P/E │ │ • News  │ │ • VaR/CVaR     │     │\n│  │ • FMP          │ │ • MACD    │ │ • EPS │ │ • Analyst│ │ • Volatility   │     │\n│  │ • Alpha Vantage│ │ • SMA/EMA │ │ • ROE │ │ • Trans.│ │ • Beta/Sharpe  │     │\n│  │ • Auto-fallback│ │ • ReAct   │ │ • RAG │ │ • ReAct │ │ • Drawdown     │     │\n│  └────────────────┘ └───────────┘ └───────┘ └─────────┘ └────────────────┘     │\n│                                                                                  │\n│  ┌─────────────────────────────────┐  ┌──────────────────────────────────────┐  │\n│  │ THEMATIC ANALYST AGENT          │  │ DISRUPTION ANALYST AGENT             │  │\n│  │                                 │  │                                      │  │\n│  │ • Theme-to-Ticker Mapping       │  │ • R\u0026D Intensity Analysis             │  │\n│  │ • Multi-Horizon Performance     │  │ • Revenue Growth Acceleration        │  │\n│  │ • Momentum \u0026 Health Scoring     │  │ • Gross Margin Trajectory            │  │\n│  │ • Correlation \u0026 Diversification │  │ • Disruption Score (0-100)           │  │\n│  │ • Sector Overlap Analysis       │  │ • Disruptor vs At-Risk Classification│  │\n│  └─────────────────────────────────┘  └──────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌───────────────────────────────────────────────────────────────────────────┐  │\n│  │ EARNINGS ANALYST AGENT                                                    │  │\n│  │                                                                           │  │\n│  │ • EPS Actual vs Estimate Tracking    • Quarterly Trend Analysis (QoQ/YoY)│  │\n│  │ • Beat/Miss Pattern Recognition      • Earnings Quality Scoring (1-10)   │  │\n│  │ • Surprise % Calculation             • Upcoming Earnings Dates           │  │\n│  └───────────────────────────────────────────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌───────────────────────────────────────────────────────────────────────────┐  │\n│  │ PERFORMANCE ANALYST AGENT                                                 │  │\n│  │                                                                           │  │\n│  │ • Multi-Horizon Absolute Returns     • Benchmark vs S\u0026P 500/Nasdaq/Sector│  │\n│  │ • Sharpe \u0026 Sortino Ratios            • Beta \u0026 Volatility Analysis        │  │\n│  │ • Rolling 30-Day Returns             • Drawdown \u0026 Recovery Analysis      │  │\n│  └───────────────────────────────────────────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌───────────────────────────────────────────────────────────────────────────┐  │\n│  │ SENTIMENT ENGINE                                                          │  │\n│  │                                                                           │  │\n│  │ • FinBERT / VADER Financial Scoring  • Per-Article Confidence Scores     │  │\n│  │ • News Volume \u0026 Spike Detection      • Sentiment Trend Analysis          │  │\n│  │ • Topic Extraction                   • Source Diversity Assessment       │  │\n│  └───────────────────────────────────────────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌─────────────────────────────────┐  ┌──────────────────────────────────────┐  │\n│  │ RAG DOCUMENT INTELLIGENCE       │  │ LLM-POWERED INSIGHT ENGINE           │  │\n│  │                                 │  │                                      │  │\n│  │ • SEC Filing Ingestion (10-K/Q) │  │ • Cross-Dimensional Synthesis        │  │\n│  │ • Earnings Transcript Search    │  │ • Contradiction Detection            │  │\n│  │ • Semantic Chunking \u0026 Retrieval │  │ • Historical Context Comparison      │  │\n│  │ • Agent RAG Mixin (optional)    │  │ • Watch Items \u0026 Catalysts            │  │\n│  └─────────────────────────────────┘  └──────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌─────────────────────────────────┐  ┌──────────────────────────────────────┐  │\n│  │ PREDICTIVE MODELS               │  │ PORTFOLIO ANALYTICS                  │  │\n│  │                                 │  │                                      │  │\n│  │ • ML Price Forecast (GBM)       │  │ • Markowitz Optimization             │  │\n│  │ • DCF Valuation (3 scenarios)   │  │ • Monte Carlo Simulation (10K)       │  │\n│  │ • Anomaly Detection (Z-score)   │  │ • Fama-French Factor Model           │  │\n│  │ • Strategy Optimizer (GA)       │  │ • Brinson Attribution                │  │\n│  └─────────────────────────────────┘  └──────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌─────────────────────────────────┐  ┌──────────────────────────────────────┐  │\n│  │ MACRO \u0026 ALTERNATIVE DATA        │  │ AUTOMATION \u0026 ALERTS                  │  │\n│  │                                 │  │                                      │  │\n│  │ • FRED API (rates, CPI, GDP)    │  │ • Real-Time Alert Engine (9 types)   │  │\n│  │ • Reddit Sentiment (WSB)        │  │ • WebSocket Push Notifications       │  │\n│  │ • Supply Chain Mapping          │  │ • Scheduled Report Digests           │  │\n│  │ • Tax-Loss Harvesting           │  │ • Email Delivery (SMTP)              │  │\n│  └─────────────────────────────────┘  └──────────────────────────────────────┘  │\n│                                                                                  │\n│  ┌───────────────────────────────────────────────────────────────────────────┐  │\n│  │ REPORT GENERATOR AGENT                                                    │  │\n│  │                                                                           │  │\n│  │ • PDF / Excel / Markdown / JSON  • Actionable Recommendations             │  │\n│  │ • Executive Summaries            • Multi-Agent Insight Aggregation        │  │\n│  └───────────────────────────────────────────────────────────────────────────┘  │\n│                                                                                  │\n├──────────────────────────────────────────────────────────────────────────────────┤\n│                                  DATA LAYER                                      │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐ │\n│  │ Vector Store │ │ Cache Layer  │ │ Database     │ │ Data Valid.│ │ Multi-   │ │\n│  │ (ChromaDB)   │ │ (Redis)      │ │ (PostgreSQL) │ │ (Quality)  │ │ Provider │ │\n│  │ + RAG Embeds │ │              │ │ + ORM Models │ │ + Outliers │ │ Fallback │ │\n│  │              │ │              │ │ + Watchlists │ │ + Mkt Hrs  │ │ + FRED   │ │\n│  └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ └──────────┘ │\n└──────────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Technology Stack\n\n| Component           | Technology                                   |\n| ------------------- | -------------------------------------------- |\n| **AI Framework**    | LangChain, LangGraph                         |\n| **LLM**             | Ollama (Llama 4, Mistral) / Groq / LM Studio |\n| **RAG**             | Semantic chunking, ChromaDB, cross-encoder re-ranking |\n| **Embeddings**      | Sentence Transformers / HuggingFace / Ollama |\n| **ML/Forecasting**  | scikit-learn (GradientBoosting), NumPy, SciPy |\n| **Vector Store**    | ChromaDB / Qdrant / Milvus / Weaviate        |\n| **Data Providers**  | YFinance, FMP, Alpha Vantage, FRED, Reddit (auto-fallback) |\n| **Backend**         | FastAPI + WebSocket, Python 3.14+            |\n| **Data Processing** | Pandas, NumPy, SciPy                         |\n| **Visualization**   | Plotly, TradingView Lightweight Charts       |\n| **Frontend**        | Streamlit, HTML5, CSS3 (dark/light themes)   |\n| **Database**        | PostgreSQL / SQLite + SQLAlchemy ORM          |\n| **Caching**         | Redis                                        |\n| **Reports**         | reportlab (PDF), openpyxl (Excel)             |\n| **Security**        | API key auth, rate limiting, input sanitization |\n\n---\n\n## 🚀 Installation\n\n### Prerequisites\n\n- Python 3.14 or higher\n- pip or conda package manager\n- OpenAI API key (or other LLM provider)\n- Alpha Vantage API key (optional, for live data)\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/gsaini/financial-research-analyst-agent.git\ncd financial-research-analyst-agent\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your API keys\n\n# Run the application\npython -m src.main\n```\n\n### Docker Installation\n\n```bash\n# Build the Docker image\ndocker build -t financial-analyst-agent .\n\n# Run the container\ndocker run -p 8000:8000 --env-file .env financial-analyst-agent\n```\n\n---\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# LLM Configuration (Open Source by Default)\nLLM_PROVIDER=ollama\nOLLAMA_BASE_URL=http://localhost:11434\nOLLAMA_MODEL=llama4:latest\nLLM_TEMPERATURE=0.1\n\n# Embedding Configuration (Open Source)\nEMBEDDING_PROVIDER=sentence-transformers\nSENTENCE_TRANSFORMER_MODEL=all-MiniLM-L6-v2\n\n# Financial Data APIs (Yahoo Finance is free, others optional)\nDATA_PROVIDER=yfinance                        # yfinance | fmp | alphavantage\nDATA_FALLBACK_PROVIDER=fmp                    # Auto-fallback if primary fails\nALPHA_VANTAGE_API_KEY=your_alpha_vantage_key  # Optional\nFMP_API_KEY=your_fmp_api_key                  # Optional (free tier: 250 req/day)\nNEWS_API_KEY=your_news_api_key                # Optional\n\n# FRED Macroeconomic Data (free key)\nFRED_API_KEY=your_fred_api_key                # Optional\n\n# Database Configuration\nDATABASE_URL=sqlite:///./data/financial_agent.db\nREDIS_URL=redis://localhost:6379\n\n# Vector Store (Open Source)\nVECTOR_STORE_PROVIDER=chroma\nCHROMA_PERSIST_DIR=./data/chroma\n\n# Application Settings\nDEBUG=false\nLOG_LEVEL=INFO\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\n\n# Security (optional — disabled in dev mode)\n# API_KEYS=key1,key2                          # Comma-separated API keys\n# RATE_LIMIT_REQUESTS=100                     # Per-window limit\n# RATE_LIMIT_WINDOW_SECONDS=60\n\n# Email Digests (optional)\n# SMTP_HOST=smtp.gmail.com\n# SMTP_PORT=587\n# SMTP_USER=your@email.com\n# SMTP_PASSWORD=your_app_password\n```\n\n### Agent Configuration\n\nEdit `config/agents.yaml` to customize agent behavior:\n\n```yaml\norchestrator:\n  max_iterations: 10\n  timeout_seconds: 300\n\ntechnical_analyst:\n  indicators:\n    - RSI\n    - MACD\n    - SMA\n    - EMA\n    - Bollinger Bands\n  lookback_periods: [14, 30, 50, 200]\n\nsentiment_analyst:\n  sources:\n    - news\n    - twitter\n    - reddit\n  sentiment_threshold: 0.3\n```\n\n---\n\n## 📖 Usage\n\n### Python API\n\n```python\nfrom src.agents import FinancialResearchAgent\n\n# Initialize the agent\nagent = FinancialResearchAgent()\n\n# Analyze a single stock\nresult = agent.analyze(\"AAPL\")\nprint(result.summary)\nprint(result.recommendation)\nprint(result.confidence_score)\n\n# Analyze multiple stocks\nportfolio = [\"AAPL\", \"GOOGL\", \"MSFT\", \"AMZN\"]\nportfolio_analysis = agent.analyze_portfolio(portfolio)\n\n# Generate a research report\nreport = agent.generate_report(\n    symbols=[\"AAPL\"],\n    include_technical=True,\n    include_fundamental=True,\n    include_sentiment=True,\n    format=\"pdf\"\n)\n```\n\n### REST API\n\n```bash\n# Analyze a stock\ncurl -X POST \"http://localhost:8000/api/v1/analyze\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\": \"AAPL\", \"analysis_type\": \"comprehensive\"}'\n\n# Get technical analysis\ncurl \"http://localhost:8000/api/v1/technical/AAPL\"\n\n# Generate report\ncurl -X POST \"http://localhost:8000/api/v1/reports\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbols\": [\"AAPL\", \"GOOGL\"], \"format\": \"pdf\"}'\n\n# List available investment themes\ncurl \"http://localhost:8000/api/v1/themes\"\n\n# Analyze an investment theme\ncurl -X POST \"http://localhost:8000/api/v1/theme/ai_machine_learning\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"theme_id\": \"ai_machine_learning\", \"include_narrative\": false}'\n\n# Compare multiple themes\ncurl -X POST \"http://localhost:8000/api/v1/themes/compare\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"theme_ids\": [\"ai_machine_learning\", \"cybersecurity\", \"electric_vehicles\"]}'\n\n# Analyze market disruption profile\ncurl \"http://localhost:8000/api/v1/disruption/TSLA\"\n\n# Disruption analysis with LLM narrative\ncurl -X POST \"http://localhost:8000/api/v1/disruption/analyze\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\": \"NVDA\", \"include_narrative\": true}'\n\n# Compare disruption profiles across competitors\ncurl -X POST \"http://localhost:8000/api/v1/disruption/compare\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbols\": [\"TSLA\", \"F\", \"GM\", \"TM\"], \"include_narrative\": false}'\n\n# Analyze quarterly earnings\ncurl \"http://localhost:8000/api/v1/earnings/AAPL\"\n\n# Earnings analysis with LLM narrative\ncurl -X POST \"http://localhost:8000/api/v1/earnings/analyze\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\": \"MSFT\", \"include_narrative\": true}'\n\n# Compare earnings profiles across companies\ncurl -X POST \"http://localhost:8000/api/v1/earnings/compare\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"], \"include_narrative\": false}'\n```\n\n### Streamlit Dashboard\n\n```bash\n# Install frontend dependencies\npip install -r frontend/requirements.txt\n\n# Launch the interactive dashboard (no LLM required)\nstreamlit run frontend/app.py\n```\n\nThe dashboard provides 13 interactive pages covering stock analysis, thematic investing, peer comparison, market disruption, quarterly earnings, portfolio analysis, reports, financial news, historical performance, AI-powered sentiment, ETF screening, and macroeconomic data — with dark/light theme toggle and mobile-responsive layout.\n\n### Command Line Interface\n\n```bash\n# Quick analysis\npython -m src.cli analyze AAPL\n\n# Portfolio analysis\npython -m src.cli portfolio AAPL GOOGL MSFT --output report.pdf\n\n# Start web dashboard\npython -m src.cli dashboard --port 8080\n```\n\n---\n\n## 📚 Interactive API Documentation\n\nThe API includes built-in interactive documentation powered by **OpenAPI 3.0** specification.\n\n### Swagger UI\n\nAccess the interactive Swagger UI at: **\u003chttp://localhost:8000/docs\u003e**\n\nFeatures:\n\n- Interactive API explorer with \"Try it out\" functionality\n- Auto-generated request/response examples\n- Authentication testing\n- Schema validation\n\n### ReDoc\n\nAccess the ReDoc documentation at: **\u003chttp://localhost:8000/redoc\u003e**\n\nFeatures:\n\n- Clean, responsive three-panel design\n- Deep linking to specific endpoints\n- Code samples in multiple languages\n- Search functionality\n\n### OpenAPI JSON Schema\n\nDownload the raw OpenAPI specification: **\u003chttp://localhost:8000/openapi.json\u003e**\n\nUse this to:\n\n- Generate client SDKs (Python, TypeScript, Go, etc.)\n- Import into Postman or Insomnia\n- Create automated API tests\n\n---\n\n## 🔧 API Reference\n\n### Endpoints\n\n| Method      | Endpoint                        | Description                                     |\n| ----------- | ------------------------------- | ----------------------------------------------- |\n| `POST`      | `/api/v1/analyze`               | Analyze a stock symbol                          |\n| `GET`       | `/api/v1/technical/{symbol}`    | Get technical analysis                          |\n| `GET`       | `/api/v1/fundamental/{symbol}`  | Get fundamental analysis                        |\n| `GET`       | `/api/v1/sentiment/{symbol}`    | Get sentiment analysis                          |\n| `POST`      | `/api/v1/portfolio`             | Analyze a portfolio                             |\n| `POST`      | `/api/v1/reports`               | Generate a report                               |\n| `GET`       | `/api/v1/market/summary`        | Get market summary                              |\n| `GET`       | `/api/v1/themes`                | List all available investment themes            |\n| `POST`      | `/api/v1/theme/{theme_id}`      | Analyze an investment theme                     |\n| `POST`      | `/api/v1/themes/compare`        | Compare multiple themes side by side            |\n| `GET`       | `/api/v1/peers/{symbol}`        | Get peer comparison (auto-discovery)            |\n| `POST`      | `/api/v1/peers/compare`         | Compare stock against specific peers            |\n| `GET`       | `/api/v1/disruption/{symbol}`   | Get market disruption analysis                  |\n| `POST`      | `/api/v1/disruption/analyze`    | Analyze disruption with optional LLM narrative  |\n| `POST`      | `/api/v1/disruption/compare`    | Compare disruption profiles across companies    |\n| `GET`       | `/api/v1/earnings/{symbol}`     | Get quarterly earnings analysis                 |\n| `POST`      | `/api/v1/earnings/analyze`      | Analyze earnings with optional LLM narrative    |\n| `POST`      | `/api/v1/earnings/compare`      | Compare earnings profiles across companies      |\n| `GET`       | `/api/v1/performance/{symbol}`  | Get historical performance tracking             |\n| `GET`       | `/api/v1/events/{symbol}`       | Get event-driven performance analysis           |\n| `POST`      | `/api/v1/backtest`              | Run a backtesting simulation                    |\n| `GET`       | `/api/v1/strategies`            | List available backtesting strategies           |\n| `GET`       | `/api/v1/observations/{symbol}` | Key observations and cross-dimensional insights |\n| `GET`       | `/api/v1/insiders/{symbol}`     | Insider \u0026 institutional activity analysis       |\n| `GET`       | `/api/v1/options/{symbol}`      | Options flow and sentiment analysis             |\n| `WebSocket` | `/ws/alerts`                    | Real-time alerts                                |\n\n### Response Schema\n\n```json\n{\n  \"symbol\": \"AAPL\",\n  \"analysis_date\": \"2024-01-15T10:30:00Z\",\n  \"technical\": {\n    \"trend\": \"bullish\",\n    \"signals\": [...],\n    \"indicators\": {...}\n  },\n  \"fundamental\": {\n    \"valuation\": \"fairly_valued\",\n    \"metrics\": {...},\n    \"growth_score\": 8.5\n  },\n  \"sentiment\": {\n    \"overall\": \"positive\",\n    \"score\": 0.72,\n    \"sources\": {...}\n  },\n  \"recommendation\": {\n    \"action\": \"BUY\",\n    \"confidence\": 0.85,\n    \"reasoning\": \"...\",\n    \"target_price\": 195.00,\n    \"stop_loss\": 175.00\n  }\n}\n```\n\n---\n\n## 🤖 Agent Capabilities\n\n### 1. Data Collector Agent\n\n```python\nCapabilities:\n- Fetch real-time stock prices\n- Historical data retrieval\n- Financial statements download\n- News article collection\n- Social media data gathering\n```\n\n### 2. Technical Analyst Agent\n\n```python\nIndicators Supported:\n- RSI (Relative Strength Index)\n- MACD (Moving Average Convergence Divergence)\n- SMA/EMA (Simple/Exponential Moving Averages)\n- Bollinger Bands\n- Fibonacci Retracements\n- Volume Analysis\n- Support/Resistance Levels\n```\n\n### 3. Fundamental Analyst Agent\n\n```python\nMetrics Analyzed:\n- P/E Ratio, P/B Ratio, P/S Ratio\n- EPS and Revenue Growth\n- ROE, ROA, ROIC\n- Debt-to-Equity Ratio\n- Free Cash Flow\n- Dividend Yield and Payout Ratio\n- Competitive Analysis\n```\n\n### 4. Sentiment Analyst Agent\n\n```python\nSources:\n- Financial news articles\n- SEC filings and earnings calls\n- Social media (Twitter, Reddit)\n- Analyst ratings\n- Insider trading activity\n```\n\n### 5. Thematic Analyst Agent\n\n```python\nCapabilities:\n- Analyze stocks grouped by investment themes (AI, EV, Green Energy, etc.)\n- Multi-horizon performance tracking (1W, 1M, 3M, 6M, 1Y, YTD)\n- Intra-theme correlation and diversification scoring\n- Momentum scoring (0-100) with configurable weights\n- Theme health scoring (0-100) combining performance, momentum, risk\n- Sector overlap breakdown\n- Top performer and laggard identification\n- LLM-generated narrative outlook (optional)\n\nAvailable Themes:\n- AI \u0026 Machine Learning          - Electric Vehicles\n- Green Energy \u0026 Clean Tech       - Cybersecurity\n- Aging Population \u0026 Healthcare   - Cloud Computing \u0026 SaaS\n- Fintech \u0026 Digital Payments      - Space Economy \u0026 Aerospace\n- Digital Entertainment \u0026 Gaming  - Blockchain \u0026 Web3\n```\n\n### 6. Disruption Analyst Agent\n\n```python\nCapabilities:\n- Analyze whether a company is a market disruptor or at risk of disruption\n- R\u0026D intensity analysis (R\u0026D/Revenue ratio, trend vs industry benchmarks)\n- Revenue growth acceleration/deceleration tracking\n- Gross margin trajectory analysis (expansion = competitive moat)\n- Disruption scoring (0-100) with weighted components\n- Classification: Active Disruptor, Moderate Innovator, Stable Incumbent, At Risk\n- Industry-specific benchmarks for 18+ industries\n- Risk factor and competitive strength identification\n- Multi-company disruption comparison with ranking\n- LLM-generated qualitative competitive assessment (optional)\n\nDisruption Classification:\n- Active Disruptor (70+)    : High R\u0026D, accelerating growth, expanding margins\n- Moderate Innovator (50-70): Some disruptive signals, mixed trajectory\n- Stable Incumbent (30-50)  : Established position, limited innovation\n- At Risk (\u003c30)             : Low innovation, weak growth, margin pressure\n\nScoring Components:\n- R\u0026D Intensity Score     (35% weight): Innovation investment vs industry\n- Revenue Growth Score    (40% weight): Growth rate and acceleration\n- Margin Trajectory Score (25% weight): Gross margin expansion/contraction\n```\n\n### 7. Earnings Analyst Agent\n\n```python\nCapabilities:\n- Track quarterly EPS actuals vs analyst estimates\n- Analyze beat/miss patterns and management guidance accuracy\n- Calculate quarter-over-quarter and year-over-year trends\n- Assess earnings quality (operational vs one-time items)\n- Identify upcoming earnings dates and estimate trends\n- Compare earnings profiles across sector peers\n- LLM-generated earnings narrative (optional)\n\nEarnings Pattern Classification:\n- Consistent Beater (80%+ beat rate): Management under-promises, reliable execution\n- Regular Beater (60-80%)           : Tends to exceed expectations\n- Mixed Results (40-60%)            : Unpredictable earnings, higher risk\n- Regular Misser (20-40%)           : Tends to disappoint\n- Consistent Misser (\u003c20%)          : Credibility concerns\n\nEarnings Quality Score (1-10):\n- High Quality (8-10)     : Driven by operations, sustainable\n- Good Quality (6.5-8)    : Primarily operational with minor concerns\n- Average Quality (5-6.5) : Some non-operational factors present\n- Below Average (3.5-5)   : Significant non-operational items\n- Low Quality (1-3.5)     : Earnings not reflective of core operations\n\nKey Metrics:\n- Beat Rate %           : Percentage of quarters exceeding estimates\n- Average Surprise %    : Mean EPS surprise across quarters\n- Revenue/Income Trends : QoQ and YoY growth trajectory\n- Margin Trajectory     : Gross margin expansion/contraction pattern\n```\n\n### 8. Performance Analyst Agent\n\n```python\nCapabilities:\n- Multi-horizon absolute returns (1D, 1W, 1M, 3M, 6M, YTD, 1Y, 3Y, 5Y)\n- Benchmark comparison vs S\u0026P 500 (SPY), Nasdaq 100 (QQQ), and sector ETF\n- Auto-detection of sector ETF based on company sector (12 sector mappings)\n- Alpha calculation across horizons with outperform/underperform assessment\n- Risk-adjusted metrics: Sharpe ratio, Sortino ratio, Beta, volatility\n- Rolling 30-day returns with momentum trend analysis\n- Drawdown analysis: max drawdown, recovery time, current drawdown\n- Daily return statistics: mean, median, best/worst day, positive day %\n\nRisk-Adjusted Ratings:\n- Excellent (2.0+)  : Superior risk-adjusted performance\n- Good (1.0-2.0)    : Above-average risk-adjusted returns\n- Moderate (0.5-1.0): Acceptable risk-reward balance\n- Poor (\u003c0.5)       : Risk not adequately compensated\n\nBenchmark Comparison:\n- vs S\u0026P 500 (SPY)          : Broad market comparison\n- vs Nasdaq 100 (QQQ)       : Growth/tech benchmark\n- vs Sector ETF (XLK, etc.) : Industry-specific comparison\n\nSector ETF Mappings:\n- Technology: XLK     - Healthcare: XLV      - Financials: XLF\n- Consumer Cyclical: XLY - Consumer Defensive: XLP - Communication: XLC\n- Industrials: XLI    - Energy: XLE          - Utilities: XLU\n- Real Estate: XLRE   - Basic Materials: XLB\n```\n\n### 9. Sentiment Engine\n\n```python\nCapabilities:\n- FinBERT financial-domain sentiment analysis (when transformers installed)\n- VADER with 60+ financial-domain lexicon enhancements (default fallback)\n- Per-article scoring with confidence and label (Positive/Negative/Neutral)\n- Time-weighted aggregate scoring (recent articles weighted higher)\n- News volume tracking with spike detection (2.5x+ normal = significant)\n- Sentiment trend analysis over time with direction/momentum\n- Source diversity assessment (broad/moderate/limited/single-source)\n- Topic extraction for key themes (earnings, analyst, product, regulation, etc.)\n- News-price correlation signal\n\nSentiment Engines:\n- FinBERT (ProsusAI/finbert)  : Financial-domain transformer, high accuracy\n- VADER + Financial Lexicon   : Fast, no GPU required, enhanced with 60+ terms\n\nFinancial Lexicon Additions:\n- Positive: beat, outperform, upgrade, bullish, rally, surge, catalyst, tailwind\n- Negative: miss, downgrade, bearish, selloff, plunge, bankruptcy, headwind, fraud\n\nVolume Spike Detection:\n- 2.5x+ normal  : Significant event coverage\n- 1.5x+ normal  : Elevated interest\n- Below 1.5x    : Normal news flow\n```\n\n---\n\n## 📊 Sample Analysis\n\n### Example: Apple Inc. (AAPL) Analysis\n\n```\n================================================================================\n                     FINANCIAL RESEARCH ANALYST REPORT\n                              Apple Inc. (AAPL)\n                           Generated: 2024-01-15\n================================================================================\n\nEXECUTIVE SUMMARY\n-----------------\nApple Inc. demonstrates strong fundamentals with continued growth in services\nrevenue and a robust product ecosystem. Technical indicators suggest a bullish\ntrend, while sentiment analysis reveals positive market perception.\n\nTECHNICAL ANALYSIS\n------------------\nTrend: BULLISH\nRSI (14): 58.3 (Neutral)\nMACD: Bullish crossover detected\nSupport: $175.00\nResistance: $195.00\n\nFUNDAMENTAL ANALYSIS\n--------------------\nP/E Ratio: 28.5 (Industry Avg: 25.2)\nRevenue Growth: 8.2% YoY\nEPS Growth: 12.1% YoY\nDebt/Equity: 1.52\nROE: 147.3%\n\nSENTIMENT ANALYSIS\n------------------\nOverall Sentiment: POSITIVE (Score: 0.72)\nNews Sentiment: 0.68\nSocial Media: 0.75\nAnalyst Consensus: 0.82\n\nRECOMMENDATION\n--------------\nAction: BUY\nConfidence: 85%\nTarget Price: $195.00\nStop Loss: $175.00\n\nReasoning: Strong fundamentals combined with positive technical signals and\nfavorable market sentiment suggest upside potential. The services segment\ncontinues to grow, providing recurring revenue stability.\n================================================================================\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run specific test suite\npytest tests/test_agents.py -v\n\n# Run thematic investing tests\npytest tests/test_thematic.py -v\n\n# Run market disruption analysis tests\npytest tests/test_disruption.py -v\n\n# Run quarterly earnings analysis tests\npytest tests/test_earnings.py -v\n\n# Run peer comparison tests\npytest tests/test_peer_comparison.py -v\n\n# Run with coverage\npytest tests/ --cov=src --cov-report=html\n\n# Run integration tests (requires network access for yfinance)\npytest tests/ -v -m integration\n```\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose\n\n```yaml\nversion: \"3.8\"\nservices:\n  api:\n    build: .\n    ports:\n      - \"8000:8000\"\n    environment:\n      - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/financial_agent\n      - REDIS_URL=redis://redis:6379\n    depends_on:\n      - db\n      - redis\n\n  db:\n    image: postgres:15\n    environment:\n      POSTGRES_DB: financial_agent\n      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} # Set in .env file\n    volumes:\n      - postgres_data:/var/lib/postgresql/data\n\n  redis:\n    image: redis:7\n    volumes:\n      - redis_data:/data\n\nvolumes:\n  postgres_data:\n  redis_data:\n```\n\n### Kubernetes\n\nSee `k8s/` directory for Kubernetes deployment manifests.\n\n---\n\n## 📁 Project Structure\n\n```\nfinancial-research-analyst-agent/\n├── src/\n│   ├── __init__.py\n│   ├── main.py                 # Application entry point\n│   ├── config.py               # Configuration management\n│   ├── agents/\n│   │   ├── __init__.py\n│   │   ├── base.py             # Base agent class (ReAct reasoning, confidence scoring)\n│   │   ├── orchestrator.py     # Orchestrator (cross-agent conflict detection, RAG ingestion)\n│   │   ├── rag_mixin.py        # RAG mixin for document-aware agents ✨\n│   │   ├── data_collector.py   # Data collection agent\n│   │   ├── technical.py        # Technical analysis (multi-step reasoning prompts) ✨\n│   │   ├── fundamental.py      # Fundamental analysis (SEC filings via RAG) ✨\n│   │   ├── sentiment.py        # Sentiment analysis (transcript tone analysis) ✨\n│   │   ├── risk.py             # Risk analysis (layered risk assessment) ✨\n│   │   ├── thematic.py         # Thematic investing analysis agent\n│   │   ├── disruption.py       # Market disruption analysis agent\n│   │   ├── earnings.py         # Quarterly earnings analysis agent\n│   │   └── report_generator.py # Report generation agent\n│   ├── tools/\n│   │   ├── __init__.py\n│   │   ├── market_data.py      # Market data fetching tools\n│   │   ├── news_fetcher.py     # News fetching tools\n│   │   ├── technical_indicators.py\n│   │   ├── financial_metrics.py\n│   │   ├── peer_comparison.py  # Peer discovery \u0026 comparison tools ✨\n│   │   ├── theme_mapper.py     # Theme-to-ticker mapping \u0026 analysis tools ✨\n│   │   ├── disruption_metrics.py # R\u0026D, growth, margin \u0026 disruption scoring ✨\n│   │   ├── earnings_data.py    # Quarterly earnings data \u0026 quality scoring ✨\n│   │   ├── performance_tracker.py # Multi-horizon returns \u0026 benchmark comparison ✨\n│   │   ├── sentiment_engine.py  # FinBERT/VADER financial sentiment scoring ✨\n│   │   ├── news_impact.py       # News volume, trends \u0026 source diversity ✨\n│   │   ├── event_analyzer.py   # Event calendar, price windows \u0026 pattern analysis ✨\n│   │   ├── strategy_definitions.py # 9 trading strategies (incl. mean reversion, breakout) ✨\n│   │   ├── backtesting_engine.py  # Backtest + walk-forward + multi-asset ✨\n│   │   ├── strategy_optimizer.py  # Genetic algorithm parameter tuning ✨\n│   │   ├── insight_engine.py     # Rule-based observations \u0026 ranking\n│   │   ├── llm_insight_engine.py # LLM-powered synthesis + historical context ✨\n│   │   ├── document_search.py   # RAG-powered SEC filing \u0026 transcript search ✨\n│   │   ├── macro_data.py        # FRED API: rates, CPI, GDP, yields ✨\n│   │   ├── social_sentiment.py  # Reddit sentiment + composite scoring ✨\n│   │   ├── dcf_model.py         # DCF valuation (WACC, 3 scenarios, sensitivity) ✨\n│   │   ├── ml_forecast.py       # ML price forecasting (GradientBoosting) ✨\n│   │   ├── anomaly_detector.py  # Volume/price anomalies + regime detection ✨\n│   │   ├── portfolio_optimizer.py # Markowitz, efficient frontier, risk-parity ✨\n│   │   ├── benchmark.py         # Alpha/beta/tracking error, attribution ✨\n│   │   ├── monte_carlo.py       # GBM simulation, VaR/CVaR, portfolio risk ✨\n│   │   ├── factor_model.py      # Fama-French factor decomposition ✨\n│   │   ├── brinson_attribution.py # Brinson-Fachler performance attribution ✨\n│   │   ├── tax_loss_harvesting.py # Tax-loss harvesting + wash sale warnings ✨\n│   │   ├── supply_chain.py      # Supplier/customer/competitor mapping ✨\n│   │   ├── alerts.py            # Real-time alert engine (9 types) ✨\n│   │   ├── scheduled_reports.py # Digest generation + SMTP delivery ✨\n│   │   ├── report_export.py     # PDF (reportlab) + Excel (openpyxl) export ✨\n│   │   ├── insider_activity.py   # Insider txns, institutional holdings \u0026 smart money\n│   │   └── options_analyzer.py   # Options flow, IV skew, max pain \u0026 unusual activity\n│   ├── rag/                        # RAG Pipeline ✨\n│   │   ├── __init__.py\n│   │   ├── ingester.py            # SEC EDGAR document ingestion\n│   │   ├── embedder.py            # Sentence Transformer embedding pipeline\n│   │   └── retriever.py           # Similarity search + cross-encoder re-ranking\n│   ├── data/                       # Multi-Provider Data Layer ✨\n│   │   ├── __init__.py\n│   │   ├── provider.py            # Abstract interface + YFinance + fallback wrapper\n│   │   ├── fmp_provider.py        # Financial Modeling Prep provider\n│   │   ├── alphavantage_provider.py # Alpha Vantage provider\n│   │   └── validator.py           # Data quality validation \u0026 outlier detection\n│   ├── models/\n│   │   ├── __init__.py\n│   │   ├── analysis.py         # Analysis data models\n│   │   ├── report.py           # Report data models\n│   │   └── persistence.py      # SQLAlchemy ORM: users, watchlists, portfolios, history ✨\n│   ├── api/\n│   │   ├── __init__.py\n│   │   ├── routes.py           # API routes + WebSocket alerts endpoint\n│   │   ├── schemas.py          # Pydantic schemas\n│   │   └── security.py         # API key auth, rate limiting, input sanitization ✨\n│   └── utils/\n│       ├── __init__.py\n│       ├── logger.py           # Logging utility\n│       └── helpers.py          # Helper functions\n├── tests/\n│   ├── __init__.py\n│   ├── test_agents.py\n│   ├── test_tools.py\n│   ├── test_api.py\n│   ├── test_peer_comparison.py # Peer comparison tests ✨\n│   ├── test_thematic.py        # Thematic investing tests ✨\n│   ├── test_disruption.py      # Market disruption analysis tests ✨\n│   ├── test_earnings.py        # Quarterly earnings analysis tests ✨\n│   ├── test_performance.py     # Performance tracking tests ✨\n│   ├── test_events.py          # Event-driven performance tests ✨\n│   ├── test_backtest.py        # Backtesting engine tests ✨\n│   ├── test_observations.py    # Key observations \u0026 insights tests ✨\n│   ├── test_insiders.py        # Insider \u0026 institutional activity tests ✨\n│   └── test_options.py         # Options flow analysis tests ✨\n├── frontend/                       # Streamlit web dashboard ✨\n│   ├── app.py                      # Main entry point \u0026 landing page\n│   ├── requirements.txt            # Streamlit dependencies\n│   ├── assets/style.css            # Dark/light theme CSS + mobile responsive ✨\n│   ├── pages/\n│   │   ├── 1_Dashboard.py          # Market overview \u0026 quick analysis\n│   │   ├── 2_Stock_Analysis.py     # Technical + fundamental + sentiment\n│   │   ├── 3_Thematic_Investing.py # Theme browser \u0026 analysis\n│   │   ├── 4_Peer_Comparison.py    # Side-by-side peer metrics\n│   │   ├── 5_Market_Disruption.py  # Disruption scoring\n│   │   ├── 6_Quarterly_Earnings.py # EPS tracking \u0026 quality\n│   │   ├── 7_Portfolio_Analysis.py # Multi-stock portfolio\n│   │   ├── 8_Reports.py           # Generate \u0026 download reports\n│   │   ├── 9_News.py             # Financial news feed\n│   │   ├── 10_Performance.py      # Historical performance tracking\n│   │   ├── 11_Sentiment.py       # Enhanced news \u0026 sentiment analysis\n│   │   ├── 12_ETF_Screener.py   # ETF screening \u0026 analysis\n│   │   └── 13_Macro_Economy.py  # FRED macro indicators \u0026 rate environment ✨\n│   ├── components/                 # Reusable UI components\n│   │   ├── sidebar.py              # Navigation sidebar\n│   │   ├── charts.py               # TradingView chart wrappers\n│   │   ├── plotly_charts.py        # Plotly visualizations\n│   │   ├── metrics_cards.py        # KPI cards \u0026 badges\n│   │   └── data_tables.py          # Styled dataframes\n│   └── utils/\n│       ├── data_service.py         # Cached tool wrappers\n│       ├── formatters.py           # Number/date formatting\n│       ├── theme.py                # Dark/light theme toggle + CSS injection ✨\n│       └── session.py              # Session state management\n├── data/\n│   └── sample_data.csv\n├── docs/\n│   ├── ARCHITECTURE.md         # System architecture design document ✨\n│   ├── IMPLEMENTATION_PLAN.md  # 4-phase implementation roadmap ✨\n│   ├── GAP_ANALYSIS.md         # Gap analysis vs smart financial analyzer ✨\n│   └── SCOPE.md                # Feature scope \u0026 enhancement roadmap\n├── notebooks/\n│   └── exploration.ipynb\n├── static/\n│   └── dashboard/\n├── config/\n│   ├── agents.yaml             # Agent configuration\n│   └── themes.yaml             # Investment theme definitions ✨\n├── .env.example\n├── requirements.txt\n├── Dockerfile\n├── docker-compose.yml\n└── README.md\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- [LangChain](https://langchain.com/) - AI Agent Framework\n- [Ollama](https://ollama.ai/) - Local LLM Inference\n- [Yahoo Finance](https://finance.yahoo.com/) - Market Data (Primary)\n- [Financial Modeling Prep](https://financialmodelingprep.com/) - Financial Data API\n- [Alpha Vantage](https://www.alphavantage.co/) - Financial Data API\n- [FRED](https://fred.stlouisfed.org/) - Federal Reserve Economic Data\n- [ChromaDB](https://www.trychroma.com/) - Vector Store for RAG\n- [Sentence Transformers](https://www.sbert.net/) - Embeddings\n- [scikit-learn](https://scikit-learn.org/) - ML Forecasting\n- [SciPy](https://scipy.org/) - Portfolio Optimization\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Created by 🤖 Antigravity AI (Google DeepMind)**\n\n**Author: Gopal Saini**\n\n_Part of the AI Agents Case Studies Collection_\n\n[⬆ Back to Top](#-financial-research-analyst-agent)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsaini%2Ffinancial-research-analyst-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgsaini%2Ffinancial-research-analyst-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsaini%2Ffinancial-research-analyst-agent/lists"}