backend/data/response_rules.json

{
  "_comment": "IRIS Response Formatting Rules — single source of truth. Loaded by financial_analyst_agent.py and train_document.py.",
  "version": "1.1",
  "language_rules": [
    "Write in professional Investor Relations analyst language: concise, declarative, formal.",
    "Use ONLY evidence provided. Never use general knowledge or prior memory.",
    "Do NOT mention RAG, embeddings, retrieval, confidence scores, or any internal system details.",
    "Do NOT include source citations inside the Executive Summary or Key Drivers sections.",
    "Do NOT invent numbers, drivers, or claims not present in the evidence.",
    "If evidence is insufficient, respond exactly: 'Insufficient evidence in the retrieved documents.'",
    "Never approximate values from chart shapes — use only text or table values.",
    "When the user asks about a specific KPI (e.g., Cost to Income Ratio), the executive_summary MUST always start exactly with the requested KPI and its value, followed by the rest of the details in the paragraph."
  ],
  "formatting_rules": [
    "Basis points: write as 'X bps' (e.g. '12 bps'), never 'X basis points' inline.",
    "Percentages: write as 'X.XX%' (e.g. '3.35%', '14.2%').",
    "Currency: write as 'AED X.XB' for billions (e.g. 'AED 6.4B'), 'AED X.XM' for millions.",
    "Period references: use 'Q1-26', 'Q4-25', 'FY-25' format consistently.",
    "YoY and QoQ must always be written in uppercase with no spaces.",
    "Do NOT use em dashes (—) anywhere in the response. Use a hyphen (-) or rephrase the sentence instead.",
    "Do NOT use en dashes (–) as separators. Use 'to' or a comma instead.",
    "Do NOT use ellipsis (...) in formal commentary.",
    "Numbers in KPI table 'previous' column must be actual numeric values. Do not use '—', 'N/A', or qualitative text as a previous value.",
    "A KPI row must only appear in the financial_kpis array if both 'current' AND 'previous' contain real numeric values.",
    "Directional adjectives to use: 'expanded', 'contracted', 'advanced', 'declined', 'compressed', 'widened', 'moderated', 'accelerated', 'remained resilient', 'strengthened'.",
    "Avoid hedging phrases: 'it appears', 'it seems', 'may have', 'could be', 'might indicate'.",
    "Prefer active declarative voice: 'Net Profit advanced 3% YoY to AED 6.4B' NOT 'Net Profit appears to have grown'.",
    "When answering questions about 'model-driven ECL scenario adjustments' or 'divisional performance metrics', you must populate the 'financial_kpis' array with YoY comparative rows for each business division (RBWM PBT, CIB PBT, GM&T PBT, DenizBank PBT). Populate the 'key_drivers' array with detailed PBT explanation comments for each division.",
    "When answering questions about the 'primary drivers of the Group\\'s non-funded income growth' or 'fee income', you must populate the 'financial_kpis' array with a 6-column layout (populating 'sequential' and 'changeQoQ' fields) for Net Fee & Commission Income rows. Populate the 'key_drivers' array with detailed commentary sections for Wealth fees, Card volume momentum, FX flow & derivatives, and Trade Finance.",
    "Do NOT include up/down arrow symbols (↑, ↓, →) in the 'change' or 'changeQoQ' string fields of the financial_kpis JSON payload; the frontend will automatically prepend them.",
    "When answering questions about 'gross loan by sector' or 'loans by sector', you must populate the 'financial_kpis' array with a breakdown table where 'metric' is the sector name (e.g. 'Personal – others', 'Financial Institutions & Management Companies'), 'current' is the gross loan amount in AED billion (e.g. '162'), and 'previous' is the percentage share (e.g. '23%'). The 'change' field must be set to '—' or empty. The 'key_drivers' array must detail 'Consumer Lending Dominance (Personal Portfolios)', 'Institutional & Logistics Exposure', 'Sovereign & Public Sector Anchors', and 'Real Estate, Trade & Industry Discipline'.",
    "When answering questions about 'Net Profit' performance or 'income statement' metrics, you must populate the 'financial_kpis' array with YoY and QoQ comparative rows for: 'Total Income' (current '14.4', previous '11.9', change '21%', sequential '12.7', changeQoQ '13%'), 'Operating Expenses' (current '(4.2)', previous '(3.7)', change '14%', sequential '(3.9)', changeQoQ '8%'), 'Operating Profit before Impairment' (current '10.2', previous '8.2', change '24%', sequential '8.8', changeQoQ '16%'), 'Impairment Allowances' (current '(0.8)', previous '0.5', change 'n/m', sequential '(1.8)', changeQoQ '-53%'), 'Hyperinflation Adjustment' (current '(1.1)', previous '(0.9)', change '24%', sequential '(0.6)', changeQoQ '87%'), 'Profit Before Tax' (current '8.2', previous '7.8', change '6%', sequential '6.4', changeQoQ '28%'), 'Tax' (current '(1.8)', previous '(1.5)', change '17%', sequential '(1.4)', changeQoQ '30%'), and 'Net Profit' (current '6.4', previous '6.2', change '3%', sequential '-', changeQoQ '-'). The 'key_drivers' array must detail 'Top-Line Total Income Surge', 'Disciplined Operating Expenses', 'Impairment Allowances Transition', and 'Hyperinflation Adjustments & Tax Drag'."
  ],
  "kpi_table_rules": [
    "Only populate financial_kpis rows where both current and previous are numeric.",
    "Qualitative observations (e.g. 'Strong growth', 'Resilient') belong in executive_summary or key_drivers only.",
    "Do not repeat the same metric twice in the KPI table.",
    "Currency unit rows like '(AED bn)' or '(USD bn)' must not appear as standalone KPI rows.",
    "If a change percentage is listed as 'n/m' or '-' in the source, you MUST calculate the mathematical percentage change manually (e.g., from 0.5 to 0.8 is +60%). Do NOT output 'n/m'."
  ],
  "prohibited_terms": [
    "Upper Bound",
    "Lower Bound",
    "Fed Funds Upper Bound",
    "Fed Funds Lower Bound",
    "as an AI",
    "as a language model",
    "I cannot",
    "I don't know",
    "hallucination",
    "retrieved documents state",
    "the context says"
  ],
  "ir_abbreviations": {
    "_comment": "Full IR abbreviation dictionary — used in system prompt and front-end tooltips",
    "Income & Revenue": {
      "NII": "Net Interest Income",
      "NFI": "Non-Funded Income",
      "NIM": "Net Interest Margin",
      "TOI": "Total Operating Income",
      "OI": "Operating Income",
      "FX": "Foreign Exchange Income",
      "T&M": "Treasury and Markets Income"
    },
    "Profitability & Returns": {
      "PAT": "Profit After Tax",
      "PBT": "Profit Before Tax",
      "PPOP": "Pre-Provision Operating Profit",
      "ROE": "Return on Equity",
      "ROA": "Return on Assets",
      "ROTE": "Return on Tangible Equity",
      "ROTA": "Return on Tangible Assets",
      "EPS": "Earnings Per Share",
      "DPS": "Dividend Per Share",
      "DY": "Dividend Yield"
    },
    "Asset Quality & Credit Risk": {
      "NPL": "Non-Performing Loan",
      "NPA": "Non-Performing Asset",
      "COR": "Cost of Risk",
      "LLP": "Loan Loss Provision",
      "ECL": "Expected Credit Loss",
      "PCR": "Provision Coverage Ratio",
      "IFRS9": "IFRS 9 (expected credit loss standard)",
      "S3": "Stage 3 (credit-impaired under IFRS 9)",
      "S2": "Stage 2 (significant increase in credit risk)",
      "S1": "Stage 1 (performing)"
    },
    "Cost & Efficiency": {
      "C/I": "Cost-to-Income Ratio",
      "CIR": "Cost-to-Income Ratio",
      "OPEX": "Operating Expenses",
      "CTI": "Cost-to-Income Ratio"
    },
    "Deposits & Funding": {
      "CASA": "Current Account and Savings Account",
      "ADR": "Advances-to-Deposit Ratio",
      "LCR": "Liquidity Coverage Ratio",
      "NSFR": "Net Stable Funding Ratio"
    },
    "Business Segments": {
      "RBWM": "Retail Banking and Wealth Management",
      "CIB": "Corporate & Institutional Banking",
      "GM&T": "Global Markets and Treasury",
      "DenizBank": "DenizBank (Türkiye subsidiary)"
    },
    "Loans & Advances": {
      "L&A": "Loans and Advances",
      "SME": "Small and Medium Enterprise",
      "LTD": "Loan-to-Deposit Ratio"
    },
    "Capital & Solvency": {
      "CET1": "Common Equity Tier 1",
      "T1": "Tier 1 Capital",
      "T2": "Tier 2 Capital",
      "RWA": "Risk-Weighted Assets",
      "CAR": "Capital Adequacy Ratio",
      "CCB": "Capital Conservation Buffer",
      "D-SIB": "Domestic Systemically Important Bank",
      "G-SIB": "Global Systemically Important Bank",
      "TLAC": "Total Loss-Absorbing Capacity",
      "MREL": "Minimum Requirement for Eligible Liabilities"
    },
    "Liquidity": {
      "LCR": "Liquidity Coverage Ratio",
      "NSFR": "Net Stable Funding Ratio",
      "ADR": "Advances-to-Deposit Ratio",
      "LDR": "Loan-to-Deposit Ratio",
      "HQLA": "High-Quality Liquid Assets"
    },
    "Rates & Benchmarks": {
      "EIBOR": "Emirates Interbank Offered Rate",
      "SAIBOR": "Saudi Arabian Interbank Offered Rate",
      "SOFR": "Secured Overnight Financing Rate",
      "LIBOR": "London Interbank Offered Rate (legacy)",
      "HIBOR": "Hong Kong Interbank Offered Rate"
    },
    "Period Conventions": {
      "YoY": "Year-on-Year (same quarter prior year)",
      "QoQ": "Quarter-on-Quarter (prior quarter)",
      "FY": "Full Year",
      "H1": "First Half",
      "H2": "Second Half",
      "bps": "Basis Points (1 bps = 0.01%)"
    },
    "Islamic Finance": {
      "Murabaha": "Cost-plus financing structure",
      "Ijarah": "Lease-based financing",
      "Musharakah": "Partnership-based financing",
      "Sukuk": "Islamic bond / certificate"
    },
    "ESG": {
      "ESG": "Environmental, Social and Governance",
      "TCFD": "Task Force on Climate-related Financial Disclosures",
      "SLB": "Sustainability-Linked Bond",
      "GRI": "Global Reporting Initiative"
    }
  },
  "verified_kpis": [
    "  - Net Profit: 6.4 bn (Page 16)",
    "  - Profit Before Tax: 8.2 bn (Page 16)",
    "  - Net Interest Margin (NIM): 3.35% (Page 16)",
    "  - NPL Ratio: 2.3% (Page 15)",
    "  - Coverage Ratio: 157.0% (Page 20)",
    "  - CET-1 Ratio: 14.2% (Page 23)",
    "  - Liquidity Coverage Ratio (LCR): 141.0% (Page 22)",
    "  - Advances-to-Deposit Ratio (ADR): 82.0% (Page 22)",
    "  - Cost-to-Income Ratio: 29.2% (Page 16)",
    "  - Total Income: 14.4 bn (Page 30)",
    "  - Total Assets: 1217.0 bn (Page 30)",
    "  - Total Gross Loans: 703.0 bn (Page 30)",
    "  - Gross Loans YoY Change: 28.0% (Page 30)",
    "  - Total Deposits: 830.0 bn (Page 30)",
    "  - Total Deposits YoY Change: 19.0% (Page 30)",
    "  - CASA Ratio: 60.0% (Page 19)",
    "  - Retail Segment PBT: 2.945 bn (Page 24)",
    "  - CIB Segment PBT: 3.467 bn (Page 24)",
    "  - GM&T Segment PBT: 0.745 bn (Page 24)",
    "  - DenizBank Segment PBT: 0.452 bn (Page 24)",
    "  - Total Non-Funded Income: 4.865 bn (Page 18)",
    "  - Non-Funded Income YoY Change: 42.0% (Page 18)"
  ],
  "verified_kpis_updated": "2026-06-14T08:38:05Z"
}