Add application file

.dockerignore

@@ -0,0 +1,153 @@
+# =============================================================================
+# .dockerignore - Exclude unnecessary files from Docker context
+# =============================================================================
+
+# Python & Virtual Environments
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+ENV/
+venv/
+Denv/
+.venv
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Testing & Coverage
+.pytest_cache/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# IDE & Editor Files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+*.sublime-project
+*.sublime-workspace
+.project
+.pydevproject
+.settings
+*.iml
+.vscode-container-dockerfile
+
+# Git
+.git/
+.gitignore
+.gitattributes
+.github/
+
+# Node (Frontend build artifacts)
+node_modules/
+NPM_DEBUG.log
+npm-debug.log
+yarn-error.log
+.npm
+dist/
+build/
+
+# TypeScript
+*.tsbuildinfo
+tsconfig.tsbuild.json
+ts_errors*.txt
+
+# Temporary & Log Files
+*.log
+*.pot
+*.mo
+.env
+.env.local
+.env.*
+temp/
+tmp/
+*.tmp
+*.swp
+logs/
+
+# Database & Data Files (unless needed at runtime)
+*.db
+*.sqlite
+*.sqlite3
+notiflow_data.xlsx
+agent_memory.json
+
+# Documentation
+CLAUDE.md
+TODO.md
+README.md  # Include only if needed
+docs/
+mkdocs.yml
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+Jenkinsfile
+azure-pipelines.yml
+
+# Docker Files (don't need these in image)
+Dockerfile
+.dockerignore
+docker-compose.yml
+docker-compose.*.yml
+
+# Package Manager Locks (handled by requirements.txt)
+package-lock.json
+yarn.lock
+poetry.lock
+Pipfile.lock
+
+# OS Files
+Thumbs.db
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Development Files
+test_*.py
+demo/
+examples/
+scripts/
+*.ipynb
+.ipynb_checkpoints/
+
+# Credentials (IMPORTANT - never include in image)
+credentials/
+*.json
+*.key
+*.pem
+*.pfx
+.credentials
+
+# Large Files
+*.zip
+*.tar.gz
+*.tar
+*.rar
+*.7z

.gitignore

