# krishivwahi/intellihedge architecture

> Architecture diagram of the GitHub repository krishivwahi/intellihedge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishivwahi/intellihedge
- Repository: https://github.com/krishivwahi/intellihedge

## Overview

IntelliHedge is a research prototype for using point-in-time news narratives to inform option-inclusive deep hedging under jump risk and transaction costs. Its primary workflow runs through either the Streamlit demo or CLI: process timestamped headlines into regime signals, simulate market and put-price paths, then train and compare hedging policies across causal-ablation arms. The repository also contains separate data-collection and parsing utilities for several news and filings sources. The main runtime relationships are supported by the README and sampled app/CLI excerpts; the data utilities are shown as independent components because their wiring to the hedging workflow was not established.

Main entry points: [`news_regime.py`](https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py) (News Regime Engine), [`app.py`](https://github.com/krishivwahi/intellihedge/blob/main/app.py) (Streamlit Demo), [`main.py`](https://github.com/krishivwahi/intellihedge/blob/main/main.py) (CLI Runner), [`merton_env.py`](https://github.com/krishivwahi/intellihedge/blob/main/merton_env.py) (Jump Market Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Run Interfaces"]
  node_demo["Streamlit Demo<br/>[app.py]"]
  node_cli["CLI Runner<br/>[main.py]"]
end

subgraph group_perception["News Perception"]
  node_news["News Regime Engine<br/>[news_regime.py]"]
  node_dedup["Headline Deduplication<br/>[news_regime.py]"]
  node_narrative["Narrative Clustering<br/>[news_regime.py]"]
  node_regime["Regime Signal<br/>[news_regime.py]"]
end

subgraph group_hedging["Market And Hedging"]
  node_market["Jump Market Simulator<br/>[merton_env.py]"]
  node_option["Put Pricing<br/>[merton_env.py]"]
  node_policy["Deep Hedging Ablation<br/>[deep_hedger.py]"]
end

subgraph group_ingestion["Data Preparation"]
  node_alpaca_collect["Alpaca Collector"]
  node_alpaca_clean["Alpaca News Cleaning"]
  node_fnspid_collect["FNSPID Collector"]
  node_fnspid_parse["FNSPID Parser<br/>[fnspid_parser.py]"]
  node_fnspid_dates["FNSPID Date Helpers<br/>[fnspid_dates.py]"]
  node_gdelt_collect["GDELT Collector<br/>[gdelt_collector.py]"]
  node_gdelt_parse["GDELT Parser<br/>[gdelt_parser.py]"]
  node_sec_collect["SEC EDGAR Collector"]
  node_sec_parse["SEC EDGAR Parser"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs demo"| node_demo
node_researcher -->|"runs CLI"| node_cli
node_demo -->|"processes headlines"| node_news
node_demo -->|"simulates paths"| node_market
node_demo -->|"runs ablation"| node_policy
node_cli -->|"runs perception"| node_news
node_cli -->|"simulates paths"| node_market
node_cli -->|"runs ablation"| node_policy
node_news -->|"filters headlines"| node_dedup
node_news -->|"clusters narratives"| node_narrative
node_news -->|"emits signals"| node_regime
node_market -->|"prices puts"| node_option
node_fnspid_parse -->|"uses date helpers"| node_fnspid_dates

click node_demo "https://github.com/krishivwahi/intellihedge/blob/main/app.py"
click node_cli "https://github.com/krishivwahi/intellihedge/blob/main/main.py"
click node_news "https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py"
click node_dedup "https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py"
click node_narrative "https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py"
click node_regime "https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py"
click node_market "https://github.com/krishivwahi/intellihedge/blob/main/merton_env.py"
click node_option "https://github.com/krishivwahi/intellihedge/blob/main/merton_env.py"
click node_policy "https://github.com/krishivwahi/intellihedge/blob/main/deep_hedger.py"
click node_alpaca_collect "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/alpaca_benzinga/alpaca_collector.py"
click node_alpaca_clean "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/alpaca_benzinga/clean_alpaca_news.py"
click node_fnspid_collect "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_collector.py"
click node_fnspid_parse "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_parser.py"
click node_fnspid_dates "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_dates.py"
click node_gdelt_collect "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/gdelt/gdelt_collector.py"
click node_gdelt_parse "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/gdelt/gdelt_parser.py"
click node_sec_collect "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/sec_edgar/sec_edgar_collector.py"
click node_sec_parse "https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/sec_edgar/sec_edgar_parser.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_demo,node_cli toneBlue
class node_news,node_dedup,node_narrative,node_regime toneAmber
class node_market,node_option,node_policy toneMint
class node_alpaca_collect,node_alpaca_clean,node_fnspid_collect,node_fnspid_parse,node_fnspid_dates,node_gdelt_collect,node_gdelt_parse,node_sec_collect,node_sec_parse toneRose
class node_researcher toneIndigo
```

## Components

### Run Interfaces

- [Streamlit Demo](https://github.com/krishivwahi/intellihedge/blob/main/app.py): `app.py`
- [CLI Runner](https://github.com/krishivwahi/intellihedge/blob/main/main.py): `main.py`

### News Perception

- [News Regime Engine](https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py): `news_regime.py`
- [Headline Deduplication](https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py): `news_regime.py`
- [Narrative Clustering](https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py): `news_regime.py`
- [Regime Signal](https://github.com/krishivwahi/intellihedge/blob/main/news_regime.py): `news_regime.py`

### Market And Hedging

- [Jump Market Simulator](https://github.com/krishivwahi/intellihedge/blob/main/merton_env.py): `merton_env.py`
- [Put Pricing](https://github.com/krishivwahi/intellihedge/blob/main/merton_env.py): `merton_env.py`
- [Deep Hedging Ablation](https://github.com/krishivwahi/intellihedge/blob/main/deep_hedger.py): `deep_hedger.py`

### Data Preparation

- [Alpaca Collector](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/alpaca_benzinga/alpaca_collector.py): `data_pipeline/alpaca_benzinga/alpaca_collector.py`
- [Alpaca News Cleaning](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/alpaca_benzinga/clean_alpaca_news.py): `data_pipeline/alpaca_benzinga/clean_alpaca_news.py`
- [FNSPID Collector](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_collector.py): `data_pipeline/fnspid/fnspid_collector.py`
- [FNSPID Parser](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_parser.py): `data_pipeline/fnspid/fnspid_parser.py`
- [FNSPID Date Helpers](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/fnspid/fnspid_dates.py): `data_pipeline/fnspid/fnspid_dates.py`
- [GDELT Collector](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/gdelt/gdelt_collector.py): `data_pipeline/gdelt/gdelt_collector.py`
- [GDELT Parser](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/gdelt/gdelt_parser.py): `data_pipeline/gdelt/gdelt_parser.py`
- [SEC EDGAR Collector](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/sec_edgar/sec_edgar_collector.py): `data_pipeline/sec_edgar/sec_edgar_collector.py`
- [SEC EDGAR Parser](https://github.com/krishivwahi/intellihedge/blob/main/data_pipeline/sec_edgar/sec_edgar_parser.py): `data_pipeline/sec_edgar/sec_edgar_parser.py`

### Other components

- **Researcher**

## Connections

- Researcher → Streamlit Demo: runs demo (evidence: `app.py`)
- Researcher → CLI Runner: runs CLI (evidence: `main.py`)
- Streamlit Demo → News Regime Engine: processes headlines (evidence: `app.py`)
- Streamlit Demo → Jump Market Simulator: simulates paths (evidence: `app.py`)
- Streamlit Demo → Deep Hedging Ablation: runs ablation (evidence: `app.py`)
- CLI Runner → News Regime Engine: runs perception (evidence: `main.py`)
- CLI Runner → Jump Market Simulator: simulates paths (evidence: `main.py`)
- CLI Runner → Deep Hedging Ablation: runs ablation (evidence: `main.py`)
- News Regime Engine → Headline Deduplication: filters headlines (evidence: `news_regime.py`)
- News Regime Engine → Narrative Clustering: clusters narratives (evidence: `news_regime.py`)
- News Regime Engine → Regime Signal: emits signals (evidence: `news_regime.py`)
- Jump Market Simulator → Put Pricing: prices puts (evidence: `merton_env.py`)
- FNSPID Parser → FNSPID Date Helpers: uses date helpers (evidence: `data_pipeline/fnspid/fnspid_parser.py`)
