Update README.md

README.md

@@ -1,3 +1,223 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+tags:
+- decision-intelligence
+- insurance
+- governance
+- audit
+- gcc
+library_name: bdr-decision-os
+---
+
+# BDR Decision Engine
+
+## 🎯 Core Decision Operating System
+
+**The foundational orchestration engine for insurance decision intelligence.**
+
+This is NOT a standalone model. It is the **reusable core engine** that powers all insurance decision systems in the Bader AI platform.
+
+---
+
+## Architecture Principle
+
+**Capabilities are NOT projects.**  
+**Insurance decision systems ARE projects.**
+
+This engine is industry-agnostic. Insurance logic is injected via configuration.
+
+---
+
+## What This Engine Does
+
+The BDR Decision Engine provides:
+
+### 1. Agent Orchestration
+- Multi-agent workflow coordination
+- Sequential and parallel execution
+- Agent state management
+- Error handling and recovery
+
+### 2. Input Normalization
+- Schema validation
+- Data type conversion
+- Missing value handling
+- Format standardization
+
+### 3. Decision Routing
+- Rule-based routing
+- Confidence-based escalation
+- Priority queue management
+- Load balancing
+
+### 4. Governance Hooks
+- Pre-decision validation
+- Post-decision logging
+- Compliance checks
+- Regulatory alignment (IFRS, AML)
+
+### 5. Metrics Hooks
+- Performance tracking
+- Confidence distribution
+- Escalation rate monitoring
+- Turnaround time measurement
+
+### 6. Human-in-the-Loop Overrides
+- Manual decision override
+- Override justification capture
+- Audit trail preservation
+- Feedback loop integration
+
+---
+
+## Standard Decision Contract
+
+All systems using this engine output the same contract:
+
+```json
+{
+  "decision": "approve | reject | escalate | investigate | adjust",
+  "confidence": 0.0-1.0,
+  "rationale": "human-readable explanation",
+  "risk_signals": ["fraud", "coverage_gap", "inconsistency"],
+  "recommended_next_step": "string"
+}
+```
+
+---
+
+## Insurance Systems Using This Engine
+
+This engine powers 4 production insurance systems:
+
+| System | Purpose | Capabilities Activated |
+|--------|---------|------------------------|
+| **ClaimsGPT** | Claim approval decisions | vision_ocr, document_parser, vision_vqa, financial_analysis, risk_scoring, decision_optimizer |
+| **FraudSimulator-AI** | Fraud detection | anomaly_detection, scenario_simulator, risk_scoring, financial_analysis |
+| **AutoRiskScoreEngine** | Underwriting & pricing | financial_analysis, optimization_engine, time_series_forecasting, scenario_simulator |
+| **InsuranceKnowledgeAgent** | Policy interpretation | language_rag, policy_clause_reasoner, document_parser |
+
+---
+
+## Capability Module Interface
+
+Each capability module must expose:
+
+```python
+{
+  "input_schema": {},
+  "output_schema": {},
+  "supported_decisions": []
+}
+```
+
+### Available Capability Categories
+
+**Vision & Documents (3 modules)**
+- `vision_ocr` - Extract text from images
+- `vision_vqa` - Visual question answering
+- `document_parser` - Parse structured documents
+
+**Language & Knowledge (3 modules)**
+- `language_rag` - Retrieval-augmented generation
+- `text_analysis` - Text classification and NER
+- `policy_clause_reasoner` - Policy interpretation
+
+**Risk & Analytics (4 modules)**
+- `anomaly_detection` - Detect unusual patterns
+- `risk_scoring` - Calculate risk scores
+- `financial_analysis` - Financial impact assessment
+- `time_series_forecasting` - Predict trends
+
+**Decision Intelligence (2 modules)**
+- `decision_optimizer` - Optimize decision outcomes
+- `scenario_simulator` - Simulate decision scenarios
+
+**Governance (4 modules)**
+- `audit_logger` - Log all decisions
+- `confidence_tracker` - Track confidence scores
+- `override_handler` - Manage human overrides
+- `drift_monitor` - Detect model drift
+
+---
+
+## Governance Guarantees
+
+✅ **Every decision is logged**  
+✅ **Rationale is always stored**  
+✅ **Confidence is tracked**  
+✅ **Human overrides are recorded**  
+✅ **Audit replay is supported**  
+
+Governance is **shared across all systems** - never duplicated.
+
+---
+
+## Usage Pattern
+
+```python
+from bdr_decision_engine import DecisionEngine
+
+# Initialize engine with config
+engine = DecisionEngine(
+    system="claims",
+    enabled_capabilities=[
+        "vision_ocr",
+        "document_parser",
+        "risk_scoring",
+        "decision_optimizer"
+    ],
+    governance="strict",
+    metrics="claims_kpis"
+)
+
+# Process decision
+result = engine.process({
+    "claim_id": "CLM-2026-001",
+    "claim_type": "motor",
+    "claim_amount": 5000,
+    "documents": [...],
+    "images": [...]
+})
+
+print(result.decision)      # "approve"
+print(result.confidence)    # 0.92
+print(result.rationale)     # "Claim meets all criteria..."
+print(result.risk_signals)  # []
+```
+
+---
+
+## Strategic Positioning
+
+**Bader AI — Insurance Decision Operating System**
+
+This engine is the foundation of the GCC reference architecture for insurance AI, designed for:
+
+- **Insurers** - Production decision automation
+- **Regulators** - Auditable AI governance
+- **System Integrators** - Reusable decision infrastructure
+
+---
+
+## What This Prevents
+
+❌ Demo chaos  
+❌ Capability sprawl  
+❌ Architectural drift  
+❌ Ungoverned AI outputs  
+❌ Non-insurance use cases  
+
+---
+
+## License
+
+Apache 2.0
+
+---
+
+## Organization
+
+[BDR AI Organization](https://huggingface.co/bdr-ai-org)
+
+**Building the future of insurance decision intelligence for the GCC region.**