How alielbaha/multi-agent works
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: llm_client.py Groq LLM client · state.py Agent state · pipeline.py Analysis pipeline · main.py FastAPI application
Components 18
API boundary
- API clients
- FastAPI application · Serves health, synchronous, and SSE recommendation endpoints.
app/main.py - Recommendation schemas
app/schemas/recommendation.py
LangGraph workflow
- Agent state · Carries research, debate rounds, transcript, and verdict.
app/graph/state.py - Analysis pipeline · Fans out research, bounds debate to three rounds, then judges.
app/graph/pipeline.py - Fundamentals analyst
app/agents/fundamentals_analyst.py - News analyst
app/agents/news_analyst.py - Bull analyst
app/agents/bull_analyst.py - Bear analyst
app/agents/bear_analyst.py - Judge · Produces the fixed-form BUY/HOLD/SELL verdict and rationale.
app/agents/judge.py
External integrations
- Fundamentals retrieval
app/retrieval/fundamentals.py - News retrieval
app/retrieval/news.py - Groq LLM client
app/services/llm_client.py - yfinance · Supplies financial metrics and current headlines.
- Groq inference
Runtime and delivery
- Runtime settings · Loads GROQ_API_KEY and runtime settings.
app/core/config.py - Docker packaging
Dockerfile - GitHub Actions CI
.github/workflows/ci.yml
Connections 28
- 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