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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass-kb-validation
-Version: 2.4.0
+Version: 2.5.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.5.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.5.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.5.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.5.0"

{compass_kb_validation-2.4.0 → compass_kb_validation-2.5.0}/ingestion_validation/report/__init__.py

@@ -58,8 +58,23 @@ _CAT_ORDER = [
     ("Content Preservation", "Fidelity, coverage, contamination"),
     ("Index & Schema", "Index fields, types, vector config"),
     ("Retrieval & Query", "Semantic search, filters, resilience"),
-    ("Other", "Existence and core integrity"),
+    # Stage-derived buckets: catch a stage's checks that don't match a semantic pattern
+    # above, so they get a named home instead of swelling an opaque "Other".
+    ("Knowledge Graph", "Graph existence, typing, links, namespaces"),
+    ("Object Storage", "Source object existence, type, size, integrity"),
+    ("Cross-Stage Consistency", "Do the stores agree about a document?"),
+    ("Ingestion API", "Upload response, document id, status"),
+    ("Other", "Uncategorised checks"),
 ]
+# When a check's label matches no semantic pattern, fall back to the category of the STEP
+# it came from (so 'Other' stays small and honest instead of holding 54% of the checks).
+_STEP_CATEGORY = {
+    "Neptune Metadata": "Knowledge Graph",
+    "GraphDB Metadata": "Knowledge Graph",
+    "S3 Storage": "Object Storage",
+    "Cross-Stage Consistency": "Cross-Stage Consistency",
+    "API Upload": "Ingestion API",
+}
 _CAT_PATTERNS = [
     ("Metadata & Consistency", re.compile(r"e_tag|required field|metadata consist|positional|section|page metadata|directory|predicate|date format|email|field rule", re.I)),
     ("Chunk Structure", re.compile(r"boundaries|chunk count|size within|ordering|overlap", re.I)),
@@ -92,6 +107,15 @@ li .check-hint{margin:4px 0 0 0;display:block;}
 .metric-chip{background:var(--chip-bg);border:1px solid var(--line);border-radius:8px;padding:6px 11px;font-size:12px;color:var(--muted);}
 .metric-chip b{color:var(--ink);font-variant-numeric:tabular-nums;}
 .exec-interp-title{font-size:12px;text-transform:uppercase;letter-spacing:.07em;color:var(--muted);font-weight:700;margin-bottom:6px;}
+.exec-narrative{font-size:13.5px;line-height:1.6;color:var(--ink);margin:0 0 10px;padding:9px 12px;background:var(--chip-bg);border-radius:8px;border-left:3px solid var(--accent);}
+.subsys-rollup{padding:14px 16px 18px;display:flex;flex-direction:column;gap:8px;border-bottom:1px solid var(--line);}
+.subsys-head{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);font-weight:700;margin-bottom:4px;}
+.subsys-row{display:grid;grid-template-columns:160px 1fr auto;align-items:center;gap:12px;font-size:12px;}
+.subsys-name{font-weight:700;color:var(--ink);}
+.subsys-bar{height:10px;background:var(--line);border-radius:5px;overflow:hidden;}
+.subsys-bar i{display:block;height:100%;border-radius:5px;}
+.subsys-meta{color:var(--muted);white-space:nowrap;font-variant-numeric:tabular-nums;}
+@media(max-width:600px){.subsys-row{grid-template-columns:1fr;gap:3px;}}
 .exec-bullets{margin:0 0 4px;padding-left:18px;font-size:13.5px;line-height:1.75;color:var(--ink);}
 .exec-bullets li{margin:0;}
 .exec-bullets li::marker{color:var(--muted);}
@@ -103,6 +127,8 @@ li .check-hint{margin:4px 0 0 0;display:block;}
 .hygiene-score{font-size:15px;font-weight:800;margin-top:2px;}
 .hygiene-score.ok{color:var(--ok);}.hygiene-score.warn{color:var(--warn);}.hygiene-score.bad{color:var(--bad);}
 .hygiene-worst{font-size:11px;color:var(--muted);margin-top:2px;}
+.hygiene-delta{font-size:11px;font-weight:700;margin-left:6px;}
+.hygiene-delta.ok{color:var(--ok);}.hygiene-delta.bad{color:var(--bad);}
 .hero-chips{display:flex;flex-wrap:wrap;gap:5px;}
 .hero-chip{font-size:10.5px;font-weight:700;padding:2px 7px;border-radius:9px;border:1px solid var(--line);color:var(--muted);white-space:nowrap;}
 .hero-chip.bad{color:var(--bad);border-color:color-mix(in srgb,var(--bad) 45%,transparent);}
