compass-kb-validation 3.1.0__tar.gz → 3.2.1__tar.gz

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/PKG-INFO

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

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/__init__.py

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

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/citation.py

@@ -245,8 +245,16 @@ def _claim_before(text: str, idx: int) -> str:
     """The statement a citation supports: the text preceding it, back to the last real
     sentence break. Excludes the citation itself and anything after it."""
     start = 0
+    prev_start = 0
     for m in _SENT_BOUND.finditer(text[:idx]):
+        prev_start = start
         start = m.end()
+    # If the last sentence boundary sits right where the citation begins, that period is the
+    # TERMINATOR of the claim sentence (the standard "...claim. (SOURCE, p. N)" format), not a
+    # separator inside the claim - so text[start:idx] would be empty and the citation would be
+    # silently dropped. Fall back one boundary to capture the claim sentence itself.
+    if start >= idx - 2:
+        start = prev_start
     nl = text.rfind("\n", 0, idx)
     if nl + 1 > start:
         start = nl + 1
@@ -642,6 +650,15 @@ def audit_citations(response: str, eval_chunks: Optional[list[dict]], adapter: A
     summary = summarize(verdicts, response, l1_ran, l2_ran)
     if l1_ran:
         summary.update(context_utilization(citations, eval_chunks or [], cfg))
+    # DEFECT-003 safety net: if the response clearly carries citation-like patterns but none
+    # were extracted, say so rather than reporting a silent total_citations=0 that reads as
+    # "no citations exist" (which was the DEFECT-001 failure mode).
+    if not citations and response:
+        raw = len(_PAREN_CITE.findall(response))
+        if raw:
+            summary["diagnostic"] = (
+                f"{raw} citation-like pattern(s) matched by regex but 0 were extracted - "
+                "likely a claim-boundary parsing issue, not an absence of citations.")
     return {"verdicts": verdicts, "l1_ran": l1_ran, "l2_ran": l2_ran, "summary": summary}
 
 

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/cli.py

@@ -36,6 +36,13 @@ pipeline:
   critical_steps: []
   readiness_threshold: 1.0       # READY when document pass-rate >= this (e.g. 0.99)
 
+# Advisory checks you have ACCEPTED as expected for this corpus (e.g. an insurance KB where
+# near-duplicate boilerplate is normal). They drop out of the hygiene / Platform Health scores
+# but are still counted and shown ("N suppressed"). Only advisory checks - a hard gating failure
+# is never suppressed. Ad-hoc equivalent: `compass discover --suppress "Near-duplicate embeddings"`.
+# suppressions:
+#   - "Near-duplicate embeddings"
+
 environments:
   dev:
     redis:
@@ -1196,6 +1203,22 @@ def cmd_compare(argv: list[str]) -> int:
     if not cases:
         print(f"  No usable cases in {args.ground_truth} "
               f"(check the eval.gt_* field paths / variant filter in your config).")
+        # Say WHICH paths were tried and what resolved on the first record, so the user can see
+        # the actual mismatch instead of guessing (DEFECT-007).
+        from compass.eval_interop import diagnose_paths
+        diag = diagnose_paths(args.ground_truth, {
+            "gt_question_path": ev.gt_question_path,
+            "gt_chunks_path": ev.gt_chunks_path,
+            "gt_filters_path": ev.gt_filters_path,
+            "gt_variant_path": ev.gt_variant_path,
+        })
+        if diag:
+            print("  Configured paths on the first record:")
+            for line in diag:
+                print(line)
+            if variant_filter:
+                print(f"  variant filter: {', '.join(variant_filter)} "
+                      f"(via gt_variant_path=\"{ev.gt_variant_path or '(unset)'}\")")
         return 2
 
     # Ground-truth cases carry production's own metadata filters. If the backend cannot
@@ -1207,7 +1230,9 @@ def cmd_compare(argv: list[str]) -> int:
               file=sys.stderr)
 
     vnote = f" (variant filter: {', '.join(variant_filter)})" if variant_filter else ""
-    print(f"  Comparing compass retrieval against {len(cases)} ground-truth case(s){vnote} ...")
+    # Progress goes to stderr under --json so stdout stays a clean, pipeable JSON document.
+    print(f"  Comparing compass retrieval against {len(cases)} ground-truth case(s){vnote} ...",
+          file=sys.stderr if args.json else sys.stdout)
     try:
         payload = comparison_report(settings, cases, top_k=args.top_k or None,
                                     skip_empty=not args.include_empty)
@@ -1305,7 +1330,8 @@ def cmd_evidence(argv: list[str]) -> int:
         return 2
     limit = 1 if args.quick else (args.limit or settings.evidence.sample_size)
 
-    print(f"  compass evidence - project={args.project or '(none)'} checks={checks} limit={limit}")
+    print(f"  compass evidence - project={args.project or '(none)'} checks={checks} limit={limit}",
+          file=sys.stderr if args.format == "json" else sys.stdout)
     try:
         payload = ev.gather_evidence(settings, checks, document_filter=args.document, limit=limit)
     except Exception as exc:  # noqa: BLE001 - unreachable/misconfigured backend -> clean message
