{"id":33329356,"url":"https://github.com/akhilkarra/investilearn","last_synced_at":"2026-04-18T00:32:21.921Z","repository":{"id":323955640,"uuid":"1095390944","full_name":"akhilkarra/investilearn","owner":"akhilkarra","description":"Research the health and value of any stock. With the help of an LLM guide.","archived":false,"fork":false,"pushed_at":"2026-04-06T16:30:09.000Z","size":336,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T18:24:47.161Z","etag":null,"topics":["data-visualization","finance","financial-data","fundamental-analysis","investment","investment-analysis","plotly","portfolio-management","python","stock-analysis","stock-market","streamlit","streamlit-app","yfinance"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akhilkarra.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":".github/CODEOWNERS","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-13T01:42:35.000Z","updated_at":"2025-12-08T05:14:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akhilkarra/investilearn","commit_stats":null,"previous_names":["akhilkarra/investilearn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akhilkarra/investilearn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akhilkarra%2Finvestilearn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akhilkarra%2Finvestilearn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akhilkarra%2Finvestilearn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akhilkarra%2Finvestilearn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akhilkarra","download_url":"https://codeload.github.com/akhilkarra/investilearn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akhilkarra%2Finvestilearn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31951321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"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":["data-visualization","finance","financial-data","fundamental-analysis","investment","investment-analysis","plotly","portfolio-management","python","stock-analysis","stock-market","streamlit","streamlit-app","yfinance"],"created_at":"2025-11-20T16:02:13.042Z","updated_at":"2026-04-18T00:32:21.902Z","avatar_url":"https://github.com/akhilkarra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InvestiLearn - AI-Powered Fundamental Investment Education Platform\n\nAn interactive educational dashboard that teaches fundamental investing principles through real company data analysis, powered by local AI models and machine learning.\n\n[![CI/CD Pipeline](https://github.com/akhilkarra/investilearn/actions/workflows/ci.yml/badge.svg)](https://github.com/akhilkarra/investilearn/actions/workflows/ci.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\n## 🎯 Project Overview\n\n**InvestiLearn** is a comprehensive educational platform designed to teach fundamental investing concepts through hands-on analysis of real financial data. The application combines traditional financial analysis tools with cutting-edge AI assistance to create an interactive learning environment.\n\n### Key Differentiators\n\n- 🧠 **Local AI Models**: All AI processing runs locally - no external API calls, complete privacy\n- 🎓 **Education-First**: Designed for learning, not investment advice\n- 🔍 **Transparent AI**: Every AI decision includes explanations and confidence levels\n- 📊 **Real Data**: Live financial data from Yahoo Finance\n- 💬 **Interactive Coach**: Context-aware LLM guidance using Ollama\n\n## ✨ Features\n\n### Core Analytics\n- 🔍 **Company Search**: Intelligent search for companies by name or ticker symbol\n- 📊 **Financial Statements**: Interactive Sankey flow diagrams showing money movement\n  - Income Statement visualization\n  - Cash Flow analysis\n  - Balance Sheet structure\n- 📐 **Financial Ratios**: 20+ key metrics with industry comparisons\n  - Profitability ratios (ROE, ROA, margins)\n  - Liquidity ratios (Current, Quick)\n  - Efficiency ratios (Asset turnover, inventory)\n  - Leverage ratios (Debt/Equity, Interest coverage)\n  - Valuation ratios (P/E, P/B, PEG)\n\n### AI-Powered Learning\n- 💬 **LLM Investment Coach**: Interactive Q\u0026A powered by Ollama (qwen2.5:14b)\n  - Context-aware explanations of metrics and concepts\n  - Company-specific analysis with full financial context\n  - Confidence-based filtering (High/Medium/Low)\n  - Streaming responses with interrupt capability\n  - Article-specific news analysis\n- 📰 **AI News Ranking**: Machine learning-powered news curation\n  - Semantic similarity using sentence-transformers\n  - Financial sentiment analysis with FinBERT\n  - Source credibility scoring\n  - Recency and relevance weighting\n  - Transparent scoring breakdowns\n- 🎯 **Smart Recommendations**: Context-aware suggestions throughout the UI\n  - Metric-specific help buttons\n  - Statement-level guidance\n  - Article interpretation assistance\n\n### Educational Tools\n- 📚 **Interactive Learning Guides**:\n  - Getting Started tutorial\n  - Fundamental investing principles\n  - How AI assists you\n  - Quick tips and best practices\n- 💡 **Contextual Explanations**: Click ❓ anywhere for instant learning\n- 🎨 **Confidence Indicators**: Visual cues for AI reliability (🟢🟡🔴)\n- 📖 **Additional Resources**: Curated external learning materials\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Python 3.10 or higher**\n- **[uv](https://github.com/astral-sh/uv)** (recommended) or pip\n- **[Ollama](https://ollama.ai)** for LLM Coach feature\n\n### Step 1: Install Dependencies\n\n#### Option A: Using uv (Recommended)\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone git@github.com:akhilkarra/investilearn.git\ncd investilearn\n\n# Create virtual environment and install dependencies\nuv venv\nsource .venv/bin/activate  # On macOS/Linux\n# or .venv\\Scripts\\activate on Windows\n\n# Install all dependencies\nuv sync\n```\n\n#### Option B: Using pip\n\n```bash\ngit clone git@github.com:akhilkarra/investilearn.git\ncd investilearn\npip install -r requirements.txt\n```\n\n### Step 2: Install Ollama and Download LLM Model\n\nThe LLM Coach feature requires Ollama with the qwen2.5:14b model:\n\n```bash\n# Install Ollama (macOS/Linux)\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# For macOS, you can also use Homebrew\nbrew install ollama\n\n# Start Ollama service\nollama serve\n\n# In a new terminal, download the model (one-time setup, ~9GB)\nollama pull qwen2.5:14b\n```\n\n**Note**: The model download is ~9GB and may take several minutes depending on your connection.\n\n### Step 3: Install ML Models (Optional)\n\nFor enhanced news ranking with semantic similarity and sentiment analysis:\n\n```bash\n# First run will automatically download models:\n# - sentence-transformers/all-MiniLM-L6-v2 (~80MB)\n# - ProsusAI/finbert (~440MB)\n\n# You can disable ML models in the UI if you prefer rule-based ranking\n```\n\n### Step 4: Run the Application\n\n```bash\n# Make sure Ollama is running in the background\n# (run 'ollama serve' in a separate terminal if needed)\n\n# Start the dashboard\nuv run streamlit run dashboard.py\n\n# Or if using traditional venv\nstreamlit run dashboard.py\n```\n\nOpen your browser to `http://localhost:8501` (should open automatically)\n\n### Troubleshooting\n\n**Ollama Connection Issues:**\n\n```bash\n# Check if Ollama is running\ncurl http://localhost:11434/api/tags\n\n# If not running, start it\nollama serve\n```\n\n**Model Not Found:**\n\n```bash\n# List installed models\nollama list\n\n# If qwen2.5:14b is missing\nollama pull qwen2.5:14b\n```\n\n**ML Models Disabled:**\n- You can still use the app with ML features turned off\n- Toggle \"🧠 News ML Models\" in the sidebar to disable/enable\n\n## 📁 Project Structure\n\n```text\ninvestilearn/\n├── dashboard.py                      # Main Streamlit application entry point\n├── utils/                            # Core utility modules\n│   ├── __init__.py                  # Package initialization\n│   ├── cache_warmer.py              # Sector-based data caching system\n│   ├── data_fetcher.py              # Yahoo Finance API integration\n│   ├── llm_coach.py                 # Ollama LLM wrapper for coaching\n│   ├── model_loader.py              # ML model initialization and caching\n│   ├── news_ai.py                   # News ranking with ML/rule-based scoring\n│   ├── ratio_calculator.py          # Financial ratio computations\n│   ├── visualizations.py            # Plotly Sankey diagram generation\n│   └── ui/                          # UI component modules\n│       ├── __init__.py\n│       ├── coach_panel.py           # LLM coach modal dialog\n│       ├── financial_statements.py  # Statement visualizations\n│       ├── header.py                # Company header component\n│       ├── landing.py               # Landing page and resources\n│       ├── news.py                  # News section with AI ranking\n│       ├── ratios.py                # Ratio analysis and comparisons\n│       ├── settings.py              # Settings panel (legacy)\n│       └── sidebar.py               # Sidebar with quick tips\n├── tests/                           # Test suite\n│   ├── __init__.py\n│   ├── test_data_fetcher.py        # Data fetching tests\n│   ├── test_llm_coach.py           # LLM coach tests\n│   ├── test_news_ai.py             # News AI tests\n│   └── test_ratio_calculator.py    # Ratio calculation tests\n├── .github/workflows/               # CI/CD pipelines\n│   └── ci.yml                      # GitHub Actions workflow\n├── pyproject.toml                   # Project configuration and dependencies\n├── requirements.txt                 # Frozen dependencies for pip\n├── README.md                        # This file\n├── CONTRIBUTING.md                  # Development guidelines\n└── LICENSE                          # MIT License\n```\n\n## 🛠️ Tech Stack\n\n### Core Framework \u0026 UI\n\n- **[Streamlit 1.39+](https://streamlit.io)**: Interactive web dashboard framework\n  - Custom CSS for AI badges and styling\n  - Modal dialog system for coach and settings\n  - Session state management for UI flow\n  - Responsive layout with columns and tabs\n\n### Data \u0026 Finance\n\n- **[yfinance](https://github.com/ranaroussi/yfinance)**: Yahoo Finance API wrapper\n  - Real-time and historical stock data\n  - Financial statements (Income, Balance, Cash Flow)\n  - Company info and sector classifications\n  - News article feeds\n- **[Pandas 2.2+](https://pandas.pydata.org)**: Data manipulation and analysis\n  - Financial statement processing\n  - Ratio calculations\n  - Time-series analysis\n- **[Plotly 5.24+](https://plotly.com/python/)**: Interactive visualizations\n  - Custom Sankey diagrams for financial flows\n  - Responsive charts with hover details\n\n### AI \u0026 Machine Learning\n\n- **[Ollama](https://ollama.ai)** + **qwen2.5:14b**: Local LLM for investment coaching\n  - 100% local inference, no external API calls\n  - Streaming responses with interrupt capability\n  - Context-aware explanations\n  - Confidence estimation\n- **[sentence-transformers](https://www.sbert.net)**: Semantic similarity\n  - Model: `all-MiniLM-L6-v2`\n  - Used for news article relevance scoring\n  - Embedding-based company-article matching\n- **[transformers](https://huggingface.co/transformers)** + **FinBERT**: Financial sentiment analysis\n  - Model: `ProsusAI/finbert`\n  - Domain-specific sentiment for financial text\n  - News article sentiment scoring\n\n### Development Tools\n\n- **[uv](https://github.com/astral-sh/uv)**: Ultra-fast Python package manager\n  - Dependency resolution and management\n  - Virtual environment creation\n  - Lock file generation\n- **[Ruff](https://github.com/astral-sh/ruff)**: Lightning-fast linting and formatting\n  - Replaces flake8, isort, black\n  - Auto-fixing capabilities\n  - ~10-100x faster than alternatives\n- **[mypy](http://mypy-lang.org)**: Static type checking\n  - Type hints validation\n  - Improved code reliability\n- **[pytest](https://pytest.org)**: Testing framework\n  - Unit tests for core functionality\n  - Mocking for external dependencies\n- **[pre-commit](https://pre-commit.com)**: Git hooks for code quality\n  - Automatic linting on commit\n  - Format checking\n\n### Code Attribution \u0026 Open Source Usage\n\nThis project was built from scratch with the following open-source libraries:\n\n**No base template or starter code was used.** All application logic, UI components, and AI integration were developed specifically for this project.\n\n#### External Libraries Used (via pip/uv)\n\n1. **Data \u0026 Visualization Libraries** (Standard usage, no modifications):\n   - `streamlit` - Web framework (official API usage)\n   - `yfinance` - Financial data fetching (official API usage)\n   - `pandas` - Data manipulation (standard library usage)\n   - `plotly` - Charting library (standard API usage)\n\n2. **AI/ML Libraries** (Standard usage, no modifications):\n   - `ollama` - LLM client library (official Python SDK)\n   - `transformers` - Hugging Face model interface (standard API)\n   - `sentence-transformers` - Sentence embeddings (standard API)\n   - `torch` - PyTorch backend for ML models (dependency)\n\n3. **Development Tools** (Standard usage):\n   - `pytest`, `mypy`, `ruff`, `pre-commit` - Standard development tools\n\n#### Custom Code Developed (100% Original)\n\nAll code in `dashboard.py` and `utils/` directory is original work, including:\n\n- **LLM Coach System** (`utils/llm_coach.py`): Custom wrapper around Ollama with:\n  - Context building from financial data\n  - Confidence estimation algorithm\n  - Streaming response handling\n  - Educational prompt engineering\n\n- **News AI Ranking** (`utils/news_ai.py`): Original ML-powered ranking system:\n  - Hybrid scoring (ML + rule-based)\n  - Semantic similarity implementation\n  - Multi-factor weighting algorithm\n  - Transparent score breakdown\n\n- **Financial Analysis** (`utils/ratio_calculator.py`, `utils/data_fetcher.py`):\n  - Custom ratio calculations beyond yfinance defaults\n  - 5-year historical averaging\n  - Industry comparison logic\n  - Data cleaning and validation\n\n- **UI Components** (`utils/ui/*.py`): Complete custom UI system:\n  - Modal dialog implementation\n  - Coach panel with confidence filtering\n  - News section with AI explanations\n  - Ratio visualizations with context\n  - Interactive Sankey diagrams for statements\n\n- **Caching System** (`utils/cache_warmer.py`): Custom sector-based caching:\n  - S\u0026P 500 company pre-loading\n  - Intelligent cache warming\n  - Performance optimization\n\n**Lines of Code**: ~4,500 lines of original Python code (excluding tests and documentation)\n\n**AI Usage Transparency**: GitHub Copilot was used as a coding assistant during development, primarily for:\n\n- Boilerplate code generation\n- Documentation string formatting\n- Test case scaffolding\n- Type hint suggestions\n\nAll core algorithms, architecture decisions, and business logic were human-designed and implemented.\n\n## 🗺️ Roadmap\n\n### ✅ Phase 1: Foundation (Completed)\n\n- [x] Project structure and development environment\n- [x] CI/CD pipeline with GitHub Actions\n- [x] Pre-commit hooks for code quality\n- [x] Documentation (README, CONTRIBUTING)\n- [x] Basic Streamlit UI framework\n\n### ✅ Phase 2: Core Analytics (Completed)\n\n- [x] Yahoo Finance integration for real-time data\n- [x] Financial statement Sankey diagrams\n- [x] 20+ financial ratio calculations\n- [x] Industry benchmark comparisons\n- [x] 5-year historical trend analysis\n- [x] Company search and data caching\n\n### ✅ Phase 3: AI Features (Completed)\n\n- [x] **LLM Coach Integration** - Ollama-powered investment guidance\n- [x] **ML News Ranking** - Semantic similarity and sentiment analysis\n- [x] **Confidence Filtering** - Transparent AI reliability indicators\n- [x] **Context-Aware Help** - Metric and statement-specific coaching\n- [x] **Interactive Dialogs** - Modal system for coach and settings\n\n### ✅ Phase 4: Polish \u0026 UX (Completed)\n\n- [x] Educational landing page and guides\n- [x] Responsive UI with improved accessibility\n- [x] Comprehensive error handling\n- [x] Session state management optimization\n- [x] All linting errors resolved (644+ fixes)\n\n### 🎯 Future Enhancements (Optional)\n\n- [ ] Portfolio tracking and comparison\n- [ ] Historical performance backtesting\n- [ ] Export functionality (PDF reports)\n- [ ] Multi-company side-by-side comparison\n- [ ] Custom ratio calculator\n- [ ] Screener for finding companies by criteria\n\n## 💻 Usage Guide\n\n### First Time Setup\n\n1. **Start Ollama** (required for LLM Coach):\n\n   ```bash\n   ollama serve\n   ```\n\n2. **Launch the Dashboard**:\n\n   ```bash\n   uv run streamlit run dashboard.py\n   ```\n\n3. **Navigate to** `http://localhost:8501`\n\n### Using the Dashboard\n\n1. **Search for a Company**:\n   - Enter ticker (e.g., \"AAPL\") or company name (e.g., \"Apple\")\n   - Press Enter to load company data\n\n2. **Explore Financial Data**:\n   - **Financial Statements Tab**: View interactive Sankey diagrams\n   - **Ratios Tab**: Compare metrics against industry averages\n   - **News Tab**: See AI-ranked relevant articles\n\n3. **Ask the Coach**:\n   - Click 💬 button next to any metric for explanations\n   - Use sidebar \"Ask the Coach\" for general questions\n   - Filter responses by confidence level\n\n4. **Configure AI Settings**:\n   - Toggle AI features on/off in sidebar\n   - Enable/disable ML models for news ranking\n   - Adjust confidence thresholds\n\n### Tips for Best Experience\n\n- **Start with familiar companies** - Easier to learn when you know the business\n- **Check confidence levels** - Use 🟢 High confidence for learning fundamentals\n- **Explore ratios** - Click ❓ to understand what each metric means\n- **Compare with industry** - Look for companies that outperform peers\n- **Read AI explanations** - Understand WHY articles are ranked as they are\n\n## 🧪 Development Setup\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.\n\n### Quick Development Setup\n\n```bash\n# Install with development dependencies\nuv sync --all-extras\n\n# Install pre-commit hooks\nuv run pre-commit install\n\n# Run the app in development mode\nuv run streamlit run dashboard.py\n```\n\n### Code Quality Tools\n\n```bash\n# Lint and auto-fix issues\nuv run ruff check . --fix\n\n# Format code\nuv run ruff format .\n\n# Type checking\nuv run mypy dashboard.py utils/\n\n# Run tests with coverage\nuv run pytest --cov=utils --cov-report=html\n\n# Run pre-commit checks manually\nuv run pre-commit run --all-files\n```\n\n### Testing\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test file\nuv run pytest tests/test_llm_coach.py\n\n# Run with verbose output\nuv run pytest -v\n\n# Generate coverage report\nuv run pytest --cov=utils --cov-report=term-missing\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Fork the repository** and create a feature branch\n2. **Follow code style**: Run `ruff format` before committing\n3. **Add tests**: Maintain \u003e80% code coverage\n4. **Update docs**: Keep README and docstrings current\n5. **Submit a PR**: Include description of changes\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## ⚠️ Disclaimer\n\n**This is an educational tool, not investment advice.**\n\n- No investment recommendations\n- No price predictions\n- No guarantee of data accuracy\n- Always verify with official SEC filings\n- Consult licensed financial advisors for personal advice\n\nAll financial data is delayed 15-20 minutes and sourced from Yahoo Finance API.\n\n## 🙏 Acknowledgments\n\n- **[Yahoo Finance](https://finance.yahoo.com)** for financial data API\n- **[Ollama](https://ollama.ai)** for local LLM infrastructure\n- **[Qwen Team](https://qwenlm.github.io)** for the qwen2.5 model\n- **[Hugging Face](https://huggingface.co)** for transformer models\n- **[Streamlit](https://streamlit.io)** for the amazing web framework\n\n## 📞 Contact \u0026 Support\n\n- **Issues**: [GitHub Issues](https://github.com/akhilkarra/investilearn/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/akhilkarra/investilearn/discussions)\n- **Author**: Akhil Karra ([@akhilkarra](https://github.com/akhilkarra))\n\n---\n\n**Built for long-term fundamental investors** 📈\n\n**Learn by doing. Invest with confidence.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakhilkarra%2Finvestilearn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakhilkarra%2Finvestilearn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakhilkarra%2Finvestilearn/lists"}