Financial AI Agent

A conversational application for exploring a simulated investment portfolio. It combines streamed LLM responses, retrieval-augmented generation, typed MCP tools, persistent sessions, and explicit trade confirmation in a reproducible six-service architecture.

This is an academic proof of concept. It uses historical 2024 market data projected onto a 2025 timeline, does not connect to a broker, and is not financial advice.

What the system does

• Streams assistant output and processing events to a React interface with server-sent events.
• Routes requests between general conversation, retrieval, and portfolio actions.
• Exposes seven portfolio and market-data operations through Model Context Protocol tools.
• Stores portfolios, orders, and chat sessions in PostgreSQL.
• Retrieves project knowledge and market context from ChromaDB.
• Converts trade requests into pending actions that require explicit confirmation.
• Runs locally through Docker Compose with Ollama for generation and embeddings.

Architecture

Service	Responsibility	Technology	Port
Frontend	Chat, portfolio state, citations, and processing trace	React, Vite	3000
Inference API	Orchestration, guardrails, SSE, and trade-intent flow	FastAPI	8081
MCP server	Typed portfolio, order, and price tools	FastAPI, FastMCP	8000
RAG pipeline	Ingestion, embeddings, and retrieval	ChromaDB, Ollama	-
Database	Portfolios, orders, and sessions	PostgreSQL	5432
Local models	Text generation and embeddings	Ollama, Qwen 2.5	11434

The model never receives direct database access. The inference service decides when a tool is appropriate, the MCP server validates and executes typed operations, and PostgreSQL remains the source of truth.

My contribution

This was a two-person academic project. I owned the backend architecture, agent orchestration, MCP integration, persistence, containerization, tests, and most frontend integration.

Concretely, I:

• built and refined the FastAPI orchestrator, server-sent event protocol, guardrails, and error handling;
• migrated portfolio state from JSON to PostgreSQL and moved executable operations behind FastMCP;
• implemented the pending-order and confirmation flow so generated text cannot silently mutate the portfolio;
• integrated RAG queries, citations, MCP tool-call visibility, and persistent sessions;
• containerized the full stack and added health checks and persistent volumes;
• added focused tests around guardrails, price lookup, order execution, persistence, and confirmation.

Run locally

Requirements: Docker with Compose, at least 8 GB RAM, and enough disk space for the Ollama models.

git clone https://github.com/SnaetWarre/Financial_AI_Agent.git
cd Financial_AI_Agent
cp .env.example .env
docker compose up --build

Then open:

• frontend: http://localhost:3000
• inference API docs: http://localhost:8081/docs
• MCP health endpoint: http://localhost:8000/health

The first start is slower because Ollama downloads the configured models and the RAG service builds its index.

Verification

# Static Python validation used in CI
python -m compileall inference mcp-server rag-pipeline shared

# Frontend production build
npm --prefix frontend ci
npm --prefix frontend run build

# Service-level tests, after the required services are available
pytest inference/tests
pytest mcp-server/tests

Supported simulated assets

SPY, GLD, SLV, AGG, TLT, and VNQ.

Limitations and production considerations

• Prices are projected historical data, not a live market feed.
• The application simulates trading and has no broker integration.
• A production version would need authenticated users, authorization boundaries, encrypted secrets, audit logging, rate limits, model and retrieval monitoring, live-data licensing, and human-reviewed financial compliance.
• Generated answers remain probabilistic; confirmation and typed tools reduce risk but do not make model output authoritative.

Further reading

• Architecture and engineering case study
• Project report

License

MIT