ReidLCaulder/agentic-equity-researcher

Equity Research Multi-Agent System

A LangGraph-based multi-agent system for comprehensive equity research, powered by Gemini 2.5 Pro. Features an adversarial research architecture with Bull and Bear teams, a Gradio web interface, and CLI.

Quick Start

Web Interface (Gradio)

uv run python -m equity_researcher.app

Opens at http://127.0.0.1:7862 with a chat interface for research queries.

Command Line Interface

uv run python -m equity_researcher.main

Interactive CLI with conversation memory.

Architecture

graph TD
    User[👤 User] --> DH[🎩 Desk Head]
    DH -->|"Send API ⚡"| BullTeam
    DH -->|"Send API ⚡"| BearTeam
    
    subgraph BullTeam["🐂 Bull Team (Subgraph)"]
        BullLead[📈 Lead Analyst] -->|"Delegates"| BullRes[📰 Research Agent]
        BullRes --> BullSEC[📊 SEC Agent]
        BullSEC -->|"Returns Findings"| BullLead
        BullLead -->|"Satisfied?"| BullDecision{Decision}
        BullDecision -->|"No: More Research"| BullLead
        BullDecision -->|"Yes"| BullThesis[📄 Bull Thesis]
    end
    
    subgraph BearTeam["🐻 Bear Team (Subgraph)"]
        BearLead[📉 Lead Analyst] -->|"Delegates"| BearRes[📰 Research Agent]
        BearRes --> BearSEC[📊 SEC Agent]
        BearSEC -->|"Returns Findings"| BearLead
        BearLead -->|"Satisfied?"| BearDecision{Decision}
        BearDecision -->|"No: More Research"| BearLead
        BearDecision -->|"Yes"| BearThesis[📄 Bear Thesis]
    end
    
    BullThesis --> Collect[📊 Collect Theses]
    BearThesis --> Collect
    Collect --> Judge[👨‍⚖️ Warren Buffett Judge]
    Judge -->|"JudgeVerdict"| Report[📝 Final Report]
    Report --> Memory[(sqlite: History)]

Team Internal Flow

Each team runs as a single-pass subgraph optimized for speed (4-5x faster than iteration):

┌─────────────────────────────────────────────────────────────────┐
│                     TEAM SUBGRAPH (Single-Pass)                  │
│                                                                  │
│   START                                                          │
│     │                                                            │
│     ▼                                                            │
│   Query Generator (Pro) ──→ Generate research & SEC queries     │
│     │                                                            │
│     ▼                                                            │
│   Research Agent (Flash) ──→ Execute web searches               │
│     │                                                            │
│     ▼                                                            │
│   SEC Agent (Flash) ──→ Retrieve & analyze filings              │
│     │                                                            │
│     ▼                                                            │
│   Synthesis Node (Pro) ──→ Full FinCoT reasoning                │
│     │                      • Uses 14k/12k char analyst prompts   │
│     │                      • Quality Constitution thresholds     │
│     │                      • Named interpretation lenses         │
│     │                      • Moat/Mortality frameworks           │
│     ▼                                                            │
│   END → final_thesis                                             │
└─────────────────────────────────────────────────────────────────┘

Project Structure

equity_researcher/
├── app.py              # Gradio web interface
├── main.py             # CLI interface
├── __init__.py
├── agents/
│   ├── bull_team/      # 🐂 Bullish research team (placeholder)
│   ├── bear_team/      # 🐻 Bearish research team (placeholder)
│   └── core/           # Orchestration & evaluation
│       ├── judge.py          # Warren Buffett-style arbitrator
│       └── desk_head.py      # Initial briefing & context extraction
├── tools/
│   ├── serper_tools.py # Web search tools (Serper API)
│   ├── sec_tools.py    # SEC EDGAR API tools
│   ├── e2b_code.py     # E2B sandboxed Python execution
│   ├── forensics.py    # (Placeholder for future)
│   └── openbb_tools.py # (Placeholder for future)
├── graph/
│   ├── workflow.py     # Main workflow with parallel Send API dispatch
│   ├── team_subgraph.py # Team subgraph factory (Bull/Bear teams)
│   ├── state.py        # MainState, TeamState, JudgeVerdict, & models
│   └── checkpoint.py   # Memory-based state persistence
├── tests/
│   ├── test_desk_head.py              # Unit tests for Desk Head
│   └── test_database_persistence.py   # Database persistence tests
└── utils/
    └── database.py     # Supabase long-term memory utilities

Agent Descriptions

🎩 Desk Head

Role: Initial Briefing & Context Extraction

The Desk Head is the first agent in every research workflow. It:

• —Uses LLM to extract ticker symbols from any company name (works for all public companies)
• —Identifies focus areas when users specify particular topics
• —Queries long-term memory to load previous analyses via Supabase
• —Creates a structured briefing that configures the research teams

🐂 Bull Team

The Bull Team builds the ownership case using Warren Buffett-Philip Fisher methodology.

📈 Bull Synthesis (14k-char Prompt)

Uses the full Buffett-Fisher Ownership Framework:

• —FinCoT Protocol: Structured Signal → Moat Interpretation → Durability → Integration
• —Business Quality Constitution: ROIC >15%, FCF/NI >80%, Gross Margin stability
• —Named Lenses: Owner, Moat, Fisher, Durability, Margin of Safety
• —Moat Types: Network Effects, Switching Costs, Cost Advantages, Intangibles, Efficient Scale

📰 Bull Research Agent

Searches for quality signals: competitive moats, pricing power, market position, management reputation.

