Module Spec: FintraOS Brain

1. The "Moneymaker" Philosophy

FintraOS Brain is designed to be the differentiator. While Connect and Core are commodities (moving data from A to B), Brain transforms raw data into high-margin utility.

It is architected to answer the three questions every user has: 1. "What happened?" (Enrichment & Categorisation) 2. "Am I okay?" (Health Scoring & Anomaly Detection) 3. "What should I do?" (Forecasting, Simulation & Nudges)

Key Architecture: The "Two-Speed Brain" - Fast Brain (Stream Processor): Designed to react in milliseconds. Rules, Categorisation, Threshold Alerts. - Slow Brain (Batch/Async): Designed to think in minutes/hours. Forecasting, Pattern Recognition, Global Model Training.

2. Pipeline A: The Enrichment Refinery (Fast Brain)

Input: Raw Bank Transaction -> Output: Structured, Intelligent Event.

This pipeline is designed to run synchronously on ingestion.

2.1. Merchant Truth Engine

Raw bank strings are garbage ("AMZN MKTPL PAYMENTS WA"). We aim to resolve them to a global entity. - Entity Resolution: Matches against our Global Merchant Database (10M+ entities). - Brand Assets: Returns clean name ("Amazon"), high-res logo, website, and Twitter handle. - Subscription Discovery: Checks the merchant against a known list of subscription providers (Netflix, Spotify, SaaS tools).

2.2. Hybrid Categorisation

We plan to use a Cascade Model to determine what a transaction is. 1. User Rule (Highest Priority): "User explicitly set 'Amazon' to 'Office Supplies'." 2. Global Merchant Truth: "We know 'Starbucks' is always 'Coffee'." 3. Contextual ML (BERT Model): "This transaction is at 11 PM on a Friday in a Bar -> 'Nightlife'." 4. MCC Fallback: "Merchant Code 5812 -> 'Food'."

2.3. Recurrence Detection (The Pulse)

Detects patterns immediately. - Logic: FFT (Fast Fourier Transform) + Date Clustering. - Output: - is_recurring: true - frequency: MONTHLY - next_expected_date: 2023-11-15 - confidence: 0.98 - Value: Enables the "Bills & Subscriptions" view in the client app.

3. Pipeline B: The Insight Engine (Slow Brain)

Input: User History (Vault) -> Output: Derived Intelligence.

This pipeline is designed to run on a schedule (e.g., Nightly) or upon significant state changes.

3.1. Cashflow Forecasting (The Crystal Ball)

We won't just project "average spend." We aim to model the user's life. - Model: Bayesian Structural Time Series (Prophet-like). - Inputs: - Detected Recurring Income/Bills. - Historical Discretionary Spend Patterns (Day-of-week seasonality). - One-off scheduled transfers. - Output: - "Safe-to-Spend" Balance: The amount you can spend today without going broke before payday. - Overdraft Prediction: "You will hit -£50 on Oct 14th."

3.2. Financial Health Score (FICO for Wealth)

A standardised 0-1000 score measuring resilience, not just credit. - Components: - Solvency: Assets / Liabilities. - Liquidity: Cash / Monthly Expenses (Runway). - Discipline: Savings Rate. - Performance: Investment Returns.

3.3. Anomaly Watchdog

Logic: Unsupervised learning (Isolation Forest) on user's history.
Triggers:
"This £500 bill is 3x your normal utility payment."
"Double charge detected."
"Subscription price hike detected (Netflix went from £10 to £12)."

3.4. Global Context & Inflation Engine

