Fintel | Technical Documentation
Summary: This agent combines role-based access control (RBAC), historical database management, and AI-powered natural language processing using Google Gemini models. The system is designed to focus on accuracy of agent reply with a simplified 2-role architecture for executive decision-making.
Key Features: - Two data ingestion pipelines: (1) Historical financial data sourced from the Data Warehouse, assuming an existing monthly ETL from SAP/HFM/ERP systems; and (2) Current-period data, including latest-month actuals and planning/analysis reports, uploaded manually for analysis. - 2-Role System: Group CEO (strategic view) and BU General Manager (detailed view) - Historical data from enterprise systems (SAP, HFM, ERP) - Real-time file upload and analysis (CSV, Excel, PDF) - Multi-dimensional financial reporting (P&L, Balance Sheet, Cash Flow) - Role-based data filtering and aggregation - Efficient cost on token usage: ~296 tokens per AI request - Space-efficient file storage: references only, no duplicates
1 Part 1: System Architecture and Workflow
1.1 1.1 High-Level Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Frontend Layer (HTML/JS) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ AI Chat UI │ │ File Upload │ │ User Login │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓ HTTPS / JWT Auth
┌─────────────────────────────────────────────────────────────────┐
│ Backend API Layer (FastAPI) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Auth Service │ │ Data Service │ │ File Service │ │
│ │ (JWT/Hash) │ │ (SQL Queries)│ │(CSV/PDF Read)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ RBAC Engine │ │ LLM Orchestr.│ │ Prompt Mgmt │ │
│ │(2-Role GCEO/ │ │(Gemini 2.5) │ │ ~296 tokens │ │
│ │ BUGM) │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Data & AI Layer │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ PostgreSQL Database │ │ Google Gemini AI │ │
│ │ (Neon Cloud) │ │ (gemini-2.5-flash/pro) │ │
│ │ ┌────────────────────┐ │ │ ┌────────────────────┐ │ │
│ │ │ financial_pl │ │ │ │ Compact Context │ │ │
│ │ │ balance_sheet │ │ │ │ Multi-turn Context│ │ │
│ │ │ cash_flow │ │ │ │ Role Awareness │ │ │
│ │ │ sap_gl_trans │ │ │ │ Structured Output │ │ │
│ │ │ hfm_actuals/budget │ │ │ └────────────────────┘ │ │
│ │ │ variance_report │ │ │ │ │
│ │ └────────────────────┘ │ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘1.2 1.2 System Workflow
Complete Request Flow:
1. User Login (JWT Authentication)
↓
2. Frontend: User types financial query
↓
3. Frontend: Optionally attach uploaded files
↓
4. API Request: POST /ai/chat
↓
5. Authentication Middleware
- Verify JWT token
- Extract user (email, role, BU assignment)
↓
6. RBAC Check
- Role: GCEO or BUGM?
- Get BU assignment for BUGM
↓
7. Build Minimal System Prompt (~80 tokens)
- Essential financial context
- Mandatory response format
↓
8. Query Database (Role-Based)
┌─────────────────┬─────────────────────┐
│ GCEO │ BUGM │
├─────────────────┼─────────────────────┤
│ Aggregated 30 │ Summary 50 rows │
│ All BUs │ Assigned BU only │
│ GROUP BY BU │ WHERE BU = 'APAC' │
└─────────────────┴─────────────────────┘
↓
9. Calculate Financial Metrics (Compact)
- Revenue, COGS, OpEx (one-line format)
- Gross Profit, Operating Income
↓
10. Read Uploaded Files (if provided, compact summary)
- CSV/Excel: 5-row preview + stats
- PDF: 300-char preview
- Reference original file only
↓
11. Build LLM Prompt (~296 tokens total)
- Minimal prompt + Compact data + User query
↓
12. Call Gemini AI
- Model: gemini-2.5-flash (fast) or gemini-2.5-pro (complex)
- Temperature: 0.3 (focused responses)
↓
13. Parse & Return Structured Response
**Answer:** [Direct answer]
**Details:** [Bullet points]
**Source:** [Table/file name]
↓
14. Frontend: Display in chat UI1.3 1.3 Key Components
1.3.1 1.3.1 Data Ingestion
Two Data Flows:
Flow 1: Historical Financial Data (ETL from Enterprise Systems)
- Source: Enterprise Data Warehouse (pre-loaded via ETL from SAP, HFM, ERP)
- ETL Frequency: Monthly batch updates from upstream systems
- Storage: PostgreSQL Database (Neon Cloud) with 7 tables, 585+ rows
- Characteristics:
- Historical data that rarely changes
- Already transformed and validated by ETL pipeline
- Pre-aggregated for performance
- Indexed for fast role-based queries
Database Tables: - financial_pl - P&L statements (153 rows) - balance_sheet - Balance sheet data (150 rows) - cash_flow - Cash flow statements (114 rows) - sap_gl_transactions - SAP General Ledger (48 rows) - hfm_actuals - HFM actual data (36 rows) - hfm_budget - HFM budget data (36 rows) - variance_report - Budget vs Actual variance (48 rows)
Note: The application does NOT handle ETL processes. Database is assumed to be pre-populated by enterprise ETL pipelines (e.g., SAP Data Services, Informatica, Talend).
Flow 2: Latest Month Reports / Planning Data (Manual File Upload)
Source: User-uploaded files (CSV, Excel, PDF)
Purpose:
- Latest month/quarter reports not yet in Data Warehouse
- Planning/forecasting files for scenario analysis
- Ad-hoc analysis reports
Storage: Local filesystem (
uploads/directory) - temporary storage onlyProcessing Strategy: Reference-only approach (no duplicate JSON files)
Processing:
# back/file_processor.py CSV/Excel → pandas.read_csv() → DataFrame ↓ Extract compact summary (5 rows preview, 4 stats only) ↓ Store original_file_path reference (no JSON duplicate) ↓ Format for LLM (100 tokens per file)Use Cases:
- “Analyze this month’s preliminary P&L (not yet in SAP)”
- “Compare this planning scenario with historical budget”
- “Review this external market report PDF”
1.3.2 1.3.2 LLM Orchestration
Architecture Pattern: RAG (Retrieval-Augmented Generation)
User Query
↓
[Retrieval Phase]
├─→ Database Query (Compact: 30-50 rows, aggregated)
├─→ Financial Metrics (One-line format)
└─→ File Upload Read (5-row preview, no duplicate)
↓
[Augmentation Phase]
Build Context (~296 tokens total):
- System: Minimal prompt (80 tokens)
- Metrics: Compact format (50 tokens)
- Historical: Summary data (150 tokens)
- Files: Preview only (16 tokens)
↓
[Generation Phase]
Gemini AI Model
├─→ gemini-2.5-flash (default, 1-2s)
└─→ gemini-2.5-pro (complex, 3-5s)
↓
Structured Response:
**Answer:** [Direct answer]
**Details:** [Bullet points]
**Source:** [Table/file]Implementation (back/main.py):
@app.post("/ai/chat")
async def ai_chat(request: ChatRequest,
current_user: User = Depends(get_current_user)):
# Minimal system prompt (~80 tokens)
user_bu = get_user_bu(current_user.email)
system_prompt = f"""You are a Financial Analyst AI for {current_user.role.upper()}{f' ({user_bu})' if user_bu else ''}.
Answer in SAME LANGUAGE as question. Use terms: Revenue, COGS, OpEx, EBITDA, Gross Margin.
MANDATORY FORMAT - Include ALL sections below:
**Answer:**
[Direct answer with key numbers]
**Details:**
• Key point 1 with number
• Key point 2 with number
• Key point 3 (if relevant)
**Source:** [financial_pl / uploaded file name]
"""
# Compact historical data (~150 tokens)
from back.data_service import get_all_historical_context
historical_data = get_all_historical_context(
current_user.role,
current_user.email
)
# Returns: "P&L DATA (APAC, Summary by Category):\n[30 rows]\nKEY METRICS:\nRevenue: $35.6M | COGS: $15.7M | OpEx: $16.3M"
system_prompt += historical_data
# Compact file summary (~16 tokens per file)
if request.file_ids:
for file_id in request.file_ids:
metadata = uploaded_files_store[file_id]
file_context = format_file_summary_for_llm(
metadata["file_summary"],
metadata["original_filename"]
)
# Returns: "File: sales.csv (CSV)\n1000 rows × 10 cols\nPreview: [200 chars]..."
system_prompt += f"\n\n{file_context}"
# Build full prompt (~296 tokens total)
full_prompt = system_prompt + "\n\nUser: " + request.message
# Call Gemini AI
model = genai.GenerativeModel(model_name=request.model)
response = model.generate_content(
full_prompt,
generation_config=genai.GenerationConfig(
temperature=0.3,
max_output_tokens=2048
)
)
return {"response": response.text}Token Efficiency:
| Metric | Context Size | Cost per Request | Requests per $1 |
|---|---|---|---|
| Current System | ~296 tokens | $0.000044 | 22,700 requests |
(Based on Gemini 2.5 Flash pricing: $0.15/1M input tokens)
1.3.3 1.3.3 Prompt Design
System Prompt Structure (Minimal - 80 tokens):
# back/main.py
system_prompt = f"""You are a Financial Analyst AI for {role.upper()} ({user_bu}).
Answer in SAME LANGUAGE as question. Use terms: Revenue, COGS, OpEx, EBITDA, Gross Margin.
MANDATORY FORMAT - Include ALL sections below:
**Answer:**
[Direct answer with key numbers]
**Details:**
• Key point 1 with number
• Key point 2 with number
• Key point 3 (if relevant)
**Source:** [financial_pl / uploaded file name]
Example response:
User: "What is our OpEx?"
AI:
**Answer:**
Total OpEx is $16.3M, representing 45.8% of revenue.
**Details:**
• APAC region contributes largest share
• Q1-Q3 data from financial_pl table
• 3-month trend shows 5% increase
**Source:** financial_pl table (APAC business unit)
"""Design Principles: - Role context (BUGM/GCEO) - Language instruction (respond in same language) - Mandatory structured format - One clear example - Essential financial terminology only
Financial Metrics Format (Compact - 50 tokens):
# back/data_service.py
context += "\nKEY METRICS:\n"
context += f"Revenue: ${metrics['total_revenue']/1e6:.1f}M | "
context += f"COGS: ${metrics['total_cogs']/1e6:.1f}M | "
context += f"OpEx: ${metrics['total_opex']/1e6:.1f}M\n"
context += f"GP: ${metrics['gross_profit']/1e6:.1f}M ({metrics['gross_margin']:.1f}%) | "
context += f"OpIncome: ${metrics['operating_income']/1e6:.1f}M ({metrics['operating_margin']:.1f}%)\n"
# Example output:
# KEY METRICS:
# Revenue: $35.6M | COGS: $15.7M | OpEx: $16.3M
# GP: $19.9M (56.0%) | OpIncome: $3.6M (10.2%)1.3.4 1.3.4 Role-Based Access Control (RBAC)
2-Role System:
# back/role_access.py
ROLE_ACCESS_MATRIX = {
"gceo": { # Group CEO
"level": "STRATEGIC",
"description": "Consolidated strategic view across all BUs",
"data_level": "Aggregated by BU, Category, Period",
"query_limit": 30,
"can_access": {
"financial_pl": "AGGREGATED",
"balance_sheet": "AGGREGATED",
"cash_flow": "AGGREGATED",
"hfm_actuals": "CONSOLIDATED",
"variance_report": "SUMMARY"
}
},
"bugm": { # BU General Manager
"level": "BU_DETAILED",
"description": "Summary view for assigned BU only",
"data_level": "Aggregated by period & category",
"query_limit": 50,
"can_access": {
"financial_pl": "BU_FILTERED_SUMMARY",
"balance_sheet": "BU_FILTERED",
"cash_flow": "BU_FILTERED",
"hfm_actuals": "ENTITY_FILTERED",
"variance_report": "BU_FILTERED"
}
}
}SQL Query Generation:
GCEO (Strategic Aggregated View):
SELECT
business_unit,
category,
TO_CHAR(date, 'YYYY-MM') as period,
SUM(amount) as total_amount
FROM financial_pl
WHERE actual_budget = 'Actual'
GROUP BY business_unit, category, TO_CHAR(date, 'YYYY-MM')
ORDER BY period DESC, business_unit, category
LIMIT 30BUGM - APAC (Summary by Category):
SELECT
TO_CHAR(date, 'YYYY-MM') as period,
category,
subcategory,
SUM(amount) as total_amount,
COUNT(*) as line_items
FROM financial_pl
WHERE actual_budget = 'Actual'
AND business_unit = 'APAC'
GROUP BY TO_CHAR(date, 'YYYY-MM'), category, subcategory
ORDER BY period DESC, category
LIMIT 50Query Characteristics:
| Metric | GCEO | BUGM |
|---|---|---|
| Rows returned | 30 | 50 |
| Data scope | All BUs | Assigned BU only |
| Aggregation | GROUP BY BU | GROUP BY category |
| Query execution time | 180ms | 180ms |
1.4 1.4 Security and Accuracy Measures
1.4.1 Security Measures:
1. Authentication & Authorization
# JWT Token-based authentication
# back/auth.py
def create_access_token(email: str) -> str:
payload = {
"sub": email,
"exp": datetime.utcnow() + timedelta(minutes=30)
}
return jwt.encode(payload, SECRET_KEY, algorithm="HS256")
# Protected endpoints
@app.post("/ai/chat")
async def ai_chat(current_user: User = Depends(get_current_user)):
# current_user automatically extracted from JWT
# Includes: email, role, is_adminSecurity Features: - JWT tokens with 30-minute expiry - Bcrypt password hashing (cost factor 12) - Token verification on every request - Automatic role extraction from token
2. File Upload Security
# back/file_processor.py
ALLOWED_EXTENSIONS = {'.csv', '.xlsx', '.xls', '.pdf'}
MAX_FILE_SIZE = 10 * 1024 * 1024 # 10MB
def validate_file(filename: str, file_size: int):
# Extension whitelist
ext = Path(filename).suffix.lower()
if ext not in ALLOWED_EXTENSIONS:
raise ValueError("File type not allowed")
# Size limit
if file_size > MAX_FILE_SIZE:
raise ValueError("File too large")
# Unique filename (prevent overwrite)
unique_name = f"{uuid.uuid4()}_{filename}"
# User-specific storage (no duplicate JSON created)
user_folder = f"uploads/{user_email}/"3. Database Security
# .env file (not committed to Git)
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
# Connection security
engine = create_engine(
DATABASE_URL,
pool_pre_ping=True, # Verify connections
connect_args={
"sslmode": "require", # Force SSL/TLS
"connect_timeout": 10
}
)1.4.2 Accuracy Measures:
1. Data Quality Checks
# Data cleaning on ingestion
def load_csv_to_db(csv_path: str):
df = pd.read_csv(csv_path)
# Remove placeholder values
df = df.replace({'-': ''}, regex=True)
# Convert numeric columns
df['amount'] = pd.to_numeric(df['amount'], errors='coerce')
# Validate dates
df['date'] = pd.to_datetime(df['date'], errors='coerce')
# Drop rows with missing critical data
df = df.dropna(subset=['date', 'amount', 'category'])
# Verify row count
logger.info(f"Loaded {len(df)} valid rows")2. Financial Metrics Validation
Test Case: OpEx Calculation
# Validation test
import pandas as pd
from back.financial_knowledge import calculate_financial_metrics
# Query actual P&L data
query = """
SELECT category, SUM(amount) as amount
FROM financial_pl
WHERE actual_budget = 'Actual'
GROUP BY category
"""
df = pd.read_sql(query, engine)
# Result:
# category amount
# 0 NonCash -873000.0
# 1 COGS -15675000.0
# 2 Revenue 35610000.0
# 3 OpEx -16305000.0
metrics = calculate_financial_metrics(df)
# AI response test
question = "What is the total OpEx?"
ai_response = ai_chat(question)
# Expected: "Total OpEx is $16.3M..."
# Actual: "Total OpEx is $16.3M, representing 45.8% of revenue."
# VALIDATION PASSED: AI correctly read from KEY METRICS3. Validation Results
| Test | Result | Status |
|---|---|---|
| OpEx accuracy | $16.3M | Correct |
| Context size | 296 tokens | Efficient |
| Response time | 1.4s | Fast |
| Disk usage (1000 files) | 100 MB | Compact |
| Quota efficiency | 22,700 req/$1 | Economical |
2 Part 2: Evaluation Design
2.1 2.1 Accuracy of Financial Interpretation
Objective: Ensure AI correctly interprets financial data and performs accurate calculations
2.1.1 Evaluation Metrics:
1. Calculation Accuracy (95% Target)
Test Suite:
# tests/test_accuracy.py
test_cases = [
{
"query": "What is the gross margin for Q1 2024?",
"expected_formula": "(Revenue - COGS) / Revenue × 100%",
"expected_result": 45.4, # ±0.5%
"data_source": "financial_pl WHERE period='2024-Q1'"
},
{
"query": "Calculate EBITDA for APAC Q1",
"expected_formula": "Operating Income + D&A",
"expected_result": 2100000, # ±1%
"must_include": ["operating income", "depreciation", "amortization"]
},
{
"query": "Variance % for EMEA OpEx",
"expected_formula": "(Actual - Budget) / Budget × 100%",
"expected_result": -8.5, # ±0.5%
"data_source": "variance_report WHERE bu='EMEA'"
}
]
def test_calculation_accuracy():
results = []
for case in test_cases:
response = ai_chat(case["query"])
# Extract calculated value
calculated = extract_number(response)
expected = case["expected_result"]
tolerance = case.get("tolerance", 0.01)
# Verify accuracy
accurate = abs(calculated - expected) / expected < tolerance
# Verify formula shown
formula_shown = case["expected_formula"] in response
results.append({
"query": case["query"],
"accurate": accurate,
"formula_shown": formula_shown,
"calculated": calculated,
"expected": expected
})
accuracy_rate = sum(r["accurate"] for r in results) / len(results)
formula_rate = sum(r["formula_shown"] for r in results) / len(results)
print(f"Calculation Accuracy: {accuracy_rate*100:.1f}%")
print(f"Formula Transparency: {formula_rate*100:.1f}%")
assert accuracy_rate >= 0.95, "Accuracy below 95%"
assert formula_rate >= 0.90, "Formula transparency below 90%"Success Criteria: - Calculation accuracy ≥ 95% - Data retrieval accuracy ≥ 95% - Expert interpretation agreement ≥ 90% - Formula transparency ≥ 90%
2.2 2.2 Response Time Performance
Performance Benchmarks:
| Metric | Target | Current | Status |
|---|---|---|---|
| Simple query (< 20 words) | < 2s | 1.4s | |
| Complex query (analysis) | < 5s | 3.2s | |
| File upload (10MB) | < 8s | 5.1s | |
| Database query | < 500ms | 180ms | |
| Health check | < 100ms | 30ms | |
| 50 concurrent users (p95) | < 5s | 3.5s |
Performance Characteristics:
- Compact Context → Fast AI Processing
- Token count: 296 tokens
- AI processing time: 1.0s
- Aggregated Queries → Fast DB
- Row count: 30-50 rows
- Query execution: 180ms
- No JSON Creation → Fast Upload
- File processing: 1.2s
- No duplicate write operation
3 Part 3: Future Enhancements
3.1 3.1 Context Caching for Further Optimization
Proposed Enhancement: Cache frequently used financial knowledge
# Gemini supports context caching
# Cache static financial knowledge for 1 hour
from google.generativeai import caching
cached_content = caching.CachedContent.create(
model="gemini-2.5-flash",
contents=[{
"role": "system",
"parts": [system_prompt] # Financial knowledge cached
}],
ttl=3600 # 1 hour cache
)
# Use cached context (no tokens charged for cached parts)
model = genai.GenerativeModel(cached_content=cached_content)
response = model.generate_content(user_query)
# Token savings: Only pay for user query + responseProjected Savings: - Current: 296 tokens (80 system + 150 data + 66 user query) - With caching: 216 tokens (0 cached system + 150 data + 66 query) - Additional 27% reduction
3.2 3.2 Scaling Across Business Units
Current Limitation: - Single database instance for all BUs - Manual BU assignment in code - No multi-tenant data isolation
Proposed Multi-Tenant Architecture:
┌───────────────────────────────────────────────────────────┐
│ Tenant Router Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ BU: APAC │ │ BU: EMEA │ │BU: Americas │ │
│ │ (Tenant 1) │ │ (Tenant 2) │ │ (Tenant 3) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└───────────────────────────────────────────────────────────┘
↓
┌───────────────────────────────────────────────────────────┐
│ Database Sharding Strategy │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ APAC Database │ │ EMEA Database │ │
│ │ Schema: apac │ │ Schema: emea │ │
│ │ - financial_pl │ │ - financial_pl │ │
│ │ - balance_sheet │ │ - balance_sheet │ │
│ │ Users: 50 │ │ Users: 35 │ │
│ └──────────────────┘ └──────────────────┘ │
└───────────────────────────────────────────────────────────┘Benefits: - Data Isolation: Each BU’s data physically separated - Performance: Smaller databases = faster queries - Compliance: Regional data residency (GDPR, etc.) - Scalability: Add new BUs without impacting existing - Cost Optimization: Scale each tenant independently
3.3 3.3 Vector Embeddings for Finance Knowledge
Current Limitation: - Minimal 80-token system prompt (efficient but limited) - No semantic search capability - Knowledge must fit in token budget
Proposed Vector Database Architecture:
┌─────────────────────────────────────────────────────────┐
│ Financial Knowledge Base │
│ - Accounting standards (IFRS, GAAP, VAS) │
│ - Financial formulas & calculations │
│ - Industry benchmarks │
│ - Company policies & procedures │
│ - Historical analysis examples │
└─────────────────────────────────────────────────────────┘
↓ Embedding
┌─────────────────────────────────────────────────────────┐
│ Vector Embedding Model (Sentence Transformers) │
│ Model: all-MiniLM-L6-v2 (384 dimensions) │
│ Text → Vector representation │
└─────────────────────────────────────────────────────────┘
↓ Store
┌─────────────────────────────────────────────────────────┐
│ Vector Database (ChromaDB / Pinecone) │
│ ┌─────────────┬──────────────┬──────────────────┐ │
│ │ Document │ Embedding │ Metadata │ │
│ ├─────────────┼──────────────┼──────────────────┤ │
│ │ "EBITDA..." │ [0.2, -0.1,] │ {type: formula} │ │
│ │ "Gross..." │ [0.5, 0.3,] │ {type: metric} │ │
│ └─────────────┴──────────────┴──────────────────┘ │
└─────────────────────────────────────────────────────────┘
↓ Query
┌─────────────────────────────────────────────────────────┐
│ User Query: "How to calculate EBITDA?" │
│ ↓ │
│ Semantic Search (top 3 matches) │
│ ↓ │
│ Retrieved: EBITDA formula + examples + benchmarks │
│ ↓ │
│ Augment LLM Prompt with relevant docs │
└─────────────────────────────────────────────────────────┘Benefits: - Scalability: Support 1000+ financial concepts - Relevance: Only retrieve knowledge relevant to query - Token Efficiency: Don’t embed entire glossary - Updatable: Add new knowledge without code changes - Semantic Understanding: “profitability” matches “EBITDA”, “margins”
4 Appendix: Source Code Structure
4.1 Current Implementation Files
Backend (Python/FastAPI):
back/
├── __init__.py # Package marker
├── main.py # FastAPI app, minimal prompts (~80 tokens)
├── auth.py # JWT authentication, password hashing
├── database.py # SQLAlchemy connection to PostgreSQL
├── models.py # User model (2-role: GCEO/BUGM)
├── role_access.py # RBAC logic, BU assignment, SQL filters
├── data_service.py # Compact queries (30/50 row limits)
├── file_processor.py # Reference-only file processing
├── financial_knowledge.py # Financial glossary, AI prompts
├── create_users.py # Utility: Create default users
└── requirements.txt # Python dependenciesFrontend (HTML/JavaScript):
front/
├── ai.html # AI chat interface (expanded layout)
└── styles.css # Styling with optimized chat areaData & Config:
.env # Environment variables (API keys, DB URL)
uploads/ # Original files only (no JSON duplicates)
app.log # Application logs4.2 System Metrics
Token Efficiency:
| Metric | Value |
|---|---|
| Tokens per request | 296 |
| Response time | 1.4s |
| Database query | 180ms |
| Accuracy maintained | 95% |
Data Flow Architecture:
Historical Data (Database):
Enterprise ETL (SAP/ERP/HFM)
↓ Monthly batch load
PostgreSQL Database (Neon)
↓ SQL queries (AGGREGATED, 30-50 rows)
data_service.py
↓ Compact format (Revenue: $35.6M | COGS: $15.7M...)
LLM Context (296 tokens total)Manual Upload Data (Files):
User Browser Upload
↓ POST /upload
file_processor.py validation
↓ Save ORIGINAL file only (no JSON duplicate)
file_processor.py processing
↓ Extract compact summary (5 rows, 4 stats)
LLM Context (100 tokens per file)AI Response Generation:
Minimal Prompt (80 tokens)
+ Compact Historical Data (150 tokens)
+ Compact Metrics (50 tokens)
+ Compact File Summary (16 tokens)
↓ Total ~296 tokens
Google Gemini API
↓ Generate structured response
**Answer:** [Direct answer]
**Details:** [Bullet points]
**Source:** [Table/file]
Frontend Display