@@ -1376,7 +1402,8 @@ def cmd_quality(argv: list[str]) -> int:
     except Exception as exc:  # noqa: BLE001 - malformed/empty project YAML -> clean message, not a traceback
         print(f"  Config error: {exc}")
         return 2
-    print(f"  Sampling up to {args.sample} chunks for quality signals ...")
+    print(f"  Sampling up to {args.sample} chunks for quality signals ...",
+          file=sys.stderr if args.json else sys.stdout)
     try:
         payload = quality_report(settings, sample=args.sample, min_chars=args.min_chars)
     except Exception as exc:  # noqa: BLE001 - clean message, never a traceback
@@ -1421,7 +1448,8 @@ def cmd_freshness(argv: list[str]) -> int:
     except Exception as exc:  # noqa: BLE001 - malformed/empty project YAML -> clean message, not a traceback
         print(f"  Config error: {exc}")
         return 2
-    print(f"  Checking source freshness for up to {args.sample} document(s) ...")
+    print(f"  Checking source freshness for up to {args.sample} document(s) ...",
+          file=sys.stderr if args.json else sys.stdout)
     try:
         payload = freshness_report(settings, sample=args.sample, stale_after_days=args.stale_after)
     except Exception as exc:  # noqa: BLE001 - clean message, never a traceback

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/config/__init__.py

@@ -750,6 +750,12 @@ class Settings:
     display_name: str = ""
     environment: str = "dev"
     skip_steps: list[str] = field(default_factory=list)
+    # Advisory check labels the project has ACCEPTED as expected for this corpus (e.g. an
+    # insurance KB where near-duplicate boilerplate is normal). Suppressed advisories are
+    # excluded from the hygiene / Platform Health scores but still counted and shown ("N
+    # suppressed"). Only advisory (warn) checks can be suppressed - a hard gating failure
+    # always counts, so a known-issue can never mask a real failure.
+    suppressions: list[str] = field(default_factory=list)
     # Advisories raised while loading (e.g. an unrecognized top-level block that was
     # ignored). Surfaced by validate_config so a silently-dropped key is never invisible.
     config_warnings: list[str] = field(default_factory=list)
@@ -760,7 +766,7 @@ class Settings:
 # --------------------------------------------------------------------------- #
 # Non-service top-level keys that are legitimately not a service block.
 _META_KEYS = frozenset({"default_env", "display_name", "environments", "skip_steps",
-                        "pipeline_dependencies"})
+                        "pipeline_dependencies", "suppressions"})
 # The service-config blocks that may appear at the top level or under an environment.
 # Single source of truth: the flatten loop AND the unknown-key check both read this, so a
 # new block can never be added to one and forgotten in the other (which is exactly how
@@ -903,6 +909,7 @@ def load_settings(
         display_name=merged.get("display_name", ""),
         environment=resolved_env,
         skip_steps=list(merged.get("skip_steps", [])),
+        suppressions=list(merged.get("suppressions", [])),
     )
     # The embedding block's declared dimension IS the index's expected dimension. Cross-fill
     # it into the vector-store check when that check has no explicit value, so a project

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/corpus_health.py

@@ -261,6 +261,17 @@ def freshness_report(settings: Settings, *, sample: int = 500, stale_after_days:
             f"{without_key} of {len(seen_docs)} sampled document(s) carry no source key, so "
             f"their source could not be checked - likely a missing s3_key field (prefix/field "
             f"mismatch) or sources in a different store, not necessarily orphans.")
+    # A near-total orphan rate almost never means every source was deleted - it points at a
+    # systemic mismatch (the chunk s3_key does not match where objects actually live: wrong
+    # bucket, or a prefix baked into the key that the store does not use). Flag it so the user
+    # checks configuration before "reconciling" hundreds of false orphans (DEFECT-006).
+    if checked and len(orphans) / checked > 0.8:
+        result["warning"] = (
+            f"{len(orphans)}/{checked} sampled sources ({round(100 * len(orphans) / checked)}%) "
+            "look orphaned - a rate this high usually means a key mismatch (wrong bucket, or a "
+            "prefix in the chunk s3_key that the object store does not expect), not that the "
+            "sources are actually gone. Verify s3.bucket_name and the s3_key values before "
+            "reconciling.")
     return result
 
 

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/eval_interop.py

@@ -32,6 +32,42 @@ def get_path(record: Any, dotted: str) -> Any:
     return cur
 
 