@@ -0,0 +1,132 @@
+# =============================================================================
+# NotiFlow v2 — .gitignore
+# =============================================================================
+
+
+# ---------------------------------------------------------------------------
+# Secrets & Environment
+# ---------------------------------------------------------------------------
+.env
+.env.*
+!.env.example          # keep the example template
+
+# ---------------------------------------------------------------------------
+# Python virtual environments
+# ---------------------------------------------------------------------------
+.venv/
+venv/
+env/
+ENV/
+.Python
+
+# ---------------------------------------------------------------------------
+# Python compiled / cache
+# ---------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+
+# ---------------------------------------------------------------------------
+# Build / packaging
+# ---------------------------------------------------------------------------
+build/
+dist/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ---------------------------------------------------------------------------
+# Data files — generated at runtime, not source code
+# ---------------------------------------------------------------------------
+data/notiflow_data.xlsx
+data/*.xlsx
+data/*.xls
+data/*.csv
+data/agent_memory.json
+*.db
+*.sqlite3
+
+# ---------------------------------------------------------------------------
+# Logs & temporary output
+# ---------------------------------------------------------------------------
+*.log
+*.log.*
+logs/
+test_out.txt
+test_output.txt
+*.tmp
+*.bak
+*.cache
+
+# ---------------------------------------------------------------------------
+# Testing & coverage
+# ---------------------------------------------------------------------------
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.hypothesis/
+*.coveragerc
+
+# ---------------------------------------------------------------------------
+# IDE & Editor
+# ---------------------------------------------------------------------------
+.vscode/
+.idea/
+*.iml
+*.swp
+*.swo
+*~
+.gradle/
+out/
+
+# ---------------------------------------------------------------------------
+# OS generated
+# ---------------------------------------------------------------------------
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# ---------------------------------------------------------------------------
+# Jupyter
+# ---------------------------------------------------------------------------
+.ipynb_checkpoints
+*.ipynb
+
+# ---------------------------------------------------------------------------
+# Node (if frontend is ever added)
+# ---------------------------------------------------------------------------
+node_modules/
+.eslintcache
+.stylelintcache
+.node_repl_history
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnp/
+.pnp.js
+
+# ---------------------------------------------------------------------------
+# Miscellaneous stray artefacts (PowerShell / curl leftovers)
+# ---------------------------------------------------------------------------
+-Body
+-ContentType
+-Uri

Dockerfile

@@ -0,0 +1,60 @@
+# =============================================================================
+# VyaparFlow - Hugging Face Space Dockerfile
+# =============================================================================
+# Multi-stage build for optimized image size
+# Runs FastAPI backend on port 7860 (Hugging Face requirement)
+
+# Stage 1: Builder
+# =============================================================================
+FROM python:3.13-slim as builder
+
+WORKDIR /build
+
+# Install system dependencies for build
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# Stage 2: Runtime
+# =============================================================================
+FROM python:3.13-slim
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PATH=/root/.local/bin:$PATH \
+    PORT=7860 \
+    NOTIFLOW_DEMO_MODE=true
+
+WORKDIR /app
+
+# Install runtime dependencies only
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Python dependencies from builder
+COPY --from=builder /root/.local /root/.local
+
+# Copy entire project
+COPY . .
+
+# Create necessary directories with proper permissions
+RUN mkdir -p /app/data /app/credentials && \
+    chmod -R 755 /app
+
+# Expose Hugging Face default port
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Default command: Run FastAPI with uvicorn
+# Listens on 0.0.0.0:7860 (required for Hugging Face Spaces)
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/__init__.py

@@ -0,0 +1 @@
+"""NotiFlow Autonomous — app package."""

app/agents/__init__.py

@@ -0,0 +1,19 @@
+"""app/agents — NotiFlow agent registry."""
+
+from app.agents.intent_agent       import IntentAgent
+from app.agents.extraction_agent   import ExtractionAgent
+from app.agents.validation_agent   import ValidationAgent
+from app.agents.invoice_agent      import InvoiceAgent
+from app.agents.payment_agent      import PaymentAgent
+from app.agents.skill_router_agent import SkillRouterAgent
+from app.agents.ledger_agent       import LedgerAgent
+
+__all__ = [
+    "IntentAgent",
+    "ExtractionAgent",
+    "ValidationAgent",
+    "InvoiceAgent",
+    "PaymentAgent",
+    "SkillRouterAgent",
+    "LedgerAgent",
+]

app/agents/escalation_agent.py

@@ -0,0 +1,143 @@
+"""
+app/agents/escalation_agent.py
+-------------------------------
+EscalationAgent — Autonomy Layer, Step 5.
+
+Triggers when priority is "high"/"critical" OR risk is "high".
+Logs structured alerts and simulates an external notification.
+
+In production, replace _notify() with a real webhook/SMS/email call.
+
+Output written to context["alerts"]:
+    [
+        {
+            "level":     "warning" | "critical",
+            "trigger":   str,          # what caused this alert
+            "message":   str,          # human-readable description
+            "timestamp": str,          # ISO-8601
+            "notified":  bool,         # True if notification was "sent"
+        },
+        ...
+    ]
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+_ESCALATION_PRIORITIES = {"high", "critical"}
+_ESCALATION_RISKS      = {"high"}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class EscalationAgent(BaseAgent):
+    """Detect high-priority or high-risk situations and raise alerts."""
+
+    name        = "EscalationAgent"
+    input_keys  = ["priority", "risk", "errors", "intent", "data"]
+    output_keys = ["alerts"]
+    action      = "Raise alerts and simulate notifications for critical situations"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        priority = (context.get("priority") or "low").lower()
+        risk     = context.get("risk", {})
+        errors   = context.get("errors", [])
+        intent   = (context.get("intent") or "other").lower()
+        data     = context.get("data", {})
+
+        alerts: list[dict[str, Any]] = []
+
+        # ── Trigger 1: high priority score (was "critical" in old model) ─────
+        score = context.get("priority_score", 0)
+        if score >= 80:
+            alert = self._build_alert(
+                level   = "critical",
+                trigger = f"priority_score={score}",
+                message = (
+                    f"CRITICAL priority score {score}/100. "
+                    f"Intent: {intent}. "
+                    f"Customer: {data.get('customer', 'unknown')}."
+                ),
+            )
+            alerts.append(alert)
+            self._notify(alert)
+
+        # ── Trigger 2: high priority label ───────────────────────────────────
+        elif priority == "high":
+            alert = self._build_alert(
+                level   = "warning",
+                trigger = f"priority=high score={score}",
+                message = (
+                    f"High priority transaction flagged. "
+                    f"Intent: {intent}. "
+                    f"Score: {score}/100. "
+                    f"Reason: {context.get('metadata', {}).get('urgency_reason', 'n/a')}."
+                ),
+            )
+            alerts.append(alert)
+            self._notify(alert)
+
+        # ── Trigger 3: high risk ─────────────────────────────────────────────
+        if risk.get("level") in _ESCALATION_RISKS:
+            risk_reasons = "; ".join(risk.get("reasons", []))
+            alert = self._build_alert(
+                level   = "warning",
+                trigger = "risk=high",
+                message = f"High risk transaction. Reasons: {risk_reasons}",
+            )
+            alerts.append(alert)
+            self._notify(alert)
+
+        # ── Trigger 4: critical errors in pipeline ───────────────────────────
+        critical_errors = [e for e in errors if "[Monitor]" in e]
+        if len(critical_errors) >= 2:
+            alert = self._build_alert(
+                level   = "warning",
+                trigger = "monitor_issues",
+                message = (
+                    f"{len(critical_errors)} monitor issue(s) detected: "
+                    f"{critical_errors[0]}"
+                ),
+            )
+            alerts.append(alert)
+
+        context["alerts"] = alerts
+        if alerts:
+            logger.warning(
+                "[EscalationAgent] %d alert(s) raised (priority=%s risk=%s)",
+                len(alerts), priority, risk.get("level", "unknown")
+            )
+        else:
+            logger.info("[EscalationAgent] no escalation needed")
+        return context
+
+    @staticmethod
+    def _build_alert(level: str, trigger: str, message: str) -> dict[str, Any]:
+        return {
+            "level":     level,
+            "trigger":   trigger,
+            "message":   message,
+            "timestamp": _now_iso(),
+            "notified":  False,   # updated by _notify()
+        }
+
+    @staticmethod
+    def _notify(alert: dict[str, Any]) -> None:
+        """
+        Simulate sending an external notification.
+        Replace this method with a real webhook/SMS/email integration.
+        """
+        alert["notified"] = True
+        logger.warning(
+            "[EscalationAgent] 🚨 ALERT [%s] %s",
+            alert["level"].upper(), alert["message"]
+        )

app/agents/extraction_agent.py

@@ -0,0 +1,181 @@
+"""
+app/agents/extraction_agent.py
+------------------------------
+ExtractionAgent — Stage 2 of the NotiFlow pipeline.
+
+Phase 5: Multi-intent support.
+    - Reads context["intents"] (list); falls back to context["intent"]
+    - Single LLM call extracts data for ALL intents at once
+    - Writes context["multi_data"]  = {intent: {fields}}  (all intents)
+    - Writes context["data"]        = multi_data[primary]  (backward compat)
+
+Single-intent path is identical to Phase 1-4 behaviour.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+from app.core.llm_service import get_llm
+
+logger = logging.getLogger(__name__)
+
+_PROMPT_PATH = Path(__file__).parent.parent.parent / "prompts" / "extraction_prompt.txt"
+
+INTENT_SCHEMA: dict[str, list[str]] = {
+    "order":       ["customer", "item", "quantity"],
+    "payment":     ["customer", "amount", "payment_type"],
+    "credit":      ["customer", "item", "quantity", "amount"],
+    "return":      ["customer", "item", "reason"],
+    "preparation": ["item", "quantity"],
+    "other":       ["note"],
+}
+VALID_INTENTS = set(INTENT_SCHEMA.keys())
+
+
+class ExtractionAgent(BaseAgent):
+    """Extract structured business fields for ALL detected intents."""
+
+    name        = "ExtractionAgent"
+    input_keys  = ["message", "intent", "intents"]
+    output_keys = ["data", "multi_data", "state"]
+    action      = "Extract structured entities for all detected intents"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        message = context.get("message", "").strip()
+
+        # Resolve intents — Phase 5 uses context["intents"], fallback to ["intent"]
+        intents = context.get("intents") or []
+        if not intents:
+            primary = (context.get("intent") or "other").lower().strip()
+            intents = [primary]
+
+        # Validate each intent
+        intents = [i if i in VALID_INTENTS else "other" for i in intents]
+        primary = intents[0]
+
+        if not message:
+            multi_data = {i: self._null_data(i) for i in intents}
+            update_context(context,
+                           data=multi_data[primary],
+                           multi_data=multi_data,
+                           state="extracted")
+            return context
+
+        # ── Single LLM call for all intents ──────────────────────────────
+        prompt   = self._load_prompt(message, intents)
+        try:
+            raw = get_llm().generate(
+                prompt,
+                max_tokens=400,
+                agent_name=self.name,
+                task_type="extraction",
+                context=context,
+            )
+        except Exception as exc:
+            logger.error("[ExtractionAgent] all LLM backends failed - using null extraction: %s", exc)
+            raw = "{}"
+        multi_data = self._parse(raw, intents)
+
+        update_context(context,
+                       data=multi_data[primary],   # backward compat
+                       multi_data=multi_data,
+                       state="extracted")
+        logger.info("[ExtractionAgent] intents=%s extracted=%s", intents, multi_data)
+        return context
+
+    # ── Helpers ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _load_prompt(message: str, intents: list[str]) -> str:
+        template   = _PROMPT_PATH.read_text(encoding="utf-8")
+        intents_str = ", ".join(intents)
+        prompt     = template.replace("{message}", message.strip())
+        prompt     = prompt.replace("{intents}", intents_str)
+        # Legacy placeholder — extraction_prompt.txt used to have {intent}
+        prompt     = prompt.replace("{intent}",  intents_str)
+        return prompt
+
+    @staticmethod
+    def _parse(raw: str, intents: list[str]) -> dict[str, dict]:
+        """
+        Parse LLM output into a per-intent data dict.
+
+        Handles two response shapes:
+          Single:  {"customer": "Rahul", "amount": 500, ...}
+          Multi:   {"payment": {"customer": ...}, "order": {"item": ...}}
+
+        Returns: {intent: {fields}} for every intent in intents.
+        """
+        cleaned = re.sub(r"```(?:json)?|```", "", raw).strip()
+        parsed: dict = {}
+        try:
+            parsed = json.loads(cleaned)
+        except json.JSONDecodeError:
+            match = re.search(r"\{.*\}", cleaned, re.DOTALL)
+            if match:
+                try:
+                    parsed = json.loads(match.group(0))
+                except json.JSONDecodeError:
+                    logger.warning("[ExtractionAgent] could not parse JSON; using nulls")
+
+        multi_data: dict[str, dict] = {}
+
+        if len(intents) == 1:
+            # Single-intent response — flat dict
+            intent = intents[0]
+            multi_data[intent] = ExtractionAgent._extract_single(parsed, intent)
+        else:
+            # Multi-intent response — keyed by intent name
+            for intent in intents:
+                if intent in parsed and isinstance(parsed[intent], dict):
+                    multi_data[intent] = ExtractionAgent._extract_single(
+                        parsed[intent], intent
+                    )
+                else:
+                    # Fallback: maybe LLM returned flat dict for first intent
+                    if not multi_data and intent == intents[0]:
+                        multi_data[intent] = ExtractionAgent._extract_single(parsed, intent)
+                    else:
+                        multi_data[intent] = ExtractionAgent._null_data(intent)
+
+        # Guarantee every requested intent has an entry
+        for intent in intents:
+            if intent not in multi_data:
+                multi_data[intent] = ExtractionAgent._null_data(intent)
+
+        return multi_data
+
+    @staticmethod
+    def _extract_single(src: dict, intent: str) -> dict:
+        """Build a schema-validated dict for one intent from a source dict."""
+        schema = INTENT_SCHEMA.get(intent, INTENT_SCHEMA["other"])
+        result = {field: src.get(field) for field in schema}
+
+        # Normalise customer to Title Case
+        if "customer" in result and isinstance(result["customer"], str):
+            result["customer"] = result["customer"].strip().title()
+            if result["customer"].lower() in ("null", "none", ""):
+                result["customer"] = None
+
+        # Coerce numeric fields
+        for num_field in ("amount", "quantity"):
+            if num_field in result and result[num_field] is not None:
+                try:
+                    val = float(result[num_field])
+                    result[num_field] = int(val) if val == int(val) else val
+                except (ValueError, TypeError):
+                    result[num_field] = None
+
+        return result
+
+    @staticmethod
+    def _null_data(intent: str) -> dict:
+        schema = INTENT_SCHEMA.get(intent, INTENT_SCHEMA["other"])
+        return {field: None for field in schema}

app/agents/intent_agent.py

@@ -0,0 +1,136 @@
+"""
+app/agents/intent_agent.py
+--------------------------
+IntentAgent — Stage 1 of the NotiFlow pipeline.
+
+Phase 5: Multi-intent support.
+    - Prompt now returns {"intents": ["payment", "order"]}
+    - context["intents"] = full detected list
+    - context["intent"]  = intents[0]  ← backward compat
+
+Backward compat: if LLM returns old {"intent": "x"} format, wraps in list.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+from app.core.llm_service import get_llm
+
+logger = logging.getLogger(__name__)
+
+# Prompt lives in the repo-level prompts/ folder
+_PROMPT_PATH = Path(__file__).parent.parent.parent / "prompts" / "intent_prompt.txt"
+
+VALID_INTENTS = {"order", "payment", "credit", "return", "preparation", "other"}
+
+
+class IntentAgent(BaseAgent):
+    """Classify ALL business intents from a Hinglish message."""
+
+    name        = "IntentAgent"
+    input_keys  = ["message"]
+    output_keys = ["intent", "intents", "state"]
+    action      = "Classify all business intents from Hinglish message"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Detect intents and write them into context.
+
+        Writes:
+            context["intents"] — ordered list of all detected intents
+            context["intent"]  — primary intent (intents[0]) for backward compat
+        Transitions state to "intent_detected" on success.
+        """
+        message = context.get("message", "").strip()
+        if not message:
+            logger.warning("[IntentAgent] empty message — defaulting to 'other'")
+            update_context(context, intent="other", intents=["other"], state="intent_detected")
+            return context
+
+        prompt  = self._load_prompt(message)
+        try:
+            raw = get_llm().generate(
+                prompt,
+                max_tokens=96,
+                agent_name=self.name,
+                task_type="classification",
+                context=context,
+            )
+        except Exception as exc:
+            logger.error("[IntentAgent] all LLM backends failed - defaulting to 'other': %s", exc)
+            raw = '{"intent": "other"}'
+        intents = self._parse(raw)
+        primary = intents[0]
+
+        update_context(context, intent=primary, intents=intents, state="intent_detected")
+        logger.info("[IntentAgent] intents=%s (primary=%s)", intents, primary)
+        return context
+
+    # ── Helpers ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _load_prompt(message: str) -> str:
+        template = _PROMPT_PATH.read_text(encoding="utf-8")
+        return template.replace("{message}", message)
+
+    @staticmethod
+    def _parse(raw: str) -> list[str]:
+        """
+        Parse LLM output into a list of valid intents.
+
+        Handles:
+          - New format:  {"intents": ["payment", "order"]}
+          - Old format:  {"intent": "payment"}     ← backward compat
+          - Bare string: payment
+        Returns at least ["other"] on any parse failure.
+        """
+        cleaned = re.sub(r"```(?:json)?|```", "", raw).strip()
+        intents: list[str] = []
+
+        try:
+            result = json.loads(cleaned)
+            if isinstance(result, dict):
+                if "intents" in result:
+                    raw_list = result["intents"]
+                    if isinstance(raw_list, list):
+                        intents = [str(x).lower().strip() for x in raw_list]
+                    else:
+                        intents = [str(raw_list).lower().strip()]
+                elif "intent" in result:
+                    # Old single-intent format — wrap in list
+                    intents = [str(result["intent"]).lower().strip()]
+        except json.JSONDecodeError:
+            # Try regex fallback for intents array (handles truncated/malformed JSON)
+            arr_match = re.search(r'"intents"\s*:\s*\[([^\]]*)', cleaned)
+            if arr_match:
+                raw_items = arr_match.group(1)
+                intents = [
+                    m.lower().strip()
+                    for m in re.findall(r'"(\w+)"', raw_items)
+                ]
+            else:
+                # Try old single-intent regex
+                match = re.search(r'"intent"\s*:\s*"(\w+)"', cleaned)
+                if match:
+                    intents = [match.group(1).lower()]
+
+        # Validate — keep only known intents, deduplicate, preserve order
+        seen:  set[str] = set()
+        valid: list[str] = []
+        for intent in intents:
+            if intent in VALID_INTENTS and intent not in seen:
+                valid.append(intent)
+                seen.add(intent)
+
+        if not valid:
+            logger.warning("[IntentAgent] could not parse valid intents from: %r", raw[:80])
+            valid = ["other"]
+
+        return valid

app/agents/invoice_agent.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+from app.core.event_bus import emit_event, push_live_log, store_invoice
+from app.services.invoice_service import InvoiceBuilder
+
+logger = logging.getLogger(__name__)
+
+PRICE_MAP = {
+    "kurti": 50.0,
+    "sugar": 50.0,
+    "atta": 40.0,
+}
+
+
+class InvoiceAgent(BaseAgent):
+    """Generate a business invoice from validated order data."""
+
+    name = "InvoiceAgent"
+    input_keys = ["intent", "data", "source"]
+    output_keys = ["invoice", "event", "state"]
+    action = "Generate invoice from validated business data"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        intent = (context.get("intent") or "other").lower()
+        data = context.get("data", {}) or {}
+
+        if intent != "order":
+            update_context(
+                context,
+                event={"event": f"{intent}_received", "data": data},
+                state="invoice_skipped",
+            )
+            return context
+
+        builder = InvoiceBuilder(catalog_prices=PRICE_MAP)
+        invoice = builder.build(
+            customer=data.get("customer") or "Walk-in customer",
+            item=data.get("item"),
+            quantity=data.get("quantity"),
+            order_id=context.get("event", {}).get("order_id"),
+        )
+        invoice = store_invoice(invoice)
+
+        update_context(
+            context,
+            invoice=invoice,
+            event={"event": "invoice_generated", "invoice": invoice},
+            state="invoice_generated",
+        )
+
+        invoice_log = push_live_log(
+            context,
+            {
+                "agent": self.name,
+                "status": "success",
+                "action": f"Invoice generated: {invoice['invoice_id']}",
+                "detail": f"[{self.name}] Invoice generated: {invoice['invoice_id']}",
+            },
+        )
+        emit_event(
+            context,
+            "invoice_generated",
+            invoice,
+            agent=self.name,
+            step="invoice",
+            message=f"Invoice generated: {invoice['invoice_id']}",
+            log_entry=invoice_log,
+        )
+        logger.info("[InvoiceAgent] invoice=%s", invoice["invoice_id"])
+        return context

app/agents/ledger_agent.py

@@ -0,0 +1,72 @@
+"""
+app/agents/ledger_agent.py
+--------------------------
+LedgerAgent — Stage 5 of the NotiFlow pipeline.
+
+Wraps services/google_sheets_service.py into the BaseAgent interface.
+Appends the processed transaction to the live Google Sheets ledger.
+
+Non-fatal: if Sheets is unavailable the pipeline continues normally and
+context["metadata"]["sheet_updated"] is set to False.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import add_error
+
+logger = logging.getLogger(__name__)
+
+
+class LedgerAgent(BaseAgent):
+    """Sync the processed transaction to the Google Sheets ledger."""
+
+    name        = "LedgerAgent"
+    input_keys  = ["intent", "data", "invoice", "payment", "metadata"]
+    output_keys = ["metadata", "state"]
+    action      = "Append transaction row to Google Sheets ledger"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Append a row to Google Sheets.
+
+        Non-fatal design: ALL exceptions from the Sheets API are caught here
+        inside execute() and recorded via add_error().  The method never
+        raises, so BaseAgent.run() always logs a "success" history entry —
+        reflecting that the agent completed its contract (best-effort sync),
+        not that Sheets itself succeeded.
+
+        Reads:  context["intent"], context["data"], context["metadata"]["source"]
+        Writes: context["metadata"]["sheet_updated"]
+        """
+        intent = context.get("intent", "other")
+        data   = context.get("data", {})
+        invoice = context.get("invoice") or {}
+        payment = context.get("payment") or {}
+        source = context.get("metadata", {}).get("source", "system")
+
+        ledger_data = {
+            "customer": invoice.get("customer") or data.get("customer"),
+            "item": invoice.get("item") or data.get("item"),
+            "quantity": invoice.get("quantity") or data.get("quantity"),
+            "amount": payment.get("amount") or invoice.get("total") or data.get("amount"),
+            "invoice_id": invoice.get("invoice_id"),
+            "status": payment.get("status") or invoice.get("status"),
+        }
+
+        sheet_updated = False
+        try:
+            from app.services.google_sheets_service import append_transaction
+            sheet_updated = append_transaction(intent=intent, data=ledger_data, source=source)
+        except Exception as exc:
+            # Soft failure — record the error but do NOT raise.
+            # This keeps LedgerAgent non-fatal without overriding run().
+            logger.warning("[LedgerAgent] Sheets sync failed (%s) — continuing", exc)
+            add_error(context, f"LedgerAgent: {exc}")
+
+        context.setdefault("metadata", {})["sheet_updated"] = sheet_updated
+        logger.info("[LedgerAgent] sheet_updated=%s", sheet_updated)
+        return context

app/agents/monitor_agent.py

@@ -0,0 +1,124 @@
+"""
+app/agents/monitor_agent.py
+----------------------------
+MonitorAgent — Autonomy Layer, Step 2.
+
+Scans the context after main pipeline execution and detects:
+    - missing required fields for the intent
+    - agents that errored in history
+    - inconsistencies (e.g. payment event but no amount in data)
+    - pipeline state anomalies
+
+Appends findings to context["errors"] (non-fatal) and writes a
+structured summary to context["monitor"].
+
+Output written to context["monitor"]:
+    {
+        "issues":   list[str],   # all detected problems
+        "warnings": list[str],   # non-critical observations
+        "healthy":  bool,        # True if no hard issues found
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import add_error
+
+logger = logging.getLogger(__name__)
+
+# Fields that must not be null for each intent to be considered healthy
+_CRITICAL_FIELDS: dict[str, list[str]] = {
+    "order":       ["item"],
+    "payment":     ["amount"],
+    "credit":      ["customer"],
+    "return":      ["reason"],
+    "preparation": ["item"],
+}
+
+
+class MonitorAgent(BaseAgent):
+    """Detect failures, missing data, and pipeline inconsistencies."""
+
+    name        = "MonitorAgent"
+    input_keys  = ["intent", "data", "event", "history", "errors", "state"]
+    output_keys = ["monitor"]
+    action      = "Scan pipeline results for failures and inconsistencies"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        issues:   list[str] = []
+        warnings: list[str] = []
+
+        intent  = (context.get("intent") or "other").lower()
+        data    = context.get("data", {})
+        event   = context.get("event", {})
+        history = context.get("history", [])
+        state   = context.get("state", "unknown")
+
+        # ── Check 1: pipeline state ──────────────────────────────────────────
+        if state == "failed":
+            issues.append(f"Pipeline ended in failed state")
+        elif state == "partial":
+            warnings.append("Pipeline ended in partial state — some steps may have been skipped")
+
+        # ── Check 2: agent errors in history ────────────────────────────────
+        errored_agents = [
+            h["agent"] for h in history if h.get("status") == "error"
+        ]
+        for agent_name in errored_agents:
+            issues.append(f"Agent '{agent_name}' reported an error during execution")
+
+        # ── Check 3: missing critical fields ────────────────────────────────
+        critical = _CRITICAL_FIELDS.get(intent, [])
+        for field in critical:
+            if data.get(field) is None:
+                issues.append(
+                    f"Critical field '{field}' is null for intent '{intent}'"
+                )
+
+        # ── Check 4: empty event after routing ──────────────────────────────
+        routed = any(
+            h["agent"] == "SkillRouterAgent" and h.get("status") == "success"
+            for h in history
+        )
+        if routed and not event:
+            issues.append("SkillRouterAgent completed but event dict is empty")
+
+        # ── Check 5: intent/event consistency ───────────────────────────────
+        event_name = event.get("event", "")
+        if intent == "payment" and event_name and "payment" not in event_name:
+            warnings.append(
+                f"Intent is 'payment' but event name is '{event_name}'"
+            )
+        if intent == "order" and event_name and "order" not in event_name:
+            warnings.append(
+                f"Intent is 'order' but event name is '{event_name}'"
+            )
+
+        # ── Check 6: duplicate errors already in context ────────────────────
+        existing_errors = context.get("errors", [])
+        if len(existing_errors) > 3:
+            warnings.append(
+                f"{len(existing_errors)} errors already accumulated in context"
+            )
+
+        # ── Write new issues as context errors ───────────────────────────────
+        for issue in issues:
+            add_error(context, f"[Monitor] {issue}")
+
+        healthy = len(issues) == 0
+        monitor = {
+            "issues":   issues,
+            "warnings": warnings,
+            "healthy":  healthy,
+        }
+
+        context["monitor"] = monitor
+        logger.info(
+            "[MonitorAgent] healthy=%s issues=%d warnings=%d",
+            healthy, len(issues), len(warnings)
+        )
+        return context

app/agents/payment_agent.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+from app.core.event_bus import emit_event, push_live_log
+
+logger = logging.getLogger(__name__)
+
+
+class PaymentAgent(BaseAgent):
+    """Prepare pending payment state for generated invoices."""
+
+    name = "PaymentAgent"
+    input_keys = ["intent", "invoice"]
+    output_keys = ["payment", "state"]
+    action = "Prepare payment request from invoice state"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        intent = (context.get("intent") or "other").lower()
+        invoice = context.get("invoice")
+
+        if intent != "order" or not invoice:
+            update_context(context, state="payment_skipped")
+            return context
+
+        payment = {
+            "invoice_id": invoice.get("invoice_id"),
+            "amount": invoice.get("total") or invoice.get("total_amount") or 0,
+            "status": "pending",
+        }
+        update_context(context, payment=payment, state="payment_requested")
+
+        payment_log = push_live_log(
+            context,
+            {
+                "agent": self.name,
+                "status": "success",
+                "action": f"Payment requested for {invoice['invoice_id']}",
+                "detail": f"[{self.name}] Payment requested: {invoice['invoice_id']}",
+            },
+        )
+        emit_event(
+            context,
+            "payment_requested",
+            {
+                **invoice,
+                "payment": payment,
+            },
+            agent=self.name,
+            step="payment",
+            message=f"Payment requested for {invoice['invoice_id']}",
+            log_entry=payment_log,
+        )
+        logger.info("[PaymentAgent] payment requested for %s", invoice["invoice_id"])
+        return context

app/agents/prediction_agent.py

@@ -0,0 +1,154 @@
+"""
+app/agents/prediction_agent.py
+-------------------------------
+PredictionAgent — Autonomy Layer, Step 3.
+
+Pure rule-based risk scoring. No ML, no external calls.
+
+Rules evaluated (each contributes a score 0–1):
+    1. High amount (payment/credit > 10000)       → risk +0.4
+    2. Very high amount (> 50000)                 → risk +0.3 additional
+    3. Null customer on payment/credit            → risk +0.3
+    4. Repeated errors in context                 → risk +0.2 per error (max 0.4)
+    5. Verification failed/partial                → risk +0.3
+    6. Pipeline ended in partial/failed state     → risk +0.2
+    7. Return with no reason                      → risk +0.2
+    8. Credit with no amount                      → risk +0.2
+
+Final risk level:
+    score < 0.3  → "low"
+    score < 0.6  → "medium"
+    score >= 0.6 → "high"
+
+Output written to context["risk"]:
+    {
+        "level":   "low" | "medium" | "high",
+        "score":   float,          # 0.0–1.0
+        "reasons": list[str],      # which rules fired
+        "action":  str,            # recommended action
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+_HIGH_AMOUNT      = 10_000
+_VERY_HIGH_AMOUNT = 50_000
+
+_ACTIONS = {
+    "low":    "Continue normal processing",
+    "medium": "Flag for manual review",
+    "high":   "Escalate immediately and pause processing",
+}
+
+
+class PredictionAgent(BaseAgent):
+    """Rule-based risk scorer — no ML, fully deterministic."""
+
+    name        = "PredictionAgent"
+    input_keys  = ["intent", "data", "verification", "errors", "state"]
+    output_keys = ["risk"]
+    action      = "Score transaction risk using rule-based evaluation"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        intent       = (context.get("intent") or "other").lower()
+        data         = context.get("data", {})
+        verification = context.get("verification", {})
+        errors       = context.get("errors", [])
+        state        = context.get("state", "")
+
+        score   = 0.0
+        reasons: list[str] = []
+
+        # ── Rule 1 & 2: high-value transaction ───────────────────────────────
+        amount = data.get("amount")
+        if amount is not None and intent in ("payment", "credit"):
+            try:
+                amount_f = float(amount)
+                if amount_f > _VERY_HIGH_AMOUNT:
+                    score += 0.7
+                    reasons.append(
+                        f"Very high amount ₹{amount_f:,.0f} (>{_VERY_HIGH_AMOUNT:,})"
+                    )
+                elif amount_f > _HIGH_AMOUNT:
+                    score += 0.4
+                    reasons.append(
+                        f"High amount ₹{amount_f:,.0f} (>{_HIGH_AMOUNT:,})"
+                    )
+            except (ValueError, TypeError):
+                pass
+
+        # ── Rule 3: null customer on financial intent ────────────────────────
+        if intent in ("payment", "credit") and not data.get("customer"):
+            score += 0.3
+            reasons.append("Customer is unknown on a financial transaction")
+
+        # ── Rule 4: repeated errors ──────────────────────────────────────────
+        error_count = len(errors)
+        if error_count > 0:
+            error_score = min(0.4, error_count * 0.2)
+            score += error_score
+            reasons.append(f"{error_count} error(s) accumulated in pipeline")
+
+        # ── Rule 5: verification failed ──────────────────────────────────────
+        v_status = verification.get("status", "")
+        if v_status == "fail":
+            score += 0.3
+            reasons.append("Verification failed for this transaction")
+        elif v_status == "partial":
+            score += 0.15
+            reasons.append("Verification only partially passed")
+
+        # ── Rule 6: abnormal pipeline state ──────────────────────────────────
+        if state in ("failed", "partial"):
+            score += 0.2
+            reasons.append(f"Pipeline ended in '{state}' state")
+
+        # ── Rule 7: return with no reason ────────────────────────────────────
+        if intent == "return" and not data.get("reason"):
+            score += 0.2
+            reasons.append("Return request has no stated reason")
+
+        # ── Rule 8: credit with no amount ────────────────────────────────────
+        if intent == "credit" and data.get("amount") is None:
+            score += 0.2
+            reasons.append("Credit extended with no amount specified")
+
+        # ── Clamp and classify ───────────────────────────────────────────────
+        score = min(round(score, 2), 1.0)
+        if score < 0.3:
+            level = "low"
+        elif score < 0.6:
+            level = "medium"
+        else:
+            level = "high"
+
+        risk = {
+            "level":   level,
+            "score":   score,
+            "reasons": reasons,
+            "action":  _ACTIONS[level],
+        }
+
+        context["risk"] = risk
+        logger.info(
+            "[PredictionAgent] risk=%s score=%.2f reasons=%d",
+            level, score, len(reasons)
+        )
+
+        # ── Also contribute to the shared priority score ──────────────────────
+        # High risk contributes 35 pts, medium 15 pts — UrgencyAgent will
+        # combine these with keyword/amount signals to derive the final label.
+        from app.core.priority import contribute_priority_score
+        if level == "high":
+            contribute_priority_score(context, 35, f"Risk level is high (score={score})")
+        elif level == "medium":
+            contribute_priority_score(context, 15, f"Risk level is medium (score={score})")
+
+        return context

app/agents/recovery_agent.py

@@ -0,0 +1,192 @@
+"""
+app/agents/recovery_agent.py
+-----------------------------
+RecoveryAgent — Autonomy Layer, Step 6 (most important).
+
+Implements self-healing logic based on the failure state of the pipeline.
+
+Decision tree:
+    if verification.status == "ok"  → no recovery needed
+    elif retry_count == 0           → retry (re-run failed agents from history)
+    elif retry_count == 1           → fallback (use safe defaults)
+    elif retry_count >= 2           → critical escalation, halt retries
+
+The agent does NOT re-run the full pipeline (no circular execution).
+Instead it performs a targeted fix:
+    RETRY    — re-runs only the agents that errored, one more time
+    FALLBACK — fills missing critical fields with safe placeholder values
+    ESCALATE — marks context as needing human intervention
+
+Output written to context["recovery"]:
+    {
+        "action":      "none" | "retry" | "fallback" | "escalate",
+        "retry_count": int,
+        "details":     str,
+        "success":     bool,
+    }
+
+context["metadata"]["retry_count"] is incremented on each recovery attempt.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import add_error
+
+logger = logging.getLogger(__name__)
+
+_MAX_RETRIES = 1   # after this, switch to fallback
+
+# Safe placeholder values used during fallback
+_FALLBACK_DEFAULTS: dict[str, Any] = {
+    "customer":     "Unknown",
+    "item":         "unspecified",
+    "quantity":     0,
+    "amount":       0,
+    "payment_type": None,
+    "reason":       "not provided",
+    "note":         "recovered by fallback",
+}
+
+
+class RecoveryAgent(BaseAgent):
+    """Self-healing agent: retry failed agents, apply fallback, or escalate."""
+
+    name        = "RecoveryAgent"
+    input_keys  = ["verification", "errors", "history", "data", "metadata"]
+    output_keys = ["recovery", "metadata"]
+    action      = "Attempt recovery from pipeline failures"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        verification = context.get("verification", {})
+        v_status     = verification.get("status", "ok")
+        metadata     = context.setdefault("metadata", {})
+        retry_count  = metadata.get("retry_count", 0)
+
+        # ── No recovery needed ───────────────────────────────────────────────
+        if v_status == "ok":
+            context["recovery"] = {
+                "action":      "none",
+                "retry_count": retry_count,
+                "details":     "Verification passed — no recovery needed",
+                "success":     True,
+            }
+            logger.info("[RecoveryAgent] no recovery needed")
+            return context
+
+        # ── Decide recovery strategy ─────────────────────────────────────────
+        if retry_count == 0:
+            action  = "retry"
+            success = self._do_retry(context)
+            details = "Retried failed agents"
+        elif retry_count <= _MAX_RETRIES:
+            action  = "fallback"
+            success = self._do_fallback(context)
+            details = "Applied safe fallback defaults to missing fields"
+        else:
+            action  = "escalate"
+            success = False
+            details = (
+                f"Recovery exhausted after {retry_count} attempt(s). "
+                "Human intervention required."
+            )
+            add_error(context, f"[Recovery] {details}")
+            logger.error("[RecoveryAgent] escalating — recovery exhausted")
+
+        # Increment retry counter
+        metadata["retry_count"] = retry_count + 1
+
+        context["recovery"] = {
+            "action":      action,
+            "retry_count": retry_count + 1,
+            "details":     details,
+            "success":     success,
+        }
+
+        logger.info(
+            "[RecoveryAgent] action=%s retry_count=%d success=%s",
+            action, retry_count + 1, success
+        )
+        return context
+
+    # ── Recovery strategies ──────────────────────────────────────────────────
+
+    def _do_retry(self, context: dict[str, Any]) -> bool:
+        """
+        Re-run agents that errored in the history.
+        Uses the registry to look them up — no direct imports.
+        Returns True if at least one agent recovered successfully.
+        """
+        from app.core.registry import get_agent
+
+        history       = context.get("history", [])
+        errored_agents = [
+            h["agent"] for h in history if h.get("status") == "error"
+        ]
+
+        if not errored_agents:
+            logger.info("[RecoveryAgent] retry: no errored agents found in history")
+            return True
+
+        recovered = 0
+        for agent_name in errored_agents:
+            # Find registry key by matching agent name to class name
+            key = self._name_to_key(agent_name)
+            if not key:
+                logger.warning(
+                    "[RecoveryAgent] retry: cannot find registry key for '%s'",
+                    agent_name
+                )
+                continue
+            try:
+                agent = get_agent(key)
+                context = agent.run(context)
+                logger.info("[RecoveryAgent] retry: '%s' re-ran successfully", agent_name)
+                recovered += 1
+            except Exception as exc:
+                logger.warning(
+                    "[RecoveryAgent] retry: '%s' failed again: %s", agent_name, exc
+                )
+
+        return recovered > 0
+
+    def _do_fallback(self, context: dict[str, Any]) -> bool:
+        """
+        Fill missing critical data fields with safe placeholder values.
+        Returns True always — fallback is best-effort.
+        """
+        data    = context.get("data", {})
+        intent  = (context.get("intent") or "other").lower()
+        filled  = 0
+
+        for field, default in _FALLBACK_DEFAULTS.items():
+            if field in data and data[field] is None:
+                data[field] = default
+                filled += 1
+                logger.info(
+                    "[RecoveryAgent] fallback: set data['%s'] = %r", field, default
+                )
+
+        context["data"] = data
+        logger.info("[RecoveryAgent] fallback: filled %d null field(s)", filled)
+        return True
+
+    @staticmethod
+    def _name_to_key(agent_class_name: str) -> str | None:
+        """Map agent class name → registry key."""
+        mapping = {
+            "IntentAgent":        "intent",
+            "ExtractionAgent":    "extraction",
+            "ValidationAgent":    "validation",
+            "SkillRouterAgent":   "router",
+            "LedgerAgent":        "ledger",
+            "VerificationAgent":  "verification",
+            "MonitorAgent":       "monitor",
+            "PredictionAgent":    "prediction",
+            "UrgencyAgent":       "urgency",
+            "EscalationAgent":    "escalation",
+        }
+        return mapping.get(agent_class_name)

app/agents/skill_router_agent.py

@@ -0,0 +1,53 @@
+"""
+app/agents/skill_router_agent.py
+--------------------------------
+SkillRouterAgent — Stage 4 of the NotiFlow pipeline.
+
+Wraps agent/router.py into the BaseAgent interface.
+Dispatches to the correct business skill based on context["intent"]
+and writes the skill result to context["event"].
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+
+logger = logging.getLogger(__name__)
+
+
+class SkillRouterAgent(BaseAgent):
+    """Route the validated context to the appropriate business skill."""
+
+    name        = "SkillRouterAgent"
+    input_keys  = ["intent", "data"]
+    output_keys = ["event", "invoice", "events", "state"]
+    action      = "Dispatch to business skill and execute"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Dispatch to the correct skill and write result to context["event"].
+
+        Reads context["intent"] and context["data"].
+        Writes context["event"] and transitions state to "routed".
+        """
+        intent = context.get("intent", "other")
+        data   = context.get("data", {})
+
+        try:
+            from app.services.router import route_to_skill
+        except ImportError:
+            from app.services.router import route_to_skill  # type: ignore
+
+        event = route_to_skill(intent, data, context=context)
+        update_context(
+            context,
+            event=event,
+            invoice=event.get("invoice", context.get("invoice")),
+            state="routed",
+        )
+        logger.info("[SkillRouterAgent] event=%s", event.get("event"))
+        return context

app/agents/urgency_agent.py

@@ -0,0 +1,109 @@
+"""
+app/agents/urgency_agent.py
+----------------------------
+UrgencyAgent — Autonomy Layer, Step 4.
+
+Detects urgency signals and contributes to context["priority_score"].
+After accumulating all signals it calls derive_priority_label() which
+derives the final context["priority"] string from the score.
+
+Score contributions:
+    Crisis keyword OR amount > 100k  → +80 points
+    Urgency keyword                  → +50 points
+    Amount > 50k                     → +45 points
+    Risk level == "high"             → +35 points
+    Intent == "other"                → –10 (score stays 0 if nothing else)
+
+Final label derived by derive_priority_label():
+    score > 70  → "high"
+    score > 40  → "medium"
+    score ≤ 40  → "low"
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.priority   import contribute_priority_score, derive_priority_label
+
+logger = logging.getLogger(__name__)
+
+_CRISIS_KEYWORDS = {"emergency", "crisis", "block", "fraud", "chori", "problem"}
+_URGENT_KEYWORDS = {
+    "jaldi", "urgent", "asap", "abhi", "turant", "important",
+    "zaruri", "help", "please", "kal tak", "immediately", "now",
+}
+_CRITICAL_AMOUNT = 100_000
+_HIGH_AMOUNT     = 50_000
+
+
+class UrgencyAgent(BaseAgent):
+    """Detect urgency signals, accumulate priority score, derive final label."""
+
+    name        = "UrgencyAgent"
+    input_keys  = ["message", "data", "intent", "risk", "priority_score"]
+    output_keys = ["priority_score", "priority"]
+    action      = "Accumulate urgency signals into priority score and derive label"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        message    = (context.get("message") or "").lower()
+        data       = context.get("data", {})
+        intent     = (context.get("intent") or "other").lower()
+        risk       = context.get("risk", {})
+        words      = set(message.split())
+        amount     = self._safe_amount(data.get("amount"))
+        risk_level = risk.get("level", "low")
+
+        # ── Contribute scores for each signal ────────────────────────────────
+        if words & _CRISIS_KEYWORDS:
+            matched = words & _CRISIS_KEYWORDS
+            contribute_priority_score(
+                context, 80,
+                f"Crisis keyword(s) detected: {', '.join(matched)}"
+            )
+
+        if amount is not None and amount > _CRITICAL_AMOUNT:
+            contribute_priority_score(
+                context, 80,
+                f"Amount ₹{amount:,.0f} exceeds critical threshold ({_CRITICAL_AMOUNT:,})"
+            )
+
+        if words & _URGENT_KEYWORDS:
+            matched = words & _URGENT_KEYWORDS
+            contribute_priority_score(
+                context, 50,
+                f"Urgency keyword(s): {', '.join(matched)}"
+            )
+
+        if amount is not None and _HIGH_AMOUNT < amount <= _CRITICAL_AMOUNT:
+            contribute_priority_score(
+                context, 45,
+                f"Amount ₹{amount:,.0f} exceeds high threshold ({_HIGH_AMOUNT:,})"
+            )
+
+        if risk_level == "high":
+            contribute_priority_score(context, 35, "Risk level is high")
+
+        # Store urgency reason for escalation agent to read
+        score = context.get("priority_score", 0)
+        context.setdefault("metadata", {})["urgency_reason"] = (
+            f"priority_score={score}"
+        )
+
+        # ── Derive final label from accumulated score ─────────────────────────
+        label = derive_priority_label(context)
+        logger.info(
+            "[UrgencyAgent] score=%d → priority=%s", score, label
+        )
+        return context
+
+    @staticmethod
+    def _safe_amount(value: Any) -> float | None:
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except (ValueError, TypeError):
+            return None

app/agents/validation_agent.py

@@ -0,0 +1,53 @@
+"""
+app/agents/validation_agent.py
+------------------------------
+ValidationAgent — Stage 3 of the NotiFlow pipeline.
+
+Wraps validators/data_validator.py into the BaseAgent interface.
+Normalises numbers, text, and payment aliases in context["data"].
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+from app.core.context import update_context
+
+logger = logging.getLogger(__name__)
+
+
+class ValidationAgent(BaseAgent):
+    """Normalise and validate extracted business data."""
+
+    name        = "ValidationAgent"
+    input_keys  = ["intent", "data"]
+    output_keys = ["data", "state"]
+    action      = "Normalise numbers, text, and payment aliases"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Validate context["data"] in-place and transition state to "validated".
+
+        Reads context["intent"] and context["data"].
+        Writes cleaned data back to context["data"].
+        """
+        intent = context.get("intent", "other")
+        raw    = context.get("data", {})
+
+        try:
+            # Import path works regardless of old vs new layout
+            try:
+                from app.validators.data_validator import validate_data
+            except ImportError:
+                from app.validators.data_validator import validate_data
+
+            validated = validate_data(intent, raw)
+        except Exception as exc:
+            logger.warning("[ValidationAgent] validation error (%s) — using raw data", exc)
+            validated = raw
+
+        update_context(context, data=validated, state="validated")
+        logger.info("[ValidationAgent] validated data for intent '%s'", intent)
+        return context

app/agents/verification_agent.py

@@ -0,0 +1,128 @@
+"""
+app/agents/verification_agent.py
+---------------------------------
+VerificationAgent — Autonomy Layer, Step 1.
+
+Validates that the skill execution produced the expected output.
+Reads context["intent"] and context["event"], writes context["verification"].
+
+Output shape written to context["verification"]:
+    {
+        "status":     "ok" | "fail" | "partial",
+        "confidence": 0.0 – 1.0,
+        "checks":     list[str],   # human-readable check results
+        "reason":     str,         # summary
+    }
+
+Never raises — failures are recorded as verification["status"] = "fail".
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+# Expected event name per intent
+_EXPECTED_EVENTS: dict[str, str] = {
+    "order":       "order_received",
+    "payment":     "payment_recorded",
+    "credit":      "credit_recorded",
+    "return":      "return_requested",
+    "preparation": "preparation_queued",
+}
+
+# Required fields inside event sub-dict per intent
+_REQUIRED_FIELDS: dict[str, dict[str, list[str]]] = {
+    "order":       {"order":   ["order_id", "item", "status"]},
+    "payment":     {"payment": ["customer", "amount", "status"]},
+    "credit":      {"credit":  ["customer", "status"]},
+    "return":      {"return":  ["return_id", "status"]},
+    "preparation": {"preparation": ["prep_id", "status"]},
+}
+
+
+class VerificationAgent(BaseAgent):
+    """Validate that the pipeline produced a complete, expected result."""
+
+    name        = "VerificationAgent"
+    input_keys  = ["intent", "event", "data"]
+    output_keys = ["verification"]
+    action      = "Verify skill execution produced expected output"
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        intent = (context.get("intent") or "other").lower()
+        event  = context.get("event", {})
+        checks: list[str] = []
+        passed = 0
+        total  = 0
+
+        # ── Check 1: event exists ────────────────────────────────────────────
+        total += 1
+        if event:
+            checks.append("✓ event dict is non-empty")
+            passed += 1
+        else:
+            checks.append("✗ event dict is empty")
+
+        # ── Check 2: correct event name ──────────────────────────────────────
+        expected_event = _EXPECTED_EVENTS.get(intent)
+        if expected_event:
+            total += 1
+            actual_event = event.get("event", "")
+            if actual_event == expected_event:
+                checks.append(f"✓ event name '{actual_event}' matches expected")
+                passed += 1
+            else:
+                checks.append(
+                    f"✗ event name '{actual_event}' != expected '{expected_event}'"
+                )
+
+        # ── Check 3: required sub-dict fields present ────────────────────────
+        required_map = _REQUIRED_FIELDS.get(intent, {})
+        for sub_key, fields in required_map.items():
+            sub = event.get(sub_key, {})
+            for field in fields:
+                total += 1
+                if sub.get(field) is not None:
+                    checks.append(f"✓ {sub_key}.{field} present")
+                    passed += 1
+                else:
+                    checks.append(f"✗ {sub_key}.{field} missing or null")
+
+        # ── Check 4: data fields not all null ────────────────────────────────
+        total += 1
+        data = context.get("data", {})
+        non_null = sum(1 for v in data.values() if v is not None)
+        if non_null > 0:
+            checks.append(f"✓ data has {non_null} non-null field(s)")
+            passed += 1
+        else:
+            checks.append("✗ all data fields are null")
+
+        # ── Compute confidence and status ────────────────────────────────────
+        confidence = round(passed / total, 2) if total > 0 else 0.0
+
+        if confidence >= 0.85:
+            status = "ok"
+        elif confidence >= 0.5:
+            status = "partial"
+        else:
+            status = "fail"
+
+        verification = {
+            "status":     status,
+            "confidence": confidence,
+            "checks":     checks,
+            "reason":     f"{passed}/{total} checks passed",
+        }
+
+        context["verification"] = verification
+        logger.info(
+            "[VerificationAgent] status=%s confidence=%.2f (%s)",
+            status, confidence, verification["reason"]
+        )
+        return context

app/api/__init__.py

@@ -0,0 +1 @@
+"""app/api — FastAPI routers."""

app/api/notification_routes.py

@@ -0,0 +1,387 @@
+"""
+api/notification_routes.py
+--------------------------
+FastAPI router for Notiflow notification endpoints.
+
+Phase 5: API now calls process_message() directly (the new multi-agent
+orchestrator) instead of run_notiflow(). Returns the full result including
+intents, multi_data, priority, risk, and alerts.
+
+Backward compatibility: all original fields (message, intent, data, event,
+source, sheet_updated, model) are still present in the response.
+
+Endpoints
+---------
+POST /api/notification
+    Receives a notification, runs the full agent pipeline,
+    returns the structured orchestrator result.
+
+GET  /api/notifications/generate
+    Calls Gemini to generate a batch of demo notifications.
+    Query param: n (default 5)
+
+WebSocket /ws/notifications
+    Streams live notifications to connected clients.
+    Accepts both frontend-pushed and Gemini-generated events.
+    Broadcasts to all connected clients.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, Query, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from app.core.event_bus import (
+    confirm_invoice_payment,
+    emit_global_event,
+    get_events_since,
+    get_latest_event_sequence,
+    get_logs,
+    push_live_log,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Request model
+# ---------------------------------------------------------------------------
+
+from pydantic import BaseModel
+
+
+class NotificationRequest(BaseModel):
+    """Incoming notification payload."""
+    source:  str = "system"   # e.g. "whatsapp", "amazon", "payment", "return"
+    message: str              # Raw Hinglish business message
+
+
+class PaymentConfirmRequest(BaseModel):
+    invoice_id: str
+
+
+# ---------------------------------------------------------------------------
+# WebSocket connection manager
+# ---------------------------------------------------------------------------
+
+class _ConnectionManager:
+    """Simple in-memory broadcast manager for WebSocket clients."""
+
+    def __init__(self):
+        self._active: list[WebSocket] = []
+
+    async def connect(self, ws: WebSocket) -> None:
+        await ws.accept()
+        self._active.append(ws)
+        logger.info("WS client connected. Total: %d", len(self._active))
+
+    def disconnect(self, ws: WebSocket) -> None:
+        self._active = [c for c in self._active if c is not ws]
+        logger.info("WS client disconnected. Total: %d", len(self._active))
+
+    async def broadcast(self, payload: dict) -> None:
+        """Send JSON payload to all connected WebSocket clients."""
+        dead = []
+        for ws in self._active:
+            try:
+                await ws.send_json(payload)
+            except Exception:
+                dead.append(ws)
+        for ws in dead:
+            self.disconnect(ws)
+
+
+_manager = _ConnectionManager()
+
+
+# ---------------------------------------------------------------------------
+# Internal: run the pipeline and build the API response dict
+# ---------------------------------------------------------------------------
+
+def _run_pipeline(message: str, source: str) -> dict[str, Any]:
+    """
+    Run the full multi-agent pipeline via process_message() and return
+    a flat API response dict that includes both legacy and new fields.
+    """
+    from app.core.orchestrator import process_message
+
+    result = process_message(message.strip(), source=source)
+
+    # Strip the raw context from the response (keep it lightweight for API)
+    ctx = result.pop("context", {})
+
+    # Determine model tag
+    event_str  = str(result.get("event", {}).get("event", ""))
+    is_live    = any(event_str.endswith(sfx)
+                     for sfx in ("_recorded", "_received", "_requested", "_queued"))
+    model_tag  = "live" if is_live else "demo"
+
+    return {
+        # ── Backward-compatible core fields ──────────────────────────────
+        "message":       result["message"],
+        "intent":        result.get("intent", "other"),
+        "data":          result.get("data", {}),
+        "event":         result.get("event", {}),
+        "invoice":       result.get("invoice"),
+        "events":        result.get("events", []),
+        "live_logs":     result.get("live_logs", []),
+        "history":       result.get("history", ctx.get("history", [])),
+        "customer":      result.get("customer", {}),
+        "order":         result.get("order", {}),
+        "payment":       result.get("payment", {}),
+        "decision":      result.get("decision", {}),
+        "source":        source,
+        "sheet_updated": result.get("sheet_updated", False),
+        "model":         model_tag,
+        # ── Phase 5: multi-intent fields ─────────────────────────────────
+        "intents":       result.get("intents", [result.get("intent", "other")]),
+        "multi_data":    result.get("multi_data", {}),
+        # ── Autonomy fields ───────────────────────────────────────────────
+        "priority":      result.get("priority", "low"),
+        "priority_score": result.get("priority_score", 0),
+        "risk":          result.get("risk", {}),
+        "alerts":        result.get("alerts", []),
+        "verification":  result.get("verification", {}),
+        "recovery":      result.get("recovery", {}),
+        "monitor":       result.get("monitor", {}),
+    }
+
+
+async def _broadcast_pipeline_response(response: dict[str, Any]) -> None:
+    await _manager.broadcast({"type": "pipeline_result", "data": response})
+    for event in response.get("events", []):
+        await _manager.broadcast({"type": "domain_event", "event": event})
+
+
+# ---------------------------------------------------------------------------
+# POST /api/notification
+# ---------------------------------------------------------------------------
+
+@router.post("/api/notification")
+async def process_notification(body: NotificationRequest):
+    """
+    Receive a business notification and run the full Notiflow pipeline.
+
+    Uses process_message() from app.core.orchestrator — the new multi-agent
+    system with dynamic planner, autonomy planner, and multi-intent support.
+
+    After processing, the result is broadcast to all connected WebSocket
+    clients so the live stream panel updates in real time.
+
+    Args:
+        body: {"source": "whatsapp", "message": "bhaiya 3 kurti bhej dena"}
+
+    Returns:
+        Full orchestrator result including intents, multi_data, priority, risk.
+    """
+    if not body.message or not body.message.strip():
+        raise HTTPException(status_code=422, detail="Message cannot be empty.")
+
+    logger.info(
+        "POST /api/notification | source=%s | msg=%r",
+        body.source, body.message
+    )
+    print("🔥 RECEIVED MESSAGE:", body.message)
+
+    try:
+        response = _run_pipeline(body.message.strip(), body.source)
+    except Exception as exc:
+        logger.error("Pipeline error: %s", exc)
+        raise HTTPException(status_code=500, detail=f"Pipeline error: {exc}")
+
+    # Broadcast full result to WebSocket clients
+    await _broadcast_pipeline_response(response)
+
+    return response
+
+
+@router.get("/api/stream/logs")
+async def stream_logs(limit: int = Query(default=200, ge=1, le=500)):
+    return {"logs": get_logs(limit)}
+
+
+@router.get("/api/stream/events")
+async def stream_events(request: Request):
+    async def event_generator():
+        last_sequence = max(0, get_latest_event_sequence() - 20)
+        while True:
+            if await request.is_disconnected():
+                break
+
+            events = get_events_since(last_sequence)
+            for event in events:
+                last_sequence = max(last_sequence, int(event.get("sequence", 0)))
+                yield f"data: {json.dumps(event)}\n\n"
+
+            await asyncio.sleep(0.25)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.post("/api/payment/confirm")
+async def confirm_payment(body: PaymentConfirmRequest):
+    invoice_id = body.invoice_id.strip()
+    if not invoice_id:
+        raise HTTPException(status_code=422, detail="invoice_id is required")
+
+    from app.utils.excel_writer import append_row
+
+    invoice = confirm_invoice_payment(invoice_id)
+    if invoice is None:
+        raise HTTPException(status_code=404, detail=f"Invoice not found: {invoice_id}")
+
+    payment_entry = {
+        "entry_id": f"PAY-{invoice_id}",
+        "timestamp": invoice.get("timestamp"),
+        "type": "payment",
+        "customer": invoice.get("customer"),
+        "item": invoice.get("item"),
+        "quantity": invoice.get("quantity"),
+        "amount": invoice.get("total") or invoice.get("total_amount"),
+        "payment_type": "manual",
+        "status": "received",
+    }
+    append_row("Ledger", payment_entry)
+
+    payment_log = push_live_log(None, {
+        "agent": "PaymentAPI",
+        "status": "success",
+        "action": f"Payment confirmed for {invoice_id}",
+        "detail": f"[PaymentAPI] Payment confirmed: {invoice_id}",
+    })
+    event = emit_global_event(
+        "payment_completed",
+        invoice,
+        agent="PaymentAPI",
+        step="payment",
+        message=f"Payment confirmed for {invoice_id}",
+        log_entry=payment_log,
+    )
+
+    response = {
+        "invoice": invoice,
+        "payment": {
+            "invoice_id": invoice.get("invoice_id"),
+            "amount": invoice.get("total") or invoice.get("total_amount"),
+            "status": "paid",
+        },
+        "event": event,
+    }
+    await _manager.broadcast({"type": "domain_event", "event": event})
+    return response
+
+
+# ---------------------------------------------------------------------------
+# GET /api/notifications/generate
+# ---------------------------------------------------------------------------
+
+@router.get("/api/notifications/generate")
+async def generate_demo_notifications(n: int = Query(default=5, ge=1, le=20)):
+    """
+    Generate n demo notifications using Gemini (or static fallback).
+
+    Query params:
+        n: number of notifications to generate (1-20, default 5)
+
+    Returns:
+        {"notifications": [{"source": str, "message": str}, ...]}
+    """
+    from app.services.notification_generator import get_notifications
+    notifications = get_notifications(n)
+    return {"notifications": notifications}
+
+
+# ---------------------------------------------------------------------------
+# WebSocket /ws/notifications
+# ---------------------------------------------------------------------------
+
+@router.websocket("/ws/notifications")
+async def websocket_notification_stream(websocket: WebSocket):
+    """
+    WebSocket endpoint for real-time notification streaming.
+
+    Clients connect and receive:
+      - Notifications pushed by the frontend simulation
+      - Notifications generated by Gemini automation
+      - Results of processed notifications (broadcast from POST endpoint)
+
+    The client can also SEND a notification over the WebSocket:
+        {"source": "whatsapp", "message": "bhaiya 3 kurti bhej dena"}
+
+    The server will process it through the pipeline and broadcast the
+    result to all connected clients.
+
+    Protocol:
+        Client → Server:  {"source": str, "message": str}
+        Server → Client:  Full pipeline result JSON (same shape as POST response)
+    """
+    await _manager.connect(websocket)
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            try:
+                payload = json.loads(raw)
+                source  = payload.get("source", "websocket")
+                message = payload.get("message", "").strip()
+
+                if not message:
+                    await websocket.send_json({"error": "Empty message"})
+                    continue
+
+                response = _run_pipeline(message, source)
+                await _broadcast_pipeline_response(response)
+
+            except json.JSONDecodeError:
+                await websocket.send_json({"error": "Invalid JSON payload"})
+            except Exception as exc:
+                logger.error("WS pipeline error: %s", exc)
+                await websocket.send_json({"error": str(exc)})
+
+    except WebSocketDisconnect:
+        _manager.disconnect(websocket)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/stream/start
+# ---------------------------------------------------------------------------
+
+@router.get("/api/stream/start")
+async def start_gemini_stream(
+    n:     int   = Query(default=5,   ge=1,  le=20),
+    delay: float = Query(default=2.0, ge=0.5, le=30.0),
+):
+    """
+    Trigger Gemini to generate n notifications and stream them to all
+    connected WebSocket clients with a delay between each.
+
+    Query params:
+        n:     number of notifications (default 5)
+        delay: seconds between each broadcast (default 2.0)
+
+    This runs in the background — the HTTP response returns immediately.
+    """
+    async def _stream():
+        from app.services.notification_generator import stream_notifications
+        async for notification in stream_notifications(n=n, delay_seconds=delay):
+            await _manager.broadcast({
+                "type":    "incoming_notification",
+                "source":  notification["source"],
+                "message": notification["message"],
+            })
+
+    asyncio.create_task(_stream())
+    return {"status": "streaming started", "n": n, "delay_seconds": delay}

app/config.py

@@ -0,0 +1,100 @@
+"""
+app/config.py
+-------------
+Central configuration for NotiFlow Autonomous.
+
+All file paths, feature flags, and model settings live here.
+Every other module imports from this file — no hardcoded paths elsewhere.
+
+CHANGED from original:
+  - Removed: BEDROCK_REGION, BEDROCK_MODEL_ID (AWS Bedrock fully removed)
+  - Added:   NVIDIA_NIM_API_KEY, NVIDIA_NIM_BASE_URL, NVIDIA_NIM_MODEL
+"""
+
+import os
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Project root
+# ---------------------------------------------------------------------------
+
+ROOT = Path(__file__).parent.parent   # notiflow/
+
+# ---------------------------------------------------------------------------
+# Data paths
+# ---------------------------------------------------------------------------
+
+DATA_DIR      = ROOT / "data"
+DATA_FILE     = DATA_DIR / "notiflow_data.xlsx"
+MEMORY_FILE   = DATA_DIR / "agent_memory.json"
+REGISTRY_FILE = ROOT / "skills" / "skill_registry.json"
+
+# ---------------------------------------------------------------------------
+# Feature flags
+# ---------------------------------------------------------------------------
+
+NOTIFLOW_DEMO_MODE = os.getenv("NOTIFLOW_DEMO_MODE", "true").lower() == "true"
+DEMO_MODE = NOTIFLOW_DEMO_MODE  # legacy alias
+
+# ---------------------------------------------------------------------------
+# NVIDIA NIM settings  (replaces AWS Bedrock)
+# ---------------------------------------------------------------------------
+
+NVIDIA_NIM_API_KEY : str | None = (
+    os.getenv("NVIDIA_NIM_API_KEY") or os.getenv("NVIDIA_API_KEY")
+)
+NVIDIA_NIM_BASE_URL: str        = (
+    os.getenv("NVIDIA_NIM_BASE_URL")
+    or os.getenv("NIM_BASE_URL")
+    or "https://integrate.api.nvidia.com/v1"
+)
+# Legacy single-model override (Phase 1-3 compat)
+NVIDIA_NIM_MODEL   : str        = os.getenv(
+    "NVIDIA_NIM_MODEL", "deepseek-ai/deepseek-v3.2"
+)
+# Phase 4: per-role model routing
+NIM_PRIMARY_MODEL  : str        = os.getenv(
+    "NIM_PRIMARY_MODEL",  "deepseek-ai/deepseek-v3.2"
+)
+NIM_FALLBACK_MODEL : str        = os.getenv(
+    "NIM_FALLBACK_MODEL", "deepseek-ai/deepseek-v3.1"
+)
+
+# ---------------------------------------------------------------------------
+# OpenRouter settings  (Phase 4 fallback)
+# ---------------------------------------------------------------------------
+
+OPENROUTER_API_KEY : str | None = os.getenv("OPENROUTER_API_KEY")
+OPENROUTER_MODEL   : str        = os.getenv(
+    "OPENROUTER_MODEL", "deepseek/deepseek-chat"
+)
+OPENROUTER_REFERER : str        = os.getenv("OPENROUTER_REFERER", "")
+OPENROUTER_TITLE   : str        = os.getenv("OPENROUTER_TITLE",   "NotiFlow")
+
+# ---------------------------------------------------------------------------
+# Gemini settings  (fallback)
+# ---------------------------------------------------------------------------
+
+GEMINI_API_KEY: str | None = os.getenv("GEMINI_API_KEY")
+
+# ---------------------------------------------------------------------------
+# Excel sync path
+# ---------------------------------------------------------------------------
+
+_env_excel      = os.getenv("EXCEL_FILE_PATH")
+EXCEL_SYNC_FILE = Path(_env_excel) if _env_excel else DATA_FILE
+
+# ---------------------------------------------------------------------------
+# Google Sheets settings
+# ---------------------------------------------------------------------------
+
+GOOGLE_SHEETS_CREDENTIALS: str = os.getenv(
+    "GOOGLE_SHEETS_CREDENTIALS", "credentials/sheets.json"
+)
+GOOGLE_SHEET_ID: str = os.getenv("GOOGLE_SHEET_ID", "")
+
+# ---------------------------------------------------------------------------
+# Ensure data directory exists at import time
+# ---------------------------------------------------------------------------
+
+DATA_DIR.mkdir(parents=True, exist_ok=True)

app/core/__init__.py

@@ -0,0 +1,21 @@
+"""app/core — NotiFlow core primitives."""
+
+from app.core.llm_service      import LLMService, get_llm
+from app.core.llm_router       import route_llm, ModelEntry
+from app.core.context          import create_context, update_context, log_step, add_error
+from app.core.base_agent       import BaseAgent
+from app.core.planner          import build_plan, PlanRule
+from app.core.autonomy_planner import build_autonomy_plan, AutonomyRule
+from app.core.priority         import contribute_priority_score, derive_priority_label, reset_priority_score
+from app.core.registry         import get_agent, register, list_agents, AGENT_REGISTRY
+
+__all__ = [
+    "LLMService", "get_llm",
+    "route_llm", "ModelEntry",
+    "create_context", "update_context", "log_step", "add_error",
+    "BaseAgent",
+    "build_plan", "PlanRule",
+    "build_autonomy_plan", "AutonomyRule",
+    "contribute_priority_score", "derive_priority_label", "reset_priority_score",
+    "get_agent", "register", "list_agents", "AGENT_REGISTRY",
+]

app/core/autonomy_planner.py

@@ -0,0 +1,161 @@
+"""
+app/core/autonomy_planner.py
+-----------------------------
+Dynamic Autonomy Planner for NotiFlow Autonomous.
+
+Mirrors the design of app/core/planner.py but governs the autonomy layer.
+Each rule has a condition that can skip agents based on context state,
+avoiding unnecessary work (e.g. skip escalation if priority is low,
+skip recovery if verification already passed).
+
+Extending
+---------
+To add a new autonomy step:
+    1. Create app/agents/my_autonomy_agent.py
+    2. Register it in app/core/registry.py
+    3. Append one AutonomyRule here — zero other changes needed
+
+Public API
+----------
+build_autonomy_plan(context) -> list[dict]
+    Evaluates rules, writes context["autonomy_plan"], returns the plan.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+# ---------------------------------------------------------------------------
+# Rule definition (same pattern as PlanRule in planner.py)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AutonomyRule:
+    """
+    A single conditional step in the autonomy execution plan.
+
+    Attributes:
+        agent:       Registry key of the agent to run.
+        condition:   callable(ctx) → bool — True means include this agent.
+        description: Human-readable reason (written to autonomy_plan entries).
+    """
+    agent:       str
+    condition:   Callable[[dict[str, Any]], bool]
+    description: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Condition functions
+# ---------------------------------------------------------------------------
+
+def _always(ctx: dict[str, Any]) -> bool:
+    return True
+
+
+def _skip_if_verified(ctx: dict[str, Any]) -> bool:
+    """Skip monitor if verification already passed cleanly — nothing to flag."""
+    v = ctx.get("verification", {})
+    return v.get("status") != "ok"
+
+
+def _skip_if_no_data(ctx: dict[str, Any]) -> bool:
+    """Skip prediction if there is no data to score."""
+    return bool(ctx.get("data"))
+
+
+def _skip_if_low_score(ctx: dict[str, Any]) -> bool:
+    """Skip urgency if priority score is already 0 and intent is 'other'."""
+    intent = (ctx.get("intent") or "other").lower()
+    if intent == "other" and ctx.get("priority_score", 0) == 0:
+        return False   # nothing will change — skip
+    return True
+
+
+def _escalation_needed(ctx: dict[str, Any]) -> bool:
+    """
+    Only run escalation if priority is high/critical OR risk is high.
+    Avoids noisy alert logs on routine transactions.
+    """
+    priority = (ctx.get("priority") or "normal").lower()
+    risk     = ctx.get("risk", {}).get("level", "low")
+    return priority in ("high", "critical") or risk == "high"
+
+
+def _recovery_needed(ctx: dict[str, Any]) -> bool:
+    """
+    Run recovery only if something actually went wrong.
+    Skipped if verification passed and no errors exist.
+    """
+    v_status = ctx.get("verification", {}).get("status", "ok")
+    errors   = ctx.get("errors", [])
+    return v_status != "ok" or len(errors) > 0
+
+
+# ---------------------------------------------------------------------------
+# Rule set  (order matters — this IS the autonomy pipeline definition)
+# ---------------------------------------------------------------------------
+
+_AUTONOMY_RULES: list[AutonomyRule] = [
+    AutonomyRule(
+        agent       = "verification",
+        condition   = _always,
+        description = "Validate skill execution produced expected output",
+    ),
+    AutonomyRule(
+        agent       = "monitor",
+        condition   = _skip_if_verified,
+        description = "Scan for missing fields, errors, and inconsistencies",
+    ),
+    AutonomyRule(
+        agent       = "prediction",
+        condition   = _skip_if_no_data,
+        description = "Rule-based risk scoring on extracted data",
+    ),
+    AutonomyRule(
+        agent       = "urgency",
+        condition   = _skip_if_low_score,
+        description = "Detect urgency signals and derive final priority label",
+    ),
+    AutonomyRule(
+        agent       = "escalation",
+        condition   = _escalation_needed,
+        description = "Raise alerts for high-priority or high-risk situations",
+    ),
+    AutonomyRule(
+        agent       = "recovery",
+        condition   = _recovery_needed,
+        description = "Attempt self-healing for pipeline failures",
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def build_autonomy_plan(context: dict[str, Any]) -> list[dict[str, Any]]:
+    """
+    Evaluate autonomy rules against the current context.
+
+    Writes the plan to context["autonomy_plan"] and returns it.
+
+    Args:
+        context: The live request context dict (after main pipeline ran).
+
+    Returns:
+        Ordered list of autonomy steps, each a dict:
+            {
+                "agent":       str,   # registry key
+                "description": str,   # human-readable reason
+            }
+    """
+    plan = []
+    for rule in _AUTONOMY_RULES:
+        if rule.condition(context):
+            plan.append({
+                "agent":       rule.agent,
+                "description": rule.description,
+            })
+    context["autonomy_plan"] = plan
+    return plan

app/core/base_agent.py

@@ -0,0 +1,122 @@
+"""
+app/core/base_agent.py
+----------------------
+BaseAgent — the standard interface for all NotiFlow agents.
+
+Every agent in the system inherits from BaseAgent and implements `execute()`.
+The public `run()` method provides:
+    - unified error handling
+    - structured logging into context["history"]
+    - state transition on success / failure
+
+Usage
+-----
+class MyAgent(BaseAgent):
+    name = "MyAgent"
+
+    def execute(self, context: dict) -> dict:
+        # do work, mutate context, return it
+        context["data"]["my_field"] = "value"
+        return context
+
+result_ctx = MyAgent().run(context)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.context import log_step, add_error, update_context
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent:
+    """
+    Abstract base for all NotiFlow agents.
+
+    Subclasses must:
+        - Set a class-level ``name`` attribute
+        - Implement ``execute(context) -> dict``
+
+    Optional class-level audit declarations (used in history logs):
+        input_keys  : list[str]  — context keys this agent reads
+        output_keys : list[str]  — context keys this agent writes
+        action      : str        — one-line description of what the agent does
+
+    The ``run()`` wrapper handles logging and error isolation automatically.
+    Agents should raise exceptions from ``execute()`` on unrecoverable errors;
+    for soft/non-fatal issues they should call ``add_error(ctx, msg)`` and
+    continue.
+    """
+
+    #: Human-readable agent identifier used in logs and history.
+    name: str = "BaseAgent"
+
+    #: Audit metadata — override in subclasses for richer logs
+    input_keys:  list[str] = []
+    output_keys: list[str] = []
+    action:      str       = ""
+
+    def run(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Execute the agent with full error handling and audit logging.
+
+        This is the ONLY method callers should invoke externally.
+
+        Args:
+            context: The live request context dict.
+
+        Returns:
+            The (mutated) context dict.
+
+        Raises:
+            Exception: Re-raises any exception from execute() so the
+                       orchestrator can decide whether to abort.
+        """
+        logger.info("[%s] starting", self.name)
+        try:
+            context = self.execute(context)
+            log_step(
+                context,
+                self.name,
+                "success",
+                action      = self.action or f"{self.name} completed",
+                input_keys  = list(self.input_keys),
+                output_keys = list(self.output_keys),
+            )
+            logger.info("[%s] completed successfully", self.name)
+        except Exception as exc:
+            error_msg = f"{self.name} failed: {exc}"
+            logger.error(error_msg, exc_info=True)
+            add_error(context, error_msg)
+            log_step(
+                context,
+                self.name,
+                "error",
+                str(exc),
+                action      = self.action or f"{self.name} failed",
+                input_keys  = list(self.input_keys),
+                output_keys = [],
+            )
+            update_context(context, state="failed")
+            raise
+        return context
+
+    def execute(self, context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Agent-specific logic. Subclasses MUST override this method.
+
+        Args:
+            context: The live request context dict.
+
+        Returns:
+            The mutated context dict.
+
+        Raises:
+            NotImplementedError: If subclass does not implement this.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement execute(context)."
+        )

app/core/config_bridge.py

@@ -0,0 +1,6 @@
+"""
+app/config.py is the authoritative config.
+This file at the project root ensures `from app.config import X` works
+when the project root is on sys.path (which backend/main.py guarantees).
+"""
+# Nothing needed — app/config.py is already at app/config.py

app/core/context.py

@@ -0,0 +1,169 @@
+"""
+app/core/context.py
+-------------------
+Unified request context for NotiFlow Autonomous.
+
+The context object is the single source of truth for every request.
+It is created at the API boundary, threaded through every agent, and
+returned to the caller as part of the final response.
+
+Structure
+---------
+{
+    "message":   str,           # original raw message
+    "intent":    str | None,    # detected intent (filled by IntentAgent)
+    "data":      dict,          # extracted + validated fields
+    "event":     dict,          # skill execution result
+    "state":     str,           # pipeline lifecycle state
+    "history":   list[dict],    # audit-level agent execution log  ← UPGRADED
+    "errors":    list[str],     # non-fatal errors accumulated during run
+    "priority":              str,           # "low" | "medium" | "high" (derived by UrgencyAgent)
+    "priority_score":        int,           # additive score 0-100 (contributed by multiple agents)
+    "priority_score_reasons": list[dict],  # audit trail of score contributions
+    "plan":          list[dict],   # ordered main plan steps (set by Planner)
+    "autonomy_plan": list[dict],   # ordered autonomy steps (set by AutonomyPlanner)
+    "metadata":  dict,          # source, sheet_updated, model, etc.
+}
+
+History entry shape (audit-ready):
+    {
+        "agent":       str,       # agent name
+        "action":      str,       # what the agent did (human-readable)
+        "input_keys":  list[str], # context keys read by this agent
+        "output_keys": list[str], # context keys written by this agent
+        "status":      str,       # "success" | "error" | "skipped"
+        "detail":      str,       # error message or extra note
+        "timestamp":   str,       # ISO-8601 UTC
+    }
+
+Pipeline states:
+    initialized → intent_detected → extracted → validated → routed → completed
+    Any stage can transition to: failed
+
+Public API (unchanged from Phase 1 — fully backward compatible)
+----------
+create_context(message, source) -> dict
+update_context(ctx, **kwargs)   -> dict
+log_step(ctx, agent, status, detail, *, action, input_keys, output_keys) -> None
+add_error(ctx, error) -> None
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from app.core.event_bus import push_live_log
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def create_context(message: str, source: str = "system") -> dict[str, Any]:
+    """
+    Create a fresh request context for a new message.
+
+    Args:
+        message: Raw business message (Hinglish or English).
+        source:  Notification source (e.g. "whatsapp", "gpay").
+
+    Returns:
+        Fully initialised context dict.
+    """
+    return {
+        "message":  message.strip(),
+        "source":   source,
+        # ── Intent (Phase 5: multi-intent) ────────────────────────────────
+        "intents":  [],     # all detected intents, ordered (set by IntentAgent)
+        "intent":   None,   # primary intent = intents[0] — kept for backward compat
+        # ── Extraction ────────────────────────────────────────────────────
+        "multi_data": {},   # per-intent extracted fields {intent_name: {fields}}
+        "data":     {},     # primary intent extraction — kept for backward compat
+        "event":    {},
+        "invoice":  None,
+        "payment":  None,
+        "events":   [],
+        "live_logs": [],
+        "state":    "initialized",
+        "history":  [],
+        "errors":   [],
+        "priority": "normal",           # final derived label (set by UrgencyAgent)
+        "priority_score": 0,            # additive score 0-100 (Phase 3 fix)
+        "priority_score_reasons": [],   # audit trail of score contributions
+        # plan is [] until Planner fills it; list[dict] in Phase 2
+        "plan":          [],
+        "autonomy_plan": [],            # filled by autonomy_planner
+        "metadata": {
+            "source":        source,
+            "sheet_updated": False,
+            "model":         None,
+            "retry_count":   0,         # replan loop counter
+            "created_at":    datetime.now(timezone.utc).isoformat(),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Mutators
+# ---------------------------------------------------------------------------
+
+def update_context(ctx: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+    """
+    Apply keyword updates to the context (in-place, returns ctx).
+
+    Supports double-underscore for nested dicts:
+        update_context(ctx, metadata__source="whatsapp")
+        update_context(ctx, intent="order", state="intent_detected")
+    """
+    for key, value in kwargs.items():
+        if "__" in key:
+            parent, child = key.split("__", 1)
+            if parent in ctx and isinstance(ctx[parent], dict):
+                ctx[parent][child] = value
+        else:
+            ctx[key] = value
+    return ctx
+
+
+def log_step(
+    ctx:         dict[str, Any],
+    agent:       str,
+    status:      str,
+    detail:      str = "",
+    *,
+    action:      str = "",
+    input_keys:  list[str] | None = None,
+    output_keys: list[str] | None = None,
+) -> None:
+    """
+    Append an audit-level execution entry to context["history"].
+
+    Backward compatible: the original 4-arg signature still works.
+    New callers can supply keyword-only audit fields for richer logs.
+
+    Args:
+        ctx:         The active context dict.
+        agent:       Agent name (e.g. "IntentAgent").
+        status:      "success" | "error" | "skipped".
+        detail:      Error message or human-readable note.
+        action:      What the agent did (e.g. "classified intent as payment").
+        input_keys:  Context keys the agent READ  (e.g. ["message"]).
+        output_keys: Context keys the agent WROTE (e.g. ["intent", "state"]).
+    """
+    entry = {
+        "agent":       agent,
+        "action":      action or f"{agent} executed",
+        "input_keys":  input_keys  or [],
+        "output_keys": output_keys or [],
+        "status":      status,
+        "detail":      detail,
+        "timestamp":   datetime.now(timezone.utc).isoformat(),
+    }
+    ctx["history"].append(entry)
+    push_live_log(ctx, entry)
+
+
+def add_error(ctx: dict[str, Any], error: str) -> None:
+    """Record a non-fatal error in context["errors"]."""
+    ctx["errors"].append(error)

app/core/event_bus.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from collections import deque
+from copy import deepcopy
+from datetime import datetime, timezone
+from typing import Any
+
+_LOG_BUFFER: deque[dict[str, Any]] = deque(maxlen=500)
+_EVENT_BUFFER: deque[dict[str, Any]] = deque(maxlen=200)
+_INVOICE_STORE: dict[str, dict[str, Any]] = {}
+_EVENT_SEQ = 0
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _make_id(prefix: str) -> str:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S%f")
+    return f"{prefix}-{stamp}"
+
+
+def push_live_log(ctx: dict[str, Any] | None, entry: dict[str, Any]) -> dict[str, Any]:
+    log_entry = {
+        "id": entry.get("id") or _make_id("log"),
+        "agent": entry.get("agent", "System"),
+        "status": entry.get("status", "info"),
+        "detail": entry.get("detail", ""),
+        "action": entry.get("action", ""),
+        "timestamp": entry.get("timestamp") or _now_iso(),
+    }
+    if ctx is not None:
+        ctx.setdefault("live_logs", []).append(log_entry)
+    _LOG_BUFFER.append(log_entry)
+    return log_entry
+
+
+def get_logs(limit: int | None = None) -> list[dict[str, Any]]:
+    logs = list(_LOG_BUFFER)
+    if limit is not None:
+        logs = logs[-limit:]
+    return logs
+
+
+def emit_event(
+    ctx: dict[str, Any] | None,
+    event_type: str,
+    payload: dict[str, Any],
+    *,
+    agent: str | None = None,
+    step: str | None = None,
+    message: str | None = None,
+    log_entry: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    global _EVENT_SEQ
+    _EVENT_SEQ += 1
+    event_id = _make_id("evt")
+    event = {
+        "id": event_id,
+        "event_id": event_id,
+        "sequence": _EVENT_SEQ,
+        "sequence_number": _EVENT_SEQ,
+        "type": event_type,
+        "timestamp": _now_iso(),
+        "agent": agent,
+        "step": step or event_type,
+        "message": message or "",
+        "data": deepcopy(payload),
+        "payload": deepcopy(payload),
+        "log": deepcopy(log_entry) if log_entry else None,
+    }
+    if ctx is not None:
+        ctx.setdefault("events", []).append(event)
+    _EVENT_BUFFER.append(event)
+
+    invoice_id = payload.get("invoice_id") or payload.get("id")
+    if invoice_id and isinstance(payload.get("items"), list):
+        store_invoice(payload)
+
+    return event
+
+
+def emit_global_event(event_type: str, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+    return emit_event(None, event_type, payload, **kwargs)
+
+
+def get_events(limit: int | None = None) -> list[dict[str, Any]]:
+    events = list(_EVENT_BUFFER)
+    if limit is not None:
+        events = events[-limit:]
+    return events
+
+
+def get_events_since(sequence: int) -> list[dict[str, Any]]:
+    return [event for event in _EVENT_BUFFER if int(event.get("sequence", 0)) > sequence]
+
+
+def get_latest_event_sequence() -> int:
+    if not _EVENT_BUFFER:
+        return 0
+    return int(_EVENT_BUFFER[-1].get("sequence", 0))
+
+
+def store_invoice(invoice: dict[str, Any]) -> dict[str, Any]:
+    normalized = deepcopy(invoice)
+    invoice_id = normalized.get("invoice_id") or normalized.get("id")
+    if not invoice_id:
+        return normalized
+    normalized["invoice_id"] = invoice_id
+    normalized["id"] = invoice_id
+    _INVOICE_STORE[invoice_id] = normalized
+    return normalized
+
+
+def get_invoice(invoice_id: str) -> dict[str, Any] | None:
+    invoice = _INVOICE_STORE.get(invoice_id)
+    return deepcopy(invoice) if invoice else None
+
+
+def confirm_invoice_payment(invoice_id: str) -> dict[str, Any] | None:
+    invoice = _INVOICE_STORE.get(invoice_id)
+    if not invoice:
+        return None
+    invoice["status"] = "paid"
+    return store_invoice(invoice)

app/core/llm_router.py

@@ -0,0 +1,147 @@
+"""
+app/core/llm_router.py
+-----------------------
+LLM Router for NotiFlow Autonomous — Phase 4.
+
+Maps (agent_name, task_type) → ordered list of models to try.
+Pure data + logic, zero I/O.  LLMService consumes this.
+
+Model entry shape:
+    {
+        "provider": "nim" | "openrouter",
+        "model":    str,               # exact model ID
+        "max_tokens": int | None,      # None = caller decides
+    }
+
+Routing strategy
+----------------
+                        primary                fallback-1              fallback-2
+intent      →  deepseek-v3.2 (nim)   openrouter-fallback    deepseek-v3.1 (nim)
+extraction  →  deepseek-v3.2 (nim)   openrouter-fallback    deepseek-v3.1 (nim)
+planning    →  deepseek-v3.2 (nim)   openrouter-fallback     deepseek-v3.1 (nim)
+reasoning   →  deepseek-v3.2 (nim)   openrouter-fallback     deepseek-v3.1 (nim)
+default     →  deepseek-v3.2 (nim)   openrouter-fallback    deepseek-v3.1 (nim)
+
+Extending
+---------
+Add / change routing by editing _ROUTES below.  No other file needs to change.
+
+Public API
+----------
+route_llm(agent_name, task_type) -> dict
+    Returns {"primary": ModelEntry, "fallbacks": [ModelEntry, ...]}
+
+ModelEntry = {"provider": str, "model": str, "max_tokens": int | None}
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TypedDict
+
+
+class ModelEntry(TypedDict):
+    provider:   str           # "nim" | "openrouter"
+    model:      str           # model identifier
+    max_tokens: int | None    # None = use caller default
+
+
+# ---------------------------------------------------------------------------
+# Model catalogue
+# ---------------------------------------------------------------------------
+
+_NIM_PRIMARY  : ModelEntry = {
+    "provider":   "nim",
+    "model":      os.getenv("NIM_PRIMARY_MODEL", "deepseek-ai/deepseek-v3.2"),
+    "max_tokens": None,
+}
+_NIM_FALLBACK : ModelEntry = {
+    "provider":   "nim",
+    "model":      os.getenv("NIM_FALLBACK_MODEL", "deepseek-ai/deepseek-v3.1"),
+    "max_tokens": None,
+}
+_OPENROUTER   : ModelEntry = {
+    "provider":   "openrouter",
+    "model":      os.getenv(
+        "OPENROUTER_MODEL",
+        "deepseek/deepseek-chat",   # sensible default
+    ),
+    "max_tokens": None,
+}
+
+
+# ---------------------------------------------------------------------------
+# Routing table
+# (agent_name, task_type) → [primary, fallback1, fallback2, ...]
+# Keys are lowercased at lookup time.
+# ---------------------------------------------------------------------------
+
+_ROUTES: dict[tuple[str, str], list[ModelEntry]] = {
+
+    # Fast classification — intent detection
+    ("intentagent",      "classification"):  [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("intentagent",      ""):                [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+
+    # Structured extraction — needs reliable JSON output
+    ("extractionagent",  "extraction"):      [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("extractionagent",  ""):                [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+
+    # Planning requires deeper reasoning
+    ("planner",          "planning"):        [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("planner",          ""):                [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+
+    # Reasoning-heavy agents — prediction, recovery
+    ("predictionagent",  "reasoning"):       [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("predictionagent",  ""):                [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("recoveryagent",    "reasoning"):       [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+    ("recoveryagent",    ""):                [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK],
+}
+
+# Default route when no specific entry is found
+_DEFAULT_ROUTE: list[ModelEntry] = [_NIM_PRIMARY, _OPENROUTER, _NIM_FALLBACK]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def route_llm(agent_name: str = "", task_type: str = "") -> dict:
+    """
+    Return the model routing plan for a given agent and task type.
+
+    Args:
+        agent_name: Class name of the calling agent (e.g. "IntentAgent").
+                    Case-insensitive.
+        task_type:  Nature of the task (e.g. "classification", "extraction",
+                    "reasoning", "planning").  Case-insensitive.
+
+    Returns:
+        {
+            "primary":   ModelEntry,
+            "fallbacks": [ModelEntry, ...],
+        }
+
+    Examples:
+        >>> route_llm("IntentAgent", "classification")
+        {"primary": {...nim primary...}, "fallbacks": [{...nim fallback...}, {...openrouter...}]}
+
+        >>> route_llm()   # unknown agent → default route
+        {"primary": {...}, "fallbacks": [...]}
+    """
+    key = (agent_name.lower(), task_type.lower())
+
+    # Exact match first
+    models = _ROUTES.get(key)
+
+    # Try (agent_name, "") if task_type not found
+    if models is None:
+        models = _ROUTES.get((agent_name.lower(), ""))
+
+    # Fall through to default
+    if models is None:
+        models = _DEFAULT_ROUTE
+
+    return {
+        "primary":   models[0],
+        "fallbacks": models[1:],
+    }

app/core/llm_service.py

@@ -0,0 +1,459 @@
+"""
+app/core/llm_service.py
+-----------------------
+Unified LLM Service for NotiFlow Autonomous — Phase 4.
+
+ALL LLM calls in the system go through this single service.
+No other module is allowed to call an LLM API directly.
+
+Phase 4 additions
+-----------------
+* generate() accepts optional agent_name + task_type kwargs
+* Internally calls llm_router.route_llm() to get ordered model list
+* Iterates primary → fallback-1 → fallback-2 until one succeeds
+* Writes model_used / fallback_used into context if passed
+* Supports NVIDIA NIM and OpenRouter (both OpenAI-compatible)
+
+Backward compatibility
+----------------------
+generate(prompt)                    — still works, uses default routing
+generate(prompt, max_tokens=256)    — still works
+generate(prompt, agent_name="intent", task_type="classification")  — Phase 4
+
+Configuration (.env)
+--------------------
+NVIDIA_NIM_API_KEY     — NIM primary key
+NVIDIA_NIM_BASE_URL    — default: https://integrate.api.nvidia.com/v1
+NIM_PRIMARY_MODEL      — default: deepseek-ai/deepseek-v3
+NIM_FALLBACK_MODEL     — default: deepseek-ai/deepseek-r1
+OPENROUTER_API_KEY     — OpenRouter fallback key
+OPENROUTER_MODEL       — default: deepseek/deepseek-chat
+
+Public API
+----------
+LLMService().generate(prompt, max_tokens, agent_name, task_type, context) -> str
+get_llm() -> LLMService
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+_NIM_API_KEY        = os.getenv("NVIDIA_NIM_API_KEY") or os.getenv("NVIDIA_API_KEY")
+_NIM_BASE_URL       = (
+    os.getenv("NVIDIA_NIM_BASE_URL")
+    or os.getenv("NIM_BASE_URL")
+    or "https://integrate.api.nvidia.com/v1"
+)
+_OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
+_OPENROUTER_BASE    = "https://openrouter.ai/api/v1"
+_LEGACY_NIM_MODEL   = os.getenv("NVIDIA_NIM_MODEL", "deepseek-ai/deepseek-v3.2")
+_REQUEST_TIMEOUT_S  = float(os.getenv("LLM_TIMEOUT_SECONDS", "60"))
+_RETRY_COUNT        = int(os.getenv("LLM_RETRY_COUNT", "2"))
+_SIMULATE_NIM_FAILURE = os.getenv("SIMULATE_NIM_FAILURE", "false").lower() == "true"
+_SIMULATED_NIM_FAILURE_USED = False
+_SIMULATE_NIM_FAIL  = os.getenv("SIMULATE_NIM_FAILURE", "false").lower() == "true"
+
+
+# ---------------------------------------------------------------------------
+# LLMService
+# ---------------------------------------------------------------------------
+
+class LLMService:
+    """
+    Single entry point for all LLM inference in NotiFlow.
+
+    Phase 4: routes per agent/task, iterates fallbacks automatically,
+    optionally writes audit info to context.
+    """
+
+    def call_llm(
+        self,
+        prompt: str,
+        agent_name: str,
+        *,
+        max_tokens: int = 256,
+        task_type: str = "",
+        context: Optional[dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> str:
+        """Convenience wrapper for agent-aware LLM calls."""
+        return self.generate(
+            prompt,
+            max_tokens=max_tokens,
+            agent_name=agent_name,
+            task_type=task_type,
+            context=context,
+            stream=stream,
+        )
+
+    def generate(
+        self,
+        prompt:     str,
+        max_tokens: int = 256,
+        *,
+        agent_name: str = "",
+        task_type:  str = "",
+        context:    Optional[dict[str, Any]] = None,
+        stream:     bool = False,
+    ) -> str:
+        """
+        Send a prompt to the best available model for this agent/task.
+
+        Args:
+            prompt:     Fully rendered prompt string.
+            max_tokens: Maximum tokens to generate (default 256).
+            agent_name: Calling agent class name — used by router.
+            task_type:  Task category — used by router.
+            context:    Optional live context dict.  If provided, writes
+                        context["model_used"] and context["fallback_used"].
+
+        Returns:
+            Raw text response (JSON or plain text — callers parse it).
+
+        Raises:
+            RuntimeError: If ALL models in the route fail.
+        """
+        from app.core.llm_router import route_llm
+        from app.core.event_bus import emit_event
+
+        route      = route_llm(agent_name, task_type)
+        primary    = route["primary"]
+        fallbacks  = route["fallbacks"]
+        all_models = [primary] + fallbacks
+        self._stream_requested = stream
+
+        if context is not None:
+            context.setdefault("metadata", {}).update({
+                "llm_timeout_seconds": _REQUEST_TIMEOUT_S,
+                "llm_retry_count": _RETRY_COUNT,
+                "llm_stream": stream,
+            })
+
+        last_exc: Optional[Exception] = None
+        tried: list[str] = []
+
+        for idx, model_entry in enumerate(all_models):
+            provider   = model_entry["provider"]
+            model_name = model_entry["model"]
+            tokens     = model_entry.get("max_tokens") or max_tokens
+
+            # ── Error Simulation: NIM failure ─────────────────────────────
+            if _SIMULATE_NIM_FAIL and provider == "nim" and "v3.2" in model_name:
+                logger.warning(f"SIMULATION: Intentional NIM timeout for {model_name}")
+                exc = RuntimeError(f"NIM gateway timeout (simulated) for {model_name}")
+                tried.append(model_name)
+                last_exc = exc
+                next_model = all_models[idx + 1] if idx + 1 < len(all_models) else None
+                if context is not None:
+                    emit_event(
+                        context,
+                        "error_occurred",
+                        {
+                            "step": agent_name or "llm",
+                            "message": str(exc),
+                            "provider": provider,
+                            "model": model_name,
+                        },
+                        agent=agent_name or "LLMService",
+                        step="llm",
+                        message=str(exc),
+                        status="error",
+                    )
+                    if next_model is not None:
+                        emit_event(
+                            context,
+                            "recovery_triggered",
+                            {
+                                "step": agent_name or "llm",
+                                "failed_provider": provider,
+                                "failed_model": model_name,
+                                "fallback_provider": next_model.get("provider"),
+                                "fallback_model": next_model.get("model"),
+                            },
+                            agent=agent_name or "LLMService",
+                            step="llm",
+                            message=f"Fallback triggered → {next_model.get('provider')}/{next_model.get('model')}",
+                        )
+                self._log_fallback(agent_name, provider, model_name, exc, next_model)
+                continue
+
+            try:
+                response = self._call_model(provider, model_name, prompt, tokens)
+
+                # ── Write audit info to context ───────────────────────────
+                if context is not None:
+                    context["model_used"]    = model_name
+                    context["fallback_used"] = idx > 0
+                    context.setdefault("metadata", {}).update({
+                        "model_used":     model_name,
+                        "model_provider": provider,
+                        "fallback_used":  idx > 0,
+                        "models_tried":   tried + [model_name],
+                    })
+                    if idx > 0:
+                        emit_event(
+                            context,
+                            "recovery_success",
+                            {
+                                "step": agent_name or "llm",
+                                "provider": provider,
+                                "model": model_name,
+                                "models_tried": tried + [model_name],
+                            },
+                            agent=agent_name or "LLMService",
+                            step="llm",
+                            message=f"Recovered with {provider}/{model_name}",
+                        )
+
+                level = "primary" if idx == 0 else f"fallback #{idx}"
+                logger.info(
+                    "LLMService → %s/%s (%s, agent=%s)",
+                    provider, model_name, level, agent_name or "unknown"
+                )
+                return response
+
+            except Exception as exc:
+                tried.append(model_name)
+                last_exc = exc
+                next_model = all_models[idx + 1] if idx + 1 < len(all_models) else None
+                if context is not None:
+                    emit_event(
+                        context,
+                        "error_occurred",
+                        {
+                            "step": agent_name or "llm",
+                            "message": str(exc),
+                            "provider": provider,
+                            "model": model_name,
+                        },
+                        agent=agent_name or "LLMService",
+                        step="llm",
+                        message=str(exc),
+                    )
+                    if next_model is not None:
+                        emit_event(
+                            context,
+                            "recovery_triggered",
+                            {
+                                "step": agent_name or "llm",
+                                "failed_provider": provider,
+                                "failed_model": model_name,
+                                "fallback_provider": next_model.get("provider"),
+                                "fallback_model": next_model.get("model"),
+                            },
+                            agent=agent_name or "LLMService",
+                            step="llm",
+                            message=f"Fallback to {next_model.get('provider')}/{next_model.get('model')}",
+                        )
+                self._log_fallback(agent_name, provider, model_name, exc, next_model)
+                continue
+
+        if not agent_name and not task_type:
+            try:
+                logger.warning("[LLMService] route exhausted - using legacy Gemini shim")
+                response = self._call_gemini(prompt)
+                if context is not None:
+                    context["model_used"] = "gemini-legacy"
+                    context["fallback_used"] = True
+                    context.setdefault("metadata", {}).update({
+                        "model_used": "gemini-legacy",
+                        "model_provider": "gemini",
+                        "fallback_used": True,
+                        "models_tried": tried + ["gemini-legacy"],
+                    })
+                return response
+            except Exception as gemini_exc:
+                last_exc = gemini_exc
+                tried.append("gemini-legacy")
+
+        logger.error("LLMService: all %d model(s) failed. Last: %s", len(tried), last_exc)
+        raise RuntimeError(
+            f"All LLM backends failed for agent='{agent_name}' task='{task_type}'. "
+            f"Tried: {tried}. Last error: {last_exc}"
+        ) from last_exc
+
+    # ── Model dispatch ────────────────────────────────────────────────────────
+
+    def _call_model(self, provider: str, model_name: str, prompt: str, max_tokens: int) -> str:
+        if provider == "nim":
+            return self._call_nim(model_name, prompt, max_tokens)
+        elif provider == "openrouter":
+            return self._call_openrouter(model_name, prompt, max_tokens)
+        else:
+            raise RuntimeError(f"Unknown LLM provider: '{provider}'")
+
+    # ── NVIDIA NIM ────────────────────────────────────────────────────────────
+
+    def _call_nim(self, model_name: str, prompt: str, max_tokens: int) -> str:
+        global _SIMULATED_NIM_FAILURE_USED
+        if _SIMULATE_NIM_FAILURE and not _SIMULATED_NIM_FAILURE_USED:
+            _SIMULATED_NIM_FAILURE_USED = True
+            raise TimeoutError("NIM timeout")
+        if not _NIM_API_KEY:
+            raise RuntimeError("NVIDIA_NIM_API_KEY is not set.")
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise RuntimeError("openai not installed. Run: pip install openai")
+
+        client = OpenAI(
+            base_url=_NIM_BASE_URL,
+            api_key=_NIM_API_KEY,
+            timeout=_REQUEST_TIMEOUT_S,
+            max_retries=0,
+        )
+        text = self._request_with_retry(
+            provider_label=f"NIM[{model_name}]",
+            request_fn=lambda: self._create_chat_completion(client, model_name, prompt, max_tokens),
+        )
+        logger.debug("NIM[%s] raw: %r", model_name, text[:200])
+        return text.strip()
+
+    # ── OpenRouter ────────────────────────────────────────────────────────────
+
+    def _call_openrouter(self, model_name: str, prompt: str, max_tokens: int) -> str:
+        if not _OPENROUTER_API_KEY:
+            raise RuntimeError("OPENROUTER_API_KEY is not set.")
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise RuntimeError("openai not installed. Run: pip install openai")
+
+        extra_headers = {"X-Title": os.getenv("OPENROUTER_TITLE", "NotiFlow")}
+        referer = os.getenv("OPENROUTER_REFERER")
+        if referer:
+            extra_headers["HTTP-Referer"] = referer
+
+        client = OpenAI(
+            base_url=_OPENROUTER_BASE,
+            api_key=_OPENROUTER_API_KEY,
+            default_headers=extra_headers,
+            timeout=_REQUEST_TIMEOUT_S,
+            max_retries=0,
+        )
+        text = self._request_with_retry(
+            provider_label=f"OpenRouter[{model_name}]",
+            request_fn=lambda: self._create_chat_completion(client, model_name, prompt, max_tokens),
+        )
+        logger.debug("OpenRouter[%s] raw: %r", model_name, text[:200])
+        return text.strip()
+
+    # ── Legacy shims — test_pipeline.py patches these directly ───────────────
+    # DO NOT rename or remove — existing tests mock them by name.
+
+    def _call_gemini(self, prompt: str) -> str:
+        """Gemini shim — kept for test_pipeline.py backward compat."""
+        try:
+            from app.services.gemini_client import generate
+        except ImportError:
+            from app.services.gemini_client import generate  # type: ignore
+        return generate(prompt)
+
+    def _create_chat_completion(self, client: Any, model_name: str, prompt: str, max_tokens: int) -> str:
+        completion = client.chat.completions.create(
+            model=model_name,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.0,
+            max_tokens=max_tokens,
+            stream=getattr(self, "_stream_requested", False),
+        )
+        if getattr(self, "_stream_requested", False):
+            chunks: list[str] = []
+            for event in completion:
+                if not getattr(event, "choices", None):
+                    continue
+                delta = getattr(event.choices[0].delta, "content", None)
+                if delta:
+                    chunks.append(delta)
+            return "".join(chunks)
+        return completion.choices[0].message.content or ""
+
+    def _request_with_retry(self, provider_label: str, request_fn: Any) -> str:
+        last_exc: Optional[Exception] = None
+        for attempt in range(_RETRY_COUNT + 1):
+            try:
+                return request_fn()
+            except Exception as exc:
+                last_exc = exc
+                if attempt >= _RETRY_COUNT:
+                    break
+                logger.warning(
+                    "%s request failed (%s) - retry %d/%d",
+                    provider_label,
+                    exc,
+                    attempt + 1,
+                    _RETRY_COUNT,
+                )
+        raise last_exc if last_exc is not None else RuntimeError(f"{provider_label} failed")
+
+    def _log_fallback(
+        self,
+        agent_name: str,
+        provider: str,
+        model_name: str,
+        exc: Exception,
+        next_model: Optional[dict[str, Any]],
+    ) -> None:
+        agent_label = agent_name or "LLMService"
+        failure_kind = "timeout" if self._is_timeout_error(exc) else "error"
+        if next_model is None:
+            logger.error(
+                "[%s] %s %s on %s - no fallback remaining",
+                agent_label,
+                self._provider_label(provider),
+                failure_kind,
+                model_name,
+            )
+            return
+        logger.warning(
+            "[%s] %s %s - fallback %s",
+            agent_label,
+            self._provider_label(provider),
+            failure_kind,
+            self._fallback_target_label(next_model),
+        )
+
+    @staticmethod
+    def _provider_label(provider: str) -> str:
+        return "NIM" if provider == "nim" else "OpenRouter"
+
+    def _fallback_target_label(self, model_entry: dict[str, Any]) -> str:
+        provider = model_entry.get("provider", "")
+        model_name = str(model_entry.get("model", ""))
+        if provider == "openrouter":
+            return "OpenRouter"
+        if provider == "nim" and "v3.1" in model_name:
+            return "v3.1"
+        if provider == "nim" and "v3.2" in model_name:
+            return "v3.2"
+        return model_name or self._provider_label(provider)
+
+    @staticmethod
+    def _is_timeout_error(exc: Exception) -> bool:
+        name = exc.__class__.__name__.lower()
+        text = str(exc).lower()
+        return "timeout" in name or "timeout" in text or "timed out" in text
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_instance: Optional[LLMService] = None
+
+
+def get_llm() -> LLMService:
+    """Return the shared LLMService singleton."""
+    global _instance
+    if _instance is None:
+        _instance = LLMService()
+    return _instance

app/core/orchestrator.py

@@ -0,0 +1,566 @@
+"""
+app/core/orchestrator.py
+------------------------
+Dynamic Agent Orchestrator for NotiFlow Autonomous (Phase 2).
+
+Replaces the static pipeline list with a planner-driven execution loop.
+
+Flow
+----
+    create_context()
+        ↓
+    build_plan(ctx)          ← Planner evaluates rules, writes ctx["plan"]
+        ↓
+    for step in ctx["plan"]:
+        agent = AGENT_REGISTRY[step["agent"]]
+        agent.run(ctx)       ← executes, writes audit entry to ctx["history"]
+        if failed and step["critical"]: abort
+        ↓
+    _build_result(ctx)       ← flatten ctx → public API response shape
+
+Key properties
+--------------
+- No hardcoded execution order anywhere in this file
+- LedgerAgent is NOT special-cased — it is just another plan step
+- Adding a new agent = one registry entry + one planner rule, zero changes here
+- Non-critical step failures are recorded and skipped, not aborted
+
+Return shape (backward compatible):
+    {
+        "message":       str,
+        "intent":        str,
+        "data":          dict,
+        "event":         dict,
+        "sheet_updated": bool,
+        "context":       dict,  ← full context (debug/audit)
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.core.context          import create_context, update_context, log_step, add_error
+from app.core.event_bus        import emit_event, push_live_log
+from app.core.planner          import build_plan
+from app.core.autonomy_planner import build_autonomy_plan
+from app.core.priority         import reset_priority_score
+from app.core.registry         import get_agent
+
+logger = logging.getLogger(__name__)
+
+_MAX_REPLANS = 2   # hard cap on feedback-loop iterations
+
+_STEP_EVENT_MAP: dict[str, tuple[str, str]] = {
+    "intent": ("intent_detected", "IntentAgent"),
+    "extraction": ("extraction_done", "ExtractionAgent"),
+    "validation": ("validation_done", "ValidationAgent"),
+    "invoice_agent": ("invoice_generated", "InvoiceAgent"),
+    "payment_agent": ("payment_requested", "PaymentAgent"),
+    "ledger": ("execution_done", "LedgerAgent"),
+    "recovery": ("recovery_triggered", "RecoveryAgent"),
+}
+
+
+def process_message(message: str, source: str = "system") -> dict[str, Any]:
+    """
+    Run a raw business message through the full NotiFlow agent pipeline.
+
+    Phase 2: main pipeline driven by Planner (dynamic).
+    Phase 3: autonomy layer driven by AutonomyPlanner (dynamic).
+    Fix:     feedback loop — replan up to _MAX_REPLANS times if needed.
+
+    Args:
+        message: Raw Hinglish or English business message.
+        source:  Notification source (e.g. "whatsapp", "gpay").
+
+    Returns:
+        Flat result dict + full context.
+
+    Raises:
+        ValueError: Empty message.
+    """
+    if not message or not message.strip():
+        raise ValueError("Message cannot be empty.")
+
+    ctx = create_context(message.strip(), source=source)
+    logger.info("Orchestrator ← %r (source=%s)", message, source)
+    _emit_pipeline_event(
+        ctx,
+        "message_received",
+        {
+            "message": ctx["message"],
+            "source": source,
+            "state": ctx.get("state"),
+        },
+        agent="Orchestrator",
+        step="message",
+        message=f"Received message from {source}",
+        log_text=f"[Orchestrator] Message received from {source}: {ctx['message']}",
+    )
+
+    # ── Main plan + autonomy + feedback loop ──────────────────────────────
+    while True:
+        retry_count = ctx["metadata"].get("retry_count", 0)
+
+        # ── 1. Build and run main plan ────────────────────────────────────
+        plan = build_plan(ctx)
+        logger.info(
+            "[cycle=%d] Main plan: [%s]",
+            retry_count,
+            ", ".join(s["agent"] for s in plan),
+        )
+        ctx = _run_plan(ctx, plan)
+
+        # ── 2. Build and run autonomy plan ────────────────────────────────
+        autonomy_plan = build_autonomy_plan(ctx)
+        logger.info(
+            "[cycle=%d] Autonomy plan: [%s]",
+            retry_count,
+            ", ".join(s["agent"] for s in autonomy_plan),
+        )
+        ctx = _run_autonomy(ctx, autonomy_plan)
+
+        # ── 3. Check if replan is needed ──────────────────────────────────
+        if retry_count >= _MAX_REPLANS:
+            logger.info("Replan cap reached (%d) — stopping loop.", _MAX_REPLANS)
+            break
+
+        if not _should_replan(ctx):
+            logger.info("[cycle=%d] No replan needed.", retry_count)
+            break
+
+        # ── 4. Prepare for replan ─────────────────────────────────────────
+        logger.warning(
+            "[cycle=%d] Replan triggered — retry_count → %d",
+            retry_count, retry_count + 1,
+        )
+        _emit_pipeline_event(
+            ctx,
+            "recovery_triggered",
+            {
+                "retry_count": retry_count + 1,
+                "reason": "replan_required",
+                "errors": ctx.get("errors", []),
+            },
+            agent="RecoveryAgent",
+            step="recovery",
+            message="Recovery triggered after pipeline replan request",
+            log_text=f"[RecoveryAgent] Recovery triggered after cycle {retry_count}",
+        )
+        ctx["metadata"]["retry_count"] = retry_count + 1
+
+        # Reset priority score so contributors don't double-count
+        reset_priority_score(ctx)
+
+        # Clear autonomy outputs so fresh evaluation happens
+        for key in ("verification", "monitor", "risk", "alerts", "recovery"):
+            ctx.pop(key, None)
+
+        # Clear accumulated errors from previous cycle (keep original errors)
+        ctx["errors"] = [e for e in ctx["errors"] if not e.startswith("[Monitor]")]
+
+    # ── Mark final state ──────────────────────────────────────────────────
+    if ctx.get("state") not in ("failed",):
+        update_context(ctx, state="completed")
+
+    logger.info(
+        "Orchestrator done → state=%s intents=%s errors=%d risk=%s priority=%s score=%d",
+        ctx["state"],
+        ctx.get("intents", [ctx.get("intent")]),
+        len(ctx["errors"]),
+        ctx.get("risk", {}).get("level", "n/a"),
+        ctx.get("priority", "n/a"),
+        ctx.get("priority_score", 0),
+    )
+
+    return _build_result(ctx)
+
+
+def _run_plan(ctx: dict[str, Any], plan: list[dict]) -> dict[str, Any]:
+    """Execute the planner-generated main pipeline steps."""
+    for step in plan:
+        agent_key   = step["agent"]
+        is_critical = step.get("critical", True)
+        _emit_pipeline_step_event(ctx, agent_key, "started")
+
+        try:
+            agent = get_agent(agent_key)
+        except KeyError as exc:
+            msg = f"Orchestrator: {exc}"
+            logger.error(msg)
+            add_error(ctx, msg)
+            log_step(ctx, agent_key, "skipped",
+                     detail=f"Agent not found in registry: {agent_key}")
+            _emit_pipeline_event(
+                ctx,
+                "error_occurred",
+                {
+                    "step": agent_key,
+                    "message": msg,
+                    "critical": is_critical,
+                },
+                agent="Orchestrator",
+                step=agent_key,
+                message=msg,
+                log_text=f"[Orchestrator] {msg}",
+                status="error",
+            )
+            if is_critical:
+                update_context(ctx, state="failed")
+                break
+            continue
+
+        try:
+            ctx = agent.run(ctx)
+            _emit_pipeline_step_event(ctx, agent_key, "completed")
+            _emit_step_success(ctx, agent_key)
+        except Exception as exc:
+            logger.error("Orchestrator: %s raised %s", agent_key, exc)
+            _emit_pipeline_step_event(ctx, agent_key, "failed", str(exc))
+            _emit_pipeline_event(
+                ctx,
+                "error_occurred",
+                {
+                    "step": agent_key,
+                    "message": str(exc),
+                    "critical": is_critical,
+                },
+                agent=getattr(agent, "name", agent_key),
+                step=agent_key,
+                message=str(exc),
+                log_text=f"[{getattr(agent, 'name', agent_key)}] {exc}",
+                status="error",
+            )
+            if is_critical:
+                logger.error("Critical agent '%s' failed — aborting pipeline.", agent_key)
+                break
+            else:
+                logger.warning("Non-critical agent '%s' failed — continuing.", agent_key)
+                if ctx.get("state") == "failed":
+                    update_context(ctx, state="partial")
+                continue
+
+        if ctx.get("state") == "failed" and is_critical:
+            logger.error("Pipeline in failed state after critical agent '%s'.", agent_key)
+            break
+
+    return ctx
+
+
+def _run_autonomy(ctx: dict[str, Any], plan: list[dict]) -> dict[str, Any]:
+    """
+    Run the dynamically planned autonomy sequence.
+
+    All autonomy agents are non-critical — failures are recorded but
+    never abort the sequence or corrupt the main pipeline result.
+    """
+    for step in plan:
+        agent_key = step["agent"]
+        _emit_pipeline_step_event(ctx, agent_key, "started")
+        try:
+            agent = get_agent(agent_key)
+        except KeyError:
+            logger.warning("[Autonomy] agent '%s' not in registry — skipping", agent_key)
+            continue
+        try:
+            ctx = agent.run(ctx)
+            _emit_pipeline_step_event(ctx, agent_key, "completed")
+            if agent_key == "recovery":
+                recovery = ctx.get("recovery", {}) or {}
+                recovery_event = "recovery_success" if recovery.get("success") else "recovery_triggered"
+                _emit_pipeline_event(
+                    ctx,
+                    recovery_event,
+                    recovery or {"action": "none"},
+                    agent=getattr(agent, "name", agent_key),
+                    step=agent_key,
+                    message=recovery.get("details") or "Recovery step completed",
+                    log_text=f"[{getattr(agent, 'name', agent_key)}] {recovery.get('details', 'Recovery step completed')}",
+                )
+        except Exception as exc:
+            logger.error("[Autonomy] '%s' raised %s — continuing", agent_key, exc)
+            add_error(ctx, f"[Autonomy] {agent_key} failed: {exc}")
+            _emit_pipeline_step_event(ctx, agent_key, "failed", str(exc))
+            _emit_pipeline_event(
+                ctx,
+                "error_occurred",
+                {
+                    "step": agent_key,
+                    "message": str(exc),
+                    "critical": False,
+                },
+                agent=getattr(agent, "name", agent_key),
+                step=agent_key,
+                message=str(exc),
+                log_text=f"[{getattr(agent, 'name', agent_key)}] {exc}",
+                status="error",
+            )
+            if ctx.get("state") == "failed":
+                update_context(ctx, state="partial")
+    return ctx
+
+
+def _should_replan(ctx: dict[str, Any]) -> bool:
+    """
+    Return True if the feedback loop should trigger a replan.
+
+    Conditions (any one is sufficient):
+        1. verification.status == "fail"
+        2. risk.level          == "high"
+        3. errors list is non-empty (excluding autonomy-internal noise)
+    """
+    v_status = ctx.get("verification", {}).get("status", "ok")
+    if v_status == "fail":
+        logger.info("[Feedback] replan trigger: verification=fail")
+        return True
+
+    risk_level = ctx.get("risk", {}).get("level", "low")
+    if risk_level == "high":
+        logger.info("[Feedback] replan trigger: risk=high")
+        return True
+
+    # Only count errors that are not pure autonomy-internal noise
+    meaningful_errors = [
+        e for e in ctx.get("errors", [])
+        if not e.startswith("[Autonomy]")
+    ]
+    if meaningful_errors:
+        logger.info(
+            "[Feedback] replan trigger: %d meaningful error(s)", len(meaningful_errors)
+        )
+        return True
+
+    return False
+
+
+def _build_result(ctx: dict[str, Any]) -> dict[str, Any]:
+    """Flatten context into the public API response shape."""
+    event = ctx.get("event", {}) or {}
+    data = ctx.get("data", {}) or {}
+    event_order = event.get("order", {}) if isinstance(event.get("order"), dict) else {}
+    risk = ctx.get("risk", {}) or {}
+    source = ctx.get("source", "system")
+
+    payment_state = ctx.get("payment") or {}
+
+    amount = payment_state.get("amount", event.get("amount"))
+    if amount is None:
+        amount = data.get("amount", 0)
+
+    try:
+        numeric_amount = float(amount or 0)
+    except (TypeError, ValueError):
+        numeric_amount = 0
+
+    return {
+        # ── Core (backward compatible) ────────────────────────────────────
+        "message":       ctx["message"],
+        "intent":        ctx.get("intent") or "other",
+        "intents":       ctx.get("intents") or [ctx.get("intent") or "other"],
+        "data":          ctx.get("data", {}),
+        "multi_data":    ctx.get("multi_data", {}),
+        "event":         ctx.get("event", {}),
+        "invoice":       ctx.get("invoice"),
+        "events":        ctx.get("events", []),
+        "live_logs":     ctx.get("live_logs", []),
+        "history":       ctx.get("history", []),
+        "sheet_updated": ctx.get("metadata", {}).get("sheet_updated", False),
+        "customer":      {"name": event.get("customer") or data.get("customer") or "Walk-in customer"},
+        "order": {
+            "item": event.get("item") or event_order.get("item") or data.get("item"),
+            "quantity": event.get("quantity") or event_order.get("quantity") or data.get("quantity"),
+            "status": event.get("status") or "received",
+            "source": source,
+        },
+        "payment": {
+            "invoice_id": payment_state.get("invoice_id") or (ctx.get("invoice") or {}).get("invoice_id") or event.get("invoice_id") or data.get("invoice_id"),
+            "amount": payment_state.get("amount") or (ctx.get("invoice") or {}).get("total") or numeric_amount,
+            "status": payment_state.get("status") or (ctx.get("invoice") or {}).get("status") or ("paid" if numeric_amount > 0 else "pending"),
+        },
+        "decision": {
+            "intent": ctx.get("intent") or "other",
+            "priority": ctx.get("priority", "low"),
+            "priority_score": ctx.get("priority_score", 0),
+            "risk": risk.get("level"),
+        },
+        # ── Autonomy fields ───────────────────────────────────────────────
+        "verification":  ctx.get("verification", {}),
+        "risk":          ctx.get("risk", {}),
+        "priority":      ctx.get("priority", "low"),
+        "priority_score": ctx.get("priority_score", 0),
+        "alerts":        ctx.get("alerts", []),
+        "recovery":      ctx.get("recovery", {}),
+        "monitor":       ctx.get("monitor", {}),
+        # ── Debug ─────────────────────────────────────────────────────────
+        "context":       ctx,
+    }
+
+
+def _emit_step_success(ctx: dict[str, Any], agent_key: str) -> None:
+    if agent_key in {"invoice_agent", "payment_agent"}:
+        return
+    event_type, agent_name = _STEP_EVENT_MAP.get(agent_key, ("execution_done", agent_key))
+    payload = _build_step_payload(ctx, agent_key)
+    message, log_text = _build_step_messages(ctx, agent_key, agent_name)
+    _emit_pipeline_event(
+        ctx,
+        event_type,
+        payload,
+        agent=agent_name,
+        step=agent_key,
+        message=message,
+        log_text=log_text,
+    )
+
+def _build_step_payload(ctx: dict[str, Any], agent_key: str) -> dict[str, Any]:
+    if agent_key == "intent":
+        return {
+            "intent": ctx.get("intent") or "other",
+            "intents": ctx.get("intents", []),
+            "model_used": ctx.get("model_used"),
+        }
+    if agent_key == "extraction":
+        return {
+            "intent": ctx.get("intent") or "other",
+            "data": ctx.get("data", {}),
+            "multi_data": ctx.get("multi_data", {}),
+        }
+    if agent_key == "validation":
+        return {
+            "intent": ctx.get("intent") or "other",
+            "data": ctx.get("data", {}),
+        }
+    if agent_key == "invoice_agent":
+        return {
+            "intent": ctx.get("intent") or "other",
+            "invoice": ctx.get("invoice"),
+        }
+    if agent_key == "payment_agent":
+        return {
+            "intent": ctx.get("intent") or "other",
+            "payment": ctx.get("payment"),
+            "invoice": ctx.get("invoice"),
+        }
+    if agent_key == "ledger":
+        return {
+            "sheet_updated": ctx.get("metadata", {}).get("sheet_updated", False),
+            "event": ctx.get("event", {}),
+        }
+    if agent_key == "recovery":
+        return ctx.get("recovery", {})
+    return {
+        "state": ctx.get("state"),
+        "event": ctx.get("event", {}),
+    }
+
+
+def _build_step_messages(ctx: dict[str, Any], agent_key: str, agent_name: str) -> tuple[str, str]:
+    if agent_key == "intent":
+        intent = ctx.get("intent") or "other"
+        return (
+            f"Intent detected: {intent}",
+            f"[{agent_name}] Intent detected: {intent}",
+        )
+    if agent_key == "extraction":
+        data = ctx.get("data", {}) or {}
+        detail_parts = [f"{key}={value}" for key, value in data.items() if value not in (None, "", [], {})]
+        detail = ", ".join(detail_parts) or "no structured fields extracted"
+        return (
+            f"Extraction completed: {detail}",
+            f"[{agent_name}] Extracted: {detail}",
+        )
+    if agent_key == "validation":
+        data = ctx.get("data", {}) or {}
+        detail_parts = [f"{key}={value}" for key, value in data.items() if value not in (None, "", [], {})]
+        detail = ", ".join(detail_parts) or "validation passed with empty payload"
+        return (
+            f"Validation completed: {detail}",
+            f"[{agent_name}] Validated: {detail}",
+        )
+    if agent_key == "invoice_agent":
+        invoice_id = (ctx.get("invoice") or {}).get("invoice_id") or "unknown"
+        return (
+            f"Invoice generated: {invoice_id}",
+            f"[{agent_name}] Invoice generated: {invoice_id}",
+        )
+    if agent_key == "payment_agent":
+        invoice_id = (ctx.get("payment") or {}).get("invoice_id") or (ctx.get("invoice") or {}).get("invoice_id") or "unknown"
+        amount = (ctx.get("payment") or {}).get("amount", 0)
+        return (
+            f"Payment requested: {invoice_id}",
+            f"[{agent_name}] Payment requested: {invoice_id} amount={amount}",
+        )
+    if agent_key == "ledger":
+        updated = ctx.get("metadata", {}).get("sheet_updated", False)
+        return (
+            f"Execution completed: sheet_updated={updated}",
+            f"[{agent_name}] Ledger update status: {updated}",
+        )
+    recovery = (ctx.get("recovery", {}) or {}).get("details") or "Recovery step completed"
+    return (recovery, f"[{agent_name}] {recovery}")
+
+
+def _emit_pipeline_event(
+    ctx: dict[str, Any],
+    event_type: str,
+    payload: dict[str, Any],
+    *,
+    agent: str,
+    step: str,
+    message: str,
+    log_text: str,
+    status: str = "success",
+) -> None:
+    log_entry = push_live_log(
+        ctx,
+        {
+            "agent": agent,
+            "status": status,
+            "action": message,
+            "detail": log_text,
+        },
+    )
+    emit_event(
+        ctx,
+        "log",
+        {
+            "step": step,
+            "message": log_text,
+        },
+        agent=agent,
+        step=step,
+        message=log_text,
+        log_entry=log_entry,
+    )
+    emit_event(
+        ctx,
+        event_type,
+        payload,
+        agent=agent,
+        step=step,
+        message=message,
+        log_entry=log_entry,
+    )
+
+
+def _emit_pipeline_step_event(
+    ctx: dict[str, Any],
+    step: str,
+    status: str,
+    detail: str = "",
+) -> None:
+    step_message = f"{step} {status}"
+    emit_event(
+        ctx,
+        "pipeline_step",
+        {
+            "step": step,
+            "status": status,
+            "detail": detail,
+        },
+        agent="Orchestrator",
+        step=step,
+        message=step_message,
+    )

app/core/planner.py

@@ -0,0 +1,197 @@
+"""
+app/core/planner.py
+-------------------
+Decision Engine (Planner) for NotiFlow Autonomous.
+
+Converts a context snapshot into an ordered execution plan.
+
+Design
+------
+The planner uses an ordered list of PlanRule objects.  Each rule has:
+    - agent:     registry key of the agent to run
+    - condition: callable(context) → bool
+                 True  = include this agent in the plan
+                 False = skip it
+    - critical:  if True, a failure from this agent aborts the pipeline
+                 if False, failure is recorded but execution continues
+
+Plan output shape (written to context["plan"]):
+    [
+        {"agent": "intent",     "critical": True},
+        {"agent": "extraction", "critical": True},
+        {"agent": "validation", "critical": True},
+        {"agent": "invoice_agent", "critical": True},
+        {"agent": "payment_agent", "critical": True},
+        {"agent": "ledger",     "critical": False},
+    ]
+
+Skipping logic (avoids redundant work on re-entry):
+    - "intent"     skipped if context["intent"] is already set
+    - "extraction" skipped if context["data"] is already non-empty
+    - "validation" skipped if context["state"] == "validated"
+    - "router"     skipped if context["event"] is already non-empty
+    - "ledger"     always included (idempotent sync)
+
+Extending
+---------
+To add a new step, append one PlanRule to _RULES.  No other file changes.
+
+Public API
+----------
+build_plan(context) -> list[dict]
+    Returns the ordered plan list and writes it to context["plan"].
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+# ---------------------------------------------------------------------------
+# Rule definition
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PlanRule:
+    """
+    A single conditional step in the execution plan.
+
+    Attributes:
+        agent:     Key in AGENT_REGISTRY to execute.
+        condition: callable(ctx) → bool — True means "include this agent".
+        critical:  If True, failure aborts the rest of the pipeline.
+                   If False, failure is logged and execution continues.
+        description: Human-readable reason for this rule (for audit logs).
+    """
+    agent:       str
+    condition:   Callable[[dict[str, Any]], bool]
+    critical:    bool = True
+    description: str  = ""
+
+
+# ---------------------------------------------------------------------------
+# Rule set  (order matters — this IS the pipeline definition)
+# ---------------------------------------------------------------------------
+
+def _intent_needed(ctx: dict[str, Any]) -> bool:
+    """Run intent detection unless intent is already resolved."""
+    return not ctx.get("intent")
+
+
+def _extraction_needed(ctx: dict[str, Any]) -> bool:
+    """Run extraction unless structured data already exists for all detected intents."""
+    if not ctx.get("data") and not ctx.get("multi_data"):
+        return True
+    # On replan: re-extract if intents changed or multi_data is missing entries
+    intents   = ctx.get("intents") or []
+    multi_data = ctx.get("multi_data", {})
+    if intents and any(i not in multi_data for i in intents):
+        return True
+    return False
+
+
+def _validation_needed(ctx: dict[str, Any]) -> bool:
+    """Run validation unless already validated."""
+    return ctx.get("state") != "validated"
+
+
+def _invoice_needed(ctx: dict[str, Any]) -> bool:
+    """Generate an invoice for order workflows when not already present."""
+    return (ctx.get("intent") or "").lower() == "order" and not ctx.get("invoice")
+
+
+def _payment_needed(ctx: dict[str, Any]) -> bool:
+    """Create pending payment state after invoice generation."""
+    return (ctx.get("intent") or "").lower() == "order" and not ctx.get("payment")
+
+
+def _ledger_needed(ctx: dict[str, Any]) -> bool:
+    """
+    Run ledger sync unless the pipeline failed before routing.
+    We still attempt it on partial failures so any partial data is recorded.
+    """
+    return True   # always attempt — LedgerAgent is non-fatal anyway
+
+
+_RULES: list[PlanRule] = [
+    PlanRule(
+        agent       = "intent",
+        condition   = _intent_needed,
+        critical    = True,
+        description = "Classify business intent from message",
+    ),
+    PlanRule(
+        agent       = "extraction",
+        condition   = _extraction_needed,
+        critical    = True,
+        description = "Extract structured fields from message",
+    ),
+    PlanRule(
+        agent       = "validation",
+        condition   = _validation_needed,
+        critical    = True,
+        description = "Normalise and validate extracted data",
+    ),
+    PlanRule(
+        agent       = "invoice_agent",
+        condition   = _invoice_needed,
+        critical    = True,
+        description = "Generate structured invoice from validated data",
+    ),
+    PlanRule(
+        agent       = "payment_agent",
+        condition   = _payment_needed,
+        critical    = True,
+        description = "Prepare pending payment workflow",
+    ),
+    PlanRule(
+        agent       = "ledger",
+        condition   = _ledger_needed,
+        critical    = False,   # Sheets failure must never crash the pipeline
+        description = "Sync transaction to Google Sheets ledger",
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def build_plan(context: dict[str, Any]) -> list[dict[str, Any]]:
+    """
+    Evaluate rules against the current context and produce an execution plan.
+
+    Writes the plan to context["plan"] and also returns it.
+
+    Args:
+        context: The live request context dict.
+
+    Returns:
+        Ordered list of plan steps, each a dict with:
+            {
+                "agent":       str,   # registry key
+                "critical":    bool,  # abort pipeline on failure?
+                "description": str,   # human-readable reason
+            }
+
+    Example:
+        >>> ctx = create_context("rahul ne 15000 bheja")
+        >>> build_plan(ctx)
+        [
+            {"agent": "intent",     "critical": True,  "description": "..."},
+            {"agent": "extraction", "critical": True,  "description": "..."},
+            {"agent": "validation", "critical": True,  "description": "..."},
+            {"agent": "router",     "critical": True,  "description": "..."},
+            {"agent": "ledger",     "critical": False, "description": "..."},
+        ]
+    """
+    plan = []
+    for rule in _RULES:
+        if rule.condition(context):
+            plan.append({
+                "agent":       rule.agent,
+                "critical":    rule.critical,
+                "description": rule.description,
+            })
+    context["plan"] = plan
+    return plan

app/core/priority.py

@@ -0,0 +1,106 @@
+"""
+app/core/priority.py
+---------------------
+Shared priority scoring utilities for NotiFlow Autonomous.
+
+Replaces the single-agent string assignment pattern with an
+additive scoring model.  Any agent can contribute points.
+UrgencyAgent is the sole agent that derives the final label.
+
+Score scale: 0 – 100 (int, clamped)
+    > 70  → "high"
+    > 40  → "medium"
+    ≤ 40  → "low"
+
+Public API
+----------
+contribute_priority_score(ctx, points, reason) -> None
+    Add points to context["priority_score"] and log the reason.
+
+derive_priority_label(ctx) -> str
+    Read context["priority_score"] and return the label string.
+    Also writes context["priority"] = label and returns it.
+
+reset_priority_score(ctx) -> None
+    Zero the score (used at replan boundaries).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_SCORE_KEY   = "priority_score"
+_REASONS_KEY = "priority_score_reasons"
+
+# Thresholds
+_HIGH_THRESHOLD   = 70
+_MEDIUM_THRESHOLD = 40
+
+
+def contribute_priority_score(
+    ctx:    dict[str, Any],
+    points: int,
+    reason: str,
+) -> None:
+    """
+    Add points (0–100 scale) to the running priority score.
+
+    Points are clamped so the total never exceeds 100.
+    The reason is appended to context["priority_score_reasons"] for audit.
+
+    Args:
+        ctx:    The live request context dict.
+        points: Integer contribution (positive only).
+        reason: Human-readable explanation of why this score was added.
+    """
+    if points <= 0:
+        return
+    current = ctx.get(_SCORE_KEY, 0)
+    new_val  = min(100, current + points)
+    ctx[_SCORE_KEY] = new_val
+    ctx.setdefault(_REASONS_KEY, []).append(
+        {"points": points, "reason": reason, "total_after": new_val}
+    )
+    logger.debug(
+        "[Priority] +%d (%s) → total=%d", points, reason, new_val
+    )
+
+
+def derive_priority_label(ctx: dict[str, Any]) -> str:
+    """
+    Derive the final priority label from the accumulated score.
+
+    Writes context["priority"] = label and returns the label.
+
+    Args:
+        ctx: The live request context dict.
+
+    Returns:
+        "high" | "medium" | "low"
+    """
+    score = ctx.get(_SCORE_KEY, 0)
+    if score > _HIGH_THRESHOLD:
+        label = "high"
+    elif score > _MEDIUM_THRESHOLD:
+        label = "medium"
+    else:
+        label = "low"
+    ctx["priority"] = label
+    logger.info(
+        "[Priority] score=%d → label=%s", score, label
+    )
+    return label
+
+
+def reset_priority_score(ctx: dict[str, Any]) -> None:
+    """
+    Reset the priority score to 0 (used at replan boundaries).
+
+    Args:
+        ctx: The live request context dict.
+    """
+    ctx[_SCORE_KEY]   = 0
+    ctx[_REASONS_KEY] = []

app/core/registry.py

@@ -0,0 +1,136 @@
+"""
+app/core/registry.py
+--------------------
+Agent Registry for NotiFlow Autonomous.
+
+Single source of truth for all registered agents.
+The orchestrator resolves agent names from this registry — it never
+imports agent classes directly.
+
+Extending the system
+--------------------
+To add a new agent:
+    1. Create app/agents/my_agent.py (subclass BaseAgent)
+    2. Add one line here:  "my_agent": MyAgent()
+
+That's it. The planner and orchestrator pick it up automatically as
+long as the planner emits the agent's key in a plan step.
+
+Public API
+----------
+AGENT_REGISTRY : dict[str, BaseAgent]
+    The live registry dict. Import and use directly.
+
+get_agent(name) -> BaseAgent
+    Safe accessor — raises KeyError with a helpful message if missing.
+
+register(name, agent) -> None
+    Runtime registration (useful for plugins / tests).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.core.base_agent import BaseAgent
+
+# ---------------------------------------------------------------------------
+# Lazy imports — prevents circular import chains at module load time
+# ---------------------------------------------------------------------------
+
+def _build_registry() -> dict[str, "BaseAgent"]:
+    from app.agents.intent_agent        import IntentAgent
+    from app.agents.extraction_agent    import ExtractionAgent
+    from app.agents.validation_agent    import ValidationAgent
+    from app.agents.invoice_agent       import InvoiceAgent
+    from app.agents.payment_agent       import PaymentAgent
+    from app.agents.skill_router_agent  import SkillRouterAgent
+    from app.agents.ledger_agent        import LedgerAgent
+    # ── Phase 3: Autonomy Layer ──────────────────────────────────────────────
+    from app.agents.verification_agent  import VerificationAgent
+    from app.agents.monitor_agent       import MonitorAgent
+    from app.agents.prediction_agent    import PredictionAgent
+    from app.agents.urgency_agent       import UrgencyAgent
+    from app.agents.escalation_agent    import EscalationAgent
+    from app.agents.recovery_agent      import RecoveryAgent
+
+    return {
+        # Core pipeline agents
+        "intent":       IntentAgent(),
+        "extraction":   ExtractionAgent(),
+        "validation":   ValidationAgent(),
+        "invoice_agent": InvoiceAgent(),
+        "payment_agent": PaymentAgent(),
+        "router":       SkillRouterAgent(),
+        "ledger":       LedgerAgent(),
+        # Autonomy layer agents
+        "verification": VerificationAgent(),
+        "monitor":      MonitorAgent(),
+        "prediction":   PredictionAgent(),
+        "urgency":      UrgencyAgent(),
+        "escalation":   EscalationAgent(),
+        "recovery":     RecoveryAgent(),
+    }
+
+
+# Module-level registry — built once on first access via get_agent()
+# Direct dict access also works: AGENT_REGISTRY["intent"]
+AGENT_REGISTRY: dict[str, "BaseAgent"] = {}
+
+_initialised = False
+
+
+def _ensure_init() -> None:
+    global _initialised
+    if not _initialised:
+        AGENT_REGISTRY.update(_build_registry())
+        _initialised = True
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def get_agent(name: str) -> "BaseAgent":
+    """
+    Retrieve an agent by registry key.
+
+    Args:
+        name: Agent key (e.g. "intent", "extraction", "ledger").
+
+    Returns:
+        The registered BaseAgent instance.
+
+    Raises:
+        KeyError: If no agent is registered under that name, with a
+                  helpful message listing valid keys.
+    """
+    _ensure_init()
+    if name not in AGENT_REGISTRY:
+        valid = ", ".join(sorted(AGENT_REGISTRY.keys()))
+        raise KeyError(
+            f"No agent registered as '{name}'. "
+            f"Valid keys: {valid}"
+        )
+    return AGENT_REGISTRY[name]
+
+
+def register(name: str, agent: "BaseAgent") -> None:
+    """
+    Register a new agent (or replace an existing one) at runtime.
+
+    Useful for plugins, testing, and dynamic skill agents.
+
+    Args:
+        name:  Registry key (e.g. "my_custom_agent").
+        agent: Instantiated BaseAgent subclass.
+    """
+    _ensure_init()
+    AGENT_REGISTRY[name] = agent
+
+
+def list_agents() -> list[str]:
+    """Return sorted list of all registered agent keys."""
+    _ensure_init()
+    return sorted(AGENT_REGISTRY.keys())

app/main.py

@@ -0,0 +1,198 @@
+"""
+app/main.py
+-----------
+Primary entry point for NotiFlow Autonomous.
+
+Public API (UNCHANGED — backward compatible):
+    run_notiflow(message, demo_mode, source) -> dict
+
+Changes from original:
+    - Live mode now calls app.core.orchestrator.process_message()
+      instead of agent.orchestrator.process_message()
+    - Demo mode is unchanged (same static responses + keyword fallback)
+    - Bedrock references removed entirely
+    - Context is created here in live mode and flows through pipeline
+
+CLI usage (unchanged):
+    python app/main.py "rahul ne 15000 bheja"
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any
+
+from app.config import DEMO_MODE
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Demo pipeline (no cloud credentials needed)
+# ---------------------------------------------------------------------------
+
+_DEMO_RESPONSES: dict[str, dict] = {
+    "rahul ne 15000 bheja": {
+        "intent": "payment",
+        "data":   {"customer": "Rahul", "amount": 15000, "payment_type": None},
+        "event":  {"event": "payment_recorded",
+                   "payment": {"customer": "Rahul", "amount": 15000,
+                               "payment_type": None, "status": "received"}},
+    },
+    "bhaiya 3 kurti bhej dena": {
+        "intent": "order",
+        "data":   {"customer": None, "item": "kurti", "quantity": 3},
+        "event":  {"event": "order_received",
+                   "order":  {"customer": None, "item": "kurti",
+                              "quantity": 3, "status": "pending"},
+                   "invoice": {"invoice_id": "INV-DEMO-0001", "total_amount": 0.0}},
+    },
+    "priya ke liye 2 kilo aata bhej dena": {
+        "intent": "order",
+        "data":   {"customer": "Priya", "item": "aata", "quantity": 2},
+        "event":  {"event": "order_received",
+                   "order":  {"customer": "Priya", "item": "aata",
+                              "quantity": 2, "status": "pending"},
+                   "invoice": {"invoice_id": "INV-DEMO-0002", "total_amount": 0.0}},
+    },
+    "size chota hai exchange karna hai": {
+        "intent": "return",
+        "data":   {"customer": None, "item": None, "reason": "size issue"},
+        "event":  {"event": "return_requested",
+                   "return": {"customer": None, "item": None,
+                              "reason": "size issue", "status": "pending_review"}},
+    },
+    "udhar me de dijiye": {
+        "intent": "credit",
+        "data":   {"customer": None, "item": None, "quantity": None, "amount": None},
+        "event":  {"event": "credit_recorded",
+                   "credit": {"customer": None, "amount": None, "status": "open"}},
+    },
+    "suresh ko 500 ka maal udhar dena": {
+        "intent": "credit",
+        "data":   {"customer": "Suresh", "item": "goods", "quantity": None, "amount": 500},
+        "event":  {"event": "credit_recorded",
+                   "credit": {"customer": "Suresh", "amount": 500, "status": "open"}},
+    },
+    "3 kurti ka set ready rakhna": {
+        "intent": "preparation",
+        "data":   {"item": "kurti", "quantity": 3},
+        "event":  {"event": "preparation_queued",
+                   "preparation": {"item": "kurti", "quantity": 3, "status": "queued"}},
+    },
+    "amit bhai ka 8000 gpay se aaya": {
+        "intent": "payment",
+        "data":   {"customer": "Amit", "amount": 8000, "payment_type": "upi"},
+        "event":  {"event": "payment_recorded",
+                   "payment": {"customer": "Amit", "amount": 8000,
+                               "payment_type": "upi", "status": "received"}},
+    },
+}
+
+
+def _fallback_intent(message: str) -> str:
+    m = message.lower()
+    if any(w in m for w in ["bheja", "aaya", "cash", "gpay", "upi", "paytm", "online"]):
+        return "payment"
+    if any(w in m for w in ["exchange", "wapas", "return", "vapas", "size"]):
+        return "return"
+    if any(w in m for w in ["udhar", "credit", "baad"]):
+        return "credit"
+    if any(w in m for w in ["ready", "pack", "rakhna", "taiyar"]):
+        return "preparation"
+    if any(w in m for w in ["bhej", "dena", "chahiye", "kilo", "piece"]):
+        return "order"
+    return "other"
+
+
+def _run_demo(message: str, source: str = "system") -> dict[str, Any]:
+    key      = message.strip().lower()
+    response = _DEMO_RESPONSES.get(key)
+    if response is None:
+        intent   = _fallback_intent(message)
+        response = {
+            "intent": intent,
+            "data":   {"note": f"Demo: classified as '{intent}'"},
+            "event":  {"event": f"{intent}_recorded",
+                       "note":  "Demo fallback — no exact match"},
+        }
+
+    from app.services.google_sheets_service import append_transaction
+    sheet_updated = append_transaction(
+        intent=response["intent"],
+        data=response["data"],
+        source=source,
+    )
+
+    return {
+        "message":       message,
+        "intent":        response["intent"],
+        "data":          response["data"],
+        "event":         response["event"],
+        "sheet_updated": sheet_updated,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def run_notiflow(
+    message:   str,
+    demo_mode: bool | None = None,
+    source:    str = "system",
+) -> dict[str, Any]:
+    """
+    Run a business message through the full NotiFlow pipeline.
+
+    .. deprecated::
+        The API layer (notification_routes.py) now calls
+        ``app.core.orchestrator.process_message()`` directly.
+        ``run_notiflow`` is kept for:
+          - Demo mode (static responses + keyword fallback)
+          - CLI usage  (python app/main.py "...")
+          - Backward-compat tests that mock it
+
+        New code should use ``process_message()`` directly.
+
+    Args:
+        message:   Raw Hinglish or English business message.
+        demo_mode: Override DEMO_MODE from config. None = use config value.
+        source:    Notification source (e.g. "whatsapp", "gpay").
+    """
+    if not message or not message.strip():
+        raise ValueError("Message cannot be empty.")
+
+    use_demo = DEMO_MODE if demo_mode is None else demo_mode
+
+    if use_demo:
+        logger.info("run_notiflow [demo] ← %r", message)
+        return _run_demo(message.strip(), source=source)
+    else:
+        logger.info("run_notiflow [live] ← %r", message)
+        # ── NEW: use context-driven orchestrator ─────────────────────────────
+        from app.core.orchestrator import process_message
+        return process_message(message.strip(), source=source)
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.WARNING)
+
+    if len(sys.argv) < 2:
+        print('Usage: python app/main.py "<business message>"')
+        sys.exit(1)
+
+    input_message = " ".join(sys.argv[1:])
+    try:
+        result = run_notiflow(input_message)
+        # Strip context from CLI output to keep it readable
+        result.pop("context", None)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    except Exception as exc:
+        print(json.dumps({"error": str(exc)}, indent=2))
+        sys.exit(1)

app/memory/__init__.py

@@ -0,0 +1 @@
+"""app/memory — agent context memory."""

app/memory/agent_memory.py

@@ -0,0 +1,145 @@
+"""
+agent_memory.py
+---------------
+Agent memory layer for Notiflow.
+
+Stores recent business context so skills and future agents can reference
+what was last discussed (customer names, items, etc.).
+
+Storage: JSON file at the path defined in app/config.py (MEMORY_FILE).
+Structure:
+    {
+        "recent_customers": ["Rahul", "Priya"],   # newest last
+        "recent_items":     ["kurti", "aata"]
+    }
+
+Public API
+----------
+load_memory()  -> dict
+update_memory(customer=None, item=None) -> None
+
+Design notes:
+  - Maximum 10 entries per list (oldest pruned automatically).
+  - Read-modify-write is done in one function call to minimise race window.
+  - None values are silently ignored (no-op).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from app.config import MEMORY_FILE
+
+logger = logging.getLogger(__name__)
+
+_MAX_ENTRIES = 10
+
+_EMPTY_MEMORY: dict = {
+    "recent_customers": [],
+    "recent_items":     [],
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _read_file() -> dict:
+    """Read memory from disk; return empty structure if file missing/corrupt."""
+    path = Path(MEMORY_FILE)
+    if not path.exists():
+        return {k: list(v) for k, v in _EMPTY_MEMORY.items()}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        # Ensure both keys are present even if file is partial
+        data.setdefault("recent_customers", [])
+        data.setdefault("recent_items", [])
+        return data
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Could not read memory file (%s) — using empty memory.", exc)
+        return {k: list(v) for k, v in _EMPTY_MEMORY.items()}
+
+
+def _write_file(memory: dict) -> None:
+    """Write memory dict to disk atomically (write to temp then rename)."""
+    path    = Path(MEMORY_FILE)
+    tmp     = path.with_suffix(".tmp")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tmp.open("w", encoding="utf-8") as f:
+            json.dump(memory, f, indent=2, ensure_ascii=False)
+        tmp.replace(path)
+    except OSError as exc:
+        logger.error("Could not write memory file: %s", exc)
+        if tmp.exists():
+            tmp.unlink(missing_ok=True)
+
+
+def _append_unique(lst: list, value: str, max_size: int = _MAX_ENTRIES) -> list:
+    """
+    Append value to list, deduplicate, and keep only the most recent entries.
+    Most recent item is always at the end.
+    """
+    if value in lst:
+        lst.remove(value)          # remove old occurrence so it moves to end
+    lst.append(value)
+    return lst[-max_size:]         # keep newest max_size entries
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def load_memory() -> dict:
+    """
+    Load the current agent memory from disk.
+
+    Returns:
+        {
+            "recent_customers": [str, ...],
+            "recent_items":     [str, ...]
+        }
+    """
+    memory = _read_file()
+    logger.debug("Memory loaded: %s", memory)
+    return memory
+
+
+def update_memory(
+    customer: Optional[str] = None,
+    item:     Optional[str] = None,
+) -> None:
+    """
+    Update agent memory with a new customer name and/or item.
+
+    None values are silently ignored.
+    Duplicates are deduplicated and moved to the end (most recent position).
+
+    Args:
+        customer: Customer name to remember (e.g. "Rahul").
+        item:     Item name to remember (e.g. "kurti").
+
+    Example:
+        >>> update_memory(customer="Rahul", item="kurti")
+    """
+    if customer is None and item is None:
+        return
+
+    memory = _read_file()
+
+    if customer:
+        memory["recent_customers"] = _append_unique(
+            memory["recent_customers"], str(customer).strip()
+        )
+
+    if item:
+        memory["recent_items"] = _append_unique(
+            memory["recent_items"], str(item).strip()
+        )
+
+    _write_file(memory)
+    logger.info("Memory updated: customer=%s item=%s", customer, item)

app/services/__init__.py

@@ -0,0 +1 @@
+"""app/services — external integrations and stateless business services."""

app/services/excel_sync.py

@@ -0,0 +1,210 @@
+"""
+services/excel_sync.py
+----------------------
+Semantic Excel sync wrapper for Notiflow.
+
+Wraps utils/excel_writer.append_row() with business-named functions so
+skills and the FastAPI backend can call append_order(), append_payment()
+etc. without knowing the sheet schema details.
+
+Excel writes always go to EXCEL_SYNC_FILE from app/config.py.
+If EXCEL_FILE_PATH env var is set, that path is used; otherwise falls
+back to the default DATA_FILE path (data/notiflow_data.xlsx).
+
+No Excel writing logic is duplicated here — this is a thin adapter only.
+
+Public API
+----------
+append_order(event_dict)    — writes to Orders sheet
+append_payment(event_dict)  — writes to Ledger sheet (type="payment")
+append_return(event_dict)   — writes to Returns sheet
+append_credit(event_dict)   — writes to Ledger sheet (type="credit")
+append_inventory(record)    — writes to Inventory sheet
+append_invoice(record)      — writes to Invoices sheet
+sync_from_event(result)     — auto-routes based on intent (convenience)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from app.config import EXCEL_SYNC_FILE
+from app.utils.excel_writer import append_row, EXCEL_FILE as _DEFAULT_FILE
+
+logger = logging.getLogger(__name__)
+
+
+def _active_file() -> Path:
+    """
+    Return the active Excel file path.
+    EXCEL_SYNC_FILE (from env EXCEL_FILE_PATH) takes priority over default.
+    """
+    return Path(EXCEL_SYNC_FILE)
+
+
+# ---------------------------------------------------------------------------
+# Sheet-specific append functions
+# ---------------------------------------------------------------------------
+
+def append_order(event_dict: dict) -> None:
+    """
+    Append an order record to the Orders sheet.
+
+    Args:
+        event_dict: The "order" sub-dict from an order skill event.
+                    Expected keys: order_id, timestamp, customer, item,
+                                   quantity, status
+    """
+    record = {
+        "order_id":  event_dict.get("order_id"),
+        "timestamp": event_dict.get("timestamp"),
+        "customer":  event_dict.get("customer"),
+        "item":      event_dict.get("item"),
+        "quantity":  event_dict.get("quantity"),
+        "status":    event_dict.get("status", "pending"),
+    }
+    append_row("Orders", record)
+    logger.info("Excel sync → Orders: %s", record.get("order_id"))
+
+
+def append_payment(event_dict: dict) -> None:
+    """
+    Append a payment record to the Ledger sheet.
+
+    Args:
+        event_dict: The "payment" sub-dict from a payment skill event.
+                    Expected keys: entry_id, timestamp, customer,
+                                   amount, payment_type, status
+    """
+    record = {
+        "entry_id":     event_dict.get("entry_id"),
+        "timestamp":    event_dict.get("timestamp"),
+        "type":         "payment",
+        "customer":     event_dict.get("customer"),
+        "item":         None,
+        "quantity":     None,
+        "amount":       event_dict.get("amount"),
+        "payment_type": event_dict.get("payment_type"),
+        "status":       event_dict.get("status", "received"),
+    }
+    append_row("Ledger", record)
+    logger.info("Excel sync → Ledger (payment): customer=%s", record.get("customer"))
+
+
+def append_return(event_dict: dict) -> None:
+    """
+    Append a return record to the Returns sheet.
+
+    Args:
+        event_dict: The "return" sub-dict from a return skill event.
+                    Expected keys: return_id, timestamp, customer,
+                                   item, reason, status
+    """
+    record = {
+        "return_id": event_dict.get("return_id"),
+        "timestamp": event_dict.get("timestamp"),
+        "customer":  event_dict.get("customer"),
+        "item":      event_dict.get("item"),
+        "reason":    event_dict.get("reason"),
+        "status":    event_dict.get("status", "pending_review"),
+    }
+    append_row("Returns", record)
+    logger.info("Excel sync → Returns: %s", record.get("return_id"))
+
+
+def append_credit(event_dict: dict) -> None:
+    """
+    Append a credit (udhar) record to the Ledger sheet.
+
+    Args:
+        event_dict: The "credit" sub-dict from a credit skill event.
+    """
+    record = {
+        "entry_id":     event_dict.get("entry_id"),
+        "timestamp":    event_dict.get("timestamp"),
+        "type":         "credit",
+        "customer":     event_dict.get("customer"),
+        "item":         event_dict.get("item"),
+        "quantity":     event_dict.get("quantity"),
+        "amount":       event_dict.get("amount"),
+        "payment_type": None,
+        "status":       event_dict.get("status", "open"),
+    }
+    append_row("Ledger", record)
+    logger.info("Excel sync → Ledger (credit): customer=%s", record.get("customer"))
+
+
+def append_inventory(record: dict) -> None:
+    """
+    Append a stock movement record to the Inventory sheet.
+
+    Args:
+        record: Dict with keys: timestamp, item, change, direction,
+                                reference_id, note
+    """
+    append_row("Inventory", record)
+    logger.info(
+        "Excel sync → Inventory: %s %s (%s)",
+        record.get("direction"), record.get("item"), record.get("change"),
+    )
+
+
+def append_invoice(record: dict) -> None:
+    """
+    Append an invoice record to the Invoices sheet.
+
+    Args:
+        record: Invoice dict from invoice_service.generate_invoice().
+    """
+    append_row("Invoices", record)
+    logger.info("Excel sync → Invoices: %s", record.get("invoice_id"))
+
+
+# ---------------------------------------------------------------------------
+# Convenience router — auto-dispatches based on orchestrator result intent
+# ---------------------------------------------------------------------------
+
+def sync_from_event(result: dict) -> None:
+    """
+    Automatically sync an orchestrator result to the correct Excel sheet(s).
+
+    Called by the FastAPI notification handler after skill execution so
+    the ledger is always up to date without skills needing to know about
+    the sync layer.
+
+    Note: Skills already write to Excel internally (Stages 5-6).
+    This function provides a secondary sync point for the FastAPI path
+    when skills are called via run_notiflow() in demo mode (where skills
+    don't execute and nothing is written). In live mode, this is a no-op
+    safety net — duplicate rows are avoided by checking event type.
+
+    Args:
+        result: Full orchestrator result dict
+                {message, intent, data, event}
+    """
+    intent = result.get("intent", "other")
+    event  = result.get("event", {})
+    event_name = event.get("event", "")
+
+    # In live mode the skill already wrote to Excel — skip to avoid duplicates.
+    # We only sync here if the result came from demo mode (event has no IDs).
+    order_data   = event.get("order")
+    payment_data = event.get("payment")
+    return_data  = event.get("return")
+    credit_data  = event.get("credit")
+
+    if intent == "order" and order_data and order_data.get("order_id"):
+        # Already written by skill — skip
+        logger.debug("sync_from_event: order already persisted by skill, skipping.")
+    elif intent == "payment" and payment_data and payment_data.get("entry_id"):
+        logger.debug("sync_from_event: payment already persisted by skill, skipping.")
+    elif intent == "return" and return_data and return_data.get("return_id"):
+        logger.debug("sync_from_event: return already persisted by skill, skipping.")
+    elif intent == "credit" and credit_data and credit_data.get("entry_id"):
+        logger.debug("sync_from_event: credit already persisted by skill, skipping.")
+    else:
+        logger.debug(
+            "sync_from_event: demo mode result or missing IDs — "
+            "no additional Excel write needed."
+        )

app/services/gemini_client.py

@@ -0,0 +1,184 @@
+"""
+models/gemini_client.py
+-----------------------
+Gemini API client for Notiflow.
+
+Serves two distinct roles:
+
+  1. FALLBACK REASONER — used by ModelRouter when Nova is unavailable.
+     generate(prompt) returns a plain-text response that must match
+     Nova's JSON output schema exactly (enforced by the prompt).
+
+  2. NOTIFICATION GENERATOR — used by notification_generator.py to
+     produce realistic Hinglish business notifications for demo mode.
+     generate_notifications(n) returns a list of notification dicts.
+
+Configuration
+-------------
+  GEMINI_API_KEY — from .env / environment variable
+
+Dependencies
+------------
+  pip install google-generativeai
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from app.config import GEMINI_API_KEY
+
+logger = logging.getLogger(__name__)
+
+# Gemini model to use — flash is fast and sufficient for this use case
+_GEMINI_MODEL = "gemini-2.5-flash"
+
+_client = None  # lazy singleton
+
+
+def _get_client():
+    """Return a cached Gemini GenerativeModel instance."""
+    global _client
+    if _client is not None:
+        return _client
+
+    if not GEMINI_API_KEY:
+        raise RuntimeError(
+            "GEMINI_API_KEY is not set. "
+            "Add it to your .env file: GEMINI_API_KEY=your_key_here"
+        )
+
+    try:
+        import google.generativeai as genai
+        genai.configure(api_key=GEMINI_API_KEY)
+        _client = genai.GenerativeModel(_GEMINI_MODEL)
+        logger.info("Gemini client initialised (model=%s)", _GEMINI_MODEL)
+        return _client
+    except ImportError:
+        raise RuntimeError(
+            "google-generativeai is not installed. "
+            "Run: pip install google-generativeai"
+        )
+    except Exception as exc:
+        raise RuntimeError(f"Failed to initialise Gemini client: {exc}") from exc
+
+
+def _strip_fences(text: str) -> str:
+    """Strip markdown code fences from model output."""
+    return re.sub(r"```(?:json)?|```", "", text).strip()
+
+
+# ---------------------------------------------------------------------------
+# Public API — Role 1: Fallback reasoner for ModelRouter
+# ---------------------------------------------------------------------------
+
+def generate(prompt: str) -> str:
+    """
+    Send a prompt to Gemini and return the raw text response.
+
+    Used by ModelRouter as a Nova fallback. The prompt already instructs
+    the model to return JSON — this function returns the raw string and
+    lets the caller parse it.
+
+    Args:
+        prompt: Fully rendered prompt (same prompt sent to Nova).
+
+    Returns:
+        Raw text response from Gemini (may contain JSON).
+
+    Raises:
+        RuntimeError: If the API call fails or client cannot be initialised.
+    """
+    client = _get_client()
+    try:
+        response = client.generate_content(prompt)
+        raw = response.text or ""
+        logger.debug("Gemini raw response: %r", raw[:200])
+        return _strip_fences(raw)
+    except Exception as exc:
+        logger.error("Gemini generate() failed: %s", exc)
+        raise RuntimeError(f"Gemini API error: {exc}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Public API — Role 2: Notification generator
+# ---------------------------------------------------------------------------
+
+_NOTIFICATION_PROMPT = """
+You are simulating incoming business notifications for a small business in India.
+
+Generate {n} realistic business notifications in Hinglish (Hindi + English mix).
+
+Each notification must come from one of these sources:
+- whatsapp   (informal text from customers or suppliers)
+- payment    (UPI payment confirmation message)
+- amazon     (marketplace order or return notification)
+- return     (customer return or exchange request)
+
+Each notification must represent ONE of these business events:
+- An order for a product (item name + quantity)
+- A payment received (person name + amount)
+- A credit/udhar request
+- A return or exchange request
+- A preparation/packing request
+
+Rules:
+- Use natural Hinglish phrasing. Not too formal.
+- Vary sources and event types.
+- Include real-sounding names (Rahul, Priya, Suresh, Amit, etc.)
+- Include real product names (kurti, aata, daal, saree, etc.)
+- Do NOT include any explanation or preamble.
+- Return ONLY a valid JSON array, nothing else.
+
+Output format (JSON array only, no markdown):
+[
+  {{"source": "whatsapp", "message": "bhaiya 3 kurti bhej dena"}},
+  {{"source": "payment", "message": "Rahul ne 15000 bheja UPI se"}}
+]
+"""
+
+
+def generate_notifications(n: int = 5) -> list[dict[str, str]]:
+    """
+    Generate n realistic Hinglish business notifications via Gemini.
+
+    Args:
+        n: Number of notifications to generate (default 5).
+
+    Returns:
+        List of dicts with keys "source" and "message".
+        Returns an empty list if generation fails (non-fatal).
+
+    Example:
+        >>> generate_notifications(3)
+        [
+            {"source": "whatsapp", "message": "bhaiya 3 kurti bhej dena"},
+            {"source": "payment",  "message": "Rahul ne 15000 bheja"},
+            {"source": "return",   "message": "size chota hai exchange karna hai"},
+        ]
+    """
+    prompt = _NOTIFICATION_PROMPT.format(n=n)
+    try:
+        raw  = generate(prompt)
+        data = json.loads(raw)
+        if not isinstance(data, list):
+            logger.warning("Gemini notification response was not a list: %s", type(data))
+            return []
+        # Validate each entry has required keys
+        valid = [
+            item for item in data
+            if isinstance(item, dict)
+            and "source"  in item
+            and "message" in item
+        ]
+        logger.info("Generated %d notifications via Gemini", len(valid))
+        return valid
+    except json.JSONDecodeError as exc:
+        logger.warning("Could not parse Gemini notification output as JSON: %s", exc)
+        return []
+    except Exception as exc:
+        logger.warning("generate_notifications failed: %s", exc)
+        return []

app/services/google_sheets_service.py

@@ -0,0 +1,140 @@
+"""
+services/google_sheets_service.py
+---------------------------------
+Google Sheets ledger integration for Notiflow.
+
+Appends a row to the configured Google Sheet every time a notification
+is processed.  Uses a service-account JSON file for authentication.
+
+Environment variables (loaded via python-dotenv):
+    GOOGLE_SHEETS_CREDENTIALS  — path to the service-account JSON file
+    GOOGLE_SHEET_ID            — the Sheet key (from the URL)
+
+Row structure:
+    [intent, item, quantity, customer, amount, source, timestamp]
+
+If the Sheets API is unreachable or misconfigured, the service logs
+the error and returns False — it NEVER crashes the pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Lazy-loaded module-level client
+# ---------------------------------------------------------------------------
+
+_sheet = None          # gspread.Worksheet (first sheet)
+_initialised = False   # True after first attempt
+
+
+def _get_sheet():
+    """
+    Lazy-initialise the gspread worksheet.
+
+    Returns the worksheet on success, or None if credentials / sheet ID
+    are missing or invalid.
+    """
+    global _sheet, _initialised
+
+    if _initialised:
+        return _sheet
+
+    _initialised = True
+
+    try:
+        import gspread
+        from google.oauth2.service_account import Credentials
+    except ImportError as exc:
+        logger.warning("Google Sheets libraries not installed (%s). "
+                       "Install gspread and google-auth.", exc)
+        return None
+
+    creds_path = os.getenv("GOOGLE_SHEETS_CREDENTIALS", "credentials/sheets.json")
+    sheet_id   = os.getenv("GOOGLE_SHEET_ID", "")
+
+    if not sheet_id:
+        logger.warning("GOOGLE_SHEET_ID not set — Sheets sync disabled.")
+        return None
+
+    # Resolve relative path from project root
+    creds_file = Path(creds_path)
+    if not creds_file.is_absolute():
+        creds_file = Path(__file__).parent.parent / creds_file
+
+    if not creds_file.exists():
+        logger.warning("Google credentials file not found at %s", creds_file)
+        return None
+
+    try:
+        scopes = [
+            "https://www.googleapis.com/auth/spreadsheets",
+            "https://www.googleapis.com/auth/drive",
+        ]
+        credentials = Credentials.from_service_account_file(
+            str(creds_file), scopes=scopes,
+        )
+        client = gspread.authorize(credentials)
+        spreadsheet = client.open_by_key(sheet_id)
+        _sheet = spreadsheet.sheet1          # first worksheet
+        logger.info("Google Sheets connected: %s", spreadsheet.title)
+        return _sheet
+    except Exception as exc:
+        logger.error("Failed to connect to Google Sheets: %s", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def append_transaction(
+    intent: str,
+    data: dict[str, Any],
+    source: str = "system",
+) -> bool:
+    """
+    Append a ledger row to the configured Google Sheet.
+
+    Args:
+        intent:  Detected intent (e.g. "order", "payment").
+        data:    Validated entity dict from the extraction agent.
+        source:  Notification source (e.g. "whatsapp", "gpay").
+
+    Returns:
+        True if the row was written successfully, False otherwise.
+    """
+    ws = _get_sheet()
+    if ws is None:
+        logger.warning("Google Sheets update skipped — not connected.")
+        return False
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
+
+    row = [
+        intent,
+        str(data.get("item", "")),
+        str(data.get("quantity", "")),
+        str(data.get("customer", "")),
+        str(data.get("amount", "")),
+        source,
+        timestamp,
+    ]
+
+    # Defensive padding — always exactly 7 columns to prevent column drift
+    row = (row + [""] * 7)[:7]
+
+    try:
+        ws.append_row(row, value_input_option="USER_ENTERED", table_range="A1")
+        logger.info("Google Sheets ledger updated successfully")
+        return True
+    except Exception as exc:
+        logger.error("Google Sheets update failed: %s", exc)
+        return False

app/services/inventory_service.py

@@ -0,0 +1,146 @@
+"""
+inventory_service.py
+--------------------
+Stage 6: Inventory Service for Notiflow
+
+Tracks stock movements as a delta log in the Inventory Excel sheet.
+Each event appends one row recording what changed, by how much,
+and in which direction (in / out).
+
+Design: delta-log (not current-stock snapshot)
+    - Every inventory change is a new row
+    - Current stock for an item = sum of all deltas for that item
+    - This keeps the history intact and avoids row-update complexity
+
+Directions:
+    "out"  — stock leaves (order fulfilled)
+    "in"   — stock arrives (return accepted, restock)
+"""
+
+import logging
+from datetime import datetime, timezone
+
+from app.utils.excel_writer import append_row, read_sheet
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def deduct_stock(item: str, quantity: int | float, reference_id: str, note: str = "") -> dict:
+    """
+    Record a stock deduction (items going out — e.g. an order is fulfilled).
+
+    Args:
+        item:         Name of the inventory item.
+        quantity:     Number of units being deducted.
+        reference_id: ID of the triggering record (e.g. order_id, invoice_id).
+        note:         Optional human-readable note.
+
+    Returns:
+        The inventory movement record that was persisted.
+
+    Example:
+        >>> deduct_stock("kurti", 3, "ORD-20240115-0001", "order fulfilled")
+        {
+            "timestamp": "...",
+            "item": "kurti",
+            "change": 3,
+            "direction": "out",
+            "reference_id": "ORD-20240115-0001",
+            "note": "order fulfilled"
+        }
+    """
+    if quantity is None or quantity <= 0:
+        logger.warning("deduct_stock called with invalid quantity: %s", quantity)
+        return {}
+
+    record = {
+        "timestamp":    _now_iso(),
+        "item":         item,
+        "change":       quantity,
+        "direction":    "out",
+        "reference_id": reference_id,
+        "note":         note or "stock deducted",
+    }
+
+    append_row("Inventory", record)
+    logger.info("Stock deducted: %s × %s (ref: %s)", quantity, item, reference_id)
+    return record
+
+
+def add_stock(item: str, quantity: int | float, reference_id: str, note: str = "") -> dict:
+    """
+    Record a stock addition (items coming in — e.g. a return is accepted).
+
+    Args:
+        item:         Name of the inventory item.
+        quantity:     Number of units being added.
+        reference_id: ID of the triggering record (e.g. return_id).
+        note:         Optional human-readable note.
+
+    Returns:
+        The inventory movement record that was persisted.
+    """
+    if quantity is None or quantity <= 0:
+        logger.warning("add_stock called with invalid quantity: %s", quantity)
+        return {}
+
+    record = {
+        "timestamp":    _now_iso(),
+        "item":         item,
+        "change":       quantity,
+        "direction":    "in",
+        "reference_id": reference_id,
+        "note":         note or "stock added",
+    }
+
+    append_row("Inventory", record)
+    logger.info("Stock added: %s × %s (ref: %s)", quantity, item, reference_id)
+    return record
+
+
+def get_stock_level(item: str) -> int | float:
+    """
+    Calculate the current stock level for an item by summing all deltas.
+
+    Args:
+        item: Name of the inventory item (case-insensitive match).
+
+    Returns:
+        Net stock level (int or float). Returns 0 if no records found.
+
+    Example:
+        >>> get_stock_level("kurti")
+        47
+    """
+    df = read_sheet("Inventory")
+
+    if df.empty or "item" not in df.columns:
+        return 0
+
+    item_rows = df[df["item"].str.lower() == item.lower()]
+
+    if item_rows.empty:
+        return 0
+
+    total = 0
+    for _, row in item_rows.iterrows():
+        change    = row.get("change", 0) or 0
+        direction = row.get("direction", "out")
+        if direction == "in":
+            total += change
+        else:
+            total -= change
+
+    return max(total, 0)   # Stock can't go below 0 in the display

app/services/invoice_service.py

@@ -0,0 +1,98 @@
+"""
+invoice_service.py
+------------------
+Invoice generation service for Notiflow.
+
+Responsibility: build a structured invoice object only.
+Excel persistence is handled separately by the skill layer.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_CATALOG_PRICES: dict[str, float] = {
+    "sugar": 50.0,
+    "atta": 50.0,
+    "rice": 60.0,
+    "kurti": 50.0,
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _make_invoice_id() -> str:
+    return f"INV-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}"
+
+
+class InvoiceBuilder:
+    """Create normalized invoice payloads from item, quantity, and optional price."""
+
+    def __init__(self, catalog_prices: dict[str, float] | None = None):
+        self.catalog_prices = catalog_prices or _CATALOG_PRICES
+
+    def build(
+        self,
+        *,
+        customer: Optional[str],
+        item: Optional[str],
+        quantity: Optional[int | float],
+        price: Optional[float] = None,
+        order_id: Optional[str] = None,
+    ) -> dict:
+        invoice_id = _make_invoice_id()
+        normalized_item = (item or "").strip() or None
+        qty = quantity or 0
+        unit_price = self._resolve_price(normalized_item, price)
+        total_amount = round(float(qty) * unit_price, 2)
+
+        invoice = {
+            "id": invoice_id,
+            "invoice_id": invoice_id,
+            "timestamp": _now_iso(),
+            "order_id": order_id,
+            "customer": customer,
+            "items": [{"name": normalized_item, "qty": qty, "price": unit_price}],
+            "item": normalized_item,
+            "quantity": quantity,
+            "unit_price": unit_price,
+            "total": total_amount,
+            "total_amount": total_amount,
+            "status": "pending",
+        }
+
+        logger.info(
+            "Invoice generated: %s | customer=%s item=%s qty=%s total=%.2f",
+            invoice_id, customer, normalized_item, quantity, total_amount,
+        )
+        return invoice
+
+    def _resolve_price(self, item: str | None, override_price: Optional[float]) -> float:
+        if override_price is not None:
+            return float(override_price)
+        if not item:
+            return 50.0
+        return float(self.catalog_prices.get(item.lower(), 50.0))
+
+
+def generate_invoice(
+    customer: Optional[str],
+    item: Optional[str],
+    quantity: Optional[int | float],
+    unit_price: float = 50.0,
+    order_id: Optional[str] = None,
+) -> dict:
+    builder = InvoiceBuilder()
+    return builder.build(
+        customer=customer,
+        item=item,
+        quantity=quantity,
+        price=unit_price,
+        order_id=order_id,
+    )

app/services/notification_generator.py

@@ -0,0 +1,109 @@
+"""
+services/notification_generator.py
+-----------------------------------
+Gemini-powered business notification generator for Notiflow.
+
+Purpose: generate realistic Hinglish business notifications for demo
+automation. This is entirely optional — the frontend simulation continues
+to work independently.
+
+Two modes:
+  1. Live Gemini generation  — calls Gemini API (requires GEMINI_API_KEY)
+  2. Static fallback pool    — returns from a hardcoded set when Gemini
+                               is unavailable (safe for offline demos)
+
+Public API
+----------
+get_notifications(n: int = 5) -> list[dict]
+    Returns a list of notification dicts:
+    [{"source": "whatsapp", "message": "..."}, ...]
+
+stream_notifications(n, delay_seconds) -> AsyncGenerator
+    Async generator yielding one notification at a time with a delay.
+    Used by the WebSocket endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from typing import AsyncGenerator
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Static fallback pool (used when Gemini is unavailable)
+# ---------------------------------------------------------------------------
+
+_FALLBACK_NOTIFICATIONS: list[dict] = [
+    {"source": "whatsapp", "message": "bhaiya 3 kurti bhej dena"},
+    {"source": "payment",  "message": "rahul ne 15000 bheja UPI se"},
+    {"source": "whatsapp", "message": "size chota hai exchange karna hai"},
+    {"source": "whatsapp", "message": "udhar me de dijiye"},
+    {"source": "amazon",   "message": "priya ke liye 2 kilo aata bhej dena"},
+    {"source": "payment",  "message": "amit bhai ka 8000 gpay se aaya"},
+    {"source": "whatsapp", "message": "3 kurti ka set ready rakhna"},
+    {"source": "return",   "message": "maal kharab tha wapas bhej diya"},
+    {"source": "whatsapp", "message": "suresh ko 500 ka maal udhar dena"},
+    {"source": "amazon",   "message": "order cancel karna hai, size bada hai"},
+    {"source": "payment",  "message": "50 piece pack karke rakhna kal tak"},
+    {"source": "whatsapp", "message": "geeta ke liye 5 metre kapda bhej dena"},
+]
+
+
+def _get_fallback(n: int) -> list[dict]:
+    """Return n randomly sampled notifications from the static pool."""
+    pool = _FALLBACK_NOTIFICATIONS * (n // len(_FALLBACK_NOTIFICATIONS) + 1)
+    return random.sample(pool, min(n, len(pool)))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def get_notifications(n: int = 5) -> list[dict]:
+    """
+    Get n business notifications.
+
+    Tries Gemini first; falls back to static pool silently if unavailable.
+
+    Args:
+        n: Number of notifications to generate/return.
+
+    Returns:
+        List of {"source": str, "message": str} dicts.
+    """
+    try:
+        from app.services.gemini_client import generate_notifications
+        results = generate_notifications(n)
+        if results:
+            return results
+        logger.info("Gemini returned empty list — using fallback pool.")
+    except Exception as exc:
+        logger.info("Gemini unavailable (%s) — using fallback pool.", exc)
+
+    return _get_fallback(n)
+
+
+async def stream_notifications(
+    n: int = 5,
+    delay_seconds: float = 2.0,
+) -> AsyncGenerator[dict, None]:
+    """
+    Async generator that yields one notification at a time.
+
+    Fetches a fresh batch from get_notifications() then yields them
+    one-by-one with a configurable delay between each.
+
+    Args:
+        n:             Number of notifications per batch.
+        delay_seconds: Pause between yielded notifications.
+
+    Yields:
+        {"source": str, "message": str}
+    """
+    notifications = get_notifications(n)
+    for notification in notifications:
+        yield notification
+        await asyncio.sleep(delay_seconds)

app/services/router.py

@@ -0,0 +1,88 @@
+"""
+router.py
+---------
+Stage 5: Skill Router for Notiflow
+
+The Skill Router is the decision layer between the Extraction Agent
+and the Business Skills. It receives a structured event (intent + data)
+and dispatches to the correct skill.
+
+Routing table:
+
+    intent          → skill function
+    ─────────────────────────────────
+    order           → process_order()
+    payment         → process_payment()
+    credit          → process_credit()
+    return          → process_return()
+    preparation     → process_preparation()
+    other           → (no skill; passthrough)
+
+If an intent has no registered skill the router returns a lightweight
+passthrough event so the pipeline never raises on unknown intents.
+"""
+
+import logging
+from typing import Any
+
+from app.skills.order_skill       import process_order
+from app.skills.payment_skill     import process_payment
+from app.skills.credit_skill      import process_credit
+from app.skills.return_skill      import process_return
+from app.skills.preparation_skill import process_preparation
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Routing table  (intent → skill callable)
+# ---------------------------------------------------------------------------
+
+_SKILL_MAP: dict[str, Any] = {
+    "order":       process_order,
+    "payment":     process_payment,
+    "credit":      process_credit,
+    "return":      process_return,
+    "preparation": process_preparation,
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def route_to_skill(intent: str, data: dict, context: dict | None = None) -> dict:
+    """
+    Route a structured business event to the appropriate skill.
+
+    Args:
+        intent: The detected intent string (e.g. "payment", "order").
+        data:   The extracted field dict returned by the Extraction Agent
+                (without the "intent" key — that lives at the top level).
+
+    Returns:
+        A skill event dict.  Structure varies per skill but always contains
+        at minimum an "event" key describing what happened.
+
+        For unrecognised / "other" intents a passthrough dict is returned:
+        {"event": "unhandled", "intent": intent, "data": data}
+
+    Example:
+        >>> route_to_skill("payment", {"customer": "Rahul", "amount": 15000})
+        {
+            "event": "payment_recorded",
+            "payment": {"customer": "Rahul", "amount": 15000, "status": "received"}
+        }
+    """
+    skill_fn = _SKILL_MAP.get(intent)
+
+    if skill_fn is None:
+        logger.info("No skill registered for intent '%s' — returning passthrough.", intent)
+        return {"event": "unhandled", "intent": intent, "data": data}
+
+    logger.info("Routing intent '%s' to skill: %s", intent, skill_fn.__name__)
+    if context is not None:
+        try:
+            return skill_fn(data, context=context)
+        except TypeError:
+            pass
+    return skill_fn(data)

app/services/skill_generator.py

@@ -0,0 +1,207 @@
+"""
+skill_generator.py
+------------------
+Dynamic Skill Generator for Notiflow.
+
+Creates new business skill Python files on demand and registers them in
+skills/skill_registry.json.
+
+Public API
+----------
+generate_skill(skill_name: str, description: str) -> dict
+list_skills() -> dict
+
+Safety rules:
+  - Raises SkillAlreadyExistsError if a skill with the same name exists.
+  - Skill names are normalised to snake_case.
+  - Generated files follow the standard skill template.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Optional
+
+from app.config import ROOT, REGISTRY_FILE
+
+logger = logging.getLogger(__name__)
+
+SKILLS_DIR = ROOT / "skills"
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class SkillAlreadyExistsError(Exception):
+    """Raised when a skill with the given name already exists."""
+
+
+# ---------------------------------------------------------------------------
+# Skill file template
+# ---------------------------------------------------------------------------
+
+_SKILL_TEMPLATE = '''\
+"""
+{skill_name}.py
+{underline}
+Auto-generated business skill for Notiflow.
+
+Description: {description}
+
+Modify this file to implement the skill logic.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+
+def {func_name}(data: dict) -> dict:
+    """
+    Execute the {display_name} skill.
+
+    Args:
+        data: Validated extraction dict from the orchestrator.
+
+    Returns:
+        Structured skill event dict.
+    """
+    logger.info("{display_name} skill executing: %s", data)
+
+    return {{
+        "event": "{event_name}",
+        "data":  data,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }}
+'''
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _to_snake_case(name: str) -> str:
+    """Normalise skill name to snake_case (alphanumeric + underscores only)."""
+    name = name.strip().lower()
+    name = re.sub(r"[^a-z0-9]+", "_", name)
+    name = re.sub(r"_+", "_", name).strip("_")
+    return name
+
+
+def _load_registry() -> dict:
+    path = Path(REGISTRY_FILE)
+    if not path.exists():
+        return {}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Could not read registry: %s", exc)
+        return {}
+
+
+def _save_registry(registry: dict) -> None:
+    path = Path(REGISTRY_FILE)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(registry, f, indent=2, ensure_ascii=False)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def generate_skill(skill_name: str, description: str) -> dict:
+    """
+    Generate a new skill file and register it.
+
+    Args:
+        skill_name:  Human-readable name (e.g. "discount_skill" or "Discount Skill").
+                     Normalised to snake_case automatically.
+        description: One-line description stored in the registry.
+
+    Returns:
+        Registry entry dict for the new skill:
+        {
+            "description": str,
+            "intent":      None,
+            "file":        "skills/<name>.py",
+            "builtin":     false
+        }
+
+    Raises:
+        SkillAlreadyExistsError: If a skill with the same name already exists
+                                 (either as a .py file or registry entry).
+        ValueError: If skill_name is empty or invalid.
+
+    Example:
+        >>> generate_skill("discount_skill", "Apply discount to an order")
+        {"description": "Apply discount...", "file": "skills/discount_skill.py", ...}
+    """
+    norm_name = _to_snake_case(skill_name)
+    if not norm_name:
+        raise ValueError(f"Invalid skill name: {skill_name!r}")
+
+    skill_file = SKILLS_DIR / f"{norm_name}.py"
+    registry   = _load_registry()
+
+    # ── Collision guard ──────────────────────────────────────────────────────
+    if norm_name in registry:
+        raise SkillAlreadyExistsError(
+            f"Skill '{norm_name}' already exists in the registry. "
+            "Choose a different name or delete the existing entry first."
+        )
+    if skill_file.exists():
+        raise SkillAlreadyExistsError(
+            f"Skill file '{skill_file}' already exists on disk. "
+            "Choose a different name or delete the existing file first."
+        )
+
+    # ── Generate file ───────���────────────────────────────────────────────────
+    display_name = norm_name.replace("_", " ").title()
+    func_name    = norm_name
+    event_name   = f"{norm_name}_executed"
+    underline    = "-" * (len(norm_name) + 3)     # matches "name.py" length
+
+    source = _SKILL_TEMPLATE.format(
+        skill_name   = norm_name,
+        underline    = underline,
+        description  = description,
+        func_name    = func_name,
+        display_name = display_name,
+        event_name   = event_name,
+    )
+
+    SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    skill_file.write_text(source, encoding="utf-8")
+    logger.info("Skill file created: %s", skill_file)
+
+    # ── Register ─────────────────────────────────────────────────────────────
+    entry = {
+        "description": description,
+        "intent":      None,          # caller can update after creation
+        "file":        f"skills/{norm_name}.py",
+        "builtin":     False,
+    }
+    registry[norm_name] = entry
+    _save_registry(registry)
+    logger.info("Skill '%s' registered.", norm_name)
+
+    return entry
+
+
+def list_skills() -> dict:
+    """
+    Return the full skill registry.
+
+    Returns:
+        Dict mapping skill_name → registry entry.
+    """
+    return _load_registry()

app/skills/__init__.py

@@ -0,0 +1 @@
+"""app/skills — business skill implementations."""

app/skills/credit_skill.py

@@ -0,0 +1,69 @@
+"""
+credit_skill.py
+---------------
+Business Skill: Credit / Udhar  (Stage 6 — with persistence)
+
+Handles the "credit" intent.
+Appends a credit entry to the Ledger sheet.
+
+Expected input fields:
+    customer  (str | None)
+    item      (str | None)
+    quantity  (int | None)
+    amount    (int | None)
+"""
+
+import logging
+from datetime import datetime, timezone
+
+from app.utils.excel_writer import append_row, read_sheet
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _generate_entry_id(prefix: str) -> str:
+    today = datetime.now(timezone.utc).strftime("%Y%m%d")
+    df    = read_sheet("Ledger")
+    seq   = len(df) + 1
+    return f"{prefix}-{today}-{seq:04d}"
+
+
+def process_credit(data: dict) -> dict:
+    """
+    Process a credit (udhar) event and append it to the Ledger sheet.
+
+    Args:
+        data: Extracted fields dict. Expected keys: customer, item, quantity, amount
+
+    Returns:
+        {
+            "event":  "credit_recorded",
+            "credit": { ledger entry }
+        }
+    """
+    logger.info("CreditSkill processing: %s", data)
+
+    entry_id = _generate_entry_id("CRD")
+
+    credit = {
+        "entry_id":     entry_id,
+        "timestamp":    _now_iso(),
+        "type":         "credit",
+        "customer":     data.get("customer"),
+        "item":         data.get("item"),
+        "quantity":     data.get("quantity"),
+        "amount":       data.get("amount"),
+        "payment_type": None,
+        "status":       "open",
+    }
+
+    append_row("Ledger", credit)
+
+    return {
+        "event":  "credit_recorded",
+        "credit": credit,
+    }

app/skills/order_skill.py

@@ -0,0 +1,130 @@
+"""
+order_skill.py
+--------------
+Business Skill: Order  (Stage 6 + UPGRADE 1 — memory update)
+
+On each order event this skill:
+    1. Appends an order record to the Orders sheet
+    2. Deducts stock from Inventory (delta log)
+    3. Generates an invoice object and saves it to Invoices sheet
+    4. Updates agent memory with customer + item        ← NEW (Upgrade 1)
+
+Expected input fields (all may be None if not captured):
+    customer  (str | None)
+    item      (str | None)
+    quantity  (int | None)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+
+from app.core.event_bus             import emit_event, push_live_log, store_invoice
+from app.utils.excel_writer         import append_row, read_sheet
+from app.services.invoice_service   import generate_invoice
+from app.services.inventory_service import deduct_stock
+from app.memory.agent_memory        import update_memory
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _generate_order_id() -> str:
+    today = datetime.now(timezone.utc).strftime("%Y%m%d")
+    df    = read_sheet("Orders")
+    seq   = len(df) + 1
+    return f"ORD-{today}-{seq:04d}"
+
+
+def process_order(data: dict, context: dict | None = None) -> dict:
+    """
+    Process an order event: persist order, update inventory, generate invoice,
+    and update agent memory.
+
+    Args:
+        data: Validated extraction dict. Keys: customer, item, quantity.
+
+    Returns:
+        {
+            "event":   "order_received",
+            "order":   { order record },
+            "invoice": { invoice record }
+        }
+    """
+    logger.info("OrderSkill ← %s", data)
+
+    customer = data.get("customer")
+    item     = data.get("item")
+    quantity = data.get("quantity")
+    order_id = _generate_order_id()
+
+    # 1 ── Persist order ──────────────────────────────────────────────────────
+    order = {
+        "order_id":  order_id,
+        "timestamp": _now_iso(),
+        "customer":  customer,
+        "item":      item,
+        "quantity":  quantity,
+        "status":    "pending",
+    }
+    append_row("Orders", order)
+
+    # 2 ── Inventory deduction ────────────────────────────────────────────────
+    if item and quantity:
+        deduct_stock(item, quantity, reference_id=order_id, note="order fulfilled")
+
+    # 3 ── Invoice generation ─────────────────────────────────────────────────
+    invoice = generate_invoice(
+        customer  = customer,
+        item      = item,
+        quantity  = quantity,
+        order_id  = order_id,
+        unit_price = 50.0,
+    )
+    invoice = store_invoice(invoice)
+    append_row("Invoices", invoice)
+    if context is not None:
+        context["invoice"] = invoice
+        invoice_log = push_live_log(context, {
+            "agent": "ExecutionAgent",
+            "status": "success",
+            "action": f"Invoice created: {invoice['invoice_id']}",
+            "detail": f"[ExecutionAgent] Invoice created: {invoice['invoice_id']}",
+        })
+        emit_event(
+            context,
+            "invoice_generated",
+            invoice,
+            agent="ExecutionAgent",
+            step="execution",
+            message=f"Invoice created: {invoice['invoice_id']}",
+            log_entry=invoice_log,
+        )
+        payment_log = push_live_log(context, {
+            "agent": "ExecutionAgent",
+            "status": "success",
+            "action": f"Payment requested for {invoice['invoice_id']}",
+            "detail": f"[ExecutionAgent] Payment requested: {invoice['invoice_id']}",
+        })
+        emit_event(
+            context,
+            "payment_requested",
+            invoice,
+            agent="ExecutionAgent",
+            step="payment",
+            message=f"Payment requested for {invoice['invoice_id']}",
+            log_entry=payment_log,
+        )
+
+    # 4 ── Memory update ──────────────────────────────────────────────────────
+    update_memory(customer=customer, item=item)
+
+    return {
+        "event":   "order_received",
+        "order":   order,
+        "invoice": invoice,
+    }

app/skills/payment_skill.py

@@ -0,0 +1,68 @@
+"""
+payment_skill.py
+----------------
+Business Skill: Payment  (Stage 6 — with persistence)
+
+Handles the "payment" intent.
+Appends a payment entry to the Ledger sheet.
+
+Expected input fields:
+    customer      (str | None)  — name of the person who sent money
+    amount        (int | None)  — monetary amount
+    payment_type  (str | None)  — "cash", "upi", "online", "cheque", or None
+"""
+
+import logging
+from datetime import datetime, timezone
+
+from app.utils.excel_writer import append_row, read_sheet
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _generate_entry_id(prefix: str) -> str:
+    today = datetime.now(timezone.utc).strftime("%Y%m%d")
+    df    = read_sheet("Ledger")
+    seq   = len(df) + 1
+    return f"{prefix}-{today}-{seq:04d}"
+
+
+def process_payment(data: dict) -> dict:
+    """
+    Process a payment event and append it to the Ledger sheet.
+
+    Args:
+        data: Extracted fields dict. Expected keys: customer, amount, payment_type
+
+    Returns:
+        {
+            "event":   "payment_recorded",
+            "payment": { ledger entry }
+        }
+    """
+    logger.info("PaymentSkill processing: %s", data)
+
+    entry_id = _generate_entry_id("PAY")
+
+    payment = {
+        "entry_id":     entry_id,
+        "timestamp":    _now_iso(),
+        "type":         "payment",
+        "customer":     data.get("customer"),
+        "item":         None,
+        "quantity":     None,
+        "amount":       data.get("amount"),
+        "payment_type": data.get("payment_type"),
+        "status":       "received",
+    }
+
+    append_row("Ledger", payment)
+
+    return {
+        "event":   "payment_recorded",
+        "payment": payment,
+    }

app/skills/preparation_skill.py

@@ -0,0 +1,117 @@
+"""
+preparation_skill.py
+--------------------
+Business Skill: Preparation / Inventory Pack  (Stage 6 — with persistence)
+
+Handles the "preparation" intent.
+Appends a preparation task to the Inventory sheet as a "reserved" movement.
+
+This records that stock is being set aside / packed, without fully
+deducting it (deduction happens when the linked order ships).
+If no linked order exists (standalone prep task), the record still logs
+the intention for the shop owner's reference.
+
+Expected input fields:
+    item      (str | None)  — item to prepare or pack
+    quantity  (int | None)  — number of units to prepare
+"""
+
+import logging
+from datetime import datetime, timezone
+
+from app.utils.excel_writer import append_row, read_sheet
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _generate_prep_id() -> str:
+    """Generate a sequential preparation ID: PREP-YYYYMMDD-XXXX."""
+    today = datetime.now(timezone.utc).strftime("%Y%m%d")
+    # Count existing preparation entries in Inventory to sequence the ID
+    df  = read_sheet("Inventory")
+    prep_rows = df[df["direction"] == "reserved"] if not df.empty and "direction" in df.columns else df
+    seq = len(prep_rows) + 1
+    return f"PREP-{today}-{seq:04d}"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def process_preparation(data: dict) -> dict:
+    """
+    Process a preparation / packing task and log it to the Inventory sheet.
+
+    The movement is logged with direction="reserved" so it is visible in
+    the inventory log but does not reduce the available stock count until
+    the items actually ship.
+
+    Args:
+        data: Extracted fields dict from the Extraction Agent.
+              Expected keys: item, quantity
+
+    Returns:
+        {
+            "event":       "preparation_queued",
+            "preparation": {
+                "prep_id":   str,
+                "timestamp": ISO-8601 str,
+                "item":      str | None,
+                "quantity":  int | None,
+                "status":    "queued"
+            }
+        }
+
+    Example:
+        >>> process_preparation({"item": "kurti", "quantity": 3})
+        {
+            "event": "preparation_queued",
+            "preparation": {
+                "prep_id": "PREP-20240115-0001",
+                "timestamp": "...",
+                "item": "kurti",
+                "quantity": 3,
+                "status": "queued"
+            }
+        }
+    """
+    logger.info("PreparationSkill processing: %s", data)
+
+    item     = data.get("item")
+    quantity = data.get("quantity")
+    prep_id  = _generate_prep_id()
+
+    # Log to Inventory sheet as a "reserved" movement
+    if item:
+        inventory_record = {
+            "timestamp":    _now_iso(),
+            "item":         item,
+            "change":       quantity or 0,
+            "direction":    "reserved",
+            "reference_id": prep_id,
+            "note":         "preparation task queued",
+        }
+        append_row("Inventory", inventory_record)
+
+    prep = {
+        "prep_id":   prep_id,
+        "timestamp": _now_iso(),
+        "item":      item,
+        "quantity":  quantity,
+        "status":    "queued",
+    }
+
+    logger.info("Preparation task logged: %s", prep_id)
+
+    return {
+        "event":       "preparation_queued",
+        "preparation": prep,
+    }