compass-kb-validation 2.4.0__tar.gz → 2.6.0__tar.gz

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass-kb-validation
-Version: 2.4.0
+Version: 2.6.0
 Summary: Knowledge-base readiness validation for RAG & AI agents — config-driven, deterministic pipeline integrity checks.
 Author: COMPASS
 License: MIT

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/compass_kb_validation.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass-kb-validation
-Version: 2.4.0
+Version: 2.6.0
 Summary: Knowledge-base readiness validation for RAG & AI agents — config-driven, deterministic pipeline integrity checks.
 Author: COMPASS
 License: MIT

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/discover_and_validate.py

@@ -138,7 +138,15 @@ def _resolve_skip_steps(settings, *, include_graphdb: bool, include_retrieval: b
     (BUG-22). ``--keep s3_storage`` overrides the auto-skip.
     """
     skip = ["API Upload"]
-    if not include_graphdb:
+    # Graph validation runs by default when a graph block is actually configured (a
+    # sparql_query or an endpoint) - a configured neptune:/graphdb: block should not be
+    # silently ignored just because --include-graphdb was not passed. Opt out with
+    # --skip neptune_metadata (or graphdb_metadata). --include-graphdb still forces it on.
+    nep, gdb = settings.neptune, settings.graphdb
+    graph_configured = bool(
+        getattr(nep, "sparql_query", "") or getattr(nep, "endpoint", "")
+        or getattr(gdb, "sparql_query", "") or getattr(gdb, "base_url", ""))
+    if not (include_graphdb or graph_configured):
         skip += ["GraphDB Metadata", "Neptune Metadata"]
     if not include_retrieval:
         skip.append("Retrieval Quality")

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/__init__.py

@@ -5,4 +5,4 @@ end-to-end: API upload -> object storage -> knowledge graph -> vector store ->
 retrieval quality, plus cross-store consistency.
 """
 
-__version__ = "2.4.0"
+__version__ = "2.6.0"

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/cli.py

@@ -278,7 +278,8 @@ def cmd_lint(argv: list[str]) -> int:
                                             "predicates, missing helper-query placeholders, ...).")
     p.add_argument("--project", help="Project name (config/projects/<name>.yaml).")
     p.add_argument("--env", default="dev", help="Environment (default: dev).")
-    p.add_argument("--strict", action="store_true", help="Exit non-zero on warnings too, not just errors.")
+    p.add_argument("--strict", action="store_true",
+                   help="Exit non-zero on warnings AND advisories too, not just errors.")
     args = p.parse_args(argv)
 
     from ingestion_validation.config import load_settings, project_config_file
@@ -297,8 +298,10 @@ def cmd_lint(argv: list[str]) -> int:
     print(f"  compass lint - project={args.project or '(none)'} env={args.env}")
     print(format_findings(findings))
     errors = sum(1 for lv, _ in findings if lv == "error")
-    warns = sum(1 for lv, _ in findings if lv == "warn")
-    return 1 if (errors or (args.strict and warns)) else 0
+    # --strict escalates everything non-error (warnings AND info advisories) - a leftover
+    # skip_steps entry is an "info" advisory, and a strict CI gate should still catch it.
+    non_error = sum(1 for lv, _ in findings if lv != "error")
+    return 1 if (errors or (args.strict and non_error)) else 0
 
 
 # --------------------------------------------------------------------------- #
@@ -355,15 +358,17 @@ def cmd_doctor(argv: list[str]) -> int:
                    help="On failure, diagnose why: DNS resolution, TCP reachability, TLS certificate.")
     args = p.parse_args(argv)
 
-    if args.all_projects:
-        return _doctor_all_projects(args)
-
+    # Load .env for BOTH paths - --all-projects previously ran before this and fell back to
+    # localhost because credentials from .env were never read.
     try:
         from dotenv import load_dotenv
         load_dotenv()
     except Exception:  # noqa: BLE001 - optional
         pass
 
+    if args.all_projects:
+        return _doctor_all_projects(args)
+
     from ingestion_validation.config import find_project_root, load_settings, validate_config
 
     try:
@@ -1311,8 +1316,10 @@ def cmd_grounding_audit(argv: list[str]) -> int:
     p.add_argument("--project")
     p.add_argument("--env", default="")
     g = p.add_mutually_exclusive_group(required=True)
