Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(observer): account for aggregate retrieval yield (#3158)

huangruiteng0b09d4580fc5
diff --git a/openviking/storage/observers/retrieval_observer.py b/openviking/storage/observers/retrieval_observer.py
index 6505a5650..597e19a1e 100644
--- a/openviking/storage/observers/retrieval_observer.py
+++ b/openviking/storage/observers/retrieval_observer.py
@@ -21,8 +21,11 @@ class RetrievalObserver(BaseObserver):
and formats them for display via the observer API.
"""
- # A zero-result rate above this threshold is considered unhealthy.
+ # A zero-result rate at or above this threshold is suspicious.
UNHEALTHY_ZERO_RESULT_RATE = 0.5
+ # Sparse fan-out may include expected empty branches. Treat it as unhealthy
+ # only when the aggregate workload returns fewer than one result per query.
+ MIN_HEALTHY_AVG_RESULTS_PER_QUERY = 1.0
@staticmethod
def _get_collector():
@@ -84,16 +87,24 @@ class RetrievalObserver(BaseObserver):
def __str__(self) -> str:
return self.get_status_table()
+ @classmethod
+ def _has_unhealthy_yield(cls, stats) -> bool:
+ """Return whether empty branches coincide with low aggregate yield."""
+ return (
+ stats.zero_result_rate >= cls.UNHEALTHY_ZERO_RESULT_RATE
+ and stats.avg_results_per_query < cls.MIN_HEALTHY_AVG_RESULTS_PER_QUERY
+ )
+
def is_healthy(self) -> bool:
- """Retrieval is healthy when the zero-result rate is acceptable."""
+ """Retrieval is healthy when empty branches still produce useful yield."""
stats = self._get_collector().snapshot()
if stats.total_queries == 0:
return True
- return stats.zero_result_rate < self.UNHEALTHY_ZERO_RESULT_RATE
+ return not self._has_unhealthy_yield(stats)
def has_errors(self) -> bool:
- """Errors are flagged when too many queries return zero results."""
+ """Errors are flagged when empty branches also have low aggregate yield."""
stats = self._get_collector().snapshot()
if stats.total_queries < 5:
return False
- return stats.zero_result_rate >= self.UNHEALTHY_ZERO_RESULT_RATE
+ return self._has_unhealthy_yield(stats)
diff --git a/tests/unit/retrieve/test_retrieval_stats.py b/tests/unit/retrieve/test_retrieval_stats.py
index ebfb629be..85b4ee800 100644
--- a/tests/unit/retrieve/test_retrieval_stats.py
+++ b/tests/unit/retrieve/test_retrieval_stats.py
@@ -145,6 +145,17 @@ class TestRetrievalObserver:
assert observer.is_healthy() is False
assert observer.has_errors() is True
+ def test_healthy_with_sparse_fan_out_yield(self):
+ collector = self._setup_collector()
+ for _ in range(6):
+ collector.record_query("unknown", 0, [])
+ for _ in range(4):
+ collector.record_query("unknown", 3, [0.9, 0.8, 0.7])
+
+ observer = RetrievalObserver()
+ assert observer.is_healthy() is True
+ assert observer.has_errors() is False
+
def test_no_errors_below_min_queries(self):
collector = self._setup_collector()
# Only 3 queries (below the 5-query minimum for error flagging)