AI Financial Report Reader

An AI-powered platform for reading and analyzing financial reports using RAG/CAG/KAG architecture with Rust.

🏗️ Architecture

Functional Core - Imperative Shell + Railway Oriented Programming

├── core/               # Business logic (Functional Core)
│   ├── domain/        # Domain models
│   ├── ports/         # Trait interfaces
│   ├── adapters/      # I/O implementations (Imperative Shell)
│   ├── services/      # RAG/CAG/KAG services
│   └── agent/         # Agent orchestration
├── api/               # Axum REST API
├── cli/               # Ratatui terminal UI
├── financial_service/ # Python yfinance microservice
├── prompts.json       # Externalized System Prompts
├── llm_config.json    # LLM provider configuration
└── docker-compose.yml # Infrastructure orchestration

🛠️ Tech Stack

• Language: Rust
• File Storage: MinIO (S3-compatible)
• Database: SurrealDB (Vector + Graph + Memory Store)
• LLM: Multi-provider support (Ollama, Gemini, OpenAI, Anthropic)
• Embeddings: Ollama mxbai-embed-large
• PDF Extraction: Extractous
• Backend: Axum with streaming support
• CLI: Ratatui
• Financial Data: Python/yfinance microservice
• Web Search: Brave Search API
• Container: Docker Compose

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Rust toolchain (1.75+)
• (Optional) Local Ollama models cached at ~/.ollama

Option 1: Full Docker Mode (Recommended)

Run everything in Docker, including the API server:

./start.sh --docker

This will:

1. Start all infrastructure (SurrealDB, Ollama, MinIO, Financial Service)
2. Build and run the API server in Docker
3. Copy local Ollama models if available (faster startup)
4. Wait for all services to be healthy

Once ready, run the CLI:

cargo run --bin cli

Option 2: Local Development Mode

Run the API locally with Docker infrastructure:

# Start infrastructure only
./start.sh

# In terminal 1: Run API server
cargo run --bin api

# In terminal 2: Run CLI
cargo run --bin cli

Quick Rebuild

Rebuild only the API container without restarting infrastructure:

./start.sh --rebuild

📊 Services

Service	Port	Description
SurrealDB	8000	Vector, Graph, and Memory Database
Ollama	11434	LLM & embedding service
MinIO	9000	S3-compatible file storage
MinIO Console	9001	Web UI for file management
API Server	3000	REST API endpoints
Financial Service	8001	Python/yfinance for stock data

⚙️ Configuration

Environment Variables (.env)

Copy from example and customize:

cp .env.example .env

Key variables:

• GEMINI_API_KEY - Google Gemini API key
• OPENAI_API_KEY - OpenAI API key
• ANTHROPIC_API_KEY - Anthropic API key
• BRAVE_SEARCH_API_KEY - Brave Search API key
• OLLAMA_BASE_URL - Ollama endpoint (default: http://localhost:11434)

LLM Configuration (llm_config.json)

Configure which LLM provider and model to use for each task:

• Main LLM for generation
• Intent detection
• Entity extraction
• Embeddings

Prompts (prompts.json)

System prompts for the AI agents:

• general_system_prompt: Used for standard RAG/CAG queries
• financial_analysis_prompt: Used for financial analysis with Chain of Thought (CoT)

📖 Usage

Upload Document via API

curl -X POST http://localhost:3000/api/documents \
  -F "file=@NAB_2024_Annual_Report.pdf"

Query via API (Streaming)

curl -X POST http://localhost:3000/api/query/stream \
  -H "Content-Type: application/json" \
  -d '{"text": "What was the total revenue?", "max_results": 50}'

Query via API (Non-Streaming)

curl -X POST http://localhost:3000/api/query \
  -H "Content-Type: application/json" \
  -d '{"text": "What are the key financial highlights?", "max_results": 50}'

Using CLI

cargo run --bin cli

Features:

• Interactive document upload
• Real-time streaming responses
• Conversation history with CAG
• Multi-document support

🧪 Architecture Details

RAG/CAG/KAG Implementation

1. RAG (Retrieval Augmented Generation)

   • Vector similarity search on embeddings
   • Retrieve top-k relevant chunks
   • LLM generates answer with context

2. CAG (Context Augmented Generation)

   • Memory Manager: Short-term (Sliding Window) and Long-term (Vector Search)
   • SurrealDB Memory Store: Persists conversation history
   • Context-aware follow-up questions

3. KAG (Knowledge Augmented Generation)

   • Graph traversal to find related documents
   • Cross-document knowledge synthesis
   • Relationship-aware answers

4. Agent Orchestrator

   • Intent Detection: Routes queries to RAG, Financial Analysis, or Web Search
   • Web Search: Integrates real-time data via Brave Search API
   • Financial Service: Fetches live stock data via yfinance
   • Multi-entity Support: Handles queries about multiple companies

Data Flow

PDF Upload → MinIO Storage
           → PDF Extraction (Extractous)
           → Text Chunking (Semantic)
           → Embedding Generation (Ollama)
           → Vector Storage (SurrealDB)
           → Graph Relationships (SurrealDB)

Query → Intent Detection (Orchestrator)
      → [Web Search Strategy] → Brave Search → Answer
      → [Financial Data Strategy] → yfinance Service → Answer
      → [RAG/CAG Strategy]
          → Memory Retrieval (Short-term + Long-term)
          → Vector Similarity Search (Documents)
          → LLM Generation (Streaming)
          → Answer with Citations

🧩 Project Structure

AI_Financial_Report_Reader_v5/
├── api/                       # REST API Server (Axum)
│   └── src/
│       ├── main.rs           # Server setup, routes, AppState
│       ├── dto.rs            # Request/Response DTOs
│       └── handlers/         # Route handlers
│           ├── documents.rs  # Upload, list, delete documents
│           ├── query.rs      # Query & streaming endpoints
│           └── health.rs     # Health check
│
├── cli/                       # Terminal UI Client (Ratatui)
│   └── src/
│       ├── main.rs           # TUI application
│       ├── ui.rs             # UI components & layout
│       ├── client.rs         # API client with streaming
│       ├── markdown.rs       # Markdown rendering
│       └── utils.rs          # Helper utilities
│
├── core/                      # Business Logic (Functional Core)
│   └── src/
│       ├── config.rs         # Configuration management
│       ├── domain/           # Pure domain models
│       │   ├── mod.rs        # Document, Chunk, Query, Answer
│       │   ├── entity.rs     # Named entities (Company, Ticker)
│       │   ├── agent.rs      # Agent types & tools
│       │   ├── memory.rs     # MemoryEntry, conversation history
│       │   └── error.rs      # Domain errors (Railway pattern)
│       │
│       ├── ports/            # Trait interfaces (Dependency Inversion)
│       │   ├── llm.rs        # LLM trait (generate, stream)
│       │   ├── embedding.rs  # Embedding trait
│       │   ├── vector_db.rs  # VectorDatabase trait
│       │   ├── graph_db.rs   # GraphDatabase trait
│       │   ├── memory_store.rs # MemoryStore trait
│       │   ├── file_storage.rs # FileStorage trait
│       │   ├── pdf_extractor.rs # PdfExtractor trait
│       │   ├── web_search.rs # WebSearch trait
│       │   ├── financial.rs  # FinancialData trait
│       │   └── entity_extraction.rs # NER trait
│       │
│       ├── adapters/         # Concrete Implementations
│       │   ├── ollama.rs     # Ollama LLM & embeddings
│       │   ├── gemini_llm.rs # Google Gemini LLM
│       │   ├── gemini_custom.rs # Custom Gemini client
│       │   ├── llm_factory.rs # Multi-provider factory
│       │   ├── surrealdb_vector.rs # Vector storage
│       │   ├── surrealdb_graph.rs  # Graph relationships
│       │   ├── surrealdb_memory.rs # Conversation memory
│       │   ├── rustfs.rs     # MinIO S3 storage
│       │   ├── pdf_extractous.rs # PDF extraction (Extractous)
│       │   ├── brave_search.rs # Brave Search API
│       │   ├── financial_service.rs # yfinance client
│       │   └── ollama_ner.rs # Named Entity Recognition
│       │
│       ├── services/         # Business Logic Services
│       │   ├── document_ingestion.rs # Upload & indexing
│       │   ├── embedding.rs  # Embedding generation
│       │   ├── memory_manager.rs # Short/long-term memory
│       │   ├── query_processing.rs # Query preprocessing
│       │   ├── re_ranker.rs  # Result re-ranking
│       │   ├── router_agent.rs # Intent detection & routing
│       │   ├── agent_orchestrator.rs # Main orchestrator
│       │   ├── cag.rs        # Context Augmented Generation
│       │   └── kag.rs        # Knowledge Augmented Generation
│       │
│       └── agent/            # Agent Framework
│           ├── agent.rs      # Agent execution loop
│           ├── builder.rs    # Agent builder pattern
│           ├── tool.rs       # Tool definitions
│           └── prompts.rs    # Agent system prompts
│
├── financial_service/         # Python Microservice (yfinance)
│   ├── main.py               # FastAPI server
│   ├── Dockerfile
│   └── requirements.txt
│
├── scripts/                   # Utility Scripts
│   ├── download_models.sh    # Ollama model setup
│   ├── run_benchmark.sh      # Performance benchmarks
│   └── test_*.sh             # Test scripts
│
├── docker-compose.yml         # Infrastructure orchestration
├── Dockerfile                 # API container build
├── start.sh                   # One-command startup
├── llm_config.json           # LLM provider configuration
├── prompts.json              # System prompts
└── .env.example              # Environment template

🔧 Development

Run Tests

cargo test --workspace

Run Benchmark

./scripts/run_benchmark.sh

Check Code

cargo check
cargo clippy

Format Code

cargo fmt

🐛 Troubleshooting

Port 3000 Already in Use

lsof -ti:3000 | xargs kill -9

Ollama Models Not Loading

# Models are auto-copied from ~/.ollama if available
# Otherwise, pull manually:
docker exec -it ollama ollama pull qwen3:8b
docker exec -it ollama ollama pull mxbai-embed-large

SurrealDB Connection Issues

# Check container health
docker exec surrealdb /surreal isready --conn http://localhost:8000

# Restart if needed
docker-compose restart surrealdb

MinIO Access

Default credentials: minioadmin / minioadmin

Console: http://localhost:9001

Docker Daemon Issues

If using both Podman Desktop and OrbStack, ensure only one is running:

# Check current Docker context
docker context ls

# Switch to OrbStack
docker context use orbstack

📄 License

MIT License

👥 Contributors

Mike Graham