@@ -198,11 +224,12 @@ def _band(status: str) -> str:
     return _BAND.get(status, "na")
 
 
-def _categorise(label: str) -> str:
+def _categorise(label: str, step: str = "") -> str:
     for name, pat in _CAT_PATTERNS:
         if pat.search(label or ""):
             return name
-    return "Other"
+    # No semantic match: give it the step's own category so it isn't dumped into "Other".
+    return _STEP_CATEGORY.get(step, "Other")
 
 
 def _esc(s) -> str:
@@ -293,7 +320,7 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                 rec["ran"] += 1
         docs_incomplete += incomplete
     for c in cases:
-        for st in c["steps"].values():
+        for step_name, st in c["steps"].items():
             # A step that did not run has nothing to say about the data. Its checks are
             # neutral, exactly like an unevaluable one - never hard failures. Without
             # this, a SKIPPED step (e.g. an unreachable graph, or a document absent from
@@ -310,7 +337,7 @@ 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", ""))
+                k = _categorise(ch.get("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"
@@ -329,7 +356,7 @@ def _aggregate(cases: list[dict], hide_skipped: bool = True) -> dict:
                 else:
                     checks_hard += 1
                 label = ch.get("label", "")
-                rec = offenders.setdefault(label, {"label": label, "docs": 0, "severity": sev})
+                rec = offenders.setdefault(label, {"label": label, "docs": 0, "severity": sev, "step": step_name})
                 rec["docs"] += 1
                 # a label is HARD overall if it ever gates
                 if sev == "hard":
@@ -444,6 +471,53 @@ _SKIP_REASON_TEXT = {
 }
 
 
+def _narrative(agg: dict) -> str:
+    """A 2-3 sentence deterministic reading of the run - the story the bullets support.
+
+    Purely template-selected from the aggregate (no LLM, no inference beyond arithmetic):
+    integrity verdict, then the dominant hygiene issue if any, then a coverage caveat if
+    the run did not look at everything. Turns "Chunk Structure 47%" (data) into "chunking
+    is the dominant issue, typically configuration not corruption" (reading).
+    """
+    total = max(agg.get("total", 0), 1)
+    gated = agg.get("failed", 0) + agg.get("errors", 0)
+    sents: list[str] = []
+
+    # 1. Integrity verdict.
+    if gated == 0:
+        sents.append(f"All {agg['total']} document(s) passed every integrity gate")
+    else:
+        sents.append(f"{gated} of {agg['total']} document(s) failed an integrity gate")
+
+    # 2. Dominant hygiene issue (advisory quality beyond the gate).
+    hy = agg.get("hygiene")
+    worst = hy.get("worst") if hy else None
+    if hy and worst and worst["rate"] < 100:
+        tier = hy["tier"].lower()
+        if gated == 0:
+            sents[-1] += f", but data-plane hygiene is {tier} at {hy['score']:g}%"
+        else:
+            sents[-1] += f"; data-plane hygiene is {tier} at {hy['score']:g}%"
+        if worst["rate"] < 50:
+            sents.append(f"The {worst['name']} checks are the dominant issue "
+                         f"({worst['rate']:g}% pass) - a pattern that usually points to "
+                         f"ingestion configuration rather than data corruption")
+        else:
+            sents.append(f"The weakest area is {worst['name']} ({worst['rate']:g}% pass)")
+    elif hy:
+        sents[-1] += f", and data-plane hygiene is {hy['tier'].lower()} at {hy['score']:g}%"
+
+    # 3. Coverage caveat - never let the reading imply full coverage it did not have.
+    cov = agg.get("coverage") or []
+    if cov:
+        worst_cov = cov[0]
+        pct = round(100 * worst_cov["skipped"] / total)
+        sents.append(f"Note: {worst_cov['name']} did not run on {pct}% of documents, so this "
+                     "reading covers less than the whole pipeline")
+
+    return ". ".join(s.rstrip(".") for s in sents) + "."
+
+
 def _exec_bullets(agg: dict) -> str:
     """The executive summary: verdict, what was NOT validated, and the top offender.
 
@@ -508,11 +582,18 @@ def _hygiene_gauge(h: dict | None) -> str:
     worst_html = (f'<div class="hygiene-worst" data-tip="Lowest-scoring dimension - fix this in '
                   f'ingestion first">worst: {_esc(worst["name"])} {worst["rate"]:g}%</div>'
                   if worst and worst["rate"] < 100 else "")
+    # Direction vs the previous run, so the trend is legible without opening the panel.
+    delta = h.get("delta")
+    delta_html = ""
+    if isinstance(delta, (int, float)) and delta != 0:
+        arrow, cls = ("&uarr;", "ok") if delta > 0 else ("&darr;", "bad")
+        delta_html = (f'<span class="hygiene-delta {cls}" data-tip="vs previous run">'
+                      f'{arrow} {abs(delta):g}</span>')
     return (
         f'<div class="hygiene-gauge" data-tip="Share of advisory (WARN) data-quality checks that '
         f'passed - data-plane hygiene, not answer quality. Separate from the READY gate.">'
         f'<div class="hygiene-cap">KB Hygiene</div>'
-        f'<div class="hygiene-score {h["band"]}">{h["score"]:g}% &middot; {h["tier"]}</div>'
+        f'<div class="hygiene-score {h["band"]}">{h["score"]:g}% &middot; {h["tier"]}{delta_html}</div>'
         f'{worst_html}</div>'
     )
 
@@ -559,6 +640,7 @@ def _exec_summary(agg: dict, corpus: dict | None = None, cases: list[dict] | Non
            "not-applicable checks could not be evaluated." if (adv or neu) else ".")
     )
     bullets = _exec_bullets(agg)
+    narrative = _narrative(agg)
     # Lead with the verdict, not the pass rate: the segment bar below already carries the
     # pass/partial/fail split, so a donut of the same number spends the most prominent
     # slot restating it. The corpus verdict is the real headline when discovery supplies
@@ -602,6 +684,7 @@ def _exec_summary(agg: dict, corpus: dict | None = None, cases: list[dict] | Non
         </div>
         <div class="exec-right" style="flex:1">
           <div class="exec-interp-title">Executive Summary</div>
+          <div class="exec-narrative">{_esc(narrative)}</div>
           <ul class="exec-bullets" data-tip="{_esc(interp)}">{bullets}</ul>
           <div class="seg-bar">{seg}</div>
           <div class="seg-legend">
@@ -755,7 +838,7 @@ def _top_issues_table(agg: dict) -> str:
         pct = round(100 * o["docs"] / total)
         sev = o.get("severity", "hard")
         sev_cls, sev_txt = ("bad", "Gating") if sev == "hard" else ("warn", "Advisory")
-        cat = _categorise(o["label"])
+        cat = _categorise(o["label"], o.get("step", ""))
         bar_cls = "bad" if sev == "hard" else "warn"
         rows += (
             f'<tr><td><b>{_esc(o["label"])}</b></td><td class="check-detail">{_esc(cat)}</td>'
@@ -770,13 +853,52 @@ def _top_issues_table(agg: dict) -> str:
     return (
         '<div class="table-card" style="margin-top:18px"><div class="table-cap">Most Frequent Issues '
         '<span class="cat-badge">ranked by documents affected</span></div>'
-        '<div class="table-wrap"><table>'
+        + _subsystem_rollup(agg)
+        + '<div class="subsys-head" style="padding:18px 16px 0">By check</div>'
+        + '<div class="table-wrap"><table>'
         '<thead><tr><th>Check</th><th>Category</th><th class="num">Documents</th>'
         '<th class="num">Share</th><th>Spread</th><th>Severity</th></tr></thead>'
         f'<tbody>{rows}</tbody></table></div></div>'
     )
 
 
+def _subsystem_rollup(agg: dict) -> str:
+    """Group offending checks by subsystem so one root cause reads as one problem.
+
+    Five failing chunk checks are not five problems - they are one chunking issue seen
+    five ways. This rolls the offenders up by category: how many distinct checks, and the
+    widest document spread within it, so the story ("chunking is the problem") is visible
+    above the per-check detail.
+    """
+    offenders = agg.get("offenders", [])
+    if not offenders:
+        return ""
+    total = max(agg.get("total", 0), 1)
+    groups: dict[str, dict] = {}
+    for o in offenders:
+        cat = _categorise(o["label"], o.get("step", ""))
+        g = groups.setdefault(cat, {"checks": 0, "max_docs": 0, "severity": "warn"})
+        g["checks"] += 1
+        g["max_docs"] = max(g["max_docs"], o["docs"])
+        if o.get("severity") == "hard":
+            g["severity"] = "hard"
+    ranked = sorted(groups.items(), key=lambda kv: (-kv[1]["max_docs"], kv[0]))
+    bars = ""
+    for cat, g in ranked:
+        pct = round(100 * g["max_docs"] / total)
+        cls = "bad" if g["severity"] == "hard" else "warn"
+        bars += (
+            f'<div class="subsys-row"><div class="subsys-name">{_esc(cat)}</div>'
+            f'<div class="subsys-bar"><i style="width:{pct}%;background:var(--{cls})"></i></div>'
+            f'<div class="subsys-meta">{g["checks"]} check(s) &middot; up to {g["max_docs"]}/{total} docs</div></div>'
+        )
+    return (
+        '<div class="subsys-rollup">'
+        '<div class="subsys-head">By subsystem <span class="cat-badge">one root cause, grouped</span></div>'
+        f'{bars}</div>'
+    )
+
+
 def _findings_section(cases: list[dict], agg: dict | None = None) -> str:
     failed_items, skipped_items = [], []
     advisory: Counter = Counter()  # warn-severity check label -> count, across the corpus
@@ -1166,7 +1288,9 @@ def _trends_section(trends: list[dict]) -> str:
     charts_block = ""
     if runs >= 2:
         series = sorted(trends, key=lambda t: str(t.get("timestamp", "")))
-        labels = [str(t.get("run_id") or str(t.get("timestamp", ""))[:16] or f"run {i+1}")
+        # Prefer the run DATE on the x-axis (a timeline reads temporally); fall back to the
+        # run id only when no timestamp was recorded. The run-id table below keeps the ids.
+        labels = [str(str(t.get("timestamp", ""))[:16].replace("T", " ") or t.get("run_id") or f"run {i+1}")
                   for i, t in enumerate(series)]
         def _rate(num, den):
             return [round(100 * t.get(num, 0) / t[den], 1) if t.get(den) else 0 for t in series]
@@ -1359,7 +1483,8 @@ function _insights(d){
   }
   return out;
 }
-function _categorise(label){
+var _STEP_CATEGORY={"Neptune Metadata":"Knowledge Graph","GraphDB Metadata":"Knowledge Graph","S3 Storage":"Object Storage","Cross-Stage Consistency":"Cross-Stage Consistency","API Upload":"Ingestion API"};
+function _categorise(label, step){
   var l=(label||'').toLowerCase();
   if(/e_tag|required field|metadata consist|positional|section|page metadata|directory|predicate|date format|email|field rule/.test(l)) return 'Metadata & Consistency';
   if(/boundaries|chunk count|size within|ordering|overlap/.test(l)) return 'Chunk Structure';
@@ -1367,9 +1492,9 @@ function _categorise(label){
   if(/fidelity|coverage|contaminat|duplicate|header|footer|table\/figure/.test(l)) return 'Content Preservation';
   if(/index|schema/.test(l)) return 'Index & Schema';
   if(/retriev|semantic|filter|hybrid|wildcard|empty query|recall|mrr|paraphrase|boundary-span|exact-term/.test(l)) return 'Retrieval & Query';
-  return 'Other';
+  return _STEP_CATEGORY[step]||'Other';
 }
-function _buildCategorisedChecks(checks){
+function _buildCategorisedChecks(checks, step){
   function _sup(c){ return c.supported !== false; }   // unsupported = neutral
   var evaluable=checks.filter(_sup);
   var total=evaluable.length, passed=evaluable.filter(function(c){return c.passed;}).length;
@@ -1379,7 +1504,7 @@ function _buildCategorisedChecks(checks){
   var hard=evaluable.filter(function(c){return !c.passed && (c.severity||'hard')!=='warn';}).length;
   var advisory=evaluable.filter(function(c){return !c.passed && c.severity==='warn';}).length;
   var groups={};
-  checks.forEach(function(c){ var cat=_categorise(c.label); (groups[cat]=groups[cat]||[]).push(c); });
+  checks.forEach(function(c){ var cat=_categorise(c.label, step); (groups[cat]=groups[cat]||[]).push(c); });
   var cats=_CAT_ORDER.filter(function(co){return groups[co[0]];});
   var note=(advisory?(' &middot; '+advisory+' advisory'):'')+(unsupported?(' &middot; '+unsupported+' not applicable'):'');
   var html='<div class="check-detail" style="margin-bottom:6px"><b style="color:var(--ink)">'+passed+'/'+total+'</b> checks passed across '+cats.length+' categor'+(cats.length===1?'y':'ies')+note+(hard?'':'. Only hard failures gate; advisory is informational.')+'</div>';
@@ -1412,14 +1537,17 @@ function showStepDetail(ci, name){
   var band=_bandOf(d.status);
   document.getElementById('fbModalTitle').textContent=name+'  —  '+c.name;
   var st=document.getElementById('fbModalStatus'); st.textContent=d.status; st.className='status-pill '+band;
-  document.getElementById('fbModalDur').textContent=(d.duration!=null?d.duration+'s':'');
+  // A step that reuses earlier steps' artifacts (e.g. Cross-Stage Consistency) does almost
+  // no I/O and rounds to 0.0s, which reads as "not measured". Show <0.1s so near-instant is
+  // legible as fast, not broken.
+  document.getElementById('fbModalDur').textContent=(d.duration!=null?(d.duration<0.05?'<0.1s':d.duration+'s'):'');
   document.getElementById('fbModalMsg').textContent=d.message||'—';
   var keys=d.metrics?Object.keys(d.metrics):[];
   var mRow=document.getElementById('fbModalMetricsRow');
   if(keys.length){ document.getElementById('fbModalMetrics').innerHTML=keys.map(function(k){return '<span class="metric-chip">'+_escHtml(k)+': <b>'+_escHtml(d.metrics[k])+'</b></span>';}).join(''); mRow.style.display=''; }
   else { mRow.style.display='none'; }
   var box=document.getElementById('fbModalChecks');
-  var inner=(!d.checks||!d.checks.length)?'<div class="check-detail">No individual checks for this step.</div>':_buildCategorisedChecks(d.checks);
+  var inner=(!d.checks||!d.checks.length)?'<div class="check-detail">No individual checks for this step.</div>':_buildCategorisedChecks(d.checks, name);
   // Chunks belong to the vector step — show them here (collapsed) rather than at document level.
   if(name===c.chunksStep && c.chunks && c.chunks.items && c.chunks.items.length){
     inner+=_buildChunksDisclosure(c.chunks);
@@ -1547,7 +1675,7 @@ function renderDoc(idx){
   }
   // Per-document Checks by Category — actionable at the document level.
   var cc={}; _CAT_ORDER.forEach(function(co){cc[co[0]]={t:0,p:0};});
-  d.order.forEach(function(name){ var s=d.steps[name]; if(!s) return; (s.checks||[]).forEach(function(ch){ if(ch.supported===false) return; var k=_categorise(ch.label); cc[k].t++; if(ch.passed) cc[k].p++; }); });
+  d.order.forEach(function(name){ var s=d.steps[name]; if(!s) return; (s.checks||[]).forEach(function(ch){ if(ch.supported===false) return; var k=_categorise(ch.label, name); cc[k].t++; if(ch.passed) cc[k].p++; }); });
   var catRows=_CAT_ORDER.filter(function(co){return cc[co[0]].t;}).map(function(co){
     var x=cc[co[0]], rate=x.t?Math.round(100*x.p/x.t):0, rb=rate===100?'ok':(rate>=50?'warn':'bad');
     var color=rb==='ok'?'#16a34a':rb==='warn'?'#d97706':'#dc2626';
@@ -1575,14 +1703,14 @@ function renderDoc(idx){
       datasets:[{label:'Passed',data:s.map(function(x){return x.passed;}),backgroundColor:OK,stack:'a'},
         {label:'Failed',data:s.map(function(x){return x.failed+x.error;}),backgroundColor:BAD,stack:'a'},
         {label:'Skipped',data:s.map(function(x){return x.skipped;}),backgroundColor:NA,stack:'a'}]},
-    options:{plugins:{legend:{labels:{color:c.text,font:{size:11}}}},
+    options:{responsive:true,maintainAspectRatio:false,plugins:{legend:{labels:{color:c.text,font:{size:11}}}},
       scales:{x:{stacked:true,ticks:{color:c.text,font:{size:10}},grid:{color:c.grid}},y:{stacked:true,ticks:{color:c.text,precision:0},grid:{color:c.grid}}}}});
   var cr=REPORT.agg.cat_rows||[];
   var catRate=cr.map(function(x){return x.total?Math.round(100*x.passed/x.total):0;});
   var cat=new Chart(document.getElementById('catChart'),{type:'bar',
     data:{labels:cr.map(function(x){return x.name.replace(' & ','/').replace(' Quality','').replace(' Preservation','').replace(' Consistency','').replace(' Structure','').replace(' Query','');}),
       datasets:[{label:'Pass rate %',data:catRate,backgroundColor:catRate.map(function(r){return r===100?OK:(r>=50?WARN:BAD);}),borderWidth:0,borderRadius:4}]},
-    options:{indexAxis:'y',plugins:{legend:{display:false}},
+    options:{indexAxis:'y',responsive:true,maintainAspectRatio:false,plugins:{legend:{display:false}},
       scales:{x:{max:100,ticks:{color:c.text,callback:function(v){return v+'%';}},grid:{color:c.grid}},y:{ticks:{color:c.text,font:{size:10}},grid:{display:false}}}}});
   if(typeof allCharts!=='undefined'){allCharts.push(donut,step,cat);}
 })();
@@ -1646,6 +1774,13 @@ def generate_batch_dashboard(
         agg["wall_seconds"] = round(wall_seconds, 1)
     if concurrency is not None:
         agg["concurrency"] = concurrency
+    # Hygiene delta vs the previous run: trends are newest-first and already include THIS
+    # run (recorded before the report), so the prior run is trends[1]. Lets the gauge show
+    # direction ("62% POOR +3 vs previous") without opening the trends panel.
+    if agg.get("hygiene") and trends and len(trends) > 1:
+        prev = trends[1].get("hygiene_score")
+        if isinstance(prev, (int, float)):
+            agg["hygiene"]["delta"] = round(agg["hygiene"]["score"] - prev, 1)
     # Shape + coverage are computed on FULL check data, before the scale-trim below
     # drops per-check detail for passed documents.
     shape_inner = _profile_section(profile) + _coverage_section(cases)

{compass_kb_validation-2.4.0 → compass_kb_validation-2.5.0}/ingestion_validation/report/_report_css.py

@@ -215,20 +215,22 @@ main { max-width:1800px; margin:0 auto; padding:24px 32px; }
 
 /* Charts */
 .charts-row {
-  display:grid; grid-template-columns:1.4fr 1fr 1fr; gap:16px; margin-top:24px;
+  display:grid; grid-template-columns:repeat(3, 1fr); gap:16px; margin-top:24px;
 }
 @media(max-width:1100px) { .charts-row { grid-template-columns:repeat(2,1fr); } }
 @media(max-width:700px)  { .charts-row { grid-template-columns:1fr; } }
 .chart-box {
   background:var(--panel); border:1px solid var(--line); border-radius:var(--radius);
   padding:16px; box-shadow:var(--box-shadow); position:relative;
+  /* flex column so the canvas fills the box height (grid stretches all boxes equal),
+     removing the empty real-estate the aspect-ratio bar charts used to leave. */
+  display:flex; flex-direction:column;
 }
 .chart-box h3 {
   font-size:13px; font-weight:600; color:var(--muted);
   text-transform:uppercase; letter-spacing:.06em; margin:0 0 12px 0;
 }
-.chart-box canvas { width:100%!important; max-height:260px; }
-#donutChart { max-height:320px!important; }
+.chart-box canvas { width:100%!important; flex:1 1 auto; min-height:230px; max-height:320px; }
 
 /* Tables */
 .table-card { background:var(--panel); border:1px solid var(--line); border-radius:var(--radius); box-shadow:var(--box-shadow); overflow:hidden; }

{compass_kb_validation-2.4.0 → compass_kb_validation-2.5.0}/ingestion_validation/trend_tracker.py

@@ -56,7 +56,8 @@ class TrendTracker:
 
     # Columns added after the original schema; absent in older DBs.
     _ADDED_COLUMNS = {"project": "TEXT", "steps_total": "INTEGER",
-                      "steps_passed": "INTEGER", "steps_failed": "INTEGER"}
+                      "steps_passed": "INTEGER", "steps_failed": "INTEGER",
+                      "hygiene_score": "REAL"}
 
     def _ensure_schema(self) -> None:
         with self._connect() as conn:
@@ -98,12 +99,23 @@ class TrendTracker:
                 )
             )
 
+        # KB Hygiene score for this run, so trends can show its direction over time. Computed
+        # from the same deterministic aggregation the report uses; None when there are no
+        # advisory checks to score.
+        hygiene_score = None
+        try:
+            from ingestion_validation.report import hygiene_from_results
+            hy = hygiene_from_results(results)
+            hygiene_score = hy["score"] if hy else None
+        except Exception:  # noqa: BLE001 - hygiene is advisory context; never break recording
+            hygiene_score = None
+
         with self._connect() as conn:
             conn.execute(
-                "INSERT INTO runs (run_id,project,timestamp,environment,total_cases,passed,failed,errors,skipped,total_duration_seconds,mode,steps_total,steps_passed,steps_failed)"
-                " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                "INSERT INTO runs (run_id,project,timestamp,environment,total_cases,passed,failed,errors,skipped,total_duration_seconds,mode,steps_total,steps_passed,steps_failed,hygiene_score)"
+                " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
                 (run_id, project, ts, environment, len(results), agg["passed"], agg["failed"], agg["errors"], agg["skipped"], round(agg["duration"], 3), mode,
-                 agg["steps_total"], agg["steps_passed"], agg["steps_failed"]),
+                 agg["steps_total"], agg["steps_passed"], agg["steps_failed"], hygiene_score),
             )
             conn.executemany(
                 "INSERT INTO run_cases (run_id,case_name,file_name,document_id,overall,duration_seconds,step_details)"

{compass_kb_validation-2.4.0 → compass_kb_validation-2.5.0}/tests/test_reporting.py

@@ -479,7 +479,8 @@ def test_trends_render_tabbed_time_series_with_multiple_runs():
     m = re.search(r"window\.TREND_SERIES=(\{.*?\});", html, re.S)
     assert m is not None
     s = json.loads(m.group(1))
-    assert s["labels"] == ["r1", "r2", "r3"]                       # oldest -> newest
+    # x-axis labels are the run DATE (a timeline reads temporally), oldest -> newest
+    assert s["labels"] == ["2026-07-12 09:00", "2026-07-14 09:00", "2026-07-17 09:00"]
     # Pass Rate carries two lines - documents and steps; the gap is the failures.
     doc_line = next(sr for sr in s["metrics"]["passRate"]["series"] if sr["name"] == "Documents")
     assert doc_line["data"] == [84.0, 59.8, 100.0]
@@ -560,3 +561,105 @@ def test_embedded_triples_keep_only_rendered_fields():
     triples = report_mod._result_payload("d.pdf", r)["steps"]["Neptune Metadata"]["triples"]
     assert triples == [{"predicate": "documentId", "value": "DOC-1"}]
     assert "subject" not in triples[0] and "predicate_uri" not in triples[0]
+
+
+def test_stage_checks_get_named_categories_not_other():
+    # Graph/storage/cross-stage checks with no semantic-pattern match were all dumped into
+    # "Other" (54% of checks on a multi-stage run). They now fall back to their stage's
+    # category so the breakdown is transparent.
+    r = PipelineResult(document_id="d", file_name="d.pdf")
+    r.add_step(StepResult("S3 Storage", StepStatus.PASSED, "ok",
+                          checks=[{"label": "File exists in storage", "passed": True}]))
+    r.add_step(StepResult("Neptune Metadata", StepStatus.PASSED, "ok",
+                          checks=[{"label": "Document found in graph", "passed": True},
+                                  {"label": "Orphan nodes absent", "passed": True}]))
+    r.add_step(StepResult("Cross-Stage Consistency", StepStatus.PASSED, "ok",
+                          checks=[{"label": "Stores agree on document", "passed": True}]))
+    agg = report_mod._aggregate([report_mod._result_payload("d.pdf", r)])
+    cats = {row["name"]: row["total"] for row in agg["cat_rows"]}
+    assert cats.get("Knowledge Graph") == 2          # graph checks, not "Other"
+    assert cats.get("Object Storage") == 1
+    assert cats.get("Cross-Stage Consistency") == 1
+    assert "Other" not in cats                        # nothing uncategorised here
+
+
+def test_categorise_semantic_pattern_still_wins_over_step():
+    # a chunk-structure check on the vector step keeps its semantic category
+    assert report_mod._categorise("Overlap correctness", "Redis Chunks") == "Chunk Structure"
+    # a graph check with no semantic match takes the stage category
+    assert report_mod._categorise("Document found in graph", "Neptune Metadata") == "Knowledge Graph"
+
+
+def test_narrative_reads_the_run_deterministically():
+    def case(i, overlap_ok):
+        r = PipelineResult(document_id=f"d{i}", file_name=f"d{i}.pdf")
+        r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok", checks=[
+            {"label": "Chunks exist", "passed": True},
+            {"label": "Overlap correctness", "passed": overlap_ok, "severity": "warn"}]))
+        r.finalize()
+        return report_mod._result_payload(f"d{i}.pdf", r)
+    # chunking poor -> names it as the dominant issue with the config-not-corruption reading
+    agg = report_mod._aggregate([case(i, overlap_ok=(i >= 8)) for i in range(10)])
+    text = report_mod._narrative(agg)
+    assert "passed every integrity gate" in text
+    assert "Chunk Structure" in text and "dominant issue" in text
+    assert "configuration rather than data corruption" in text
+
+
+def test_narrative_flags_incomplete_coverage():
+    def case(i):
+        r = PipelineResult(document_id=f"d{i}", file_name=f"d{i}.pdf")
+        r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok",
+                              checks=[{"label": "Chunks exist", "passed": True}]))
+        r.add_step(StepResult("Neptune Metadata", StepStatus.SKIPPED, "unreachable",
+                              details={"skip_reason": "unreachable", "unreachable": True},
+                              checks=[{"label": "reachable", "passed": False}]))
+        r.finalize()
+        return report_mod._result_payload(f"d{i}.pdf", r)
+    text = report_mod._narrative(report_mod._aggregate([case(i) for i in range(4)]))
+    assert "did not run on" in text and "less than the whole pipeline" in text
+
+
+def test_subsystem_rollup_groups_offenders_by_category():
+    def case(i):
+        r = PipelineResult(document_id=f"d{i}", file_name=f"d{i}.pdf")
+        r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok", checks=[
+            {"label": "Overlap correctness", "passed": i >= 8, "severity": "warn"},
+            {"label": "Chunk boundaries clean", "passed": i >= 7, "severity": "warn"},
+            {"label": "No near-duplicate embeddings", "passed": i >= 4, "severity": "warn"}]))
+        r.finalize()
+        return report_mod._result_payload(f"d{i}.pdf", r)
+    agg = report_mod._aggregate([case(i) for i in range(10)])
+    html = report_mod._subsystem_rollup(agg)
+    # two chunk checks roll up into one Chunk Structure row (one root cause, not two)
+    assert "Chunk Structure" in html and "2 check(s)" in html
+    assert "Embedding Quality" in html and "1 check(s)" in html
+    # Chunk Structure (worst spread 8/10) ranks above Embedding Quality
+    assert html.index("Chunk Structure") < html.index("Embedding Quality")
+
+
+def test_hygiene_gauge_shows_delta_direction():
+    up = report_mod._hygiene_gauge({"score": 62, "tier": "POOR", "band": "bad", "worst": None, "delta": 3.0})
+    assert "&uarr;" in up and "3" in up and "hygiene-delta ok" in up
+    down = report_mod._hygiene_gauge({"score": 58, "tier": "POOR", "band": "bad", "worst": None, "delta": -4.0})
+    assert "&darr;" in down and "hygiene-delta bad" in down
+    flat = report_mod._hygiene_gauge({"score": 62, "tier": "POOR", "band": "bad", "worst": None, "delta": 0})
+    assert "hygiene-delta" not in flat            # no change -> no arrow
+
+
+def test_trend_tracker_persists_hygiene_score(tmp_path):
+    from ingestion_validation.trend_tracker import TrendTracker
+
+    def results(overlap_ok):
+        r = PipelineResult(document_id="d", file_name="d.pdf")
+        r.add_step(StepResult("Redis Chunks", StepStatus.PASSED, "ok", checks=[
+            {"label": "Chunks exist", "passed": True},
+            {"label": "Overlap correctness", "passed": overlap_ok, "severity": "warn"}]))
+        r.finalize()
+        return [{"name": "d.pdf", "result": r}]
+
+    tt = TrendTracker(str(tmp_path / "t.db"))
+    tt.record(results(False), run_id="r1", project="p")   # hygiene 0%
+    tt.record(results(True), run_id="r2", project="p")     # hygiene 100%
+    scores = [r.get("hygiene_score") for r in tt.summary(project="p")]
+    assert scores == [100.0, 0.0]                          # newest-first, both persisted