# alielbaha/multi-agent architecture

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

- Interactive diagram: https://gitdiagram.com/alielbaha/multi-agent
- Repository: https://github.com/alielbaha/multi-agent

## Overview

#### Purpose and entry points
This is a Python 3.12+ backend for multi-agent stock recommendations. FastAPI accepts a ticker, executes a LangGraph analysis workflow, and returns or streams research, debate, and a BUY/HOLD/SELL verdict. Runtime entry point: `app/main.py`; container entry: `Dockerfile`.

#### API boundary
`app/main.py` exposes health, synchronous recommendation, and SSE streaming recommendation endpoints. Request/response validation and the response contract live in `app/schemas/recommendation.py`. The API builds the initial graph state and is the boundary between clients and the internal agent workflow.

#### Shared workflow state and orchestration
`app/graph/state.py` defines the shared `AgentState` passed and incrementally updated by all stages: ticker, research summaries, debate history/round state, and final verdict. `app/graph/pipeline.py` compiles the LangGraph control flow: parallel research fan-out, fan-in to debate, bounded bull/bear loop, then judging and termination.

#### Research stage: external market data plus LLM summaries
Two independent graph nodes run in parallel:
- Fundamentals: `app/agents/fundamentals_analyst.py` obtains financial metrics through `app/retrieval/fundamentals.py`, then produces an LLM summary.
- News: `app/agents/news_analyst.py` obtains current headlines through `app/retrieval/news.py`, then produces a sentiment/relevance summary.

Both retrieval modules use yfinance, making market-data availability and ticker validity external-data boundaries.

#### Debate stage
After both research outputs are present, `app/agents/bull_analyst.py` creates the positive investment case and `app/agents/bear_analyst.py` rebutts it. The graph repeatedly routes between these nodes for at most three rounds. Each agent consumes the accumulated research and prior opposing argument, while appending its output to the shared debate transcript.

#### Judgment and output
`app/agents/judge.py` is the terminal reasoning node. It reviews the complete transcript and emits a fixed-form verdict and rationale, stored in graph state before the workflow reaches `END`. The normal endpoint serializes the completed state; the streaming endpoint emits agent completions as SSE events.

#### LLM, configuration, and deployment dependencies
All five agents call the Groq chat-completions integration behind `app/services/llm_client.py`. `app/core/config.py` loads runtime settings, notably `GROQ_API_KEY` (documented by `app/.env.example`). Material infrastructure is FastAPI/Uvicorn, LangGraph orchestration, Groq-hosted LLM inference, yfinance market/news retrieval, Docker packaging (`Dockerfile`), and GitHub Actions CI (`.github/workflows/ci.yml`).