+def diagnose_paths(path: str, gt_paths: dict) -> list[str]:
+    """Explain why a ground-truth file yielded no usable cases: for each configured gt_* path,
+    report whether it resolves on the first record and what type/size was found. Deterministic,
+    read-only, best-effort - returns human-readable lines (empty list if the file is unreadable).
+    """
+    import json
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            head = f.read(2_000_000)
+        data = json.loads(head)
+    except (OSError, ValueError):
+        # Maybe JSONL: try the first line.
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = [json.loads(f.readline())]
+        except (OSError, ValueError):
+            return []
+    rec = data[0] if isinstance(data, list) and data else (data if isinstance(data, dict) else None)
+    if not isinstance(rec, dict):
+        return ["first record is not an object - expected a JSON array (or JSONL) of case objects"]
+    lines = []
+    for label, dotted in gt_paths.items():
+        if not dotted:
+            lines.append(f"  {label}: (unset)")
+            continue
+        val = get_path(rec, dotted)
+        if val is None:
+            lines.append(f"  {label}: \"{dotted}\" -> NOT FOUND")
+        elif isinstance(val, list):
+            lines.append(f"  {label}: \"{dotted}\" -> found (list, {len(val)} item(s))")
+        else:
+            lines.append(f"  {label}: \"{dotted}\" -> found ({type(val).__name__})")
+    return lines
+
+
 def normalize_filters(raw: Any) -> dict:
     """Parse a filters value into ``{field: "a|b"}`` (compass filter form).
 

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/grounding.py

@@ -411,9 +411,21 @@ def run_audit(eval_record: dict, adapter: Any, eval_cfg: Any, doc_exists: Any =
     scores = get_path(eval_record, getattr(eval_cfg, "gt_scores_path", "scores")) or {}
     test_id = str(eval_record.get("test_id") or eval_record.get("id") or "")
 
+    # Retrieval is empty only if BOTH the configured context path AND the retrieved chunks are
+    # empty. The default gt_context_path (and gt_chunks_path) do not fit every eval schema, so
+    # keying "empty retrieval" off one path alone raised a false HIGH signal on records that
+    # clearly had chunks (DEFECT-002). Cross-check the configured chunk path plus the common
+    # nested locations so the emptiness verdict is schema-agnostic.
+    eval_chunks = get_path(eval_record, getattr(eval_cfg, "gt_chunks_path", "context.chunks"))
+    _chunk_candidates = (eval_chunks,
+                         get_path(eval_record, "context.chunks"),
+                         get_path(eval_record, "chunks"))
+    has_chunks = any(isinstance(c, list) and len(c) > 0 for c in _chunk_candidates)
+    context_empty = _is_empty_context(context) and not has_chunks
+
     qtype, intents = classify_query(query, getattr(eval_cfg, "structured_query_patterns", []))
     result = GroundingResult(test_id=test_id, query=query, query_type=qtype, intents=intents,
-                             context_empty=_is_empty_context(context),
+                             context_empty=context_empty,
                              eval_scores=scores if isinstance(scores, dict) else {})
     # Record which fields were auto-detected (vs configured), and whether this is a
     # retrieval-only case (no generated answer) - so the CLI can explain "0 citations" honestly.
@@ -429,7 +441,7 @@ def run_audit(eval_record: dict, adapter: Any, eval_cfg: Any, doc_exists: Any =
     # Citation audit: verify each cited claim at its cited location (Level 1 against the eval's
     # retrieved chunks when present, Level 2 against the live KB). The "cited document absent"
     # signal is derived from it, so citation extraction lives in exactly one place.
-    eval_chunks = get_path(eval_record, getattr(eval_cfg, "gt_chunks_path", "context.chunks"))
+    # (eval_chunks was resolved above for the empty-retrieval cross-check.)
     result.citations = citation.audit_citations(
         response, eval_chunks if isinstance(eval_chunks, list) else None, adapter, eval_cfg,
         extra_patterns=getattr(eval_cfg, "citation_patterns", None), doc_exists=doc_exists)

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/providers/vectorstore.py

@@ -205,6 +205,15 @@ class RedisVectorStoreAdapter(VectorStoreAdapter):
         special = r"""\.+*?[]{}<>()@!#$%^&-=~'"`:;,/| """
         return "".join(f"\\{ch}" if ch in special else ch for ch in value)
 
+    @staticmethod
+    def escape_text(value: str) -> str:
+        """Escape RediSearch query-parser metacharacters for a TEXT-field query while
+        PRESERVING spaces as token separators. TAG escaping (escape_tag) backslash-escapes
+        spaces, which collapses a multi-word value into a single unmatchable token, so every
+        multi-word TEXT search silently returned nothing (DEFECT-008)."""
+        special = r"""\+*?[]{}<>()@!#$%^&-=~'"`:;,/|"""
+        return "".join(f"\\{ch}" if ch in special else ch for ch in value)
+
     def _id_query(self, search_value: str) -> str:
         field = self.config.document_id_field
         if self.config.document_id_field_type == "TAG":
@@ -305,7 +314,9 @@ class RedisVectorStoreAdapter(VectorStoreAdapter):
         return self._parse_search(raw, keep_binary_fields=(emb,))
 
     def text_search(self, field: str, value: str, limit: int = 10) -> list[dict]:
-        escaped = self.escape_tag(value)
+        # TEXT-field query: escape parser metacharacters but keep spaces as token separators
+        # so a multi-word value matches its tokens (was TAG-escaped -> matched nothing).
+        escaped = self.escape_text(value)
         query = f"@{field}:({escaped})"
         try:
             raw = self.client.execute_command(

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass/report/__init__.py

@@ -317,7 +317,8 @@ def _result_payload(name: str, r: PipelineResult) -> dict:
     }
 
 
-def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
+def _aggregate(cases: list[dict], hide_skipped: bool = True,
+               suppress: set[str] | None = None) -> dict:
     total = len(cases)
     passed = sum(1 for c in cases if c["overall"] == "PASSED")
     failed = sum(1 for c in cases if c["overall"] == "FAILED")
@@ -330,6 +331,12 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
     # check is either a HARD failure (fails the step) or an ADVISORY warning (does not).
     # Neutral checks (the backend/config can't evaluate them) are counted separately.
     checks_hard = checks_advisory = checks_neutral = 0
