AlphaAnalyst-open-source-autonomous-equity-research-agent

AlphaAnalyst

AlphaAnalyst is an open-source autonomous equity research agent. Give it a US stock ticker and it produces a research memo: executive summary, financial snapshot, recent catalysts, DCF + comparables valuation, earnings-call tone shift, bull/bear cases, and risks — every numerical claim cited back to its primary source.

The pipeline runs ten data fetchers concurrently (SEC EDGAR, Polygon, FMP, Finnhub, MarketAux, Google News, FRED, Voyage embeddings, sec-api XBRL, FMP transcripts), indexes the long-form documents into pgvector, then runs six LLM agents — five “constructive” agents plus a Devil’s Advocate forced to use a different model family for genuine independence. A pure-Python DCF in decimal.Decimal and a peer-comparable multiples engine produce the valuation. A synthesizer with a hard schema and a citation validator writes the final memo.

Two design choices anchor the project: the LLM is a writer, not a knower (numbers come from APIs; the synthesizer downgrades any section whose numerical claims aren’t tagged to a real source) and valuation is pure Python (decimal.Decimal everywhere; no LLM ever touches an arithmetic operator). The result is a memo you can hand to an analyst and have them audit every number to a 10-K page.

Architecture

                     ┌──────────────┐
  ticker (e.g. TSLA) │   Frontend   │  Next.js 14 + TanStack Query
  ──────────────────►│  (App Router)│  Types codegen'd from /openapi.json
                     └──────┬───────┘
                            │ POST /api/v1/analyze
                            ▼
                     ┌──────────────┐
                     │   FastAPI    │  Lifespan, CORS, exception handlers
                     │ Orchestrator │  Per-step Redis progress writes
                     └──────┬───────┘
                            │ asyncio.gather
       ┌────────────────────┼─────────────────────────┐
       ▼                    ▼                         ▼
  ┌─────────┐         ┌──────────────┐          ┌──────────┐
  │Fetchers │         │   Indexer    │          │  Agents  │
  │  (10)   │         │ (Voyage AI,  │          │   (6+1)  │
  │         │         │   pgvector)  │          │          │
  └────┬────┘         └──────┬───────┘          └────┬─────┘
       │                     │                       │
       ▼                     ▼                       ▼
 SEC EDGAR / sec-api   Postgres + pgvector    Anthropic + OpenAI
 Polygon / FMP                                via LiteLLM
 Finnhub / MarketAux
 FRED / Google News
                            │
                            ▼
                     ┌──────────────┐
                     │   Modeler    │  decimal.Decimal everywhere
                     │ (DCF + Comps)│  5×5 sensitivity grid
                     └──────┬───────┘
                            │
                            ▼
                     ┌──────────────────┐
                     │   Synthesizer    │  task=synthesis (Claude Opus)
                     │     + Citation   │
                     │      Validator   │ ◄─── Devil's Advocate
                     └──────┬───────────┘      task=devils_advocate
                            │                  (gpt-4o, intentionally
                            │                   different family)
              ┌─────────────┴───────────────┐
              ▼                             ▼
          PDF (reportlab)               Excel (openpyxl)
                                        live formulas + sensitivity

Repository layout

alpha-analyst/
├── backend/                 Python service (FastAPI + agents + pipeline)
│   ├── src/
│   │   ├── clients/         External-API wrappers (httpx + tenacity)
│   │   ├── llm/             LiteLLM wrapper + cost tracking
│   │   ├── models/          Pydantic data models
│   │   ├── fetchers/        clients + cache + DB persistence
│   │   ├── agents/          LLM-driven analysis units + synthesizer
│   │   ├── modeler/         DCF + comps (pure Python)
│   │   ├── orchestrator/    pipeline + PDF/Excel exporters
│   │   └── api/             FastAPI app, routes, schemas
│   ├── alembic/             schema migrations
│   ├── config/models.yaml   per-task model + fallback config
│   └── tests/               pytest + respx + eval harness
├── frontend/                Next.js 14 app (App Router, TanStack Query)
├── scripts/run_evals.py     eval CLI (hits real APIs)
└── docker-compose.yml       postgres (pgvector) + redis

Setup

Prerequisites

• macOS / Linux
• Python 3.11+ via uv (brew install uv)
• Docker Desktop or OrbStack (brew install orbstack)
• Node.js 20+ and npm
• API keys (see backend/.env.example)

Backend

cd backend
cp .env.example .env                       # fill in API keys
uv sync                                    # creates .venv with all deps
docker compose -f ../docker-compose.yml up -d   # postgres + redis
uv run alembic upgrade head                # apply both migrations
uv run pytest                              # ~80 tests should pass
uv run uvicorn src.api.main:app --reload --port 8000

The API ships its OpenAPI schema at http://localhost:8000/openapi.json. Interactive docs at http://localhost:8000/docs.

Frontend

cd frontend
cp .env.local.example .env.local           # NEXT_PUBLIC_API_URL=...
npm install
npm run codegen                            # regenerates types/api.ts
npm run dev                                # http://localhost:3000

npm run codegen re-fetches /openapi.json and rewrites types/api.ts. Run it whenever the backend’s API contract changes.

Running an analysis

From the home page, type a ticker (e.g. TSLA) and press Enter. The page routes to /analysis/{job_id} which polls /api/v1/jobs/{job_id} every 2s, shows step-by-step progress, and renders the memo when the pipeline finishes. Download buttons in the right rail stream the PDF / live-formula Excel from the backend.

Production roadmap

• v0.2 Structured Memo: extend MemoResponse with financials.price_history, financials.annual_series, catalysts.events[], valuation.sensitivity_table, valuation.method_comparison. Wire into the existing chart components.
• v0.3 Multi-period DCF: orchestrator pulls 5+ years of XBRL facts, computes proper revenue CAGR, exposes per-segment series.
• v0.4 Backtesting harness: memo → forward-12-month return; track hit rate against benchmark.
• v0.5 Real-time streaming: incremental memo updates on new 8-Ks, news, or price moves > 2σ.
• v0.6 Multi-currency + non-US filers (TSE, LSE, HKEX).
• v0.7 MNPI compliance: source-provenance gate, audit log, per-user permissions.
• v1.0 Production observability: per-run tracing, cost dashboards, SLOs.

Tagging the v0.1.0 release

Once python scripts/run_evals.py passes locally:

git tag -a v0.1.0 -m "v0.1.0 — eval thresholds met"
git push --tags

---

A note on the eval suite philosophy. Every claim in this README — the memo’s structure, the Devil’s Advocate model split, the strict synthesizer validator — exists because we expect a human analyst to audit the output. The eval suite tests exactly that: numerical claims trace back to 10-K pages, citations are non-fabricated, the cost-per-analysis is sustainable. If those three properties degrade, the whole pitch falls apart, so the eval CLI is wired to fail loudly.