# rishabhzn200/agentic-stock-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/rishabhzn200/agentic-stock-analysis
- Repository: https://github.com/rishabhzn200/agentic-stock-analysis

## Overview

This is a stock-analysis application offering both model-only prediction and an agentic, news-aware report. The primary agent workflow runs ticker metadata, LLM query planning, news retrieval, sentiment analysis, ML prediction, signal alignment, and report summarization; a separate API route exposes model-only prediction with optional explanation. The graph wiring, API routes, predictor, training, and news-service relationships are supported by excerpts or README statements. Several node implementations are unsampled, so their internal dependencies are omitted rather than inferred.

Main entry points: [`src/agentic_stock_analysis/agent/graph.py`](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/graph.py) (Agent graph), [`src/agentic_stock_analysis/news/service.py`](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/service.py) (News aggregation), [`src/agentic_stock_analysis/ml/predictor.py`](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/predictor.py) (Stock predictor), [`src/agentic_stock_analysis/api/routes.py`](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/api/routes.py) (Analysis routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and entrypoints"]
  node_api_routes["Analysis routes<br/>[routes.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_agent["Analysis agent"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_state["Workflow state<br/>[state.py]"]
  node_metadata["Ticker metadata<br/>[metadata.py]"]
  node_query_plan["News query planning<br/>[plan_news_query.py]"]
  node_news_node["News node<br/>[news.py]"]
  node_sentiment["News sentiment<br/>[news_sentiment.py]"]
  node_prediction_node["Agent prediction<br/>[predict.py]"]
  node_alignment["Signal alignment<br/>[alignment.py]"]
  node_summarize["Report summary<br/>[summarize.py]"]
end

subgraph group_market["Market data and ML"]
  node_predictor["Stock predictor<br/>[predictor.py]"]
  node_features["Technical features<br/>[features.py]"]
  node_model[("Classifier and artifact<br/>[model.py]")]
  node_training["Model training<br/>[training.py]"]
  node_ticker_universe["Ticker universe<br/>[ticker_data.py]"]
  node_fetch_data["Historical prices<br/>[fetch_data.py]"]
end

subgraph group_news["News retrieval"]
  node_news_service["News aggregation<br/>[service.py]"]
  node_dedupe["Article deduplication<br/>[dedupe.py]"]
  node_news_sort["Article sorting<br/>[news_sorter.py]"]
  node_newsapi["NewsAPI provider<br/>[newsapi.py]"]
  node_stocknews["StockNews provider<br/>[stocknews.py]"]
  node_yfinance_news["yfinance news<br/>[yfinance_news.py]"]
end

subgraph group_language["LLM explanation"]
  node_explainer["Prediction explainer<br/>[explainer.py]"]
end

node_user(("Analyst"))
node_openai{{"OpenAI LLM"}}

node_user -->|"submits analysis"| node_api_routes
node_api_routes -->|"validates requests"| node_schemas
node_api_routes -->|"runs prediction"| node_predictor
node_api_routes -->|"invokes agent"| node_graph
node_api_routes -->|"requests explanation"| node_explainer
node_cli -->|"runs prediction"| node_predictor
node_cli -->|"requests explanation"| node_explainer
node_graph -->|"dispatches first"| node_metadata
node_graph -->|"dispatches next"| node_query_plan
node_graph -->|"dispatches next"| node_news_node
node_graph -->|"dispatches next"| node_sentiment
node_graph -->|"dispatches next"| node_prediction_node
node_graph -->|"dispatches next"| node_alignment
node_graph -->|"dispatches last"| node_summarize
node_query_plan -->|"plans terms"| node_openai
node_news_node -->|"retrieves articles"| node_news_service
node_prediction_node -->|"requests prediction"| node_predictor
node_summarize -->|"generates report"| node_openai
node_sentiment -->|"analyzes sentiment"| node_openai
node_news_service -->|"fetches articles"| node_newsapi
node_news_service -->|"fetches articles"| node_stocknews
node_news_service -->|"falls back"| node_yfinance_news
node_predictor -->|"downloads prices"| node_fetch_data
node_predictor -->|"computes indicators"| node_features
node_predictor -->|"loads and predicts"| node_model
node_training -->|"selects tickers"| node_ticker_universe
node_training -->|"fetches history"| node_fetch_data
node_training -->|"builds features"| node_features
node_training -->|"trains classifier"| node_model
node_news_service -->|"merges duplicates"| node_dedupe
node_news_service -->|"sorts articles"| node_news_sort
node_explainer -->|"requests explanation"| node_openai

click node_api_routes "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/api/routes.py"
click node_schemas "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/api_models/schemas.py"
click node_cli "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/cli.py"
click node_graph "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/graph.py"
click node_state "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/state.py"
click node_metadata "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/metadata.py"
click node_query_plan "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/plan_news_query.py"
click node_news_node "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/news.py"
click node_sentiment "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/news_sentiment.py"
click node_prediction_node "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/predict.py"
click node_alignment "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/alignment.py"
click node_summarize "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/summarize.py"
click node_predictor "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/predictor.py"
click node_features "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/features.py"
click node_model "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/model.py"
click node_training "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/training.py"
click node_ticker_universe "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/ticker_data.py"
click node_fetch_data "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/services/fetch_data.py"
click node_news_service "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/service.py"
click node_dedupe "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/dedupe.py"
click node_news_sort "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/news_sorter.py"
click node_newsapi "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/newsapi.py"
click node_stocknews "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/stocknews.py"
click node_yfinance_news "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/yfinance_news.py"
click node_explainer "https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/llm/explainer.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_api_routes,node_schemas,node_cli toneBlue
class node_graph,node_state,node_metadata,node_query_plan,node_news_node,node_sentiment,node_prediction_node,node_alignment,node_summarize toneAmber
class node_predictor,node_features,node_model,node_training,node_ticker_universe,node_fetch_data toneMint
class node_news_service,node_dedupe,node_news_sort,node_newsapi,node_stocknews,node_yfinance_news toneRose
class node_explainer,node_user,node_openai toneIndigo
```

## Components

### API and entrypoints

- [Analysis routes](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/api/routes.py): `src/agentic_stock_analysis/api/routes.py`
- [Request schemas](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/api_models/schemas.py): `src/agentic_stock_analysis/api_models/schemas.py`
- [CLI](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/cli.py): `src/agentic_stock_analysis/cli.py`

### Analysis agent

- [Agent graph](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/graph.py): `src/agentic_stock_analysis/agent/graph.py`
- [Workflow state](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/state.py): `src/agentic_stock_analysis/agent/state.py`
- [Ticker metadata](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/metadata.py): `src/agentic_stock_analysis/agent/nodes/metadata.py`
- [News query planning](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/plan_news_query.py): `src/agentic_stock_analysis/agent/nodes/plan_news_query.py`
- [News node](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/news.py): `src/agentic_stock_analysis/agent/nodes/news.py`
- [News sentiment](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/news_sentiment.py): `src/agentic_stock_analysis/agent/nodes/news_sentiment.py`
- [Agent prediction](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/predict.py): `src/agentic_stock_analysis/agent/nodes/predict.py`
- [Signal alignment](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/alignment.py): `src/agentic_stock_analysis/agent/nodes/alignment.py`
- [Report summary](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/agent/nodes/summarize.py): `src/agentic_stock_analysis/agent/nodes/summarize.py`

### Market data and ML

- [Stock predictor](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/predictor.py): `src/agentic_stock_analysis/ml/predictor.py`
- [Technical features](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/features.py): `src/agentic_stock_analysis/ml/features.py`
- [Classifier and artifact](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/model.py): `src/agentic_stock_analysis/ml/model.py`
- [Model training](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/training.py): `src/agentic_stock_analysis/ml/training.py`
- [Ticker universe](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/ml/ticker_data.py): `src/agentic_stock_analysis/ml/ticker_data.py`
- [Historical prices](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/services/fetch_data.py): `src/agentic_stock_analysis/services/fetch_data.py`

### News retrieval

- [News aggregation](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/service.py): `src/agentic_stock_analysis/news/service.py`
- [Article deduplication](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/dedupe.py): `src/agentic_stock_analysis/news/dedupe.py`
- [Article sorting](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/news_sorter.py): `src/agentic_stock_analysis/news/news_sorter.py`
- [NewsAPI provider](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/newsapi.py): `src/agentic_stock_analysis/news/providers/newsapi.py`
- [StockNews provider](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/stocknews.py): `src/agentic_stock_analysis/news/providers/stocknews.py`
- [yfinance news](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/news/providers/yfinance_news.py): `src/agentic_stock_analysis/news/providers/yfinance_news.py`

### LLM explanation

- [Prediction explainer](https://github.com/rishabhzn200/agentic-stock-analysis/blob/main/src/agentic_stock_analysis/llm/explainer.py): `src/agentic_stock_analysis/llm/explainer.py`

### Other components

- **Analyst**
- **OpenAI LLM**

## Connections

- Analyst → Analysis routes: submits analysis
- Analysis routes → Request schemas: validates requests (evidence: `src/agentic_stock_analysis/api/routes.py`)
- Analysis routes → Stock predictor: runs prediction (evidence: `src/agentic_stock_analysis/api/routes.py`)
- Analysis routes → Agent graph: invokes agent (evidence: `src/agentic_stock_analysis/api/routes.py`)
- Analysis routes → Prediction explainer: requests explanation (evidence: `src/agentic_stock_analysis/api/routes.py`)
- CLI → Stock predictor: runs prediction (evidence: `src/agentic_stock_analysis/cli.py`)
- CLI → Prediction explainer: requests explanation
- Agent graph → Ticker metadata: dispatches first (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → News query planning: dispatches next (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → News node: dispatches next (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → News sentiment: dispatches next (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → Agent prediction: dispatches next (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → Signal alignment: dispatches next (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- Agent graph → Report summary: dispatches last (evidence: `src/agentic_stock_analysis/agent/graph.py`)
- News query planning → OpenAI LLM: plans terms (evidence: `src/agentic_stock_analysis/agent/nodes/plan_news_query.py`)
- News node → News aggregation: retrieves articles (evidence: `src/agentic_stock_analysis/agent/nodes/news.py`)
- Agent prediction → Stock predictor: requests prediction (evidence: `src/agentic_stock_analysis/agent/nodes/predict.py`)
- Report summary → OpenAI LLM: generates report
- News sentiment → OpenAI LLM: analyzes sentiment
- News aggregation → NewsAPI provider: fetches articles (evidence: `src/agentic_stock_analysis/news/service.py`)
- News aggregation → StockNews provider: fetches articles (evidence: `src/agentic_stock_analysis/news/service.py`)
- News aggregation → yfinance news: falls back (evidence: `src/agentic_stock_analysis/news/service.py`)
- Stock predictor → Historical prices: downloads prices (evidence: `src/agentic_stock_analysis/ml/predictor.py`)
- Stock predictor → Technical features: computes indicators (evidence: `src/agentic_stock_analysis/ml/predictor.py`)
- Stock predictor → Classifier and artifact: loads and predicts (evidence: `src/agentic_stock_analysis/ml/predictor.py`)
- Model training → Ticker universe: selects tickers (evidence: `src/agentic_stock_analysis/ml/training.py`)
- Model training → Historical prices: fetches history (evidence: `src/agentic_stock_analysis/ml/training.py`)
- Model training → Technical features: builds features (evidence: `src/agentic_stock_analysis/ml/training.py`)
- Model training → Classifier and artifact: trains classifier (evidence: `src/agentic_stock_analysis/ml/training.py`)
- News aggregation → Article deduplication: merges duplicates (evidence: `src/agentic_stock_analysis/news/service.py`)
- News aggregation → Article sorting: sorts articles (evidence: `src/agentic_stock_analysis/news/service.py`)
- Prediction explainer → OpenAI LLM: requests explanation (evidence: `src/agentic_stock_analysis/llm/explainer.py`)