FinDocMadeEz

Problem statement (one line): FinDocMadeEz is an interactive decision-support prototype that maps financial documents and market data into question answering, heuristic forecasting, and rule-based investment recommendations.

Architecture / approach

The system is implemented as a modular, stateful Streamlit application (src/enhanced_streamlit_app.py) with cached singleton components (@st.cache_resource) and eight analysis pages.

1) Document ingestion and metric extraction

• PDF parsing: PyMuPDF (fitz) in src/document_processor.py.
• Text normalization: regex whitespace cleanup and page-marker stripping.
• Financial metric extraction: rule/regex-based pattern matching for revenue, net income, assets, liabilities, debt, equity; derived ratio computation (profit_margin, debt_to_equity, return_on_equity) in src/ai_analyzer.py.
• Optional LLM augmentation: OpenRouter Chat Completions via openai client (deepseek/deepseek-chat-v3-0324:*) for long-form analysis and JSON-style extraction fallback.

2) FinanceBench Q&A and sentiment pipeline

• Data source: JSONL FinanceBench files loaded with pandas (data/financebench_open_source.jsonl, data/financebench_document_information.jsonl).
• Runtime retrieval in app (SimpleRAGEngine):
  • approximate question matching via difflib.SequenceMatcher ratio thresholding;
  • lexical evidence retrieval via token-overlap scoring over evidence snippets.
• Sentiment component: headline-level lexicon scoring (positive/negative keyword counts) over news pulled from Google News RSS, Yahoo Finance (yfinance), and NewsAPI.
• Important distinction: initialize_rag.py builds dense embeddings (BAAI/bge-small-en-v1.5) and Chroma vector stores through LangChain, but the Streamlit Q&A path currently uses heuristic matching in SimpleRAGEngine, not dense vector retrieval.

3) Forecasting and market signals

• Market data integration: yfinance historical OHLCV + metadata + statement pulls in src/market_data_integration.py.
• Technical indicators: SMA(20/50), EMA(12/26), RSI(14), MACD, Bollinger Bands.
• Volume forecasting model: RandomForestRegressor with handcrafted lag/rolling/cyclical features in src/forecasting_engine.py; model serialization via pickle.
• Price trend forecasting: rule-based synthesis of indicator states (bullish/bearish/neutral signals), not a learned price model.

4) Investment decision and portfolio construction

• Decision policy: weighted score fusion (0.4 * financial + 0.4 * forecast + 0.2 * sentiment) in InvestmentDecisionEngine.
• Action mapping: thresholded policy to BUY/SELL/HOLD conditioned by risk profile minimum-confidence rules.
• Risk controls: deterministic target/stop-loss/take-profit formulas from volatility assumptions.
• Portfolio step: confidence- and risk-adjusted weighting with summary metrics (expected return proxy, risk proxy, Sharpe-style ratio) in PortfolioOptimizer.

Key engineering decisions and tradeoffs

1. Fallback-first execution (demo modes, mock outputs, broad exception handling).

   • Why: keep UI responsive even when APIs, credentials, or data are missing.
   • Tradeoff: improves availability but weakens statistical validity and reproducibility.

2. Heuristic retrieval and scoring in the online Q&A path.

   • Why: low-latency, dependency-light behavior without requiring prebuilt vector indexes at runtime.
   • Tradeoff: reduced semantic recall versus true embedding-based nearest-neighbor retrieval.

3. Feature-engineered Random Forest for volume prediction.

   • Why: simple tabular model with interpretable engineered predictors and fast retraining.
   • Tradeoff: no explicit temporal sequence modeling; evaluation is currently in-sample during training.

4. Single-process Streamlit orchestration over service decomposition.

   • Why: fast prototyping and integrated visualization.
   • Tradeoff: limited scalability, weaker separation of concerns, and difficult production hardening.

Tech stack (from repository configuration)

• Runtime / framework

  • Python (project scripts target Python 3.8+ in prior README)
  • Streamlit 1.29.0
  • FastAPI 0.104.1 + Uvicorn 0.24.0 are listed in requirements.txt but not used by the main app entrypoint.

• Data and ML

  • pandas 2.1.4, numpy 1.24.3
  • scikit-learn 1.3.2 (also duplicated as 1.3.0 in requirements)
  • torch 2.1.2, torchvision 0.16.2
  • transformers 4.36.2 (also duplicated as 4.36.0)
  • sentence-transformers 2.2.2
  • langchain 0.1.0, langchain-community 0.0.10, langchain-openai 0.0.2
  • chromadb 0.4.22 (also duplicated as 0.4.18)

• Document, APIs, and visualization

  • pymupdf 1.23.8
  • openai 1.6.1
  • yfinance 0.2.28, requests 2.31.0
  • plotly 5.17.0
  • beautifulsoup4 4.12.2, nltk 3.8.1, spacy 3.7.2, textblob 0.17.1, vaderSentiment 3.3.2 (listed; not all are exercised in current code paths)

Limitations and concrete improvements

1. Mismatch between claimed and executed retrieval architecture: vector-store initialization exists, but app-time Q&A uses string/keyword heuristics.

   • Improvement: route Q&A through Chroma dense retrieval + explicit reranking and source attribution.

2. Multiple UI sections use synthetic defaults or mocked values (e.g., random sentiment, placeholder decisions/performance trajectories).

   • Improvement: separate demo and production modes clearly; tag all simulated outputs in UI and logs.

3. Forecast model evaluation is not out-of-sample (train_new_model evaluates on training data).

   • Improvement: add time-aware train/validation/test splits and backtesting metrics.

4. Security/configuration hygiene needs hardening (e.g., hardcoded NewsAPI key in source; duplicated dependency pins).

   • Improvement: move all credentials to environment variables and normalize dependency versions.

5. No formal claim to novelty or research contribution is supported by implemented evaluation artifacts.

   • Improvement: add controlled experiments, ablations, and reproducible benchmark protocols before making comparative claims.

Running the app

pip install -r /home/runner/work/FinDocMadeEz/FinDocMadeEz/requirements.txt
python /home/runner/work/FinDocMadeEz/FinDocMadeEz/initialize_rag.py   # optional: builds Chroma stores
python /home/runner/work/FinDocMadeEz/FinDocMadeEz/run_app.py

Then open http://localhost:8501.