+    # Advisory checks a project has explicitly accepted (config `suppressions`). They are
+    # excluded from scoring - like neutral checks - but tallied and shown, never hidden. HARD
+    # (gating) checks can NEVER be suppressed, so an accepted known-issue can't mask a failure.
+    checks_suppressed = 0
+    suppressed: Counter = Counter()
+    suppress = suppress or set()
     cat = {name: {"total": 0, "passed": 0, "adv_total": 0, "adv_passed": 0} for name, _ in _CAT_ORDER}
     # Which checks fail across the MOST documents. One systemic cause usually shows up as
     # one label repeated over many documents, so ranking by document count points at the
@@ -369,10 +376,19 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                 if ch.get("supported", True) is False:
                     checks_neutral += 1  # neutral — backend can't evaluate this check
                     continue
-                k = _categorise(ch.get("label", ""), step_name)
+                _label = ch.get("label", "")
+                _sev = "warn" if str(ch.get("severity", "hard")).lower() == "warn" else "hard"
+                # Suppressed = an ADVISORY check the project accepted as expected (e.g. known
+                # boilerplate near-duplicates). Excluded from scoring but counted + shown.
+                # Only advisory can be suppressed - a hard/gating check ignores the list.
+                if _sev == "warn" and _label in suppress:
+                    checks_suppressed += 1
+                    suppressed[_label] += 1
+                    continue
+                k = _categorise(_label, step_name)
                 cat[k]["total"] += 1
                 ch_passed = bool(ch.get("passed"))
-                sev = "warn" if str(ch.get("severity", "hard")).lower() == "warn" else "hard"
+                sev = _sev
                 # Hygiene tracks ADVISORY (WARN) checks only - the quality BEYOND the
                 # integrity gate. HARD checks passing is what READY already reports, so
                 # counting them would just pull hygiene toward 100 and hide the signal.
@@ -387,9 +403,17 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                     checks_advisory += 1
                 else:
                     checks_hard += 1
-                label = ch.get("label", "")
-                rec = offenders.setdefault(label, {"label": label, "docs": 0, "severity": sev, "step": step_name})
+                label = _label
+                rec = offenders.setdefault(
+                    label, {"label": label, "docs": 0, "severity": sev, "step": step_name, "detail": ""})
                 rec["docs"] += 1
+                # Keep one concrete, measured example (the check's own detail, e.g.
+                # "4200 (~3000 expected)") so the Action Plan can show a specific number
+                # instead of a generic cause. First non-empty wins - deterministic.
+                if not rec["detail"]:
+                    _dv = str(ch.get("detail") or "").strip()
+                    if _dv:
+                        rec["detail"] = _dv
                 # a label is HARD overall if it ever gates
                 if sev == "hard":
                     rec["severity"] = "hard"
@@ -433,6 +457,11 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
         # rests on less than the full pipeline.
         "docs_incomplete": docs_incomplete,
         "hygiene": hygiene,
+        # Accepted advisory issues (config `suppressions`): count + per-label tally, shown
+        # so a suppressed warning is disclosed, never silently dropped.
+        "checks_suppressed": checks_suppressed,
+        "suppressed": [{"label": lbl, "docs": n} for lbl, n in
+                       sorted(suppressed.items(), key=lambda kv: (-kv[1], kv[0]))],
     }
 
 
@@ -444,15 +473,16 @@ _HYGIENE_TIERS = (
 )
 
 
-def hygiene_from_results(results: list[dict]) -> dict | None:
+def hygiene_from_results(results: list[dict], suppress: list[str] | None = None) -> dict | None:
     """Public: compute the KB Hygiene score from a list of ``{name, result}`` items.
 
     Same deterministic scoring the report uses, exposed so the CLI can gate on it
-    (``--quality-threshold``) without rendering HTML. Returns None if there are no
-    advisory checks to score.
+    (``--quality-threshold``) without rendering HTML. ``suppress`` accepts the same accepted
+    advisory labels as the report, so the gate and the report agree. Returns None if there
+    are no advisory checks to score.
     """
     cases = [_result_payload(item.get("name", item["result"].file_name), item["result"]) for item in results]
-    return _aggregate(cases).get("hygiene")
+    return _aggregate(cases, suppress=set(suppress or [])).get("hygiene")
 
 
 def _hygiene_score(cat: dict) -> dict | None:
@@ -693,6 +723,12 @@ def _exec_summary(agg: dict, corpus: dict | None = None, cases: list[dict] | Non
                      f'these documents - see Coverage">{agg["docs_incomplete"]} not fully validated</span>')
     if agg.get("checks_advisory"):
         chips.append(f'<span class="hero-chip">{agg["checks_advisory"]} advisory</span>')
+    if agg.get("checks_suppressed"):
+        # Accepted known-issues: disclosed, never hidden. Tooltip names what was suppressed.
+        acc = ", ".join(f'{s["label"]} (x{s["docs"]})' for s in agg.get("suppressed", [])[:8])
+        chips.append(f'<span class="hero-chip" data-tip="Accepted advisory issues (config '
+                     f'suppressions) - excluded from hygiene &amp; health, never from the gate: '
+                     f'{_esc(acc)}">{agg["checks_suppressed"]} suppressed</span>')
     chips_html = f'<div class="hero-chips">{"".join(chips)}</div>' if chips else ""
     t = max(agg["total"], 1)
     seg = ""
