A comprehensive financial analysis application with advanced income statement, balance sheet, and cash flow analysis powered by FinBERT sentiment analysis and GPU acceleration via Modal.
# Install dependencies
pip install -r requirements.txt
# Run the app locally
python src/main.pyThe Gradio UI will launch at http://localhost:7860
- Financial Statement Parsing: Automated extraction from Excel files (IAS-compliant)
- Advanced Ratio Analysis: 20+ financial metrics (profitability, liquidity, efficiency)
- Sentiment Analysis: FinBERT-powered tone analysis for financial documents
- GPU Acceleration: NVIDIA A10G GPU support via Modal for fast processing
- Multi-currency Support: Full support for KES (Kenyan Shilling) and other currencies
- Interactive UI: Gradio-based interface for easy file uploads and analysis
fin_forecasting/
├── src/
│ ├── main.py # Application entry point
│ ├── frontend/
│ │ └── gradio_app.py # Gradio UI
│ └── backend/
│ ├── agent_logic.py # Main analysis logic
│ ├── modal_server.py # Modal GPU deployment
│ └── mcp/ # Analysis modules
│ ├── parsing.py
│ ├── ratios.py
│ ├── sentiment.py
│ ├── forecasting.py
│ └── extraction.py
├── financials/ # Financial data (2020-2024)
├── requirements.txt
└── documentation/ # Full guides and references
- Balance Sheet Analysis: Asset composition, leverage ratios, working capital
- Income Statement Analysis: Revenue trends, profitability margins, cost structure
- Cash Flow Analysis: Operating cash flow, financing activities, liquidity metrics
- Advanced Ratios: ROE, ROA, debt-to-equity, current ratio, efficiency metrics
- Trend Analysis: Year-over-year comparisons, moving averages, forecasting
- Sentiment Analysis: Tone detection in financial documents
- Extraction: Automated line item identification and normalization
python src/main.pyOption 1: Gradio Web App (Recommended - Interactive UI)
./deploy_modal_gradio.shOpens an interactive web interface at: https://hf-hackathon-mcp--samani-web.modal.run
Option 2: Backend Only (API - For integrations)
./deploy_modal.shDeploys compute backend only (no web UI)
View deployment guides: documentation/MODAL_DEPLOYMENT_GUIDE.md and documentation/MODAL_GRADIO_LIVE.md
All comprehensive guides are in the documentation/ folder:
| Document | Purpose |
|---|---|
| MODAL_QUICK_START.md | 5-minute deployment guide |
| MODAL_DEPLOYMENT_GUIDE.md | Complete deployment reference |
| MODAL_INDEX.md | Navigation for 3 deployment paths |
| QUICK_START.md | Getting started guide |
| TECHNICAL_REFERENCE.md | Architecture & API reference |
| IMPLEMENTATION_SUMMARY.md | Feature implementation details |
| ENHANCEMENT_GUIDE.md | Extension & customization |
| DEPLOYMENT_CHECKLIST.md | Pre-deployment verification |
| DELIVERY_SUMMARY.md | Full development summary |
- Python 3.9+
- torch >= 2.6.0
- transformers
- pandas, openpyxl
- gradio >= 4.0
- Modal (for GPU deployment)
HF_TOKEN=<your_huggingface_token> # For FinBERT
MODAL_TOKEN_ID=<your_modal_token> # For GPU deployment
OPEN_AI_API_TOKEN=<optional> # For extended featuresDefault currency: KES (Kenyan Shilling)
All financial values are in thousands (KES '000)
Sample data included for fiscal years 2020-2024:
- Statement of Financial Position (Balance Sheet)
- Statement of Profit or Loss (Income Statement)
- Statement of Cash Flows
Add your own Excel files to the financials/ folder organized by year.
- Financial statement analysis and interpretation
- Trend identification and forecasting
- Ratio-based company valuation
- Sentiment tracking in financial reports
- Multi-year comparative analysis
- Risk assessment and monitoring
- Local: ~2-5 seconds per analysis
- GPU (Modal A10G): <1 second per analysis with FinBERT
See Fin_analysis/LICENSE for details
For deployment issues, refer to documentation/MODAL_DEPLOYMENT_GUIDE.md
For feature details, see documentation/TECHNICAL_REFERENCE.md
Status: Production-ready with GPU acceleration ✅