Skip to content

README.md

Latest commit

 

History

History
101 lines (76 loc) · 6.46 KB

README.md

File metadata and controls

101 lines (76 loc) · 6.46 KB
Raw

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.