Skip to content

architecture.md

Latest commit

 

History

History
72 lines (57 loc) · 2.29 KB

architecture.md

File metadata and controls

72 lines (57 loc) · 2.29 KB
Raw

Architecture

Overview

The Financial AI Assistant is a backend-first service for financial insights. It combines live market data, retrieval-augmented knowledge lookup, and reasoning orchestration behind a FastAPI interface.

System Flow

User Query
    -> FastAPI Endpoint (POST /ask)
    -> FinancialAgent
    -> Tool Selection
    -> Market Data Tool (Finnhub API)
        -> RAG Query Engine (LlamaIndex + FAISS)
    -> Context Aggregation
    -> Analysis + Insight Generation
    -> Structured JSON Response

Component Map

  • app/main.py
    • FastAPI app bootstrap, global exception handler, startup/shutdown logging.
  • app/api/routes.py
    • HTTP routes: /health and /ask.
    • Request validation and HTTP-level error mapping.
  • app/agents/financial_agent.py
    • Query analysis, tool routing, fallback behavior, and response synthesis.
  • app/tools/market_data_tool.py
    • Finnhub market data retrieval and normalization helpers.
  • app/services/data_pipeline.py
    • Cleaning, metric derivation, and normalized stock output shaping.
  • app/rag/index_builder.py
    • Builds and loads FAISS-backed index from local finance documents.
  • app/rag/query_engine.py
    • Retrieves top-k snippets for financial concepts and definitions.
  • app/mcp/mcp_server.py
    • Exposes tools through MCP and provides a local MCP executor abstraction.

Data Layer

  • data/financial_docs/
    • Source documents for retrieval.
  • data/faiss_index/
    • Persisted vector index files and stores generated by LlamaIndex.

Error Handling Strategy

  • Input validation at API boundary and service boundaries.
  • Tool-level failure isolation in agent orchestration.
  • MCP tool execution and transport failures converted to explicit exceptions.
  • Centralized FastAPI catch-all handler for unhandled server errors.

Test Strategy

  • Unit tests by subsystem:
    • tests/test_data_pipeline.py
    • tests/test_rag_pipeline.py
    • tests/test_financial_agent.py
    • tests/test_mcp_server.py
    • tests/test_api_routes.py
  • End-to-end behavior validated through API route tests and direct pipeline calls.

Extensibility Notes

The architecture is intentionally modular to support future additions such as:

  • Additional retrieval corpora or embedding models.
  • Alternate LLM reasoning backends.
  • Additional MCP tools.
  • A future news retrieval module.