Titan Financial Auditor
AI-Powered Financial Forensics Pipeline
About the Project
Titan is an auditable, sector-aware financial analysis engine. It normalizes official filings (Brazilian CVM + US SEC) and PDFs, applies deterministic math checks (Altman Z, DuPont, Piotroski, banking rules), flags forensic anomalies, and generates human-readable audit narratives (bull/bear) via LLMs. Interactive Streamlit dashboard.
Pipeline Architecture
The system follows a pipeline architecture orchestrated by Streamlit. Full flow: Router (detects asset type and source) → Extractor (normalizes data) → Calculator (deterministic metrics) → Auditor (LLM narrative).
Orchestration Layer (app.py): Streamlit interface for user interactions, quick market lookups, PDF uploads and dashboard rendering.
Routing & Ingest (router.py): Detects asset type and source (CVM/SEC/On-chain), downloads/parses XBRL or selects PDF path, applies sector detection (e.g., banking tickers).
Extraction & Normalization
The TitanExtractor converts raw XBRL/PDF/text into normalized numeric fields via Pydantic FinancialStatement model.
Fields include: assets, liabilities, equity, pdd_balance, loan_portfolio, non_performing_loans, sector, period, currency, company_name.
Banking sector receives special treatment: uses CVM account 2.08 for equity, nullifies current_assets/current_liabilities to avoid corporate liquidity flags.
Deterministic Math Engine
The TitanMathEngine computes financial metrics with deterministic precision. No calculations depend on LLM:
Altman Z-Score: Adapted for available inputs, detects bankruptcy risk.
DuPont Decomposition: net margin × asset turnover × financial leverage → ROE.
Piotroski F-Score: 9-point checklist for fundamental quality.
Banking Heuristics: Basel proxy via capital_ratio, PDD/Portfolio coverage (4-6% healthy thresholds), annualized ROE from YTD numbers.
Forensic Anomaly Detection
Forensic flags check for inconsistencies that may indicate accounting manipulation:
Inconsistent growth between related metrics, persistent negative cash flow, sudden margin swings.
Detection of malformed XBRL mappings that may hide balance sheet problems.
LLM Audit & Narrative
The TitanAuditor composes specialized prompts, calls OpenAI/Grok and parses JSON with robust fallback for malformed outputs.
Returns FinalAuditReport with: verdict, headline, executive_summary, bull_case, bear_case, math_explanation and management_trust_score.
LLMs are used ONLY for narrative — all numerical calculations are deterministic in the Math Engine.
Dashboard & UX
Streamlit dashboard with progressive disclosure: summary cards → bull/bear arguments → raw data → audit debugging.
Export: copy-as-markdown + download .md. Source document links (CVM/SEC) when available.
Banking-specific cards: Basel, PDD/Portfolio, annualized ROE, leverage.