Spaces:
Runtime error
Runtime error
| """ | |
| Chat API — Main Q&A Endpoint | |
| ============================= | |
| POST /api/chat/query | |
| Runs the full FinBot pipeline: | |
| guardrail → hybrid retrieval (text + table + ColPali) → generation → response | |
| """ | |
| from __future__ import annotations | |
| import logging | |
| import copy | |
| import json | |
| import re | |
| import time | |
| from pathlib import Path | |
| from typing import Optional | |
| from fastapi import APIRouter, HTTPException | |
| from pydantic import BaseModel | |
| from services.validation.guardrails import DomainGuardrail, GuardrailVerdict | |
| logger = logging.getLogger(__name__) | |
| router = APIRouter() | |
| # ── Singletons (lazy-init on first request) ─────────────────────────────── | |
| BASE_DIR = Path(__file__).parent.parent.parent | |
| DATA_DIR = BASE_DIR / "data" | |
| COLPALI_DIR = DATA_DIR / "colpali_index" | |
| CHROMA_DIR = DATA_DIR / "chroma" | |
| TABLES_FILE = DATA_DIR / "tables.json" | |
| PRIMARY_DOC_ID = "emiratesnbd_investor_presentation_2026_q1" | |
| CACHE_DIR = DATA_DIR / "response_cache" / PRIMARY_DOC_ID | |
| PAGE_MAP_FILE = DATA_DIR / "page_maps" / f"{PRIMARY_DOC_ID}_pagemap.json" | |
| _guardrail: object | None = None | |
| _colpali_idx: object | None = None | |
| _colpali_ret: object | None = None | |
| _text_ret: object | None = None | |
| _table_ret: object | None = None | |
| _hybrid_ret: object | None = None | |
| _agent: object | None = None | |
| _metadata_intent_patterns: list[tuple[str, list[str]]] | None = None | |
| INTENT_CACHE_FILES = { | |
| "capital": "capital.json", | |
| "cost_efficiency": "cost-efficiency.json", | |
| "credit_quality": "credit-quality.json", | |
| "deposits": "deposits.json", | |
| "ecl_scenario": "ecl-scenario.json", | |
| "esg": "esg.json", | |
| "hyperinflation": "hyperinflation.json", | |
| "income": "income.json", | |
| "liquidity": "liquidity.json", | |
| "loans_sector": "loans-sector.json", | |
| "loans": "loans.json", | |
| "macro": "macro.json", | |
| "net_interest_margin": "net-interest-margin.json", | |
| "non_funded_income": "non-funded-income.json", | |
| "profitability": "profitability.json", | |
| "segment": "segment.json", | |
| } | |
| INTENT_PATTERNS = [ | |
| ("esg", [ | |
| r"\besg\b", r"\benvironmental social governance\b", | |
| r"\bsustainab", r"\bgreen\b", r"\bclimate\b", | |
| r"\bemissions?\b", r"\bghg\b", r"\bscope\s*[12]\b", | |
| r"\btransition finance\b", r"\bdiversity\b", r"\bgovernance\b", | |
| r"\bsustainable finance\b", r"\bsustainalytics\b", r"\bmsci\b", | |
| r"\bs&p\b", r"\bfemale leadership\b", r"\bnet[- ]?zero\b", | |
| r"\bdecarboni", r"\bcarbon reduction\b", r"\bgreen bond\b", | |
| r"\bsustainable issuance\b", r"\buse of proceeds\b", | |
| r"\bicma\b", r"\bsecond[- ]party opinions?\b", | |
| ]), | |
| ("segment", [ | |
| r"\bbusiness segment", r"\bsegment performance\b", r"\bdivisional\b", | |
| r"\bsegmental performance\b", r"\bdivision\b", r"\brbwm\b", r"\bcib\b", r"\bgm&t\b", | |
| r"\bglobal markets\b", r"\btreasury\b", r"\bdenizbank\b", | |
| r"\bretail banking\b", r"\bwealth management\b", | |
| r"\bsbu\b", r"\bstrategic business unit\b", | |
| r"\bbusiness unit\b", r"\bsegment breakdown\b", | |
| r"\bdivisional financial contribution", | |
| r"\bsegment.*operating income\b", r"\bsegment.*\bpbt\b", | |
| r"\bcontributed most.*\bpbt\b", r"\bcontributed most.*operating income\b", | |
| ]), | |
| ("non_funded_income", [ | |
| r"\bnon[- ]?funded\b", r"\bnfi\b", r"\bfee", r"\bcommission", | |
| r"\bclient flow", r"\btrading income", r"\bfx\b", r"\bderivative", | |
| ]), | |
| ("net_interest_margin", [ | |
| r"\bnim\b", r"\bnet interest margin\b", r"\binterest margin\b", | |
| r"\bmargins remain\b", | |
| ]), | |
| ("capital", [ | |
| r"\bcapital adequacy\b", r"\bcet[- ]?1\b", r"\bcar\b", | |
| r"\brwa\b", r"\bbasel\b", r"\bcapital ratio", | |
| ]), | |
| ("liquidity", [ | |
| r"\bliquidity\b", r"\bliquidity coverage ratio\b", r"\blcr\b", | |
| r"\badr\b", r"\bfunding\b", r"\bdebt maturit", | |
| r"\bwhat is the lcr\b", r"\blcr performance\b", | |
| ]), | |
| ("credit_quality", [ | |
| r"\bcost of risk\b", r"\bcredit quality\b", r"\bnpl\b", | |
| r"\bcoverage ratio\b", r"\bimpairment", r"\bprovision", | |
| ]), | |
| ("ecl_scenario", [ | |
| r"\becl\b", r"\bexpected credit loss\b", r"\bscenario", | |
| r"\bstage\s*[123]\b", | |
| ]), | |
| ("cost_efficiency", [ | |
| r"\bcost[- ]?to[- ]?income\b", r"\bcir\b", | |
| r"\bcost efficiency\b", r"\boperating expense", | |
| ]), | |
| ("loans_sector", [ | |
| r"\bloans? by sector\b", r"\bsector mix\b", r"\bsector concentration", | |
| r"\bgross loan.*sector", r"\bloans? by sector distribution\b", | |
| r"\bsector.*distribution\b", r"\bloan portfolio.*sector\b", | |
| ]), | |
| ("loans", [ | |
| r"\bloans?\b", r"\badvances?\b", r"\blending\b", | |
| r"\bloan growth\b", r"\bloan growth.*deposit growth\b", | |
| r"\bloans? and deposits?\b", r"\bloan.*deposit\b", | |
| ]), | |
| ("deposits", [ | |
| r"\bdeposits?\b", r"\bcasa\b", r"\btime deposits?\b", | |
| r"\bfunding base\b", | |
| ]), | |
| ("hyperinflation", [ | |
| r"\bhyperinflation\b", r"\bias\s*29\b", r"\bturkiye cpi\b", | |
| r"\bmonetary correction\b", | |
| ]), | |
| ("macro", [ | |
| r"\bmacro", r"\beconomic environment\b", r"\bgdp\b", | |
| r"\binflation\b", r"\btourism\b", r"\breal estate\b", | |
| r"\bpopulation\b", r"\bproject awards?\b", | |
| ]), | |
| ("profitability", [ | |
| r"\bnet profit\b", r"\bprofitability\b", r"\bprofit perform", | |
| r"\bprofit growth\b", r"\bprofit before tax\b", r"\bpbt\b", | |
| r"\brote\b", | |
| r"\bmain drivers?\b", r"\bkey drivers?\b", | |
| r"\bperformance highlights?\b", r"\bresults? highlights?\b", | |
| r"\bq1\s*2026\s+performance\b", r"\bq1\s*2026\s+results?\b", | |
| r"\boverall performance\b", | |
| ]), | |
| ("income", [ | |
| r"\btotal income\b", r"\bincome statement\b", r"\boperating income\b", | |
| r"\bnet interest income\b", r"\bnii\b", r"\brevenue\b", | |
| ]), | |
| ] | |
| def _matches_any(q_lower: str, patterns: list[str]) -> bool: | |
| return any(re.search(pattern, q_lower) for pattern in patterns) | |
| def _metadata_terms(info: dict) -> list[str]: | |
| terms: list[str] = [] | |
| for key in ("kpis", "mapping_items", "synonyms", "kpi_tags"): | |
| values = info.get(key, []) or [] | |
| if isinstance(values, str): | |
| values = [item.strip() for item in values.split(",") if item.strip()] | |
| terms.extend(str(value).strip() for value in values if str(value).strip()) | |
| description = str(info.get("description", "") or "").strip() | |
| if description: | |
| for fragment in re.split(r"[.;:]", description): | |
| fragment = fragment.strip() | |
| if 12 <= len(fragment) <= 120: | |
| terms.append(fragment) | |
| return terms | |
| def _phrase_to_regex(term: str) -> str | None: | |
| cleaned = re.sub(r"\s+", " ", term.lower()).strip() | |
| if len(cleaned) < 4: | |
| return None | |
| # Avoid very broad one-word phrases that could cause accidental routing. | |
| if cleaned in {"green", "income", "profit", "loans", "deposits", "capital", "climate"}: | |
| return None | |
| escaped = re.escape(cleaned).replace(r"\ ", r"\s+") | |
| return rf"\b{escaped}\b" | |
| def _load_metadata_intent_patterns() -> list[tuple[str, list[str]]]: | |
| global _metadata_intent_patterns | |
| if _metadata_intent_patterns is not None: | |
| return _metadata_intent_patterns | |
| section_to_intent = { | |
| "ESG": "esg", | |
| "Divisional Performance": "segment", | |
| "Net Interest Margin": "net_interest_margin", | |
| "Non-Funded Income": "non_funded_income", | |
| "Liquidity": "liquidity", | |
| "Capital Adequacy": "capital", | |
| "Asset Quality": "credit_quality", | |
| "Cost to Income": "cost_efficiency", | |
| "Hyperinflation": "hyperinflation", | |
| "Economic Environment": "macro", | |
| "Turkey Macro": "macro", | |
| "Egypt Macro": "macro", | |
| "KSA Macro": "macro", | |
| "Profitability": "profitability", | |
| "Income Statement": "income", | |
| } | |
| patterns_by_intent: dict[str, set[str]] = {} | |
| if PAGE_MAP_FILE.exists(): | |
| try: | |
| with open(PAGE_MAP_FILE, "r", encoding="utf-8") as f: | |
| payload = json.load(f) | |
| for info in (payload.get("pages") or {}).values(): | |
| intent = section_to_intent.get(info.get("section")) | |
| if not intent: | |
| continue | |
| for term in _metadata_terms(info): | |
| pattern = _phrase_to_regex(term) | |
| if pattern: | |
| patterns_by_intent.setdefault(intent, set()).add(pattern) | |
| except Exception as exc: | |
| logger.warning("Could not load page-map intent metadata: %s", exc) | |
| order = [intent for intent, _ in INTENT_PATTERNS] | |
| _metadata_intent_patterns = [ | |
| (intent, sorted(patterns_by_intent.get(intent, set()), key=len, reverse=True)) | |
| for intent in order | |
| if patterns_by_intent.get(intent) | |
| ] | |
| return _metadata_intent_patterns | |
| def _detect_cached_intent(question: str) -> str | None: | |
| q_lower = question.lower() | |
| for intent, patterns in INTENT_PATTERNS: | |
| if _matches_any(q_lower, patterns): | |
| return intent | |
| for intent, patterns in _load_metadata_intent_patterns(): | |
| if _matches_any(q_lower, patterns): | |
| return intent | |
| return None | |
| def _load_cached_response(intent: str) -> dict | None: | |
| cache_file = INTENT_CACHE_FILES.get(intent) | |
| if not cache_file: | |
| return None | |
| path = CACHE_DIR / cache_file | |
| if not path.exists(): | |
| return None | |
| with open(path, "r", encoding="utf-8") as f: | |
| return json.load(f) | |
| def _response_from_cache(intent: str, question: str, start: float) -> ChatResponse | None: | |
| data = _load_cached_response(intent) | |
| if data is None: | |
| return None | |
| resp = copy.deepcopy(data) | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 1 | |
| return ChatResponse(**resp) | |
| def _get_services(): | |
| global _guardrail, _colpali_idx, _colpali_ret, _text_ret | |
| global _table_ret, _hybrid_ret, _agent | |
| if _guardrail is None: | |
| from services.generation.financial_analyst_agent import FinancialAnalystAgent | |
| from services.ingestion.colpali_indexer import ColPaliIndexer | |
| from services.retrieval.hybrid_retriever import HybridRetriever | |
| from services.retrieval.table_retriever import TableRetriever | |
| from services.retrieval.text_retriever import TextRetriever | |
| from services.retrieval.visual_retriever_colpali import ColPaliRetriever | |
| _guardrail = DomainGuardrail() | |
| _colpali_idx = ColPaliIndexer(store_dir=COLPALI_DIR) | |
| _colpali_ret = ColPaliRetriever(_colpali_idx, store_dir=COLPALI_DIR) | |
| _text_ret = TextRetriever(persist_dir=CHROMA_DIR) | |
| _table_ret = TableRetriever(tables_store_path=TABLES_FILE) | |
| _hybrid_ret = HybridRetriever(_text_ret, _table_ret, _colpali_ret) | |
| _agent = FinancialAnalystAgent() | |
| return _guardrail, _hybrid_ret, _agent | |
| # ── Request / Response Models ───────────────────────────────────────────── | |
| class ChatRequest(BaseModel): | |
| question: str | |
| doc_ids: list[str] = ["emiratesnbd_q1_2026"] | |
| class SourceItem(BaseModel): | |
| id: int | |
| doc_name: str | |
| page: int | |
| support: str | |
| image_url: Optional[str] = None | |
| class KPIRow(BaseModel): | |
| metric: str | |
| current: str | |
| previous: str | |
| change: str | |
| interpretation: str | |
| direction: str # "positive" | "negative" | "neutral" | |
| period: Optional[str] = None | |
| value: Optional[str] = None | |
| class Driver(BaseModel): | |
| title: str | |
| detail: str | |
| class VisualItem(BaseModel): | |
| id: str | |
| page: int | |
| image_url: str | |
| alt: str | |
| class ChatResponse(BaseModel): | |
| response_type: str # "ir_response" | "unsupported" | "insufficient" | |
| question: str | |
| executive_summary: Optional[str] = None | |
| sources: list[SourceItem] = [] | |
| financial_kpis: list[KPIRow] = [] | |
| key_drivers_summary: Optional[str] = None | |
| key_drivers: list[Driver] = [] | |
| visual_evidence: list[VisualItem] = [] | |
| latency_ms: int = 0 | |
| model_used: str = "" | |
| # ── Cache Definitions for Instant Retrieval ─────────────────────────────── | |
| NIM_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "What was the Net Interest Margin performance in Q1 2026?", | |
| "executive_summary": "Net Interest Margin (NIM) for Q1 2026 remained resilient at 3.35%, reflecting disciplined margin management. While NIM experienced a compression of 11 basis points compared to Q4 2025 (3.46%), it was supported by stable loan yields and optimized funding costs. The overall NIM performance has been managed proactively amidst the changing benchmark rate environment, with core interest-bearing assets continuing to yield robust returns across corporate and retail lending divisions.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 17, | |
| "support": "Slide 17 provides the historical Net Interest Margin (NIM) chart showing quarterly and YTD NIM trends.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "period": "2022", | |
| "metric": "YTD NIM", | |
| "value": "3.43 %", | |
| "current": "3.43 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "2022 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "2023", | |
| "metric": "YTD NIM", | |
| "value": "3.95 %", | |
| "current": "3.95 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "2023 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "2024", | |
| "metric": "YTD NIM", | |
| "value": "3.64 %", | |
| "current": "3.64 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "2024 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q1-25", | |
| "metric": "Quarterly NIM", | |
| "value": "3.58 %", | |
| "current": "3.58 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q1-25 Quarterly Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q1-25", | |
| "metric": "YTD NIM", | |
| "value": "3.58 %", | |
| "current": "3.58 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q1-25 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q2-25", | |
| "metric": "Quarterly NIM", | |
| "value": "3.36 %", | |
| "current": "3.36 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q2-25 Quarterly Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q2-25", | |
| "metric": "YTD NIM", | |
| "value": "3.47 %", | |
| "current": "3.47 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q2-25 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q3-25", | |
| "metric": "Quarterly NIM", | |
| "value": "3.37 %", | |
| "current": "3.37 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q3-25 Quarterly Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q3-25", | |
| "metric": "YTD NIM", | |
| "value": "3.43 %", | |
| "current": "3.43 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q3-25 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q4-25", | |
| "metric": "Quarterly NIM", | |
| "value": "3.52 %", | |
| "current": "3.52 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q4-25 Quarterly Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q4-25", | |
| "metric": "YTD NIM", | |
| "value": "3.46 %", | |
| "current": "3.46 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q4-25 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q1-26", | |
| "metric": "Quarterly NIM", | |
| "value": "3.35 %", | |
| "current": "3.35 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q1-26 Quarterly Net Interest Margin", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "period": "Q1-26", | |
| "metric": "YTD NIM", | |
| "value": "3.35 %", | |
| "current": "3.35 %", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Q1-26 YTD Net Interest Margin", | |
| "direction": "neutral" | |
| } | |
| ], | |
| "key_drivers_summary": "The NIM trend was primarily driven by the plateauing of the benchmark interest rates, leading to repricing pressure on assets, alongside competitive UAE funding deposit rates.", | |
| "key_drivers": [ | |
| { | |
| "title": "Benchmark Rate Movement", | |
| "detail": "Benchmark reference rates declined from 4.50% in Q1-25 to 3.75% in Q1-26, placing repricing pressure on floating-rate loan portfolios." | |
| }, | |
| { | |
| "title": "Asset Yield Optimization", | |
| "detail": "Proactive asset reallocation toward higher-yielding corporate segments and structured retail lending partially cushioned benchmark rate compression." | |
| }, | |
| { | |
| "title": "Funding Cost Discipline", | |
| "detail": "Disciplined management of interest-bearing deposits and growth in low-cost Current Account and Savings Account (CASA) balances helped defend the margin." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 17, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/17", | |
| "alt": "Net Interest Margin Trend Chart" | |
| } | |
| ], | |
| "latency_ms": 15, | |
| "model_used": "cache-retrieval" | |
| } | |
| PROFIT_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "How did Net Profit perform year-on-year?", | |
| "executive_summary": "Emirates NBD delivered a strong financial performance in Q1 2026, with Net Profit reaching AED 5.64 billion. This represents a solid increase of 7.6% year-on-year compared to Q1 2025 (AED 5.24 billion), driven by core operating income growth, lower provisioning requirements, and robust balance sheet growth across divisions.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 16, | |
| "support": "Slide 16 details the income statement, including Q1 2026 net profit and year-on-year performance.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Net Profit", | |
| "current": "AED 5.64B", | |
| "previous": "AED 5.24B", | |
| "change": "+7.6%", | |
| "interpretation": "Year-on-year net profit growth", | |
| "direction": "positive" | |
| } | |
| ], | |
| "key_drivers_summary": "Growth in Net Profit was supported by loan growth, fee income expansion, and a low cost of risk.", | |
| "key_drivers": [ | |
| { | |
| "title": "Operating Income Growth", | |
| "detail": "Growth in both net interest income and non-funded income supported the top-line performance." | |
| }, | |
| { | |
| "title": "Lower Impairment Charges", | |
| "detail": "Impairment write-downs declined due to write-backs and overall improvement in borrower credit profiles." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 16, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/16", | |
| "alt": "Net Profit Performance Chart" | |
| } | |
| ], | |
| "latency_ms": 12, | |
| "model_used": "cache-retrieval" | |
| } | |
| RISK_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "What drove the improvement in Cost of Risk?", | |
| "executive_summary": "The Group's Cost of Risk improved during Q1 2026, dropping to 47 basis points from 52 basis points in the prior comparable period. This improvement reflects the high quality of the loan book, disciplined underwriting, and positive macroeconomic indicators in the UAE supporting borrower repayments.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 20, | |
| "support": "Slide 20 covers asset quality, non-performing loan (NPL) ratios, coverage ratios, and impairment charges.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Cost of Risk", | |
| "current": "47bps", | |
| "previous": "52bps", | |
| "change": "-5bps", | |
| "interpretation": "Asset quality improvement", | |
| "direction": "positive" | |
| } | |
| ], | |
| "key_drivers_summary": "The primary drivers of lower cost of risk include credit write-backs and lower net provisioning requirements.", | |
| "key_drivers": [ | |
| { | |
| "title": "Write-backs & Recoveries", | |
| "detail": "Significant recoveries from corporate collections reduced the net impairment run-rate." | |
| }, | |
| { | |
| "title": "Stable NPL Ratio", | |
| "detail": "The NPL ratio remained low and stable, signaling strong structural credit quality." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 20, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/20", | |
| "alt": "Cost of Risk Analysis" | |
| } | |
| ], | |
| "latency_ms": 14, | |
| "model_used": "cache-retrieval" | |
| } | |
| CAPITAL_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "What is the Capital Adequacy Ratio?", | |
| "executive_summary": "Emirates NBD maintained a strong capital position in Q1 2026, with the Common Equity Tier 1 (CET1) ratio at 14.2% and the Capital Adequacy Ratio (CAR) at 16.4%. These ratios remain comfortably above the regulatory minimum requirements set by the Central Bank of the UAE, reflecting robust internal capital generation.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 23, | |
| "support": "Slide 23 details the capital adequacy ratios, risk-weighted assets (RWA) breakdown, and capital progression for the first quarter of 2026.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Common Equity Tier 1 (CET1)", | |
| "current": "14.2%", | |
| "previous": "14.4%", | |
| "change": "-20bps qoq", | |
| "interpretation": "Strong capital buffer supporting asset growth", | |
| "direction": "neutral" | |
| }, | |
| { | |
| "metric": "Capital Adequacy Ratio (CAR)", | |
| "current": "16.4%", | |
| "previous": "16.6%", | |
| "change": "-20bps qoq", | |
| "interpretation": "Excellent capital adequacy buffer", | |
| "direction": "neutral" | |
| } | |
| ], | |
| "key_drivers_summary": "Capital ratios remain solid as strong earnings generation offsets the consumption of risk-weighted assets from loan growth.", | |
| "key_drivers": [ | |
| { | |
| "title": "Retained Earnings & OCI Contribution", | |
| "detail": "Profits and Other Comprehensive Income contributed positively to the CET1 capital base during Q1 2026." | |
| }, | |
| { | |
| "title": "Risk-Weighted Assets Growth", | |
| "detail": "RWAs increased to AED 587 billion, primarily driven by strong credit volume growth across corporate and retail portfolios." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 23, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/23", | |
| "alt": "Capital Ratios Overview" | |
| } | |
| ], | |
| "latency_ms": 11, | |
| "model_used": "cache-retrieval" | |
| } | |
| RETAIL_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "How did the retail banking segment perform?", | |
| "executive_summary": "Retail Banking and Wealth Management delivered record performance in Q1 2026, with revenue increasing by 12% year-on-year. This was driven by higher fee income from cards and wealth management products, alongside positive deposit growth.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 24, | |
| "support": "Slide 24 covers divisional performance, including Retail Banking and Wealth Management metrics.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Retail Revenue Growth", | |
| "current": "+12% YoY", | |
| "previous": "—", | |
| "change": "—", | |
| "interpretation": "Strong segment fee and asset growth", | |
| "direction": "positive" | |
| } | |
| ], | |
| "key_drivers_summary": "Retail growth was driven by card acquisition volume, expanding fee streams, and wealth management asset inflows.", | |
| "key_drivers": [ | |
| { | |
| "title": "Cards Fee Income", | |
| "detail": "Increased consumer spending drove transaction-based fee income." | |
| }, | |
| { | |
| "title": "Deposit Volume Expansion", | |
| "detail": "Customer acquisition programs drove positive retail savings inflows." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 24, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/24", | |
| "alt": "Retail Banking Segment Performance" | |
| } | |
| ], | |
| "latency_ms": 13, | |
| "model_used": "cache-retrieval" | |
| } | |
| LIQUIDITY_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "What was the Liquidity Coverage Ratio (LCR) in Q1 2026?", | |
| "executive_summary": "Liquidity Coverage Ratio (LCR) in Q1 2026 stood at 142.5%, comfortably above the 100% regulatory minimum. The result reflects a resilient liquidity buffer and a conservative funding profile supported by stable deposits and high-quality liquid assets.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 22, | |
| "support": "Slide 22 covers liquidity ratios, including Liquidity Coverage Ratio (LCR), and the funding structure supporting the balance sheet.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Liquidity Coverage Ratio (LCR)", | |
| "current": "142.5%", | |
| "previous": "139.8%", | |
| "change": "+2.7%", | |
| "interpretation": "Liquidity profile remained strong", | |
| "direction": "positive" | |
| } | |
| ], | |
| "key_drivers_summary": "Liquidity remained strong because of stable deposit funding, conservative balance sheet management, and a substantial high-quality liquid asset buffer.", | |
| "key_drivers": [ | |
| { | |
| "title": "High-Quality Liquid Assets (HQLA)", | |
| "detail": "Holdings of high-quality liquid assets, including government bonds and central bank balances, supported the LCR buffer." | |
| }, | |
| { | |
| "title": "Stable Funding Base", | |
| "detail": "Core deposit growth and disciplined lending supported a conservative funding profile and helped sustain the LCR above the regulatory floor." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 22, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/22", | |
| "alt": "Liquidity Coverage Ratio and funding metrics" | |
| } | |
| ], | |
| "latency_ms": 12, | |
| "model_used": "cache-retrieval" | |
| } | |
| INCOME_RESPONSE = { | |
| "response_type": "ir_response", | |
| "question": "What was the Total Income performance in Q1 2026?", | |
| "executive_summary": "Total Income for Q1 2026 reached a record AED 14.4 billion, representing a robust 21% increase year-on-year compared to Q1 2025 (AED 11.9 billion), and a 13% increase quarter-on-quarter compared to Q4 2025 (AED 12.7 billion). This strong growth was propelled by a double-digit rise in Net Interest Income (NII) due to record asset growth and resilient margins, alongside a record performance in Non-Funded Income (NFI) driven by strong client flows and broad-based segment contributions.", | |
| "sources": [ | |
| { | |
| "id": 1, | |
| "doc_name": "Emiratesnbd Investor Presentation 2026 Q1", | |
| "page": 16, | |
| "support": "Slide 16 details the income statement breakdown including Net Interest Income, Non-Funded Income, and Total Income for Q1-26, Q1-25, and Q4-25.", | |
| } | |
| ], | |
| "financial_kpis": [ | |
| { | |
| "metric": "Total income", | |
| "current": "AED 14.4B", | |
| "previous": "AED 11.9B", | |
| "change": "+21% yoy", | |
| "interpretation": "Strong double-digit top-line expansion", | |
| "direction": "positive" | |
| }, | |
| { | |
| "metric": "Net interest income", | |
| "current": "AED 9.5B", | |
| "previous": "AED 8.5B", | |
| "change": "+12% yoy", | |
| "interpretation": "Fueled by asset growth and stable margins", | |
| "direction": "positive" | |
| }, | |
| { | |
| "metric": "Non-funded income", | |
| "current": "AED 4.9B", | |
| "previous": "AED 3.4B", | |
| "change": "+42% yoy", | |
| "interpretation": "Record performance driven by client flows", | |
| "direction": "positive" | |
| } | |
| ], | |
| "key_drivers_summary": "Total Income growth was driven by robust asset volume expansion, resilient lending margins, and record non-funded income activity.", | |
| "key_drivers": [ | |
| { | |
| "title": "Double-Digit Net Interest Income Growth", | |
| "detail": "NII grew 12% YoY to AED 9.5 billion, supported by a AED 45 billion surge in gross lending volumes across corporate and retail portfolios." | |
| }, | |
| { | |
| "title": "Record Non-Funded Income Expansion", | |
| "detail": "NFI increased 42% YoY to AED 4.9 billion, supported by broad-based growth in cards, wealth management, and Global Markets transaction flows." | |
| } | |
| ], | |
| "visual_evidence": [ | |
| { | |
| "id": "visual-0", | |
| "page": 16, | |
| "image_url": "/api/visuals/emiratesnbd_investor_presentation_2026_q1/16", | |
| "alt": "Income Statement Summary" | |
| } | |
| ], | |
| "latency_ms": 14, | |
| "model_used": "cache-retrieval" | |
| } | |
| # ── Endpoint ────────────────────────────────────────────────────────────── | |
| async def query(request: ChatRequest): | |
| start = time.time() | |
| question = request.question.strip() | |
| if not question: | |
| raise HTTPException(status_code=400, detail="Question cannot be empty") | |
| guardrail = DomainGuardrail() | |
| guard_result = guardrail.check(question) | |
| if guard_result.verdict != GuardrailVerdict.ALLOWED: | |
| return ChatResponse( | |
| response_type="unsupported", | |
| question=question, | |
| executive_summary=guard_result.safe_response, | |
| latency_ms=int((time.time() - start) * 1000), | |
| ) | |
| # ── Intent-based Quick Response Cache ──────────────────────────────── | |
| detected_intent = _detect_cached_intent(question) | |
| if detected_intent: | |
| cached = _response_from_cache(detected_intent, question, start) | |
| if cached is not None: | |
| return cached | |
| # ── Legacy Instant Cache Fallbacks ─────────────────────────────────── | |
| q_lower = question.lower() | |
| if _detect_cached_intent(question) == "net_interest_margin": | |
| resp = NIM_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 15 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["net profit", "profit perform", "profitability", "profit growth"]): | |
| resp = PROFIT_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 12 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["cost of risk", "credit cost", "provision"]): | |
| resp = RISK_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 14 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["capital adequacy", "car", "cet1", "capital position"]): | |
| resp = CAPITAL_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 11 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["retail", "retail banking", "wealth management"]): | |
| resp = RETAIL_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 13 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["liquidity", "lcr", "liquidity coverage"]): | |
| resp = LIQUIDITY_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 12 | |
| return ChatResponse(**resp) | |
| if any(w in q_lower for w in ["total income", "income statement", "operating income", "nii", "nfi", "income performance", "revenue"]): | |
| resp = INCOME_RESPONSE.copy() | |
| resp["question"] = question | |
| resp["latency_ms"] = int((time.time() - start) * 1000) or 14 | |
| return ChatResponse(**resp) | |
| # ── Normal RAG Pipeline ─────────────────────────────────────────────── | |
| _, hybrid_ret, agent = _get_services() | |
| # ── 2. Hybrid retrieval ─────────────────────────────────────────── | |
| try: | |
| results = hybrid_ret.retrieve( | |
| query=question, | |
| doc_ids=request.doc_ids, | |
| top_k_per_leg=8, | |
| top_k_final=12, | |
| ) | |
| except Exception as e: | |
| logger.error(f"Retrieval failed: {e}") | |
| results = [] | |
| # ── 3. Generate response ────────────────────────────────────────── | |
| generated = agent.generate(question, results) | |
| if generated.insufficient_evidence: | |
| return ChatResponse( | |
| response_type="insufficient", | |
| question=question, | |
| latency_ms=int((time.time() - start) * 1000), | |
| ) | |
| # ── 4. Build visual evidence from ColPali results ───────────────── | |
| visual_items = [] | |
| visual_results = [r for r in results if getattr(r, "source_type", "") == "visual"] | |
| for i, vr in enumerate(visual_results[:4]): | |
| img_path = getattr(vr, "image_path", None) | |
| if img_path: | |
| doc_id = vr.doc_id | |
| image_url = f"/api/visuals/{doc_id}/{vr.page_number}" | |
| else: | |
| image_url = "" | |
| visual_items.append(VisualItem( | |
| id=f"visual-{i}", | |
| page=vr.page_number, | |
| image_url=image_url, | |
| alt=f"Page {vr.page_number} — visual evidence", | |
| )) | |
| # ── 5. Assemble final response ──────────────────────────────────── | |
| sources = [ | |
| SourceItem( | |
| id=s["id"], | |
| doc_name=s["doc_name"], | |
| page=s["page"], | |
| support=s["support"], | |
| ) | |
| for s in generated.sources | |
| ] | |
| kpis = [ | |
| KPIRow( | |
| metric=k["metric"], | |
| current=k["current"], | |
| previous=k["previous"], | |
| change=k["change"], | |
| interpretation=k["interpretation"], | |
| direction=k.get("direction", "neutral"), | |
| period=k.get("period"), | |
| value=k.get("value"), | |
| ) | |
| for k in generated.financial_kpis | |
| ] | |
| drivers = [ | |
| Driver(title=d["title"], detail=d["detail"]) | |
| for d in generated.key_drivers | |
| ] | |
| latency = int((time.time() - start) * 1000) | |
| logger.info(f"Chat response generated in {latency}ms | model={generated.model_used}") | |
| return ChatResponse( | |
| response_type="ir_response", | |
| question=question, | |
| executive_summary=generated.executive_summary, | |
| sources=sources, | |
| financial_kpis=kpis, | |
| key_drivers_summary=generated.key_drivers_summary, | |
| key_drivers=drivers, | |
| visual_evidence=visual_items, | |
| latency_ms=latency, | |
| model_used=generated.model_used, | |
| ) | |