@@ -1064,8 +1100,14 @@ def _action_plan_section(agg: dict) -> str:
     # cards below; a pointer here makes the remainder explicit rather than silently dropped.
     cards = ""
     for i, g in enumerate(ranked[:_ACTION_CAP], 1):
+        ranked_checks = sorted(g["checks"], key=lambda o: -o["docs"])
         evidence = ", ".join(f'{_esc(o["label"])} {round(100 * o["docs"] / g["total"])}%'
-                             for o in sorted(g["checks"], key=lambda o: -o["docs"])[:3])
+                             for o in ranked_checks[:3])
+        # A concrete measured example from the worst check (e.g. "4200 (~3000 expected)"),
+        # so Observed carries a specific number - the "why" - not just which check failed.
+        example = next((o.get("detail") for o in ranked_checks if o.get("detail")), "")
+        if example:
+            evidence += f' <span class="check-detail">e.g. {_esc(example)}</span>'
         # A concise, category-specific INSTRUCTION here - the diagnosis now lives in the
         # Observed/Likely/Possible tiers, so the fix line is just "what to do" and never
         # repeats a cause. The verbose per-check hint stays in the detailed cards below.
@@ -1687,6 +1729,16 @@ def _glossary_section(agg: dict | None = None, corpus: dict | None = None, mode:
             '</dl>'
             '<dd style="margin-top:8px">A document is PASSED only when every non-skipped step passes. Critical-step failures halt remaining steps.</dd>')
 