-    g.add_argument("--eval-result", metavar="FILE", help="One eval record as JSON.")
-    g.add_argument("--eval-results", metavar="FILE", help="JSONL of eval records (one per line).")
+    g.add_argument("--eval-result", metavar="FILE", help="One eval record as a single JSON object.")
+    g.add_argument("--eval-results", metavar="FILE",
+                   help="Batch: a JSONL file (one JSON object per LINE, not a JSON array). "
+                        "`compass ask --format eval` emits a compatible file.")
     p.add_argument("--format", choices=["markdown", "json"], default="markdown")
     p.add_argument("--output", help="Write the report to a file (default: stdout).")
     p.add_argument("--fail-on-fabrication", action="store_true",
@@ -1335,11 +1342,25 @@ def cmd_grounding_audit(argv: list[str]) -> int:
     records: list[dict] = []
     try:
         if args.eval_result:
-            records = [_json.loads(Path(args.eval_result).read_text(encoding="utf-8"))]
+            one = _json.loads(Path(args.eval_result).read_text(encoding="utf-8"))
+            if isinstance(one, list):
+                print("  --eval-result expects a single JSON object, but got an array. "
+                      "Use --eval-results for a batch (JSONL: one object per line).")
+                return 2
+            if not isinstance(one, dict):
+                print("  --eval-result must be a single JSON object.")
+                return 2
+            records = [one]
         else:
-            for line in Path(args.eval_results).read_text(encoding="utf-8").splitlines():
-                if line.strip():
+            for n, line in enumerate(Path(args.eval_results).read_text(encoding="utf-8").splitlines(), 1):
+                if not line.strip():
+                    continue
+                try:
                     records.append(_json.loads(line))
+                except Exception:  # noqa: BLE001 - point at the offending line, not char 1
+                    print(f"  --eval-results is JSONL (one JSON object per line); line {n} is not valid JSON. "
+                          "A JSON array is not accepted here - see `compass ask --format eval`.")
+                    return 2
     except Exception as exc:  # noqa: BLE001 - clean message, never a traceback
         print(f"  Could not read eval input: {exc}")
         return 2

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/config/__init__.py

@@ -612,6 +612,9 @@ class EvalConfig:
     # Extra query-intent regexes, merged with the built-in defaults (how many / count / by
     # type / list all / most recent ...). Lets a domain add its own phrasings.
     structured_query_patterns: list[str] = field(default_factory=list)
+    # Index field holding the source document name, so grounding-audit can verify a cited
+    # document actually exists in the KB.
+    gt_doc_name_field: str = "file_name"
 
 
 @dataclass

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/grounding.py

@@ -99,9 +99,15 @@ def extract_numeric_claims(response: str) -> list[NumericClaim]:
         if nums:
             _add(label, nums[-1], "table")
 
-    # Inline "N documents / docs / files / records / PDFs".
-    for m in re.finditer(r"\*{0,2}([\d,]+)\*{0,2}\s+(?:total\s+)?(?:documents?|docs|files?|records?|pdfs?)\b",
-                         text, flags=re.IGNORECASE):
+    _noun = r"(?:documents?|docs|files?|records?|pdfs?|items?)"
+    # Inline "N <TYPE> documents" - capture the type label ("59 WIU documents" -> WIU=59).
+    # The type token is a short UPPER/CamelCase word, so plain "24 documents" stays "total".
+    for m in re.finditer(rf"\*{{0,2}}([\d,]+)\*{{0,2}}\s+([A-Z][A-Za-z0-9]{{1,14}})\s+{_noun}\b", text):
+        label = m.group(2)
+        if label.lower() not in ("total", "the", "these", "those", "all", "some"):
+            _add(label, int(m.group(1).replace(",", "")), "inline")
+    # Inline "N documents / docs / ..." with no type -> total.
+    for m in re.finditer(rf"\*{{0,2}}([\d,]+)\*{{0,2}}\s+(?:total\s+)?{_noun}\b", text, flags=re.IGNORECASE):
         _add("total", int(m.group(1).replace(",", "")), "inline")
 
     return claims
@@ -132,24 +138,41 @@ def verify_structured_claims(adapter: Any, claims: list[NumericClaim],
         return [ClaimVerdict(c.label, c.count, None, False, False, "backend cannot aggregate")
                 for c in claims], meta
     if not aggregatable_fields:
+        # Don't dead-end: name the index's own fields so the user knows exactly what to
+        # configure, instead of a generic "not configured".
+        candidates = ""
+        try:
+            fields = (adapter.index_info() or {}).get("fields", {}) if hasattr(adapter, "index_info") else {}
+            tags = [n for n, t in fields.items() if str(t).upper() in ("TAG", "TEXT")]
+            if tags:
+                candidates = (" Fields available to group by: " + ", ".join(sorted(tags)[:12])
+                              + ". Example: eval.aggregatable_fields: [{field: <a TAG field>, "
+                              "count_by: <doc-identity field>}].")
+        except Exception:  # noqa: BLE001 - schema unavailable -> generic message
+            candidates = ""
         meta["reason"] = ("no eval.aggregatable_fields configured - declare the group-by and "
-                          "doc-identity fields to verify count claims.")
+                          "doc-identity fields to verify count claims." + candidates)
         return [ClaimVerdict(c.label, c.count, None, False, False, "no aggregatable fields configured")
                 for c in claims], meta
 
     # Build a value -> count map across every configured aggregation, plus an overall
-    # total (distinct documents) for "total" claims.
+    # total (distinct documents) for "total" claims. The total is the distinct-document
+    # count of the FIRST grouping only - summing across every spec double-counted the same
+    # documents (a 2-spec config reported 2x the real total).
     value_counts: dict[str, int] = {}
     total_docs = 0
-    for spec in aggregatable_fields:
+    for i, spec in enumerate(aggregatable_fields):
         gfield = spec.get("field", "")
-        dfield = spec.get("distinct_by") or None
+        # `count_by` (the original config spelling) and `distinct_by` are both accepted;
+        # without a distinct field COUNT_DISTINCTISH degrades to a raw chunk COUNT.
+        dfield = spec.get("distinct_by") or spec.get("count_by") or None
         counts = adapter.aggregate_count(gfield, dfield) if gfield else None
         if counts:
             meta["aggregated"] = True
             for k, v in counts.items():
                 value_counts[str(k).lower()] = value_counts.get(str(k).lower(), 0) + int(v)
-                total_docs += int(v)
+            if i == 0:
+                total_docs = sum(int(v) for v in counts.values())
     if not meta["aggregated"]:
         meta["reason"] = "aggregation returned nothing (empty index, or the configured fields are absent)."
 
@@ -174,6 +197,89 @@ def verify_structured_claims(adapter: Any, claims: list[NumericClaim],
     return verdicts, meta
 
 
+_SEV_ORDER = {"INFO": 0, "LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
+
+
+def _score_and_target(v: Any) -> tuple:
+    """A metric value may be {'score':..,'target':..} or a bare number. Return (score, target)."""
+    if isinstance(v, dict):
+        return v.get("score"), v.get("target", 0.7)
+    if isinstance(v, (int, float)):
+        return v, 0.7
+    return None, None
+
+
+def semantic_triage(response: str, context_empty: bool, scores: dict) -> tuple[list[dict], str]:
+    """Deterministic semantic signals + a severity, WITHOUT extracting or judging claims.
+
+    Everything here is a fact already in hand: the eval's own scores, and whether retrieval
+    was empty while the model still answered. No LLM, no quality verdict - just turning
+    signals the eval produced into an honest severity, so a semantic case with all-zero
+    scores stops reading as "LOW / nothing to see here".
+    """
+    signals: list[dict] = []
+    sev = "INFO"
+
+    def bump(level: str) -> None:
+        nonlocal sev
+        if _SEV_ORDER[level] > _SEV_ORDER[sev]:
+            sev = level
+
+    failed = []
+    for name, v in (scores or {}).items():
+        score, target = _score_and_target(v)
+        if score is None:
+            continue
+        if score < (target if isinstance(target, (int, float)) else 0.7):
+            failed.append((name, score))
+            low = name.lower()
+            if "guardrail" in low or "safety" in low:
+                signals.append({"label": "Guardrail/safety metric failed", "severity": "HIGH",
+                                "detail": f"{name} = {score}"})
+                bump("HIGH")
+            elif ("ground" in low or "faithful" in low) and score < 0.2:
+                signals.append({"label": "Groundedness metric very low", "severity": "HIGH",
+                                "detail": f"{name} = {score} (target {target})"})
+                bump("HIGH")
+
+    if context_empty and len((response or "").strip()) > 40:
+        signals.append({"label": "Answered with empty retrieval", "severity": "HIGH",
+                        "detail": "retrieval returned nothing, yet the model produced a substantive answer"})
+        bump("HIGH")
+
+    if failed and _SEV_ORDER[sev] < _SEV_ORDER["MEDIUM"]:
+        signals.append({"label": f"{len(failed)} eval metric(s) below target", "severity": "MEDIUM",
+                        "detail": ", ".join(f"{n}={s}" for n, s in failed[:4])})
+        bump("MEDIUM")
+
+    return signals, sev
+
+
+_CITATION_RE = re.compile(r"\*\*([^*]+\.(?:pdf|docx|pptx|txt|md))\*\*", re.IGNORECASE)
+
+
+def verify_citations(response: str, adapter: Any, doc_name_field: str) -> list[dict]:
+    """Deterministic: does each document the response CITES actually exist in the KB?
+
+    A fabricated source reference is one of the clearest grounding failures. Uses the
+    adapter's text search on the configured doc-name field; skips silently if the backend
+    can't search (never a false positive).
+    """
+    signals: list[dict] = []
+    search = getattr(adapter, "text_search", None)
+    if not callable(search) or not doc_name_field:
+        return signals
+    for doc in sorted(set(_CITATION_RE.findall(response or ""))):
+        try:
+            hits = search(doc_name_field, doc, limit=1)
+        except Exception:  # noqa: BLE001 - search unavailable -> don't assert absence
+            return signals
+        if not hits:
+            signals.append({"label": "Cited document not found in KB", "severity": "HIGH",
+                            "detail": doc})
+    return signals
+
+
 def _is_empty_context(ctx: Any) -> bool:
     """True when the eval's retrieved context is effectively empty (null/blank fields)."""
     if not ctx:
@@ -191,6 +297,8 @@ class GroundingResult:
     claim_verdicts: list[ClaimVerdict] = field(default_factory=list)
     context_empty: bool = True
     eval_scores: dict = field(default_factory=dict)
+    signals: list[dict] = field(default_factory=list)   # deterministic semantic-path findings
+    signal_severity: str = "INFO"                        # severity from the signals above
     meta: dict = field(default_factory=dict)
 
     @property
@@ -210,14 +318,26 @@ class GroundingResult:
             return "FABRICATION: the model's counts disagree with the KB despite retrieved context."
         if self.query_type == "structured" and self.verified_claims and not self.wrong_claims:
             return "GROUNDED: every verifiable count matches the KB."
-        if not self.verified_claims:
-            return "UNVERIFIED: no count claim could be checked (see notes)."
-        return "MIXED: some counts match, others do not."
+        # Semantic path: report the strongest deterministic signal.
+        if self.signals:
+            if any("not found in KB" in s["label"] for s in self.signals):
+                return "FABRICATED SOURCE: the response cites a document not present in the KB."
+            if any("empty retrieval" in s["label"].lower() for s in self.signals):
+                return ("UNGROUNDED: retrieval returned nothing, so the answer came from the model, "
+                        "not the KB.")
+            return "AT RISK: the eval's own scores indicate a grounding problem (see signals)."
+        if self.query_type == "structured" and not self.verified_claims:
+            return "UNVERIFIED: no count claim could be extracted from the response (see notes)."
+        return "NO SIGNAL: no deterministic grounding problem detected on this case."
 
     def severity(self) -> str:
         if self.wrong_claims:
-            return "HIGH"      # confident wrong data reaching users
-        if not self.verified_claims:
+            return "HIGH"      # confident wrong count reaching users
+        # Semantic severity comes from the deterministic signals (eval scores, empty
+        # retrieval, fabricated citation) - never a flat LOW that hides a 0.00-score case.
+        if _SEV_ORDER.get(self.signal_severity, 0) > 0:
+            return self.signal_severity
+        if self.query_type == "structured" and not self.verified_claims:
             return "LOW"
         return "INFO"
 
@@ -249,16 +369,24 @@ def run_audit(eval_record: dict, adapter: Any, eval_cfg: Any) -> GroundingResult
     result = GroundingResult(test_id=test_id, query=query, query_type=qtype, intents=intents,
                              context_empty=_is_empty_context(context),
                              eval_scores=scores if isinstance(scores, dict) else {})
+    # Deterministic semantic triage runs on EVERY case: eval-score severity, empty-retrieval,
+    # and cited-document existence are facts regardless of query type, so a semantic case with
+    # all-zero scores no longer reads as "LOW / nothing to see here".
+    sig, sig_sev = semantic_triage(response, result.context_empty, result.eval_scores)
+    cites = verify_citations(response, adapter, getattr(eval_cfg, "gt_doc_name_field", "file_name"))
+    result.signals = sig + cites
+    result.signal_severity = max([sig_sev] + [s["severity"] for s in cites],
+                                 key=lambda x: _SEV_ORDER.get(x, 0))
+
     if qtype == "structured":
         claims = extract_numeric_claims(response)
         result.claim_verdicts, result.meta = verify_structured_claims(
             adapter, claims, getattr(eval_cfg, "aggregatable_fields", []) or [])
     else:
-        # Semantic path (free-text claim verification) is a separate, measurement-gated
-        # mode; for now say so rather than run a fragile extractor and imply a verdict.
         result.meta = {"semantic": True,
-                       "note": "Semantic claim verification is not yet enabled; only the "
-                               "retrieved-context check ran."}
+                       "note": "Semantic path: deterministic signals only (eval-score severity, "
+                               "empty-retrieval, cited-document existence). Per-claim entailment "
+                               "is a separate mode."}
     return result
 
 
@@ -293,6 +421,15 @@ def render_report(result: GroundingResult, *, project: str = "") -> str:
             L.append(f"| {metric} | {score} | {target} | {status} |")
         L.append("")
 
+    if result.signals:
+        L.append("### Deterministic signals")
+        L.append("")
+        L.append("| Signal | Severity | Detail |")
+        L.append("|---|---|---|")
+        for s in result.signals:
+            L.append(f"| {s['label']} | {s['severity']} | {s['detail']} |")
+        L.append("")
+
     if result.claim_verdicts:
         L.append("### Claim verification against the KB")
         L.append("")
@@ -326,10 +463,21 @@ def render_report(result: GroundingResult, *, project: str = "") -> str:
             "  these exactly), not semantic search.",
             "- On **empty retrieval, refuse or flag uncertainty** rather than letting the model fill the gap.",
         ]
+    elif result.query_type == "structured" and not result.verified_claims:
+        # Was misreported as "no action indicated" - but NOTHING was checked. Say so.
+        L += [
+            "- **Could not extract a verifiable count from the response** - the claim (if any) was",
+            "  not in a recognised form. Review manually; the count was NOT confirmed against the KB.",
+        ]
+    elif any(s["severity"] in ("HIGH", "CRITICAL") for s in result.signals):
+        L += [
+            "- Deterministic signals flag a grounding problem (see the signals table). On **empty",
+            "  retrieval, refuse or flag uncertainty**; verify any cited source exists before citing it.",
+        ]
     elif result.query_type == "semantic":
         L += [
-            "- This is a topic query; run the semantic grounding mode (when enabled) to verify",
-            "  individual claims against the KB.",
+            "- No deterministic grounding problem detected. Per-claim entailment (a separate mode)",
+            "  would verify individual statements against the KB.",
         ]
     else:
         L.append("- Counts verified against the KB; no action indicated for this case.")

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/profiler.py

@@ -468,6 +468,20 @@ def emit_project_config(profiles: dict, *, project: str, env: str = "dev") -> st
         if exts:
             lines.append(f"      supported_extensions: [{', '.join(repr(e) for e in exts)}]")
 
+    # Suggest an eval block so `compass grounding-audit` can verify count claims out of the
+    # box: a low-cardinality field (a doc type/category) grouped by the doc-identity field.
+    if vector.get("reachable"):
+        cands = vector.get("id_candidates") or []
+        group = next((c["field"] for c in cands if str(c.get("kind", "")).startswith("low-cardinality")), "")
+        ident = next((c["field"] for c in cands if str(c.get("kind", "")).startswith("identity")),
+                     vector.get("chosen_id_field") or "")
+        if group and ident:
+            lines += [
+                "    eval:",
+                "      # For `compass grounding-audit` count verification (detected fields):",
+                f"      aggregatable_fields: [{{field: {group}, count_by: {ident}}}]",
+            ]
+
     return "\n".join(lines) + "\n"
 
 

{compass_kb_validation-2.4.0 → compass_kb_validation-2.6.0}/ingestion_validation/providers/vectorstore.py

@@ -102,6 +102,15 @@ class VectorStoreAdapter(ABC):
         """Return the master-metadata record for ``doc_id`` if the store has one."""
         return None
 
+    def has_master_metadata_index(self) -> bool:
+        """Whether a master-metadata index actually exists in this store.
+
+        Distinguishes "this KB has no master-metadata index" (the check is N/A) from "the
+        index exists but this document is missing from it" (a real gap). Base returns True
+        so backends without the concept are unaffected; the Redis adapter probes.
+        """
+        return True
+
     def distinct_doc_ids(self, limit: int = 1000) -> list[str]:
         """Enumerate distinct document ids present in the index.
 
@@ -341,6 +350,21 @@ class RedisVectorStoreAdapter(VectorStoreAdapter):
             return []
         return self._parse_search(raw)
 
+    def has_master_metadata_index(self) -> bool:
+        idx = self.config.master_metadata_index
+        if not idx:
+            return False
+        cached = getattr(self, "_master_idx_exists", None)
+        if cached is not None:
+            return cached
+        try:
+            self.client.execute_command("FT.INFO", idx)
+            exists = True
+        except Exception:  # noqa: BLE001 - no such index -> the KB doesn't use master metadata
+            exists = False
+        self._master_idx_exists = exists
+        return exists
+
     def master_metadata(self, doc_id: str) -> Optional[dict]:
         idx = self.config.master_metadata_index
         if not idx:
@@ -412,8 +436,12 @@ class RedisVectorStoreAdapter(VectorStoreAdapter):
     def aggregate_count(self, group_field, distinct_field=None, limit=100000):
         if not group_field:
             return None
+        # LOAD both fields: COUNT_DISTINCTISH @distinct can only count what is loaded, so
+        # loading just the group field silently degraded distinct-doc counts into raw chunk
+        # counts.
+        load = [f"@{group_field}"] + ([f"@{distinct_field}"] if distinct_field else [])
         cmd = ["FT.AGGREGATE", self.config.search_index, "*",
-               "LOAD", "1", f"@{group_field}",
+               "LOAD", str(len(load)), *load,
                "GROUPBY", "1", f"@{group_field}"]
         if distinct_field:
             cmd += ["REDUCE", "COUNT_DISTINCTISH", "1", f"@{distinct_field}", "AS", "__count__"]

compass_kb_validation-2.6.0/ingestion_validation/remediation.py

@@ -0,0 +1,154 @@
+"""Deterministic remediation hints.
+
+For a failed check label, return a short, actionable note: what the failure
+usually means and where in the pipeline to look. Pattern-matched, no LLM, no
+config - purely a lookup so the report can turn a diagnostic ("chunk check
+failed") into something a team can act on ("likely a re-embed gap; check the
+ingestion worker"). Hints are advisory; they never affect pass/fail.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Ordered most-specific first; the first matching pattern wins. Keep specific/stage-scoped
+# patterns above the broad ones, so e.g. a Redis "master metadata" check does not fall into
+# a graph hint.
+_HINTS: list[tuple[str, str]] = [
+    # ---- Vector store (chunks / embeddings) ------------------------------------------
+    (r"non.?empty|empty text",
+     "Chunks have empty text: the parser produced blank content or the text field was not populated. "
+     "Check the document extractor and the configured text field."),
+    (r"chunks exist|no chunks|chunk count",
+     "No/too-few chunks for this document: the embedding+indexing job likely never ran, "
+     "failed partway, or wrote to a different index. Check the ingestion worker and the configured index name."),
+    (r"l2 normal|embedding.*normal|normaliz",
+     "Embeddings are not normalised to match ingestion: the stored vectors' norm differs from what the "
+     "index/query path expects. Normalise at embed time, or set the expected normalisation to match the store."),
+    (r"embedding (validity|status)|zero|nan|inf",
+     "Degenerate or missing embeddings (zero/NaN vectors, or not written): the embedding model returned "
+     "bad output or the vectors were not stored. Re-run embedding for this document and verify the output."),
+    (r"vector dimension|embedding dimension|dim ",
+     "Embedding dimension mismatch: the model's output dimension differs from the index. "
+     "Align expected_embedding_dim with the embedding model and recreate the index if needed."),
+    (r"distance metric",
+     "Index distance metric differs from config: recreate the index with the expected metric, "
+     "or update expected_distance_metric to match the store."),
+    (r"correct document id|cross-document contamin",
+     "Chunks carry the wrong document id: ingestion wrote this document's chunks under another document's "
+     "key (or vice versa). Check the id field the chunker stamps on each chunk."),
+    (r"near-duplicate|no exact duplicate|repeated boilerplate|header|footer",
+     "Duplicate / boilerplate chunks: identical vectors or repeated disclaimer/header-footer text bloat the "
+     "index and skew retrieval. De-duplicate at ingestion and strip boilerplate before chunking."),
+    (r"chunk size|overlap|ordering|positional|section|page|boundaries|coherence|structure check",
+     "Chunk structure is off: the chunker's size/overlap/boundaries differ from config, or chunks were "
+     "written out of order / with gaps. Tune the chunking step's size and overlap parameters."),
+    (r"fidelity|full coverage|coverage of source|table/figure",
+     "Chunk text does not faithfully cover the source: extraction lost or garbled content (often tables/"
+     "figures). Inspect the document parser/extractor."),
+    (r"master metadata",
+     "The master-metadata record is missing for this document: the master-metadata write step did not run, "
+     "or the master index name is wrong. Check that step and redis.master_metadata_index."),
+    (r"metadata consistency",
+     "A document's metadata disagrees across its own chunks: the ingestion wrote inconsistent field values "
+     "per chunk. Fix the field at the chunk-write step so every chunk of a document agrees."),
+    (r"required fields|index schema|handles wildcard|required field",
+     "Index schema / required field problem: a declared field is missing, the wrong type, or the index does "
+     "not answer a basic query. Recreate the index with the expected field definitions."),
+    (r"semantic retrieval|filter.*vector|hybrid",
+     "The document is not retrievable via KNN as expected: the stored vector does not surface for its own "
+     "content, or the filter field is not indexed. Verify the embedding path and the filter field's index."),
+    (r"all chunks validated",
+     "This document has more chunks than the fetch cap, so only a prefix was validated. Raise "
+     "redis.max_chunks_per_document to cover the whole document."),
+
+    # ---- Knowledge graph -------------------------------------------------------------
+    (r"document found in graph",
+     "No graph node for this document: the graph-write step never created it, or wrote a different subject "
+     "id than the pipeline uses. Check the graph-write stage and the id/subject it emits."),
+    (r"required predicate|predicates present",
+     "Expected predicates are missing in the graph: the metadata-write step failed or used different "
+     "predicate names. Check the graph-write stage and the configured required_predicates."),
+    (r"identity is unique|document identity",
+     "Duplicate document identity in the graph: two subjects share the same id. De-duplicate the graph "
+     "write, or fix the id the ingestion assigns."),
+    (r"rdf type",
+     "Wrong or missing rdf:type on the document node: the graph-write step did not type the node as expected. "
+     "Check the typing in the graph-write stage."),
+    (r"namespace consistency|predicate namespace",
+     "Mixed predicate namespaces in the graph: some triples use a different ontology prefix. Align the "
+     "graph-write to one namespace (see the configured ontology_prefix/namespace)."),
+    (r"linked entities|dangling",
+     "A referenced entity does not exist in the graph (a dangling link): the linking step ran before its "
+     "target was written, or wrote the wrong id. Check ingestion ordering and the link target ids."),
+    (r"orphan",
+     "The document node has no edges (orphan): the relationship/linking step did not run for this document. "
+     "Check the graph-linking stage."),
+    (r"older versions superseded|supersed",
+     "A superseded version is not marked as such: the version/supersede predicate was not updated when a "
+     "newer document arrived. Update it in the graph-write step."),
+    (r"storage reference|storage key|storage ref",
+     "The graph's storage reference (key/eTag) does not match the object store: storage and graph were "
+     "written from different runs. Re-ingest so the graph points at the current object."),
+    (r"graph (document id|name|metadata) matches|classification matches|name matches source",
+     "A graph value disagrees with the pipeline/source (id, name, classification, or metadata): the graph "
+     "was written from a stale or different source. Re-sync the graph write with the source of truth."),
+    (r"date (field )?format|email (field )?format|field rule",
+     "A metadata field is malformed: fix the field formatting at the source/ingestion step "
+     "(e.g. ISO-8601 dates, valid email)."),
+
+    # ---- Cross-stage consistency -----------------------------------------------------
+    (r"present in every.*store|present in all",
+     "The document exists in some stores but not all: a stage's ingestion (storage, graph, or vector) did "
+     "not run for it. Re-run the missing stage so all stores agree."),
+    (r"shared metadata agrees|agree.*across|across stores",
+     "The same field has different values across storage/graph/index for this document: a partial or stale "
+     "re-ingest left the stores out of sync. Re-ingest to realign the shared fields."),
+    (r"access-control|acl|confidential",
+     "Access-control/confidentiality metadata was not propagated to the vector store: the ingestion did not "
+     "carry it onto the chunks. Add the field to the chunk-write so filtered retrieval can enforce it."),
+    (r"e_tag|etag|md5|integrity|matches s3|cross-system|docid",
+     "Cross-system id/hash mismatch: the same document differs between stages (storage vs graph vs index). "
+     "A re-upload or partial ingestion likely left stale copies; re-ingest to realign."),
+
+    # ---- Retrieval quality -----------------------------------------------------------
+    (r"embedding-model match|declared vs stored",
+     "Stored vectors were embedded with a different model than the one declared/serving: retrieval is "
+     "silently wrong. Re-embed the corpus with the declared model, or correct the declared model."),
+    (r"exact-term retrieval|keyword-index completeness|findable lexically",
+     "Chunks are not findable by exact keyword: the text field is not indexed for lexical search. Enable "
+     "hybrid (keyword + vector) retrieval, or index the text field for full-text search."),
+    (r"negative retrieval|off-topic",
+     "An off-topic query still scored high: embeddings are too generic or the index is polluted by "
+     "boilerplate. Improve chunk quality and strip boilerplate so unrelated queries do not match."),
+    (r"recall|mrr|paraphrase|boundary|empty query",
+     "The document is not retrievable as expected for real queries: embeddings may not match the query "
+     "path, or the filter field is not indexed. Verify the retrieval/query configuration."),
+
+    # ---- Ingestion API / storage / connectivity --------------------------------------
+    (r"http status|graphql|success status|valid json|api ",
+     "The ingestion API rejected or failed the upload: check the endpoint URL, auth, and the mutation/request shape."),
+    (r"upload latency",
+     "The upload exceeded its latency budget: the ingestion API is slow or overloaded; check service health."),
+    (r"source content|extractable text|structure \+ extractable",
+     "The source document has little or no extractable text (often an image-only/scanned PDF) or a corrupt "
+     "structure: downstream chunks will be empty or garbled. OCR the source or replace it with a text-bearing version."),
+    (r"file exists|content type|content-type|object|size|last ?modified|pdf",
+     "The object is missing or wrong in storage: the upload did not persist correctly "
+     "(wrong key/prefix, empty body, or wrong content type). Check the storage-write step."),
+    (r"reachable|unreachable|connect",
+     "Backend unreachable: check the endpoint, network, and credentials for this service."),
+]
+
+_COMPILED: list[tuple[re.Pattern, str]] = [(re.compile(p, re.IGNORECASE), h) for p, h in _HINTS]
+
+
+def hint_for(label: str) -> str | None:
+    """Return a remediation hint for a check label, or None if none matches."""
+    for rx, hint in _COMPILED:
+        if rx.search(label or ""):
+            return hint
+    return None
+
+
+__all__ = ["hint_for"]