ltcai 11.1.0 → 11.2.0

package/latticeai/services/automation_intelligence.py

@@ -55,6 +55,13 @@ _SIGNATURE_SIMILARITY = 0.6
 _MIN_SUGGESTION_CONFIDENCE = 0.35
 _LOW_CONFIDENCE_THRESHOLD = 0.5
 _KG_GROUNDING_LIMIT = 5
+#: Charged when the graph *was* consulted and found nothing related. v11.2.0
+#: fixes a dead policy: the floor above was unreachable for recurring questions
+#: (the cheapest possible question — asked twice, one phrasing, no recipe —
+#: scored 0.475), so the suppression branch could only ever be exercised by a
+#: test that moved the constant. Absence of grounding is real evidence, and
+#: charging for it is what makes the floor mean something again.
+_UNGROUNDED_PENALTY = 0.15
 
 
 def _question_confidence(
@@ -67,7 +74,13 @@ def _question_confidence(
 
     Evidence factors: how often the question repeats, how many distinct
     phrasings exist, whether it maps onto a known starter-recipe intent, and
-    (when the graph is available) how many Brain nodes relate to it.
+    what the Brain knows about it.
+
+    That last factor is three-valued on purpose. ``None`` means the graph could
+    not be consulted — unknown, so nothing is added or taken away. A positive
+    count is supporting evidence. **Zero** is not the same as unknown: the
+    graph was asked, and it knows nothing about this question, which is a
+    reason to be less sure rather than a reason to be neutral.
     """
     score = 0.3 + 0.5 * min(1.0, (int(count) - 1) / 4)
     score += min(0.15, 0.05 * len(examples or []))
@@ -75,13 +88,16 @@ def _question_confidence(
         score += 0.15
     if kg_related:
         score += min(0.2, 0.05 * int(kg_related))
+    elif kg_related == 0:
+        score -= _UNGROUNDED_PENALTY
     factors = {
         "repeat_count": int(count),
         "distinct_examples": len(examples or []),
         "intent_match": bool(recipe_id),
         "kg_related_nodes": kg_related,
+        "kg_grounded": None if kg_related is None else bool(kg_related),
     }
-    return round(min(1.0, score), 2), factors
+    return round(max(0.0, min(1.0, score)), 2), factors
 
 
 def _source_confidence(indexed: int, watch_enabled: bool) -> tuple:
@@ -357,6 +373,10 @@ class AutomationIntelligenceService:
                 pattern["count"], pattern["examples"], recipe_id, kg_related
             )
             if confidence < _MIN_SUGGESTION_CONFIDENCE:
+                # Asked a couple of times, phrased one way, matching no recipe,
+                # and the Brain knows nothing about it — not enough to propose
+                # automating. Counted, so the surface can say how many were held
+                # back rather than silently showing fewer.
                 suppressed_low_confidence += 1
                 continue
             if recipe_id:

package/latticeai/services/brain_intelligence.py

@@ -52,6 +52,21 @@ def _parse_ts(value: Any) -> Optional[datetime]:
     return parsed
 
 
+def _no_graph_reason(graph_available: bool) -> str:
+    """Why a graph-derived health dimension has nothing to say.
+
+    Two different situations that both end in ``status: "unavailable"``: the
+    graph could not be read at all, and the graph read fine but holds nothing
+    yet. Telling them apart is the difference between "something is broken"
+    and "you have not saved anything yet".
+    """
+    return (
+        "no knowledge saved yet"
+        if graph_available
+        else "the knowledge graph could not be read"
+    )
+
+
 class BrainIntelligenceService:
     def __init__(
         self,
@@ -395,7 +410,11 @@ class BrainIntelligenceService:
                 "stale_threshold_days": _STALE_DAYS,
             }
         else:
-            dimensions["freshness"] = {"status": "unavailable", "score": None}
+            dimensions["freshness"] = {
+                "status": "unavailable",
+                "score": None,
+                "reason": _no_graph_reason(sample["available"]),
+            }
 
         # Connectivity — orphan nodes are knowledge the Brain cannot reason
         # across; a well-tended graph keeps them rare.
@@ -414,7 +433,11 @@ class BrainIntelligenceService:
                 "edges": len(edges),
             }
         else:
-            dimensions["connectivity"] = {"status": "unavailable", "score": None}
+            dimensions["connectivity"] = {
+                "status": "unavailable",
+                "score": None,
+                "reason": _no_graph_reason(sample["available"]),
+            }
 
         # Embedding coverage — semantic recall only works for indexed items.
         index_status: Dict[str, Any] = {}
@@ -425,7 +448,23 @@ class BrainIntelligenceService:
                 LOGGER.exception("brain intelligence index status failed")
                 index_status = {"error": str(exc)}
         scale = index_status.get("scale") or {}
-        if "coverage_ratio" in scale:
+        indexable = scale.get("source_items", index_status.get("source_items"))
+        if "coverage_ratio" not in scale:
+            dimensions["embedding_coverage"] = {
+                "status": "unavailable",
+                "score": None,
+                "reason": "this knowledge store does not report vector index coverage",
+            }
+        elif indexable == 0:
+            # An empty index covers 100% of nothing. Scoring that as a perfect
+            # 100 is how a brand-new Brain used to grade itself "excellent"
+            # off its only measurable dimension (audit v11.2.0, Finding 3).
+            dimensions["embedding_coverage"] = {
+                "status": "unavailable",
+                "score": None,
+                "reason": "no indexable items yet",
+            }
+        else:
             dimensions["embedding_coverage"] = {
                 "status": "ok",
                 "score": round(float(scale["coverage_ratio"]) * 100),
@@ -433,8 +472,6 @@ class BrainIntelligenceService:
                 "pending_items": scale.get("pending_items"),
                 "needs_reindex": index_status.get("status") == "needs_reindex",
             }
-        else:
-            dimensions["embedding_coverage"] = {"status": "unavailable", "score": None}
 
         # Edge quality + contradiction pressure — reuses the quality layer.
         if sample["available"] and edges:
@@ -450,7 +487,15 @@ class BrainIntelligenceService:
                 "contradiction_edges": len(contradiction_edges),
             }
         else:
-            dimensions["consistency"] = {"status": "unavailable", "score": None}
+            dimensions["consistency"] = {
+                "status": "unavailable",
+                "score": None,
+                "reason": (
+                    _no_graph_reason(sample["available"])
+                    if not (sample["available"] and nodes)
+                    else "no relationships recorded yet"
+                ),
+            }
 
         scores = [d["score"] for d in dimensions.values() if d.get("score") is not None]
         overall = round(sum(scores) / len(scores)) if scores else None
@@ -461,6 +506,29 @@ class BrainIntelligenceService:
             else "attention" if overall >= 50
             else "critical"
         )
+        # What the verdict rests on. A composite averages only what could be
+        # measured, so the count of measured dimensions is part of the answer
+        # rather than a footnote — and when nothing could be measured the
+        # report says so instead of leaving a bare null (the 9.9.7 rule: a
+        # "—" always states why).
+        unmeasured = sorted(
+            name for name, dim in dimensions.items() if dim.get("score") is None
+        )
+        coverage: Dict[str, Any] = {
+            "measured": len(scores),
+            "total": len(dimensions),
+            "unavailable": unmeasured,
+            "partial": bool(unmeasured),
+        }
+        reason: Optional[str] = None
+        if overall is None:
+            reason = (
+                "no health dimension could be measured yet — "
+                + "; ".join(
+                    f"{name}: {dimensions[name].get('reason') or 'unavailable'}"
+                    for name in unmeasured
+                )
+            )
 
         actions: List[Dict[str, str]] = []
         emb = dimensions["embedding_coverage"]
@@ -490,14 +558,18 @@ class BrainIntelligenceService:
                 "reason": f"{cons_dim['contradiction_edges']} contradiction edges recorded in the graph.",
             })
 
-        return {
+        report: Dict[str, Any] = {
             "overall_score": overall,
             "grade": grade,
             "dimensions": dimensions,
+            "coverage": coverage,
             "recommended_actions": actions,
             "graph_available": sample["available"],
             "generated_at": _now(),
         }
+        if reason is not None:
+            report["reason"] = reason
+        return report
 
     # ── vector freshness (v9.8.0) ────────────────────────────────────────
 
@@ -511,7 +583,51 @@ class BrainIntelligenceService:
         raises. The vector index is store-global (not workspace-partitioned);
         scope arguments are accepted for router symmetry but do not narrow
         the report.
+
+        Since v11.2.0 a store that can split its backlog also gets a
+        ``breakdown`` key (see :meth:`_freshness_breakdown`). It is additive:
+        the four keys above keep their meaning and their types, so the
+        freshness chip that reads ``pending_items`` is untouched, and a store
+        without the split simply has no ``breakdown``.
         """
+        payload = self._vector_freshness_contract()
+        breakdown = self._freshness_breakdown()
+        if breakdown is not None:
+            payload["breakdown"] = breakdown
+        return payload
+
+    def _freshness_breakdown(self) -> Optional[Dict[str, Any]]:
+        """``vector_freshness_breakdown()`` from the store, or ``None``.
+
+        "12 pending" hides two different situations — twelve items never
+        embedded (a new import) and twelve whose text changed under an
+        existing embedding (edits, where current answers are quietly wrong).
+        The store has always known the difference; until now nothing asked it.
+
+        ``None`` covers every reason the split is not available (graph off,
+        an older store, an unreadable index), because a caller can only act on
+        numbers that were really measured — never on zeros standing in for
+        them.
+        """
+        if not self._enable_graph or self._kg is None:
+            return None
+        breakdown_fn = getattr(self._kg, "vector_freshness_breakdown", None)
+        if not callable(breakdown_fn):
+            return None
+        try:
+            raw = breakdown_fn()
+        except Exception:
+            LOGGER.exception("vector freshness breakdown read failed")
+            return None
+        # An empty or unrecognisable answer is "not measured", which is what
+        # ``None`` already means here — publishing an empty block would claim
+        # a split nobody computed.
+        if not isinstance(raw, dict) or not raw:
+            return None
+        return dict(raw)
+
+    def _vector_freshness_contract(self) -> Dict[str, Any]:
+        """The four-key freshness payload, unchanged since v9.8.0."""
 
         def _unavailable(detail: str) -> Dict[str, Any]:
             return {

package/latticeai/services/command_center.py

@@ -214,11 +214,17 @@ class CommandCenterService:
         except Exception:
             LOGGER.exception("command center health read failed")
             return {"available": False}
-        overall = report.get("overall") or {}
+        # ``BrainIntelligenceService.health_report()`` publishes the score and
+        # the grade at the top level. This used to read them out of a nested
+        # ``overall`` block that no producer has ever written, so the section
+        # was permanently unavailable: Today's Briefing showed a dash with no
+        # reason beside it, and the "check-health" quick action below could
+        # never fire. Read the shape the real collaborator returns.
+        score = report.get("overall_score")
         return {
-            "available": overall.get("score") is not None,
-            "grade": overall.get("grade"),
-            "score": overall.get("score"),
+            "available": score is not None,
+            "grade": report.get("grade"),
+            "score": score,
             "recommended_actions": list(report.get("recommended_actions") or [])[:3],
         }