Automatisor Financial Research Agent

This project is a local financial research assistant. You choose an analyst persona and a sector, ask a question, and receive an answer grounded in the included SQLite database.

The agent does not search the internet while answering questions. It reads financial data only through the MCP server, and every result includes source links, the data date, confidence, and any important limitations.

Run the project

1. Install the requirements

You need:

• Python 3.12

• uv

• An OpenAI API key

Open a terminal in the project folder and run:

uv sync

This installs all required Python packages.

2. Create the environment file

Copy the example file:

Copy-Item .env.example .env

Open .env and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

That is the only value you must provide to use the included database. The other settings already contain working local defaults.

SEC_USER_AGENT is needed only if you choose to rebuild the database from SEC filings. It is not needed for normal testing.

3. Start the three services

Open three terminals in the project folder. Keep all three running.

Terminal 1 — start the MCP server:

uv run automatisor-mcp

Terminal 2 — start the API:

uv run automatisor-api

Terminal 3 — start the user interface:

uv run streamlit run streamlit_app.py --server.address 127.0.0.1

Open http://127.0.0.1:8501 in your browser.

Related MCP server: Stock Research Data Foundation MCP Server

Questions you can try

Choose the matching persona and sector in the left sidebar before asking a question.

The covered companies are:

• Tech: Box, Dropbox, Teradata, and Rapid7

• Retail: Abercrombie & Fitch, Urban Outfitters, Dick's Sporting Goods, and Best Buy

• Logistics: GXO Logistics, Hub Group, ArcBest, and C.H. Robinson

About the included database

The repository already includes data/financial_agent.db. The reviewer does not need to build or download data before using the application.

This database is a point-in-time snapshot built from real source data:

• SEC Company Facts for reported financial metrics

• SEC 10-K and 10-Q filings for headcount, hiring, strategy, operations, and risks

• Yahoo Finance price history for the IGV, XRT, and IYT sector benchmarks

It currently contains 12 companies, 380 financial metric rows, 55 operating signals, 148 qualitative evidence records, and 64 source records. It contains no synthetic fixture sources.

When a user asks a question, the agent and MCP server read this local database. They do not fetch new information from the internet. This keeps answers reproducible and prevents the model from filling gaps with unverified web information.

The data is real but not permanently current. Every answer therefore shows its data date and limitations. For example, headcount is often reported annually and may be older than the latest quarterly financial results.

Optional: rebuild the database with newer data

This step is not required for normal review. To rebuild the database, first set a real SEC contact value in .env:

SEC_USER_AGENT=Your Name your.email@example.com

Then run:

uv run automatisor-build-db --mode live --cache-dir data/cache --output data/financial_agent.db

The cache stores downloaded SEC and market responses so an interrupted or repeated build does not download the same files again.

Database schema design

The SQLite database uses six linked tables. Financial facts, operating signals, qualitative evidence, and benchmarks all point to a source record. Runtime access is read-only.

Read the database schema design

MCP design

MCP is the safety boundary between the AI agent and the database. The agent cannot run arbitrary SQL and cannot write to the database. It can use only six predefined, validated tools.

Read the MCP design

MCP tools and capabilities

All tools are sector-scoped, read-only, parameterized, and bounded. Missing companies or metrics return safe error codes instead of raw database errors.

One improvement with more time

I would add richer sector-specific operating KPIs. The current database has a strong common financial foundation, but measures such as SaaS retention for software, comparable-store sales for retail, and shipment or yield metrics for logistics would make company comparisons more precise.

Architecture

At question time, the path is always: User → Streamlit → API → Agent → MCP → SQLite. Internet sources are used only by the optional database build command.

flowchart LR
    User[User in browser] --> UI[Streamlit UI :8501]
    UI --> API[FastAPI :8000]
    API --> Agent[Financial research agent]
    Agent -->|Six approved tools| MCP[MCP server :8001]
    MCP --> Repo[Read-only repository]
    Repo --> DB[(SQLite real-data snapshot)]

    SEC[SEC filings and Company Facts] -->|Database build only| Builder[Ingestion pipeline]
    Yahoo[Yahoo benchmark history] -->|Database build only| Builder
    Builder --> DB