Uses external streams (from Module-Connect) to provide "Real" value metrics. - Inflation-Proofing: Adjusts all savings goals and "Financial Freedom" dates daily based on CPI/RPI. - Metric: real_purchasing_power = nominal_cash / inflation_index. - Market Impact: Recalculates net_worth in real-time based on crypto/equity price feeds. - Tax Efficiency: Identifies "Tax Drag" by comparing gross yields vs. net yields (using the user's marginal tax bracket).

4. Feature C: The Metric Registry (Custom Intelligence)

Extensibility is the core value proposition.

Brain allows tenants to define Custom Calculators that produce proprietary data points. These are stored alongside standard metrics.

4.1. The "Crowdsourced" Metric Store

Tenants can push logic (SQL/Code) or data to create new derived attributes. * Example Use Case: A coffee subscription app wants to know "Average Weekend Coffee Spend." * Mechanism: Tenant registers a MetricDefinition.

{
  "metric_id": "coffee_weekend_avg",
  "display_name": "Weekend Coffee Habit",
  "logic": {
    "filter": "category == 'Coffee' AND day_of_week IN ['Sat', 'Sun']",
    "aggregation": "AVG(amount)",
    "window": "90d"
  },
  "visibility": "TENANT_PRIVATE" // or PUBLIC (Shared with ecosystem)
}

* Result: Every Profile now carries this calculated value: user.metrics.coffee_weekend_avg = 12.50.

5. Feature D: The Simulator (Monte Carlo)

The "What-If" Engine for Wealth Management.

This is a stateless, on-demand calculation engine.

5.1. `POST /v1/brain/simulate`

Allows clients to overlay "Life Events" on the user's actual financial curve.

Supported Scenarios: 1. Rate Shock: "What if my Mortgage rate goes from 2% to 6%?" (Recalculates debt service). 2. Inflation Stress: "What if groceries/fuel cost 10% more?" 3. Income Shock: "What if I lose my job?" (Calculates exact "Runway Date"). 4. Big Purchase: "Can I afford a £500k house?" (Models down payment + new mortgage + maintenance). 5. Retirement: "If I save £X/month, when can I retire?"

Output:

{
  "baseline_runway_days": 180,
  "simulated_runway_days": 45,
  "survival_probability": 0.25,
  "recommendation": "Increase emergency fund by £5,000."
}

6. Feature E: The Nudge Factory (Recommendations)

Turning passive data into active advice.

Brain scans for Arbitrage Opportunities.

6.1. Opportunity Catalog

Type	Logic	Recommendation
Idle Cash	`Avg_Bal > 3x Monthly_Spend` AND `APY < 1%`	"Move £5k to Savings to earn £200/yr."
Fee Killer	`Foreign_Tx_Fee > £0`	"You paid £15 in FX fees. Switch cards."
Sub Zombie	`Recurring_Tx` hasn't been used (requires Login integration)	"Cancel unused Gym membership."
Refi Alert	`Mortgage_Rate > Market_Rate + 1%`	"Refinance now to save £150/month."

7. Feature F: Agent Skills Registry (Actionable AI)

Moving beyond chat to "Do it for me".

This feature allows tenants to register Actionable Skills that the Fintra AI Agent can invoke on behalf of the user.

7.1. Skill Definition

Tenants register "Tools" that map natural language intents to their own webhooks.

{
  "skill_id": "transfer_money",
  "description": "Moves money between accounts",
  "parameters": {
    "amount": "number",
    "from_account": "string",
    "to_account": "string"
  },
  "webhook_url": "https://api.tenant.com/webhooks/execute-transfer",
  "required_scopes": ["WRITE_PAYMENTS"]
}

* Flow: User says "Send £50 to savings" -> Brain identifies transfer_money skill -> Guard checks permissions -> Brain calls Tenant Webhook.

8. Feature G: Predictive Business Models (B2B)

Helping the Tenant understand the User.

8.1. Churn Prediction

Uses the Anomaly Watchdog infrastructure to detect behavioral shifts indicating a user is about to leave the tenant's platform. * Signals: Sudden decrease in login frequency, massive withdrawal of funds, linking of competitor app. * Output: Brain.Risk.ChurnProbable event sent to Tenant via Pulse.

8.2. Financial Distress Model

Detects pre-delinquency signals before a default happens. * Signals: Gambling increase, payday loan usage, stopping savings contributions. * Output: Brain.Risk.DistressDetected event (allows Tenant to offer hardship plans).

9. The Network Effect (Global Learning)

How we get smarter with every user.

9.1. The Feedback Loop

When a user corrects a category in Tenant A: 1. Event: Brain.CorrectionReceived (Starbucks -> "Coffee"). 2. Anonymization: Stripped of UserID/TenantID. 3. Global Training: Added to the "Ground Truth" dataset. 4. Deployment: The model is retrained. 5. Benefit: Tenant B's users now get better categorisation for Starbucks.

9.2. Peer Benchmarking

"Users like you spend £200 on groceries." - Cohorts: We cluster users by Income, Location, and Age (using the Financial Passport identity fields). - Privacy: Aggregated via Differential Privacy (k-anonymity).

10. Technology Stack

Inference: Python (FastAPI) + ONNX Runtime (for speed).
Training: PyTorch / Scikit-Learn.
Feature Store: Redis (for real-time variables).
Vector DB: Qdrant (for Merchant/Transaction embeddings).