Modern financial applications often fail when they rely on black-box LLMs for financial analysis. This creates a critical risk: hallucinated calculations, inconsistent projections and unreliable recommendations.
This engine solves that problem by separating deterministic computation from natural language synthesis.
The system uses Python and SQL for all financial calculations, forecasts and alert conditions. The LLM is used exclusively to interpret results, summarize insights and generate executive-style briefings.
In other words: the model does not calculate. The system calculates. The model explains.
The system implements a state-machine architecture using LangGraph.
The agent does not guess financial answers. Instead, it follows a controlled workflow and invokes deterministic SQL tools to retrieve precise financial data.
This makes the agent auditable, modular and safer for financial use cases.
The financial logic is handled outside the LLM.
The engine implements:
- Weighted moving averages for forecasting.
- Three-month rolling windows for trend detection.
- Alert triggers based on deficit projections and threshold breaches.
- Deterministic calculations for savings goals and financial risk indicators.
This ensures consistency, auditability and repeatable outputs.
The system follows a decoupled backend/frontend architecture.
The backend is built with FastAPI and exposes the core financial intelligence layer through API endpoints. This allows the engine to be integrated with external dashboards, internal tools or future frontend interfaces.
This separation improves scalability, maintainability and deployment flexibility.
The intelligence layer uses Gemini 1.5 Flash to transform raw numerical outputs into clear, empathetic and actionable executive briefings.
The LLM is not responsible for financial computation. Its role is to synthesize deterministic results into human-readable insights.
This reduces hallucination risk while preserving the value of natural language interaction.
Defines the agentic workflow using LangGraph nodes.
This module controls the state transitions, tool invocation logic and overall reasoning flow of the financial agent.
Implements the deterministic monitoring service.
This module calculates deficit projections, detects threshold breaches and determines when an alert should be triggered before sending the result to the LLM notification layer.
Contains the forecasting logic for financial projections and savings goal tracking.
This module handles trend analysis, goal progress evaluation and prediction-related calculations.
Every agent response is tied to a specific SQL tool execution or deterministic calculation.
This makes the system explainable and easier to debug, test and validate.
The architecture supports adding new analytical tools as additional LangGraph nodes without rewriting the core orchestration logic.
New capabilities can be integrated progressively while preserving the stability of the system.
By delegating math to Python and SQL, the system eliminates LLM-based arithmetic errors.
The LLM acts as a communication layer, not as the source of financial truth.
This project shows more than interface-building. It demonstrates architectural thinking.
The key senior-level decisions are:
- Designing an agent as a controlled state machine instead of a free-form chatbot.
- Separating deterministic computation from language generation.
- Using SQL and Python as the source of truth for financial logic.
- Limiting the LLM to interpretation, summarization and alert communication.
- Building a modular architecture that can scale through additional tools and nodes.
- Prioritizing auditability, reliability and explainability in a high-risk domain.
A junior profile builds an interface around an LLM.
A senior AI engineering profile designs the system around the limits of the LLM.
That distinction is the core value of this project.