📊 Bull SEC Agent

Finds financial quality: ROIC trends, margin analysis, FCF conversion, capital allocation track record.

🐻 Bear Team

The Bear Team builds the risk case using Charlie Munger-Seth Klarman methodology.

📉 Bear Synthesis (12k-char Prompt)

Uses the full Capital Guardian Framework:

• —FinCoT Protocol: Signal → Skeptical Interpretation → Failure Mapping → Integration
• —Forensic Accounting Constitution: CFO/NI ratios, accrual analysis, EBITDA skepticism
• —Named Lenses: Klarman, Munger, Marks, Forensic, Too Hard
• —Mortality Mapping: Business failure, moat decay, management failure scenarios

📰 Bear Research Agent

Searches for risk factors: competitive threats, regulatory risks, short seller reports, customer churn.

📊 Bear SEC Agent

Performs forensic analysis: cash flow quality, accrual trends, related party transactions, SBC burden.

👨‍⚖️ Judge Agent

Role: Warren Buffett-style Arbitrator

After both teams present their theses, the Judge evaluates the arguments and delivers a final verdict on the investment opportunity.

Interfaces

Gradio Web UI (app.py)

A modern chat interface with:

• —Real-time progress indicators showing which step is executing during analysis
• —Parallel Bull/Bear team status with completion tracking
• —Persistent conversation sessions via thread_id
• —Formatted markdown output with headers and sections
• —Error handling with user-friendly messages

Progress Display:

## Analyzing AAPL...

**[2/5] Research Teams** (parallel execution)

| Team | Status |
|------|--------|
| Bull | [✓] Completed |
| Bear | [...] Running |

Configuration:

• —Server: 127.0.0.1:7860
• —Model: Gemini 3.0 Pro (temperature=0)

CLI (main.py)

An interactive terminal interface with:

• —Conversation memory across queries
• —Real-time processing status
• —Type quit, exit, or q to exit

Example Prompts

Research Tesla and give me a comprehensive report including recent news, 
SEC filings, and financial analysis.

What are Apple's latest 10-K and 10-Q filings? Summarize their financial position.

Analyze Palantir and tell me the bull and bear cases.

Analyze NVDA and calculate its current valuation multiples.

Environment Variables

Create a .env file in the project root:

# Required
GOOGLE_API_KEY=your-gemini-api-key
SERPER_API_KEY=your-serper-api-key

# Optional
SEC_USER_AGENT=YourAppName your-email@example.com
E2B_API_KEY=your-e2b-api-key  # For code execution (get from https://e2b.dev)

# Long-Term Memory (Supabase)
SUPABASE_URL=your-supabase-project-url
SUPABASE_KEY=your-supabase-anon-key

Dependencies

Core dependencies from pyproject.toml:

External APIs:

• —SEC EDGAR API (free, no key required)
• —Serper API (requires key)
• —E2B API (requires key for code execution)
• —Supabase (requires URL and key for long-term memory)

Technical Details

State Management

The system uses multiple state types:

AgentState (main graph):

class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    session_id: str
    briefing: Optional[DeskHeadBriefing]
    bull_thesis: Optional[str]
    bear_thesis: Optional[str]
    verdict: Optional[str]
    next_agent: str

TeamState (team subgraphs):

class TeamState(TypedDict):
    briefing: DeskHeadBriefing
    team_bias: Literal["bull", "bear"]
    research_findings: list[str]
    sec_findings: list[str]
    pending_requests: list[dict]
    iteration_count: int
    max_iterations: int
    is_satisfied: bool
    final_thesis: Optional[str]

Memory Architecture

Short-Term Memory:

• —MemorySaver for in-memory state persistence within a session
• —Conversations persist via thread_id

Long-Term Memory (Supabase):

• —Stores completed analyses with key facts, verdicts, and theses
• —Desk Head retrieves previous analyses for context

Workflow Routing

1. 1.Desk Head processes user input → extracts ticker via LLM → creates briefing
2. 2.Bull Team subgraph executes (Lead Analyst iterates with Research/SEC agents)
3. 3.Bear Team subgraph executes (same pattern)
4. 4.Judge compares theses → renders verdict
5. 5.Results saved to long-term memory

Current Status

Completed:

• —Real-Time Progress Indicator (January 2026) - Streaming progress updates during analysis
• —Uses graph.stream(stream_mode="updates") with Gradio generator pattern
• —Shows step-by-step progress (Desk Head → Research Teams → Judge → Report)
• —Parallel Bull/Bear team status with completion tracking
• —Analyst Architecture Fixed (January 2026) - Full FinCoT prompts now integrated
• —Bull Team: 14k-char Buffett-Fisher prompt with moat frameworks, Quality Constitution
• —Bear Team: 12k-char Munger-Klarman prompt with inversion methodology, Forensic Accounting Constitution
• —Named interpretation lenses (Owner, Moat, Fisher, Klarman, Marks, etc.)
• —Quality scorecards and mortality mapping now generated
• —Database persistence (Supabase) - Analyses now persist to long-term memory
• —Desk Head briefing extraction with LLM-based ticker identification
• —Parallel Bull/Bear team execution via LangGraph Send API
• —Judge verdict with structured output

Future Roadmap

Planned enhancements:

• —Enhanced Judge Logic: Full debate-style evaluation with rebuttals
• —Forensics Tool: Deep-dive financial forensics and accounting analysis
• —OpenBB Tools: Integration with OpenBB terminal for market data
• —RAG Knowledge Base: ChromaDB with Buffett letters for judge decisions