cfa-kernel 0.1.5__tar.gz → 0.1.7__tar.gz

cfa_kernel-0.1.7/CFA_LLM_Demo.ipynb

@@ -0,0 +1,706 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "# CFA — Contextual Flux Architecture\n",
+    "## LLM-Powered Governance Demo\n",
+    "\n",
+    "| Section | Feature | LLM Role |\n",
+    "|---|---|---|\n",
+    "| S1 | Setup & Secrets | Read API key from Databricks Secret Scope |\n",
+    "| S2 | Catalog | Operational metadata |\n",
+    "| S3 | LLM Normalizer | Semantic intent resolution (replaces keywords) |\n",
+    "| S4 | Strict Mode | LLM output validated against catalog |\n",
+    "| S5 | LLM Audit Trail | Every call SHA-256 traceable |\n",
+    "| S6 | LLM Systematizer | NL governance → BehaviorSpec → PolicyRules |\n",
+    "| S7 | Full Kernel + LLM | End-to-end governed execution |\n",
+    "| S8 | Runtime Gate + LLM | Guard with LLM-backed validation |\n",
+    "| S9 | Compare Normalizers | Rule-based vs LLM side-by-side |\n",
+    "| S10 | PolicyEngine + LLM Rules | Close the NL→Rules→Engine loop |\n",
+    "\n",
+    "**API key:** stored in Databricks Secret Scope `cfa-secrets`, never in code.\n",
+    "\n",
+    "---\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "## Section 1 — Setup & Secrets\n",
+    "\n",
+    "API key read from Databricks Secret Scope `cfa-secrets/deepseek-key`.\n",
+    "Falls back to `DEEPSEEK_API_KEY` env var for local testing.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "## Section 0 — Install\n",
+    "\n",
+    "Run this cell first to install dependencies.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install -q cfa-kernel[all] openai\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# --- Test if openai is importable ---\n",
+    "HAS_OPENAI = False\n",
+    "try:\n",
+    "    import openai\n",
+    "    print(f\"openai {openai.__version__} - OK\")\n",
+    "    HAS_OPENAI = True\n",
+    "except ImportError as e:\n",
+    "    print(f\"ERROR: openai not importable: {e}\")\n",
+    "    print(\"Run: %%pip install openai\")\n",
+    "\n",
+    "import cfa, os\n",
+    "from cfa.normalizer.llm import OpenAILMProvider, LLMNormalizerBackend\n",
+    "from cfa.normalizer.base import IntentNormalizer, RuleBasedNormalizerBackend\n",
+    "from cfa.runtime import RuntimeGate\n",
+    "from cfa.policy.engine import PolicyEngine\n",
+    "from cfa.types import StateSignature\n",
+    "from cfa.core.kernel import KernelConfig\n",
+    "\n",
+    "print(f\"CFA version: {cfa.__version__}\")\n",
+    "\n",
+    "# --- Read API keys from secret scope ---\n",
+    "def _try_secret(key):\n",
+    "    try:\n",
+    "        return dbutils.secrets.get(\"cfa-secrets\", key)\n",
+    "    except Exception:\n",
+    "        return None\n",
+    "\n",
+    "# Try Databricks secrets, fall back to env vars\n",
+    "OPENAI_KEY = _try_secret(\"openai-key\") or os.environ.get(\"OPENAI_API_KEY\")\n",
+    "DEEPSEEK_KEY = _try_secret(\"deepseek-key\") or os.environ.get(\"DEEPSEEK_API_KEY\")\n",
+    "\n",
+    "# Auto-select: prefer OpenAI (better reachability from Azure), fallback to DeepSeek\n",
+    "if OPENAI_KEY:\n",
+    "    LLM_MODEL = \"gpt-4o-mini\"\n",
+    "    LLM_BASE_URL = None  # default api.openai.com\n",
+    "    LLM_API_KEY = OPENAI_KEY\n",
+    "    print(f\"Using OpenAI ({LLM_MODEL})\")\n",
+    "elif DEEPSEEK_KEY:\n",
+    "    LLM_MODEL = \"deepseek-chat\"\n",
+    "    LLM_BASE_URL = \"https://api.deepseek.com\"\n",
+    "    LLM_API_KEY = DEEPSEEK_KEY\n",
+    "    print(f\"Using DeepSeek ({LLM_MODEL})\")\n",
+    "else:\n",
+    "    LLM_MODEL = None\n",
+    "    LLM_BASE_URL = None\n",
+    "    LLM_API_KEY = None\n",
+    "    print(\"WARNING: No API key found.\")\n",
+    "    print(\"  Databricks: secrets create-scope cfa-secrets\")\n",
+    "    print(\"  Local:      set OPENAI_API_KEY or DEEPSEEK_API_KEY env var\")\n",
+    "\n",
+    "# Combined gate: need both openai + API key\n",
+    "HAS_LLM = HAS_OPENAI and LLM_API_KEY is not None\n",
+    "\n",
+    "# Helper: create an LLM provider with the auto-detected config\n",
+    "def make_provider():\n",
+    "    \"\"\"Return OpenAILMProvider with auto-detected config.\"\"\"\n",
+    "    return OpenAILMProvider(\n",
+    "        model=LLM_MODEL,\n",
+    "        api_key=LLM_API_KEY,\n",
+    "        base_url=LLM_BASE_URL,\n",
+    "        temperature=0.0,\n",
+    "    )\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 2 — Data Catalog\n",
+    "\n",
+    "Catalog grounds the LLM. The LLM receives it in the prompt and MUST reference real datasets.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "CATALOG = {\n",
+    "    'nfe_bronze': {\n",
+    "        'type': 'delta', 'layer': 'bronze', 'size_gb': 50,\n",
+    "        'partition_by': ['processing_date'], 'pii': False,\n",
+    "        'description': 'Notas Fiscais Eletronicas brutas',\n",
+    "    },\n",
+    "    'clientes_bronze': {\n",
+    "        'type': 'delta', 'layer': 'bronze', 'size_gb': 10,\n",
+    "        'partition_by': ['processing_date'], 'pii': True,\n",
+    "        'pii_columns': ['cpf', 'nome', 'endereco'],\n",
+    "        'description': 'Dados cadastrais com CPF e endereco',\n",
+    "    },\n",
+    "    'vendas_bronze': {\n",
+    "        'type': 'delta', 'layer': 'bronze', 'size_gb': 2000,\n",
+    "        'pii': False,\n",
+    "        'description': 'Registros de transacoes de venda',\n",
+    "    },\n",
+    "    'fornecedores_bronze': {\n",
+    "        'type': 'delta', 'layer': 'bronze', 'size_gb': 10,\n",
+    "        'pii': False,\n",
+    "        'description': 'Cadastro de fornecedores',\n",
+    "    },\n",
+    "    'vendas_gold_agregado': {\n",
+    "        'type': 'delta', 'layer': 'gold', 'size_gb': 500,\n",
+    "        'pii': False,\n",
+    "        'description': 'Agregados de vendas para BI',\n",
+    "    },\n",
+    "}\n",
+    "\n",
+    "from cfa.policy.catalog import validate_catalog\n",
+    "result = validate_catalog(CATALOG)\n",
+    "print(f\"Catalog valid: {result.valid}\")\n",
+    "print(f\"  {len(CATALOG)} datasets registered\")\n",
+    "for msg in result.messages:\n",
+    "    print(f\"  {msg}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 3 — LLM Normalizer: Semantic Intent Resolution\n",
+    "\n",
+    "Rule-based = keyword matching (`join`, `aggregate`, `anonymize`).\n",
+    "LLM = sends `intent + catalog` to DeepSeek, parses structured JSON.\n",
+    "\n",
+    "The `SemanticResolution` returned contains the resolved `StateSignature`.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if not HAS_LLM:\n",
+    "    print(\"SKIP: no API key configured.\")\n",
+    "else:\n",
+    "    provider = make_provider()\n",
+    "    llm_backend = LLMNormalizerBackend(provider=provider, strict=False)\n",
+    "    normalizer = IntentNormalizer(backend=llm_backend)\n",
+    "\n",
+    "    print(\"=\" * 55)\n",
+    "    print(\"LLM NORMALIZER -- Semantic Resolution\")\n",
+    "    print(\"=\" * 55)\n",
+    "\n",
+    "    intents = [\n",
+    "        \"Join NFe with Clientes anonymize CPF and persist to Silver\",\n",
+    "        \"Aggregate vendas by region persist to Gold\",\n",
+    "        \"Export raw clientes PII to Gold\",\n",
+    "    ]\n",
+    "\n",
+    "    for raw in intents:\n",
+    "        print(f'\\nIntent: \"{raw}\"')\n",
+    "        res = normalizer.normalize(raw, {}, CATALOG)\n",
+    "        sig = res.signature\n",
+    "        print(f\"  Domain       : {sig.domain}\")\n",
+    "        print(f\"  Intent       : {sig.intent}\")\n",
+    "        print(f\"  Target layer : {sig.target_layer}\")\n",
+    "        ds_names = [d.name for d in sig.datasets]\n",
+    "        print(f\"  Datasets     : {ds_names}\")\n",
+    "        print(f\"  Confidence   : {res.confidence_score:.2f}\")\n",
+    "        print(f\"  Ambiguity    : {res.ambiguity_level}\")\n",
+    "        if res.reasoning:\n",
+    "            print(f\"  Reasoning    : {res.reasoning[:150]}...\")\n",
+    "\n",
+    "    print(\"\\nLLM normalizer baseline complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 4 — Strict Mode: Catalog-Grounded LLM\n",
+    "\n",
+    "`strict=True` validates the LLM output against the catalog.\n",
+    "Hallucinated datasets/references raise `ValueError`.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if not HAS_LLM:\n",
+    "    print(\"SKIP: no API key available\")\n",
+    "else:\n",
+    "    sp = make_provider()\n",
+    "    sb = LLMNormalizerBackend(provider=sp, strict=True)\n",
+    "    sn = IntentNormalizer(backend=sb)\n",
+    "\n",
+    "    print(\"=\" * 55)\n",
+    "    print(\"STRICT MODE — Catalog-grounded LLM\")\n",
+    "    print(\"=\" * 55)\n",
+    "\n",
+    "    for raw in [\n",
+    "        \"Join NFe with Clientes anonymize CPF persist to Silver\",\n",
+    "        \"Full scan vendas without partition to Gold\",\n",
+    "    ]:\n",
+    "        print(f\"\\nIntent: \\\"{raw}\\\"\")\n",
+    "        try:\n",
+    "            res = sn.normalize(raw, {}, CATALOG)\n",
+    "            print(f\"  PASSED  | confidence={res.confidence_score:.2f}  layer={res.signature.target_layer}\")\n",
+    "        except ValueError as e:\n",
+    "            print(f\"  REJECTED | {str(e)[:120]}\")\n",
+    "\n",
+    "    print(\"\\nStrict mode demo complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 5 — LLM Audit Trail\n",
+    "\n",
+    "Every LLM call is SHA-256 hashed (prompt, response, catalog).\n",
+    "Full traceability for compliance audits.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if not HAS_LLM:\n",
+    "    print(\"SKIP: no API key available\")\n",
+    "else:\n",
+    "    # The 'sb' backend from section 4 already recorded calls\n",
+    "    records = sb.audit_records\n",
+    "    print(\"=\" * 55)\n",
+    "    print(\"LLM AUDIT TRAIL — Tamper-evident LLM calls\")\n",
+    "    print(\"=\" * 55)\n",
+    "    print(f\"  Total LLM calls recorded: {len(records)}\")\n",
+    "\n",
+    "    for i, rec in enumerate(records):\n",
+    "        print(f\"\\n  Call {i+1}:\")\n",
+    "        print(f\"    Model         : {rec.model}\")\n",
+    "        print(f\"    Prompt hash   : {rec.prompt_hash[:16]}...\")\n",
+    "        print(f\"    Response hash : {rec.response_hash[:16]}...\")\n",
+    "        print(f\"    Catalog hash  : {rec.catalog_hash[:16]}...\")\n",
+    "        if rec.catalog_validation_errors:\n",
+    "            for err in rec.catalog_validation_errors:\n",
+    "                print(f\"    Val. error    : {err}\")\n",
+    "        if rec.parsed_json:\n",
+    "            keys = list(rec.parsed_json.keys())\n",
+    "            print(f\"    Parsed keys   : {keys[:8]}\")\n",
+    "\n",
+    "    print(\"\\nLLM audit trail complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 6 — LLM Systematizer: NL → PolicyRules\n",
+    "\n",
+    "Describe governance in natural language. LLM produces `BehaviorSpec`.\n",
+    "`Systematizer` converts it to executable `PolicyRule` objects.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from cfa.behavior.llm import OpenAISystematizerBackend\n",
+    "from cfa.behavior import Systematizer\n",
+    "\n",
+    "taxonomy, rules = None, None\n",
+    "\n",
+    "if not HAS_LLM:\n",
+    "    print(\"SKIP: no LLM available (missing openai or API key)\")\n",
+    "else:\n",
+    "    try:\n",
+    "        print(\"=\" * 55)\n",
+    "        print(\"LLM SYSTEMATIZER -- NL to Policy Rules\")\n",
+    "        print(\"=\" * 55)\n",
+    "\n",
+    "        governance_desc = \"\"\"\\\n",
+    "Fiscal ETL pipeline governance:\n",
+    "1. All datasets moving from Bronze to Silver/Gold MUST anonymize PII (CPF, nome, endereco)\n",
+    "2. Every Silver and Gold write requires a merge_key (upsert, not append)\n",
+    "3. Datasets larger than 100GB MUST have partition_by defined\n",
+    "4. No raw PII columns may appear in Gold layer\n",
+    "5. Maximum cost per pipeline run: 50 DBU\n",
+    "\"\"\"\n",
+    "\n",
+    "        sys_backend = OpenAISystematizerBackend(\n",
+    "            model=LLM_MODEL,\n",
+    "            api_key=LLM_API_KEY,\n",
+    "            base_url=LLM_BASE_URL,\n",
+    "            temperature=0.0,\n",
+    "            max_tokens=2048,\n",
+    "        )\n",
+    "\n",
+    "        taxonomy, rules = Systematizer().systematize_from_nl(\n",
+    "            governance_desc,\n",
+    "            backend=sys_backend,\n",
+    "            context=\"Fiscal ETL: NFe, Clientes, Vendas, Fornecedores on Databricks Delta Lake\",\n",
+    "            target_layer=\"silver\",\n",
+    "        )\n",
+    "\n",
+    "        print(f\"  Categories      : {taxonomy.category_count}\")\n",
+    "        print(f\"  Rules generated : {len(rules)}\")\n",
+    "        print()\n",
+    "\n",
+    "        for rule in rules:\n",
+    "            print(f\"  Rule : {rule.name}\")\n",
+    "            print(f\"    code     : {rule.fault_code}\")\n",
+    "            print(f\"    action   : {rule.action.value}\")\n",
+    "            print(f\"    severity : {rule.severity.value}\")\n",
+    "            print()\n",
+    "\n",
+    "        test_intents = taxonomy.generate_test_intents(3)\n",
+    "        print(f\"  CI test intents generated: {len(test_intents)}\")\n",
+    "        for intent in test_intents:\n",
+    "            print(f\"    - {intent}\")\n",
+    "\n",
+    "        print(\"\\nLLM Systematizer complete\")\n",
+    "    except Exception as e:\n",
+    "        print(f\"  LLM call failed: {type(e).__name__}: {str(e)[:100]}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 7 — Full Kernel with LLM Normalizer\n",
+    "\n",
+    "Same 5-phase pipeline (Formalize → Govern → Generate → Execute → Validate/Audit).\n",
+    "Only the **Formalize** phase switches from keyword-matching to DeepSeek.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from cfa import KernelOrchestrator\n",
+    "\n",
+    "if not HAS_LLM:\n",
+    "    print(\"SKIP: no API key available\")\n",
+    "else:\n",
+    "    provider = make_provider()\n",
+    "    backend = LLMNormalizerBackend(provider=provider, strict=True)\n",
+    "\n",
+    "    kernel = KernelOrchestrator(\n",
+    "        catalog=CATALOG,\n",
+    "        config=KernelConfig(\n",
+    "            policy_bundle_version=\"fiscal-prod-v1.0\",\n",
+    "            backend=\"pyspark\",\n",
+    "        ),\n",
+    "        normalizer_backend=backend,\n",
+    "    )\n",
+    "\n",
+    "    print(\"=\" * 55)\n",
+    "    print(\"FULL KERNEL + LLM NORMALIZER\")\n",
+    "    print(\"=\" * 55)\n",
+    "\n",
+    "    for intent in [\n",
+    "        \"Join NFe with Clientes anonymize CPF and persist to Silver\",\n",
+    "        \"Aggregate vendas by region persist to Gold\",\n",
+    "        \"Export raw clientes PII to Gold\",\n",
+    "    ]:\n",
+    "        print(f\"\\nIntent: \\\"{intent}\\\"\")\n",
+    "        try:\n",
+    "            result = kernel.process(intent)\n",
+    "            print(f\"  -> Decision  : {result.state.value.upper()}\")\n",
+    "            if result.signature is not None:\n",
+    "                print(f\"  -> Sig hash  : {result.signature.signature_hash[:24]}...\")\n",
+    "            if result.replan_history:\n",
+    "                print(f\"  -> Replans   : {len(result.replan_history)}\")\n",
+    "            if result.generated_code and result.generated_code.code:\n",
+    "                lines = result.generated_code.code.splitlines()\n",
+    "                print(f\"  -> Code gen  : {len(lines)} lines {result.generated_code.language}\")\n",
+    "        except Exception as e:\n",
+    "            print(f\"  -> BLOCKED   : {type(e).__name__} | {str(e)[:100]}\")\n",
+    "\n",
+    "    calls = backend.audit_records\n",
+    "    print(f\"\\n  LLM calls by kernel: {len(calls)}\")\n",
+    "    for rec in calls:\n",
+    "        print(f\"    prompt={rec.prompt_hash[:16]}...  response={rec.response_hash[:16]}...\")\n",
+    "\n",
+    "    print(\"\\nFull kernel + LLM complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 8 — Runtime Gate\n",
+    "\n",
+    "`RuntimeGate` validates intents before execution.\n",
+    "With `policy_rules` from LLM Systematizer, the gate inherits NL-defined governance.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import traceback\n",
+    "print(\"=\" * 55)\n",
+    "print(\"RUNTIME GATE\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "try:\n",
+    "    gate = RuntimeGate(\n",
+    "        catalog=CATALOG,\n",
+    "        policy_rules=rules if rules is not None else None,\n",
+    "    )\n",
+    "\n",
+    "    result = gate.validate(\"Join NFe with Clientes and persist to Silver\")\n",
+    "    print(f\"  validate() -> state={result.state.value}  passed={result.passed}\")\n",
+    "    print(f\"  gate_id={result.gate_id}  execution_id={result.execution_id[:8]}...\")\n",
+    "\n",
+    "    @gate.guard(\"aggregate sales data with PII protected\")\n",
+    "    def my_pipeline():\n",
+    "        return \"pipeline executed\"\n",
+    "\n",
+    "    print(f\"  @gate.guard -> {my_pipeline()}\")\n",
+    "    print(\"\\nRuntime Gate demo complete\")\n",
+    "except Exception as e:\n",
+    "    print(f\"  RUNTIME GATE FAILED: {type(e).__name__}\")\n",
+    "    traceback.print_exc()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 9 — Comparing Normalizers: Rule-Based vs LLM\n",
+    "\n",
+    "Same intent, two backends — side-by-side comparison.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"=\" * 55)\n",
+    "print(\"NORMALIZER COMPARISON: Rule-Based vs LLM\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "rule_norm = IntentNormalizer(backend=RuleBasedNormalizerBackend())\n",
+    "llm_norm = None\n",
+    "if HAS_LLM:\n",
+    "    provider = make_provider()\n",
+    "    llm_norm = IntentNormalizer(backend=LLMNormalizerBackend(provider=provider, strict=True))\n",
+    "\n",
+    "header = f\"{'Intent':<50s} | {'Method':<12s} | {'Domain':<10s} | {'Layer':<8s} | {'Confidence':>10s}\"\n",
+    "print(header)\n",
+    "print(\"-\" * len(header))\n",
+    "\n",
+    "for raw in [\n",
+    "    \"Join NFe with Clientes anonymize CPF and persist to Silver\",\n",
+    "    \"Aggregate vendas by region persist to Gold\",\n",
+    "    \"Export raw clientes PII to Gold\",\n",
+    "]:\n",
+    "    # Rule-based\n",
+    "    rb = rule_norm.normalize(raw, {}, CATALOG)\n",
+    "    sig_rb = rb.signature\n",
+    "    print(f\"{raw[:47]:<50s} | {'rule-based':<12s} | {sig_rb.domain:<10s} | {sig_rb.target_layer:<8s} | {rb.confidence_score:>9.2f}\")\n",
+    "    # LLM\n",
+    "    if llm_norm is not None:\n",
+    "        try:\n",
+    "            llm = llm_norm.normalize(raw, {}, CATALOG)\n",
+    "            sig_llm = llm.signature\n",
+    "            print(f\"{'':50s} | {'LLM':<12s} | {sig_llm.domain:<10s} | {sig_llm.target_layer:<8s} | {llm.confidence_score:>9.2f}\")\n",
+    "        except Exception as e:\n",
+    "            print(f\"{'':50s} | {'LLM':<12s} | ERROR: {type(e).__name__}\")\n",
+    "    else:\n",
+    "        print(f\"{'':50s} | {'LLM':<12s} | (no API key)\")\n",
+    "    print()\n",
+    "\n",
+    "print(\"Normalizer comparison complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Section 10 — PolicyEngine with LLM-Generated Rules\n",
+    "\n",
+    "Rules from `LLMSystematizer` (Section 6) feed `PolicyEngine`.\n",
+    "Closes the loop: NL governance → LLM → BehaviorSpec → PolicyRules → Engine.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from cfa.types import DatasetRef, SignatureConstraints, TargetLayer, ExecutionContext\n",
+    "\n",
+    "print(\"=\" * 55)\n",
+    "print(\"POLICY ENGINE WITH LLM-GENERATED RULES\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "if rules is None:\n",
+    "    print(\"SKIP: rules not available (LLM Systematizer requires API key)\")\n",
+    "    print(\"   Using default policy rules instead.\")\n",
+    "    engine = PolicyEngine()  # default rules\n",
+    "else:\n",
+    "    print(f\"  Using {len(rules)} LLM-generated rules from Section 6\")\n",
+    "    engine = PolicyEngine(rules=rules)\n",
+    "\n",
+    "# --- Safe signature ---\n",
+    "sig_safe = StateSignature(\n",
+    "    domain=\"fiscal\",\n",
+    "    intent=\"Join NFe with Clientes anonymize CPF persist to Silver\",\n",
+    "    source_intent_raw=\"Join NFe with Clientes anonymize CPF persist to Silver\",\n",
+    "    target_layer=TargetLayer.SILVER,\n",
+    "    datasets=(\n",
+    "        DatasetRef(name=\"nfe_bronze\"),\n",
+    "        DatasetRef(name=\"clientes_bronze\", pii_columns=(\"cpf\", \"nome\")),\n",
+    "    ),\n",
+    "    constraints=SignatureConstraints(\n",
+    "        no_pii_raw=True,\n",
+    "        merge_key_required=True,\n",
+    "        partition_by=(\"processing_date\",),\n",
+    "    ),\n",
+    "    execution_context=ExecutionContext(\n",
+    "        policy_bundle_version=\"v1.0\",\n",
+    "        catalog_snapshot_version=\"catalog_default\",\n",
+    "        context_registry_version_id=\"ctx-default\",\n",
+    "    ),\n",
+    ")\n",
+    "\n",
+    "r = engine.evaluate(sig_safe)\n",
+    "print(f\"\\n  Safe signature   -> {r.action.value.upper()}  faults={len(r.faults)}\")\n",
+    "\n",
+    "# --- Unsafe signature ---\n",
+    "sig_unsafe = StateSignature(\n",
+    "    domain=\"fiscal\",\n",
+    "    intent=\"Export raw clientes PII to Gold\",\n",
+    "    source_intent_raw=\"Export raw clientes PII to Gold\",\n",
+    "    target_layer=TargetLayer.GOLD,\n",
+    "    datasets=(\n",
+    "        DatasetRef(name=\"clientes_bronze\", pii_columns=(\"cpf\", \"nome\", \"endereco\")),\n",
+    "    ),\n",
+    "    constraints=SignatureConstraints(\n",
+    "        no_pii_raw=False,\n",
+    "        merge_key_required=False,\n",
+    "        partition_by=(),\n",
+    "    ),\n",
+    "    execution_context=ExecutionContext(\n",
+    "        policy_bundle_version=\"v1.0\",\n",
+    "        catalog_snapshot_version=\"catalog_default\",\n",
+    "        context_registry_version_id=\"ctx-default\",\n",
+    "    ),\n",
+    ")\n",
+    "\n",
+    "r2 = engine.evaluate(sig_unsafe)\n",
+    "print(f\"  Unsafe signature -> {r2.action.value.upper()}  faults={len(r2.faults)}\")\n",
+    "for fault in r2.faults[:4]:\n",
+    "    print(f\"    [{fault.severity.value.upper():<10s}] {fault.code}\")\n",
+    "\n",
+    "print(\"\\nLLM-rules PolicyEngine complete\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Summary\n",
+    "\n",
+    "| LLM Feature | Status | Notes |\n",
+    "|---|---|---|\n",
+    "| LLM Normalizer | \\\\u2713 | Semantic intent resolution via DeepSeek |\n",
+    "| Strict Mode | \\\\u2713 | LLM output validated against catalog |\n",
+    "| LLM Audit Trail | \\\\u2713 | Every call SHA-256 traceable |\n",
+    "| LLM Systematizer | \\\\u2713 | NL → BehaviorSpec → PolicyRules |\n",
+    "| Full Kernel + LLM | \\\\u2713 | End-to-end with LLM normalizer |\n",
+    "| Runtime Gate | \\\\u2713 | Guard with LLM-generated policy rules |\n",
+    "| Normalizer Comparison | \\\\u2713 | Rule-based vs LLM side-by-side |\n",
+    "| Secret Management | \\\\u2713 | Databricks Secret Scope `cfa-secrets` |\n",
+    "\n",
+    "**Key differences from rule-based:**\n",
+    "\n",
+    "- LLM understands intent **semantics**, not just keywords\n",
+    "- Natural language governance descriptions → executable rules\n",
+    "- Every LLM call is audited (prompt/response/catalog SHA-256)\n",
+    "- Strict mode prevents hallucinations by validating against catalog\n",
+    "- API key stored in **Databricks Secret Scope** — never in code\n",
+    "\n",
+    "**Secret scope setup (one-time):**\n",
+    "```bash\n",
+    "databricks secrets create-scope cfa-secrets\n",
+    "databricks secrets put-secret cfa-secrets deepseek-key\n",
+    "```\n",
+    "\n",
+    "---\n",
+    "\n",
+    "**Links**\n",
+    "- [Documentation](https://marquesantero.github.io/cfa/docs/intro)\n",
+    "- [PyPI](https://pypi.org/project/cfa-kernel/)\n",
+    "- [GitHub](https://github.com/marquesantero/cfa)\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}