market-agent

An AI stock analyst that doesn't make up numbers.
Ask about any US company. Get charts, tables, and analysis built from SEC filings and market data, and open a linked figure to see where it came from.

Asking the analyst to compare NVDA and AMD, then opening the evidence behind one figure

Ask a general-purpose chatbot for a company's gross margin and you get a confident number with no way to check it. market-agent answers only from facts it has stored: SEC company facts, filing extracts, and Polygon prices. Code, not the model, builds the charts and tables. The model writes the narrative, but its figures come from the evidence the app gathered, and linked figures open to their source. A second model checks each inference before you see it.

Quickstart

Try the demo in your browser, with nothing to install. It replays one recorded conversation, so ask its three questions in order and open any linked figure to see its source.

To run it yourself, try the analyst offline first. This needs Node 22.19 or later and npm. No Docker, no API keys.

git clone https://github.com/xang1234/market-agent.git
cd market-agent
cp .env.dev.example .env.dev
DEV_PROFILE=chat DEV_MODE=ui ./scripts/dev-shell.sh up

Open http://localhost:5173. Dev mode signs you in as a mock user. Go to Chat, start a thread, and ask these word for word: Analyze NVDA, then Compare it with AMD YTD, then Explain the differences and show the evidence. This mode replays a recorded conversation, so other questions and most other pages have no data.

Run it on live data

The full stack needs Docker for Postgres and MinIO. Add your keys to .env.dev, then start it:

# in .env.dev
POLYGON_API_KEY=...                                 # tickers, quotes, and bars
SEC_EDGAR_USER_AGENT="market-agent [email protected]" # SEC fundamentals
LLM_CHANNELS=anthropic                              # or any OpenAI-compatible endpoint
LLM_ANTHROPIC_PROTOCOL=anthropic
LLM_ANTHROPIC_API_KEY=...
LLM_ANTHROPIC_MODELS=claude-sonnet-5-5,claude-haiku-5-5
LITELLM_MODEL=anthropic/claude-sonnet-5-5
JUDGE_LITELLM_MODEL=anthropic/claude-haiku-5-5

./scripts/dev-shell.sh up   # installs packages, migrates, seeds, and starts the services

Chat answers only from facts already stored. Open a company's symbol page once, on the Financials tab, to fetch its SEC facts before you ask about it.

Configuration lists every key and model setting. Development covers the other dev modes and tests.

What you can do


Chat with an analyst. Answers arrive as charts, tables, metric rows, and a short narrative. Threads persist.	Check the numbers. Click a linked figure to see the fact behind it and open the source filing. Each chart, table, and metric row is labelled verified, source-linked, or not verified.

Research a company. Price history, key stats, analyst consensus, and price targets, with financials, earnings, holders, and signals one tab away.	Screen the market. Filter by sector, growth, valuation, returns, and technicals. Save a screen and reuse it as a universe for agents and grids.

Watch a thesis. Agents check your thesis conditions on a schedule, mark each one supported, challenged, or unresolved, and link to the evidence when there is some.	See what changed. Home collects agent findings, market pulse, watchlist movers, and pinned screens.

The user guide covers every page, including Analyze memos, Analyst Grids, watchlists, the review queue, and Settings.

How it works

The resolver turns each company you name into a canonical id. An ambiguous name gets a clarifying question, not a guess.
Code builds the charts, tables, and metric rows from stored facts. The analyst does not browse the web.
The model writes its narrative as structured assertions. A check rejects any assertion whose references or comparisons do not match the evidence. Every figure in the prose comes from a template filled with a value from the evidence.
The app seals a snapshot of every fact the answer used and checks each one against the logged tool calls. That snapshot is what the evidence inspector shows.
A judge model checks each inference against the facts it rests on. An inference appears only once the judge accepts it.

Set CHAT_FINANCIAL_MODE=enforce and questions that name a metric run through the financial engine, which computes with exact fractions and shows anything it cannot verify as a gap. Other questions still use the standard path until #398 lands. Architecture has the full flow and the service map.

Documentation

Guide	For
User guide	Every page in the app
Configuration	API keys, models, data sources, and the financial engine
Development	Dev modes, the golden conversation, and tests
Architecture	How an answer is built, and what each service owns
Discovery campaigns	Rolling out discovery campaigns safely
Design decisions	Architecture decision records

Roadmap

Route every company question through the verified financial engine (#398)
Live business-segment revenue in cited chat breakdowns (#196)
Valuation scenarios with explicit P/E assumptions and dated analyst estimates (#201, #224, #225)
Comparisons that disclose their basis, peers, and exclusions (#209), and checked gap comparisons (#288)
A wider research-quality eval beyond NVDA, AMD, and AAPL, with a blinded review (#283, #222)
Discovery campaigns through their release review (rollout plan)

The two epics, #190 and #205, track the rest.

Contributing

Issues and pull requests are welcome. Work is tracked in GitHub Issues. Start with Development. If you use a coding agent, point it at AGENTS.md.

Disclaimer

market-agent is a research tool. It is not financial advice and it does not place trades. Check the sources before you act on anything it shows you.

License

MIT.