+    # Suppressed: only when this run actually accepted advisory issues.
+    if agg is not None and agg.get("checks_suppressed"):
+        section("Suppressed (accepted)", dl([
+            ("Suppressed", "An advisory check the project accepted as expected for this corpus "
+             "(config `suppressions` / `--suppress`) - e.g. near-duplicate boilerplate in policy "
+             "documents. Excluded from the hygiene and Platform Health scores but still counted "
+             "and shown as 'N suppressed'. Only advisory checks can be suppressed; a hard gating "
+             "failure is never suppressed, so an accepted known-issue can never mask a real one."),
+        ]))
+
     # Readiness Verdict: only when a corpus supplied one.
     if corpus is not None:
         section("Readiness Verdict",
@@ -2057,6 +2109,7 @@ def generate_batch_dashboard(
     wall_seconds: float | None = None,
     concurrency: int | None = None,
     evidence: dict | None = None,
+    suppress: list[str] | None = None,
 ) -> str:
     """Generate a self-contained, interactive HTML dashboard. Returns abs path.
 
@@ -2076,7 +2129,8 @@ def generate_batch_dashboard(
     _ICON = {s.name: s.icon for s in registered_steps()}
 
     cases = [_result_payload(item.get("name", item["result"].file_name), item["result"]) for item in results]
-    agg = _aggregate(cases, hide_skipped=hide_skipped)  # computed on FULL data, before any trim
+    # computed on FULL data, before any trim; suppressions accepted from config
+    agg = _aggregate(cases, hide_skipped=hide_skipped, suppress=set(suppress or []))
     # Wall clock vs compute time: agg["duration"] is the SUM of per-document durations, so
     # under --parallel it far exceeds the elapsed time (a 502-doc run summed 1319s but
     # finished in 329s). Carry the real wall clock and concurrency so the summary can show

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/compass_kb_validation.egg-info/PKG-INFO

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

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/discover_and_validate.py

@@ -26,7 +26,8 @@ EXIT_OK, EXIT_GATE_FAILED, EXIT_CONFIG = 0, 1, 2
 
 
 def parse_args(argv=None) -> argparse.Namespace:
-    p = argparse.ArgumentParser(description="Discover storage documents and validate vector chunks")
+    p = argparse.ArgumentParser(prog="compass discover",
+                                description="Discover storage documents and validate vector chunks")
     p.add_argument("--project", help="Project name (required unless --list-checks)")
     p.add_argument("--list-checks", action="store_true",
                    help="Print the vector-store check catalogue (number, name, default severity tier) and exit.")
@@ -90,6 +91,11 @@ def parse_args(argv=None) -> argparse.Namespace:
                         "--disable-check chunk_count near_duplicate_embeddings.")
     p.add_argument("--severity", nargs="*", default=[], metavar="NAME=TIER",
                    help="Override a check's severity, e.g. --severity duplicate_detection=hard.")
+    p.add_argument("--suppress", nargs="*", default=[], metavar="CHECK",
+                   help="Accept an ADVISORY check as expected for this corpus, e.g. --suppress "
+                        "'Near-duplicate embeddings'. Excluded from the hygiene / Platform Health "
+                        "scores but still counted and shown ('N suppressed'). Adds to config "
+                        "suppressions. Only advisory checks - a hard gating failure is never suppressed.")
     # --- baselines + drift (continuous gate) ---
     p.add_argument("--save-baseline", nargs="?", const="", default=None, metavar="PATH",
                    help="Snapshot this run as a baseline (default: baselines/<project>.json).")
@@ -469,6 +475,11 @@ def main(argv=None) -> int:
         print(f"  Config error: {exc}")
         return EXIT_CONFIG
 
+    # Accepted advisory issues = config suppressions + any ad-hoc --suppress (deduped, order-kept).
+    # Threaded into BOTH the hygiene gate and the report so the score and the HTML agree.
+    suppress = list(dict.fromkeys(
+        list(getattr(settings, "suppressions", []) or []) + list(args.suppress or [])))
+
     # Discovery validates the END STATE of an already-ingested corpus. Ingestion-stage
     # steps (upload, storage) already happened, so they must never HALT the run before
     # the chunk/retrieval checks that are the point. Strip them from critical_steps.
@@ -596,7 +607,7 @@ def main(argv=None) -> int:
             print(f"    evidence skipped: {exc}")
 
     if args.output_format in ("html", "all"):
-        print(f"\n  HTML report: {generate_batch_dashboard(results, base + '.html', project=args.project, environment=args.env, run_id=run_id, trends=trend_rows, corpus=corpus, mode='Discovery', profile=profile_data, wall_seconds=wall_seconds, concurrency=concurrency, evidence=evidence_by_doc)}")
+        print(f"\n  HTML report: {generate_batch_dashboard(results, base + '.html', project=args.project, environment=args.env, run_id=run_id, trends=trend_rows, corpus=corpus, mode='Discovery', profile=profile_data, wall_seconds=wall_seconds, concurrency=concurrency, evidence=evidence_by_doc, suppress=suppress)}")
     if args.output_format in ("json", "all"):
         print(f"  JSON report: {export_json(results, base + '.json')}")
     if args.output_format in ("junit", "all"):
@@ -617,7 +628,7 @@ def main(argv=None) -> int:
     # Best-effort context - a failure to score it must not crash the gate decision.
     from compass.report import hygiene_from_results
     try:
-        hygiene = hygiene_from_results(results)
+        hygiene = hygiene_from_results(results, suppress=suppress)
     except Exception:  # noqa: BLE001 - hygiene is advisory; never break the run over it
         hygiene = None
     if hygiene:

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/profile_kb.py

@@ -27,7 +27,11 @@ EXIT_OK, EXIT_NONE_REACHABLE, EXIT_CONFIG = 0, 1, 2
 
 
 def parse_args(argv=None) -> argparse.Namespace:
-    p = argparse.ArgumentParser(description="Profile pipeline stages and suggest a COMPASS config")
+    # Explicit prog: when dispatched via `compass profile` / `python -m compass profile`, the
+    # command name is stripped and sys.argv[0] can be None, which argparse's default
+    # prog=basename(sys.argv[0]) chokes on (TypeError on None). Naming it avoids that.
+    p = argparse.ArgumentParser(prog="compass profile",
+                                description="Profile pipeline stages and suggest a COMPASS config")
     p.add_argument("--project", required=True, help="Project name")
     p.add_argument("--env", default="dev", help="Environment")
     p.add_argument("--stage", choices=["storage", "graph", "vector", "all"], default="all",

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/run_validation.py

@@ -29,7 +29,8 @@ EXIT_OK, EXIT_FAILURES, EXIT_CONFIG = 0, 1, 2
 
 
 def parse_args(argv=None) -> argparse.Namespace:
-    p = argparse.ArgumentParser(description="COMPASS — AI knowledge base validation")
+    p = argparse.ArgumentParser(prog="compass validate",
+                                description="COMPASS - AI knowledge base validation")
     p.add_argument("--project", required=True, help="Project name (loads config/projects/<name>.yaml)")
     p.add_argument("--env", default=None, help="Environment: dev, staging, prod")
     p.add_argument("--file", help="Validate a single file (overrides test_data)")
@@ -228,7 +229,7 @@ def main(argv=None) -> int:
     report_base = f"reports/{args.project}-report"
     fmt = args.output_format
     if fmt in ("html", "all"):
-        print(f"  HTML report: {generate_batch_dashboard(results, report_base + '.html', project=args.project, environment=settings.environment, run_id=run_id, trends=trend_rows, corpus=corpus, mode='Live Ingestion')}")
+        print(f"  HTML report: {generate_batch_dashboard(results, report_base + '.html', project=args.project, environment=settings.environment, run_id=run_id, trends=trend_rows, corpus=corpus, mode='Live Ingestion', suppress=list(getattr(settings, 'suppressions', []) or []))}")
     if fmt in ("json", "all"):
         print(f"  JSON report: {export_json(results, report_base + '.json')}")
     if fmt in ("junit", "all"):

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_citation.py

@@ -443,3 +443,32 @@ def test_report_renders_citation_section():
     assert "Citation audit" in md and "Generation hallucination" in md
     assert "lexical" in md.lower()                    # honest-boundary note present
     assert "Where to fix" in md and "**Generation**" in md   # per-fault remediation present
+
+
+def test_citation_after_sentence_period_is_extracted():
+    # DEFECT-001: the standard "...claim. (SOURCE, p. N)" format (citation right after the
+    # sentence-ending period) must extract the claim, not silently drop the citation.
+    text = ("Growth is expected to stay robust, supported by resilient demand. "
+            "(SOURCE, June 2026, p. 1) Earnings are projected to grow.")
+    cites = citation.extract_citations(text)
+    assert len(cites) == 1
+    assert cites[0].claim.endswith("resilient demand.")     # the claim sentence, not empty
+    # multiple sentences: the claim is the LAST sentence before the citation, not the whole text
+    multi = citation.extract_citations("First point here. Second claim with detail. "
+                                       "(SOURCE, 2026, p. 2) Next.")
+    assert multi and multi[0].claim == "Second claim with detail."
+    # a mid-sentence citation still resolves to the preceding text
+    mid = citation.extract_citations("Earnings grew 12% (SOURCE, 2026, p. 3) which beat.")
+    assert mid and mid[0].claim == "Earnings grew 12%"
+
+
+def test_diagnostic_when_pattern_matches_but_nothing_extracted():
+    # DEFECT-003: a citation-like pattern with no supporting claim (extraction yields 0) must
+    # surface a diagnostic, not a silent total_citations=0 that reads as "no citations exist".
+    from types import SimpleNamespace
+    cfg = SimpleNamespace(citation_patterns=[], citation_page_tolerance=0,
+                          citation_verify_entities=False,
+                          gt_chunk_doc_field="document_title", gt_chunk_page_field="page_start")
+    res = citation.audit_citations("(SOURCE, 2026, p. 1)", None, None, cfg)
+    assert res["summary"]["total_citations"] == 0
+    assert "matched by regex but 0 were extracted" in res["summary"].get("diagnostic", "")

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_config.py

@@ -110,6 +110,22 @@ class TestLoadSettings:
         assert s.redis.search_index == "demo_index"  # overridden
         assert s.redis.expected_embedding_dim == 1536  # inherited from base
 
+    def test_suppressions_load_from_project_yaml(self, tmp_path):
+        cfg_dir = tmp_path / "config"
+        (cfg_dir / "projects").mkdir(parents=True)
+        (cfg_dir / "base.yaml").write_text("default_env: dev\n")
+        (cfg_dir / "projects" / "demo.yaml").write_text(
+            textwrap.dedent(
+                """
+                suppressions:
+                  - "Near-duplicate embeddings"
+                  - "Duplicate text chunks"
+                """
+            )
+        )
+        s = load_settings(project="demo", env="dev", config_dir=cfg_dir)
+        assert s.suppressions == ["Near-duplicate embeddings", "Duplicate text chunks"]
+
     def test_environment_selection(self, tmp_path):
         cfg_dir = tmp_path / "config"
         cfg_dir.mkdir()

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_corpus_health.py

@@ -102,3 +102,15 @@ def test_cmd_freshness_end_to_end(monkeypatch, capsys):
                         if cat == "vectorstore" else store)
     assert cli.cmd_freshness([]) == 0
     assert "Freshness" in capsys.readouterr().out
+
+
+def test_freshness_warns_on_near_total_orphan_rate():
+    # DEFECT-006: a ~100% orphan rate almost always means a key/bucket mismatch, not that every
+    # source was deleted. Flag it so the user checks config before "reconciling" false orphans.
+    now = datetime(2026, 7, 10, tzinfo=timezone.utc)
+    chunks = [make_chunk(f"doc{i}", 0, s3_key=f"missing{i}.pdf") for i in range(5)]
+    store = FakeStorageAdapter(objects={})   # nothing found -> all orphaned
+    rep = freshness_report(Settings(), sample=10, now=now,
+                           vectorstore=FakeVectorStoreAdapter(chunks=chunks), storage=store)
+    assert rep["orphan_count"] == 5
+    assert "warning" in rep and "key mismatch" in rep["warning"]

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_eval_interop.py

@@ -206,3 +206,19 @@ def test_cmd_compare_end_to_end(monkeypatch, tmp_path, capsys):
     assert cli.cmd_compare(["--ground-truth", str(gt)]) == 0
     out = capsys.readouterr().out
     assert "Retrieval comparison" in out and "VERDICT" in out
+
+
+def test_diagnose_paths_reports_found_and_missing(tmp_path):
+    # DEFECT-007: when compare finds no usable cases, say which configured paths resolved on the
+    # first record and which did not, instead of a generic "check your config".
+    from compass.eval_interop import diagnose_paths
+    p = tmp_path / "gt.json"
+    p.write_text(json.dumps([{"input": "q", "context": {"chunks": [{"text": "a"}, {"text": "b"}]}}]))
+    lines = "\n".join(diagnose_paths(str(p), {
+        "gt_question_path": "question",          # absent
+        "gt_chunks_path": "context.chunks",      # present, 2 items
+        "gt_variant_path": "",                   # unset
+    }))
+    assert 'gt_question_path: "question" -> NOT FOUND' in lines
+    assert 'gt_chunks_path: "context.chunks" -> found (list, 2 item(s))' in lines
+    assert "gt_variant_path: (unset)" in lines

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_grounding.py

@@ -263,3 +263,22 @@ def test_fabrication_gate_covers_semantic_fabricated_source():
     r2 = run_audit({"input": "outlook?", "response": "Cautious.", "context.retrieved": "cautious given rates",
                     "scores": {"Groundedness": {"score": 0.9, "target": 0.7}}}, KB(), _cfg(gt_context_path="context.retrieved"))
     assert r2.has_fabrication is False
+
+
+def test_context_not_empty_when_chunks_present_defect_002():
+    # DEFECT-002: chunks nested under context.chunks must not read as "empty retrieval" just
+    # because the configured gt_context_path does not resolve for this eval schema.
+    from compass.config import Settings
+
+    class _Ad:
+        def text_search(self, *a, **k):
+            return []
+        def get_by_id(self, *a, **k):
+            return None
+
+    ev = Settings().eval
+    with_chunks = {"input": "q", "output": "answer",
+                   "context": {"type": "knowledge_retrieval", "chunks": [{"text": "a"}, {"text": "b"}]}}
+    assert run_audit(with_chunks, _Ad(), ev).context_empty is False
+    truly_empty = {"input": "q", "output": "answer", "context": {}}
+    assert run_audit(truly_empty, _Ad(), ev).context_empty is True

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_reporting.py

@@ -632,6 +632,49 @@ def test_engineering_wins_are_check_backed_and_specific():
                    for w in report_mod._engineering_wins({**agg, "failed": 3}))
 
 
+def test_advisory_suppression_excludes_from_scoring_but_discloses():
+    # An accepted advisory (config `suppressions`) drops out of hygiene / offenders but is
+    # still counted and listed - never silently hidden.
+    r = PipelineResult(document_id="d", file_name="d.pdf")
+    r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok", checks=[
+        {"label": "Near-duplicate embeddings", "passed": False, "severity": "warn"},
+        {"label": "Chunk boundaries clean", "passed": True, "severity": "warn"},
+    ]))
+    cases = [report_mod._result_payload("d.pdf", r)]
+    base = report_mod._aggregate(cases)
+    supp = report_mod._aggregate(cases, suppress={"Near-duplicate embeddings"})
+    assert any(o["label"] == "Near-duplicate embeddings" for o in base["offenders"])
+    assert not any(o["label"] == "Near-duplicate embeddings" for o in supp["offenders"])
+    assert supp["checks_suppressed"] == 1
+    assert supp["suppressed"] == [{"label": "Near-duplicate embeddings", "docs": 1}]
+    # suppressing the failing advisory lifts hygiene (only the clean advisory remains scored)
+    assert supp["hygiene"]["score"] > base["hygiene"]["score"]
+
+
+def test_hard_check_is_never_suppressed():
+    # A gating failure must count even if its label is in the suppress list - a known-issue
+    # can never mask a real failure (the integrity mandate).
+    r = PipelineResult(document_id="d", file_name="d.pdf")
+    r.add_step(StepResult("Redis Chunks", StepStatus.FAILED, "bad",
+        checks=[{"label": "Chunks exist", "passed": False, "severity": "hard"}]))
+    agg = report_mod._aggregate([report_mod._result_payload("d.pdf", r)], suppress={"Chunks exist"})
+    assert agg["checks_suppressed"] == 0
+    assert any(o["label"] == "Chunks exist" for o in agg["offenders"])
+    assert agg["checks_hard"] == 1
+
+
+def test_action_plan_surfaces_a_measured_detail():
+    # Specific RCA: the Action Plan's Observed line carries a concrete measured example from
+    # the check's own detail, not just which check failed.
+    r = PipelineResult(document_id="d", file_name="d.pdf")
+    r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok", checks=[
+        {"label": "Chunk count in range", "passed": False, "severity": "warn",
+         "detail": "4200 (~3000 expected)"}]))
+    agg = report_mod._aggregate([report_mod._result_payload("d.pdf", r)])
+    html = report_mod._action_plan_section(agg)
+    assert "4200 (~3000 expected)" in html          # the measured number, surfaced
+
+
 def test_glossary_is_run_driven_not_a_fixed_catalogue():
     # A run with retrieval + chunk findings: the glossary explains exactly what appeared -
     # its categories, Platform Health, the Action Plan tiers, and only the mode that ran -

{compass_kb_validation-3.1.0 → compass_kb_validation-3.2.1}/tests/test_vectorstore_filters.py

@@ -83,6 +83,20 @@ def test_redis_builds_hybrid_tag_prefilter():
     assert "=>[KNN 5 @text_embedding $vec AS __score]" in client.query
 
 
+def test_text_search_preserves_spaces_for_multiword_queries():
+    # DEFECT-008: a multi-word TEXT search must keep spaces as token separators. TAG-escaping
+    # backslash-escaped them, collapsing the value into one unmatchable token so every
+    # multi-word search silently returned nothing.
+    client = _FakeRedis()
+    a = RedisVectorStoreAdapter(_cfg("redis"), client=client)
+    a.text_search("text", "Growth is robust", 5)
+    assert client.query == "@text:(Growth is robust)"      # spaces intact
+    assert "\\ " not in client.query                        # NOT the broken TAG-escaped form
+    # single words are unchanged; query-parser metacharacters are still escaped
+    assert RedisVectorStoreAdapter.escape_text("ACWI") == "ACWI"
+    assert "\\(" in RedisVectorStoreAdapter.escape_text("S&P (est)")
+
+
 # --------------------------------------------------------------------------- #
 # Qdrant - Filter(must=[FieldCondition(MatchValue|MatchAny)])
 # --------------------------------------------------------------------------- #