Main entry points: [`app/services/llm_client.py`](https://github.com/alielbaha/multi-agent/blob/master/app/services/llm_client.py) (Groq LLM client), [`app/graph/state.py`](https://github.com/alielbaha/multi-agent/blob/master/app/graph/state.py) (Agent state), [`app/graph/pipeline.py`](https://github.com/alielbaha/multi-agent/blob/master/app/graph/pipeline.py) (Analysis pipeline), [`app/main.py`](https://github.com/alielbaha/multi-agent/blob/master/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_clients(("API clients<br/>consumer"))
  node_main["FastAPI application<br/>API runtime<br/>[main.py]"]
  node_schemas["Recommendation schemas<br/>request/response contract<br/>[recommendation.py]"]
end

subgraph group_workflow["LangGraph workflow"]
  node_state["Agent state<br/>shared workflow state<br/>[state.py]"]
  node_pipeline["Analysis pipeline<br/>LangGraph orchestration<br/>[pipeline.py]"]
  node_fundamentals_agent["Fundamentals analyst<br/>research agent"]
  node_news_agent["News analyst<br/>research agent<br/>[news_analyst.py]"]
  node_bull_agent["Bull analyst<br/>debate agent<br/>[bull_analyst.py]"]
  node_bear_agent["Bear analyst<br/>debate agent<br/>[bear_analyst.py]"]
  node_judge["Judge<br/>terminal reasoning agent<br/>[judge.py]"]
end

subgraph group_integrations["External integrations"]
  node_fundamentals_retrieval["Fundamentals retrieval<br/>market data adapter<br/>[fundamentals.py]"]
  node_news_retrieval["News retrieval<br/>news data adapter<br/>[news.py]"]
  node_llm_client["Groq LLM client<br/>chat-completions adapter<br/>[llm_client.py]"]
  node_yfinance{{"yfinance<br/>external market data"}}
  node_groq{{"Groq inference<br/>external LLM service"}}
end

subgraph group_delivery["Runtime and delivery"]
  node_config["Runtime settings<br/>configuration loader<br/>[config.py]"]
  node_dockerfile["Docker packaging<br/>container entry"]
  node_ci["GitHub Actions CI<br/>continuous integration<br/>[ci.yml]"]
end

node_clients -->|"HTTP / SSE requests"| node_main
node_main -->|"validates and serializes"| node_schemas
node_main -->|"initializes"| node_state
node_main -->|"invokes / streams"| node_pipeline
node_pipeline -->|"parallel research"| node_fundamentals_agent
node_pipeline -->|"parallel research"| node_news_agent
node_fundamentals_agent -->|"updates research"| node_state
node_news_agent -->|"updates research"| node_state
node_pipeline -->|"fan-in then debate"| node_bull_agent
node_bull_agent -->|"argument and rebuttal"| node_bear_agent
node_bear_agent -.->|"repeat, max 3 rounds"| node_bull_agent
node_bull_agent -->|"appends transcript"| node_state
node_bear_agent -->|"appends transcript"| node_state
node_pipeline -->|"after debate"| node_judge
node_judge -->|"stores verdict"| node_state
node_fundamentals_agent -->|"fetches metrics"| node_fundamentals_retrieval
node_news_agent -->|"fetches headlines"| node_news_retrieval
node_fundamentals_retrieval -->|"queries"| node_yfinance
node_news_retrieval -->|"queries"| node_yfinance
node_fundamentals_agent -->|"summarizes"| node_llm_client
node_news_agent -->|"summarizes"| node_llm_client
node_bull_agent -->|"reasons"| node_llm_client
node_bear_agent -->|"reasons"| node_llm_client
node_judge -->|"decides"| node_llm_client
node_llm_client -->|"chat completions"| node_groq
node_config -->|"provides API key"| node_llm_client
node_dockerfile -->|"container entry"| node_main
node_ci -.->|"validates delivery"| node_dockerfile

click node_main "https://github.com/alielbaha/multi-agent/blob/master/app/main.py"
click node_schemas "https://github.com/alielbaha/multi-agent/blob/master/app/schemas/recommendation.py"
click node_state "https://github.com/alielbaha/multi-agent/blob/master/app/graph/state.py"
click node_pipeline "https://github.com/alielbaha/multi-agent/blob/master/app/graph/pipeline.py"
click node_fundamentals_agent "https://github.com/alielbaha/multi-agent/blob/master/app/agents/fundamentals_analyst.py"
click node_news_agent "https://github.com/alielbaha/multi-agent/blob/master/app/agents/news_analyst.py"
click node_bull_agent "https://github.com/alielbaha/multi-agent/blob/master/app/agents/bull_analyst.py"
click node_bear_agent "https://github.com/alielbaha/multi-agent/blob/master/app/agents/bear_analyst.py"
click node_judge "https://github.com/alielbaha/multi-agent/blob/master/app/agents/judge.py"
click node_fundamentals_retrieval "https://github.com/alielbaha/multi-agent/blob/master/app/retrieval/fundamentals.py"
click node_news_retrieval "https://github.com/alielbaha/multi-agent/blob/master/app/retrieval/news.py"
click node_llm_client "https://github.com/alielbaha/multi-agent/blob/master/app/services/llm_client.py"
click node_config "https://github.com/alielbaha/multi-agent/blob/master/app/core/config.py"
click node_dockerfile "https://github.com/alielbaha/multi-agent/tree/master/Dockerfile"
click node_ci "https://github.com/alielbaha/multi-agent/blob/master/.github/workflows/ci.yml"

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_clients,node_main,node_schemas toneBlue
class node_state,node_pipeline,node_fundamentals_agent,node_news_agent,node_bull_agent,node_bear_agent,node_judge toneAmber
class node_fundamentals_retrieval,node_news_retrieval,node_llm_client,node_yfinance,node_groq toneMint
class node_config,node_dockerfile,node_ci toneRose
```

## Components

### API boundary

- **API clients**: consumer
- [FastAPI application](https://github.com/alielbaha/multi-agent/blob/master/app/main.py): API runtime · Serves health, synchronous, and SSE recommendation endpoints. · `app/main.py`
- [Recommendation schemas](https://github.com/alielbaha/multi-agent/blob/master/app/schemas/recommendation.py): request/response contract · `app/schemas/recommendation.py`

### LangGraph workflow

- [Agent state](https://github.com/alielbaha/multi-agent/blob/master/app/graph/state.py): shared workflow state · Carries research, debate rounds, transcript, and verdict. · `app/graph/state.py`
- [Analysis pipeline](https://github.com/alielbaha/multi-agent/blob/master/app/graph/pipeline.py): LangGraph orchestration · Fans out research, bounds debate to three rounds, then judges. · `app/graph/pipeline.py`
- [Fundamentals analyst](https://github.com/alielbaha/multi-agent/blob/master/app/agents/fundamentals_analyst.py): research agent · `app/agents/fundamentals_analyst.py`
- [News analyst](https://github.com/alielbaha/multi-agent/blob/master/app/agents/news_analyst.py): research agent · `app/agents/news_analyst.py`
- [Bull analyst](https://github.com/alielbaha/multi-agent/blob/master/app/agents/bull_analyst.py): debate agent · `app/agents/bull_analyst.py`
- [Bear analyst](https://github.com/alielbaha/multi-agent/blob/master/app/agents/bear_analyst.py): debate agent · `app/agents/bear_analyst.py`
- [Judge](https://github.com/alielbaha/multi-agent/blob/master/app/agents/judge.py): terminal reasoning agent · Produces the fixed-form BUY/HOLD/SELL verdict and rationale. · `app/agents/judge.py`

### External integrations

- [Fundamentals retrieval](https://github.com/alielbaha/multi-agent/blob/master/app/retrieval/fundamentals.py): market data adapter · `app/retrieval/fundamentals.py`
- [News retrieval](https://github.com/alielbaha/multi-agent/blob/master/app/retrieval/news.py): news data adapter · `app/retrieval/news.py`
- [Groq LLM client](https://github.com/alielbaha/multi-agent/blob/master/app/services/llm_client.py): chat-completions adapter · `app/services/llm_client.py`
- **yfinance**: external market data · Supplies financial metrics and current headlines.
- **Groq inference**: external LLM service

### Runtime and delivery

- [Runtime settings](https://github.com/alielbaha/multi-agent/blob/master/app/core/config.py): configuration loader · Loads GROQ_API_KEY and runtime settings. · `app/core/config.py`
- [Docker packaging](https://github.com/alielbaha/multi-agent/tree/master/Dockerfile): container entry · `Dockerfile`
- [GitHub Actions CI](https://github.com/alielbaha/multi-agent/blob/master/.github/workflows/ci.yml): continuous integration · `.github/workflows/ci.yml`

## Connections

- API clients → FastAPI application: HTTP / SSE requests
- FastAPI application → Recommendation schemas: validates and serializes
- FastAPI application → Agent state: initializes
- FastAPI application → Analysis pipeline: invokes / streams
- Analysis pipeline → Fundamentals analyst: parallel research
- Analysis pipeline → News analyst: parallel research
- Fundamentals analyst → Agent state: updates research
- News analyst → Agent state: updates research
- Analysis pipeline → Bull analyst: fan-in then debate
- Bull analyst → Bear analyst: argument and rebuttal
- Bear analyst → Bull analyst: repeat, max 3 rounds
- Bull analyst → Agent state: appends transcript
- Bear analyst → Agent state: appends transcript
- Analysis pipeline → Judge: after debate
- Judge → Agent state: stores verdict
- Fundamentals analyst → Fundamentals retrieval: fetches metrics
- News analyst → News retrieval: fetches headlines
- Fundamentals retrieval → yfinance: queries
- News retrieval → yfinance: queries
- Fundamentals analyst → Groq LLM client: summarizes
- News analyst → Groq LLM client: summarizes
- Bull analyst → Groq LLM client: reasons
- Bear analyst → Groq LLM client: reasons
- Judge → Groq LLM client: decides
- Groq LLM client → Groq inference: chat completions
- Runtime settings → Groq LLM client: provides API key
- Docker packaging → FastAPI application: container entry
- GitHub Actions CI → Docker packaging: validates delivery
