{"id":35134732,"url":"https://github.com/its-me-koustubhya/financial-report-generator","last_synced_at":"2026-04-13T12:01:23.192Z","repository":{"id":329954467,"uuid":"1099551723","full_name":"its-me-koustubhya/financial-report-generator","owner":"its-me-koustubhya","description":"AI agent system for generating financial analysis reports using LangGraph and LLMs","archived":false,"fork":false,"pushed_at":"2025-12-23T06:47:57.000Z","size":290,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-03T01:32:20.333Z","etag":null,"topics":["financial-analysis","groq","langchain","langgraph-agents","llama","multi-agent-system","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/its-me-koustubhya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-11-19T06:17:43.000Z","updated_at":"2025-12-23T06:48:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/its-me-koustubhya/financial-report-generator","commit_stats":null,"previous_names":["its-me-koustubhya/financial-report-generator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/its-me-koustubhya/financial-report-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-me-koustubhya%2Ffinancial-report-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-me-koustubhya%2Ffinancial-report-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-me-koustubhya%2Ffinancial-report-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-me-koustubhya%2Ffinancial-report-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/its-me-koustubhya","download_url":"https://codeload.github.com/its-me-koustubhya/financial-report-generator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/its-me-koustubhya%2Ffinancial-report-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["financial-analysis","groq","langchain","langgraph-agents","llama","multi-agent-system","python"],"created_at":"2025-12-28T08:08:52.872Z","updated_at":"2026-04-13T12:01:23.180Z","avatar_url":"https://github.com/its-me-koustubhya.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 AI Financial Report Generator - Production API\n\n\u003e **Live Production API**: https://financial-report-generator-production.up.railway.app\n\n\u003cdiv align=\"center\"\u003e\n\nAn intelligent multi-user AI application that generates comprehensive financial analysis reports using LangGraph workflows and real-time web search.\n\n[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.126+-green.svg)](https://fastapi.tiangolo.com)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-blue.svg)](https://postgresql.org)\n[![Deployed on Railway](https://img.shields.io/badge/Deployed-Railway-blueviolet.svg)](https://railway.app)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 What It Does\n\nThis production-ready application automatically generates financial analysis reports for any public company by:\n\n- **Web Searching** for current financial data (Tavily API)\n- **AI Analysis** using multi-agent workflows (LangGraph + Groq/Llama 3.3)\n- **Report Generation** with structured insights and citations\n- **Multi-User Support** with authentication and background processing\n\n### Key Features\n\n✅ **Production Deployment** - Live on Railway with PostgreSQL  \n✅ **Multi-User Architecture** - JWT authentication, user-specific API keys  \n✅ **Background Processing** - Asynchronous report generation (no blocking)  \n✅ **Status Polling** - Real-time status updates for long-running operations  \n✅ **Thread-Safe** - Factory pattern for concurrent user requests  \n✅ **RESTful API** - Complete API with Swagger documentation\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│              FastAPI Backend (Railway)              │\n│  ┌───────────────────────────────────────────────┐  │\n│  │  Authentication (JWT)                         │  │\n│  │  User API Key Management                      │  │\n│  │  Background Task Processing                   │  │\n│  └───────────────────────────────────────────────┘  │\n└──────────────────┬──────────────────────────────────┘\n                   │\n     ┌─────────────┼─────────────┐\n     │             │             │\n     ▼             ▼             ▼\n┌──────────┐  ┌───────────┐  ┌──────────┐\n│PostgreSQL│  │ LangGraph │  │Web Search│\n│ Database │  │Multi-Agent│  │ (Tavily) │\n│ (Users,  │  │ Workflow  │  │   API    │\n│ Reports) │  │           │  │          │\n└──────────┘  └───────────┘  └──────────┘\n```\n\n**Agent Workflow**\n\n```mermaid\ngraph TD\n    A[User Input] --\u003e B[Data Collector Agent]\n    B --\u003e C[Analyst Agent]\n    C --\u003e D{Quality Check}\n    D --\u003e|Pass| E[Writer Agent]\n    D --\u003e|Fail| F[Retry Collection]\n    F --\u003e B\n    E --\u003e G[Editor Agent]\n    G --\u003e H{Report Quality Check}\n    H --\u003e|Pass| I[Final Report]\n    H --\u003e|Fail| J[Retry Writing]\n    J --\u003e E\n    D --\u003e|Max Retries| K[Early Exit]\n    K --\u003e L[Disclaimer Report]\n```\n\n### Agents handling differnt tasks\n\n| Agent               | Temperature | Purpose                                                 |\n| ------------------- | ----------- | ------------------------------------------------------- |\n| **Data Collector**  | 0.1         | Searches web, generates queries, collects data          |\n| **Analyst**         | 0.3         | Extracts metrics, identifies trends, generates insights |\n| **Writer**          | 0.5         | Creates structured report with professional tone        |\n| **Editor**          | 0.2         | Polishes grammar, formatting, and consistency           |\n| **Quality Checker** | -           | Validates outputs and triggers retries                  |\n\n---\n\n## 🚀 Live Demo\n\n### API Endpoints\n\n**Base URL**: `https://financial-report-generator-production.up.railway.app`\n\n#### Authentication\n\n```bash\n# Register\nPOST /auth/register\nBody: {\"email\": \"user@example.com\", \"username\": \"user\", \"password\": \"password123\"}\n\n# Login\nPOST /auth/login\nBody: {\"email\": \"user@example.com\", \"password\": \"password123\"}\nReturns: {\"access_token\": \"eyJ...\", \"token_type\": \"bearer\"}\n\n# Set API Keys\nPUT /auth/api-keys\nHeaders: Authorization: Bearer \u003ctoken\u003e\nBody: {\"groq_api_key\": \"gsk_...\", \"tavily_api_key\": \"tvly-...\"}\n```\n\n#### Report Generation\n\n```bash\n# Generate Report (Returns immediately with status=pending)\nPOST /reports/generate\nHeaders: Authorization: Bearer \u003ctoken\u003e\nBody: {\"company_name\": \"Tesla\"}\nReturns: {\"id\": 1, \"status\": \"pending\", \"company_name\": \"Tesla\"}\n\n# Check Status\nGET /reports/1\nHeaders: Authorization: Bearer \u003ctoken\u003e\nReturns: {\"id\": 1, \"status\": \"success\", \"report_content\": \"# Financial Analysis...\"}\n\n# Get All Reports\nGET /reports/\nHeaders: Authorization: Bearer \u003ctoken\u003e\n```\n\n### Try It Now\n\n**Interactive API Documentation**: https://financial-report-generator-production.up.railway.app/docs\n\n---\n\n## 💻 Tech Stack\n\n### Backend\n\n- **FastAPI** - Modern async web framework\n- **PostgreSQL** - User data and report storage\n- **SQLAlchemy** - ORM for database operations\n- **Pydantic** - Data validation and settings\n- **JWT** - Token-based authentication\n\n### AI/ML\n\n- **LangGraph** - Multi-agent workflow orchestration\n- **LangChain** - LLM application framework\n- **Groq API** - Ultra-fast LLM inference (Llama 3.3 70B)\n- **Tavily API** - Real-time web search\n\n### Infrastructure\n\n- **Railway** - Cloud deployment platform\n- **Docker** - Containerization (implicit via Railway)\n- **Background Tasks** - FastAPI BackgroundTasks for async processing\n\n---\n\n## 📊 Example Output\n\n```markdown\n# Financial Analysis Report\n\n**Company:** Tesla\n**Generated:** 2024-12-22\n**Status:** Complete\n\n## Executive Summary\n\nTesla demonstrated strong financial performance in 2024 with revenue\nreaching $97.69B and profit of $1.13B. The company's growth rate was\nmodest at 0.95%...\n\n## Key Metrics\n\n- **Revenue**: $97.69B\n- **Net Income**: $1.13B\n- **Growth Rate**: 0.95%\n\n[Full report with 6 sections including market analysis, competitive\nlandscape, and strategic observations]\n```\n\n---\n\n## 🔧 Local Development Setup\n\n### Prerequisites\n\n- Python 3.11+\n- PostgreSQL 14+\n- API Keys: [Groq](https://console.groq.com/), [Tavily](https://tavily.com/)\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/its-me-koustubhya/financial-report-generator.git\ncd financial-report-generator\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # 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 DATABASE_URL, SECRET_KEY, GROQ_API_KEY, TAVILY_API_KEY\n\n# Initialize database\npython -c \"from database.init_db import init_database; init_database()\"\n\n# Run server\nuvicorn main_api:app --reload\n```\n\nVisit: `http://localhost:8000/docs`\n\n---\n\n## 🧪 Testing\n\n```bash\n# Health check\ncurl https://financial-report-generator-production.up.railway.app/health\n\n# Full workflow test (requires auth)\npython test_background.py\n```\n\n---\n\n## 📁 Project Structure\n\n```\nfinancial-report-generator/\n├── main_api.py              # FastAPI application entry point\n├── config.py                # Pydantic settings with validation\n├── Procfile                 # Railway deployment config\n├── railway.json             # Railway build configuration\n├── requirements.txt         # Python dependencies\n├── database/\n│   ├── models.py            # SQLAlchemy models (User, Report)\n│   ├── connection.py        # Database session management\n│   └── init_db.py           # Database initialization\n├── auth/\n│   ├── routes.py            # Auth endpoints\n│   ├── utils.py             # JWT, password hashing\n│   ├── schemas.py           # Pydantic models\n│   └── dependencies.py      # Auth middleware\n├── reports/\n│   └── routes.py            # Report CRUD + generation\n├── agents/\n│   ├── data_collector.py    # Web search agent\n│   ├── analyst.py           # Analysis agent\n│   ├── writer.py            # Report writer\n│   └── editor.py            # Editing agent\n└── graph/\n    └── workflow.py          # LangGraph orchestration\n```\n\n---\n\n## 🎓 Technical Highlights\n\n### 1. Thread-Safe API Key Management\n\n- **Factory Pattern** for LLM instantiation\n- User-specific API keys passed through workflow\n- No shared global state\n\n### 2. Background Processing\n\n- `BackgroundTasks` for async report generation\n- Status polling pattern (industry standard)\n- Non-blocking user experience\n\n### 3. Multi-User Architecture\n\n- JWT authentication with expiry\n- User data isolation via foreign keys\n- Concurrent request handling\n\n### 4. Production Best Practices\n\n- Pydantic Settings for config validation\n- Proper error handling and logging\n- Database connection pooling\n- Environment-based configuration\n\n---\n\n## 🚧 Future Enhancements\n\n- [ ] Rate limiting per user\n- [ ] Report caching for duplicate requests\n- [ ] Email notifications on completion\n- [ ] Export to PDF\n- [ ] Frontend dashboard (React/Streamlit)\n- [ ] WebSocket for real-time updates\n- [ ] Cost tracking per user\n\n---\n\n## 👤 Author\n\n**Koustubhya Singh**  \nAspiring Data Analyst \u0026 Python Developer\n\n- GitHub: [@its-me-koustubhya](https://github.com/its-me-koustubhya)\n- LinkedIn: [koustubhya-singh](https://linkedin.com/in/koustubhya-singh)\n- Email: singh10api@gmail.com\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ If you found this helpful, please star the repo!**\n\n**Built with FastAPI, LangGraph, PostgreSQL, and deployed on Railway**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fits-me-koustubhya%2Ffinancial-report-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fits-me-koustubhya%2Ffinancial-report-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fits-me-koustubhya%2Ffinancial-report-generator/lists"}