feat: product enrichment observability, lab KB study, benchmark, copy + local-Hub E2E, docs; 1.3.0

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

central/app/enrichment/observations.py

@@ -0,0 +1,27 @@
+"""ERP observations -> KB evidence. A client observation is EVIDENCE of family CLIENT_OBSERVATION; it never becomes VERIFIED_KB by itself
+(needs the official dataset AND a second independent family, or >= 2 distinct clients + another family - see kb.evaluate)."""
+from __future__ import annotations
+
+from ..classification import normalize_code
+from . import kb
+from .gtin import normalize_gtin
+
+
+def observe(session, rows, client_label: str, is_official) -> dict:
+    """rows: iterable of {"GTIN","PRODUTO","NCM"}. Only VALID_GTIN rows with an OFFICIAL 8-digit NCM are recorded. Returns counters."""
+    stats = {"rows": 0, "valid_gtin": 0, "with_official_ncm": 0, "recorded": 0}
+    for row in rows:
+        stats["rows"] += 1
+        g = normalize_gtin(row.get("GTIN"))
+        if g["status"] != "VALID_GTIN":
+            continue
+        stats["valid_gtin"] += 1
+        ncm = normalize_code(row.get("NCM"))
+        if len(ncm) != 8 or not is_official(ncm):
+            continue
+        stats["with_official_ncm"] += 1
+        product = kb.upsert_product(session, g["key"], row.get("PRODUTO"))
+        kb.add_evidence(session, product, "ncm", ncm, "client:observation", family=kb.CLIENT_FAMILY, client_label=client_label)
+        stats["recorded"] += 1
+    session.flush()
+    return stats