liquid-loop 0.6.2__tar.gz → 0.6.4__tar.gz

{liquid_loop-0.6.2 → liquid_loop-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: liquid-loop
-Version: 0.6.2
+Version: 0.6.4
 Summary: Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation
 Author: fishbook0001
 Maintainer: fishbook0001

liquid_loop-0.6.4/liquid_loop/cognitive_budget.py

@@ -0,0 +1,105 @@
+"""认知预算稳态器（落地 PEEK arXiv:2604.09932 固定预算驱逐）
+
+把 PEEK 三模块蒸馏并适配液环：
+  Distiller     evidence.weight + anchor.value_score + recency → 蒸馏价值
+  Cartographer  价值 × (0.5+0.5*访问热度) × 流动性 → 重要性
+  Evictor       超额时驱逐最低重要性证据，标记 archived（冷归档，零丢失）
+
+设计哲学（呼应液环零向量/零丢失）：
+  驱逐 ≠ 删除。超预算证据标记 archived=True，从活跃检索集移出（recall 跳过），
+  但数据与审计链完整保留，可随时解冻。记忆系统因此维持"稳态预算"而非无限膨胀。
+
+预算来源：环境变量 LIQUID_EVIDENCE_BUDGET（默认 0 = 不限制）。
+"""
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+
+LIQUIDITY_HEAT = {"hot": 1.0, "warm": 0.7, "cold": 0.4, "frozen": 0.1}
+
+
+@dataclass
+class _BudgetItem:
+    id: str
+    weight: float = 1.0
+    anchor_value: float = 1.0
+    access_count: int = 0
+    liquidity: str = "warm"
+    gap_hours: float = 0.0
+    distilled_value: float = 0.0
+    importance: float = 0.0
+
+
+def _distill(it: _BudgetItem) -> float:
+    recency = 1.0 / (1.0 + it.gap_hours / 168.0)
+    v = 0.4 * it.weight + 0.3 * it.anchor_value + 0.3 * recency
+    it.distilled_value = max(0.0, min(1.0, v))
+    return it.distilled_value
+
+
+def _rank(items: list[_BudgetItem]) -> list[_BudgetItem]:
+    for it in items:
+        if it.distilled_value == 0.0:
+            _distill(it)
+        access_heat = min(it.access_count / 10.0, 1.0)
+        liquidity_heat = LIQUIDITY_HEAT.get(it.liquidity, 0.4)
+        it.importance = it.distilled_value * (0.5 + 0.5 * access_heat) * liquidity_heat
+    return sorted(items, key=lambda x: x.importance, reverse=True)
+
+
+def _evict(items: list[_BudgetItem], budget: int) -> list[_BudgetItem]:
+    if len(items) <= budget:
+        return []
+    ranked = _rank(items)
+    return ranked[budget:]  # 尾部最低重要性
+
+
+class CognitiveBudgetStabilizer:
+    """接 WorkspaceState，超预算时冷归档低价值证据"""
+
+    def __init__(self, state, budget: Optional[int] = None):
+        self.state = state
+        self.budget = budget if budget is not None else int(os.environ.get("LIQUID_EVIDENCE_BUDGET", "0"))
+
+    @staticmethod
+    def _gap_hours(anchor) -> float:
+        if not anchor or not anchor.last_accessed:
+            return 9999.0
+        try:
+            last = datetime.fromisoformat(anchor.last_accessed)
+            return (datetime.now(timezone.utc) - last).total_seconds() / 3600
+        except ValueError:
+            return 9999.0
+
+    def stabilize(self) -> dict:
+        if self.budget <= 0:
+            return {"evicted": 0, "budget": 0, "total": len(self.state.evidences),
+                    "note": "预算未设置（LIQUID_EVIDENCE_BUDGET=0），跳过"}
+        evs = self.state.evidences
+        if len(evs) <= self.budget:
+            return {"evicted": 0, "budget": self.budget, "total": len(evs)}
+        anchor_map = {a.id: a for a in self.state.anchors}
+        items: list[_BudgetItem] = []
+        for e in evs:
+            a = anchor_map.get(e.anchor_id)
+            items.append(_BudgetItem(
+                id=e.id,
+                weight=e.weight,
+                anchor_value=a.value_score if a else 0.5,
+                access_count=a.access_count if a else 0,
+                liquidity=a.liquidity if a else "warm",
+                gap_hours=self._gap_hours(a),
+            ))
+        evicted = _evict(items, self.budget)
+        evicted_ids = {it.id for it in evicted}
+        for e in evs:
+            if e.id in evicted_ids:
+                e.archived = True  # 冷归档，零丢失
+        return {
+            "evicted": len(evicted_ids),
+            "evicted_ids": list(evicted_ids),
+            "budget": self.budget,
+            "total": len(evs),
+        }

{liquid_loop-0.6.2 → liquid_loop-0.6.4}/liquid_loop/workspace.py

@@ -9,6 +9,8 @@ import os
 import re
 from collections import Counter
 
+from .cognitive_budget import CognitiveBudgetStabilizer
+
 
 def now() -> str:
     return datetime.now(timezone.utc).isoformat()
@@ -84,6 +86,7 @@ class Anchor:
     last_accessed: str = ""
     value_score: float = 1.0
     anchor_strength: float = 1.0
+    seal_adjust: float = 0.0  # SEAL 自评层增量；_recalc 合成进 stability，不被覆盖（解 v0.6.3 假落地）
 
     def decay_value(self, factor: float = 0.95, evidence_count: int = 0) -> float:
         if not self.created_at:
@@ -149,6 +152,7 @@ class Evidence:
     timestamp: str = field(default_factory=now)
     weight: float = 1.0
     quality: str = "normal"
+    archived: bool = False  # 预算超额冷归档标记（PEEK 落地，零丢失）
 
 
 @dataclass
@@ -266,11 +270,18 @@ class WorkspaceState:
         return e
 
     def _on_evidence_added(self, anchor_id: str):
-        """证据添加后的统一后处理：衰减→成核→稳定性刷新→冲突检测"""
+        """证据添加后的统一后处理：衰减→成核→稳定性刷新→冲突检测→预算稳态"""
         self._decay_anchor(anchor_id)
         self._nucleate(anchor_id)
         self._recalc_anchor(anchor_id)
         self._detect_conflicts(anchor_id)
+        self._stabilize_budget()
+
+    def _stabilize_budget(self):
+        """认知预算稳态（PEEK 落地）：超预算时冷归档最低价值证据。默认无预算不动作。"""
+        result = CognitiveBudgetStabilizer(self).stabilize()
+        if result.get("evicted", 0) > 0:
+            self.updated_at = now()
 
     def _decay_anchor(self, anchor_id: str):
         for e in self.evidences:
@@ -360,7 +371,10 @@ class WorkspaceState:
         avg_weight = sum(e.weight for e in group) / len(group)
         for a in self.anchors:
             if a.id == anchor_id:
-                a.stability = avg_weight
+                # base = 证据权重均值；stability = base + SEAL 自评层（seal_adjust 不被覆盖）
+                base = avg_weight
+                a.base_stability = base
+                a.stability = round(min(1.0, max(0.1, base + a.seal_adjust)), 3)
                 evidence_count = len(group)
                 a.decay_value(evidence_count=evidence_count)
                 a.recalc_strength(evidence_count)
@@ -851,6 +865,51 @@ class SelfRefineEngine:
                     repairs.append(f"REPAIR: 为锚点[{target_anchor.name}]新增evidence: {gold[:40]}")
         return repairs
 
+    # ── SEAL 落地（arXiv:2605.24426 失败诊断双优化）──
+    def diagnose(self, failure: Dict[str, Any]) -> Dict[str, Any]:
+        """SEAL 诊断：失败探测归因到锚点，判定失败类型。
+
+        fail_type:
+          retrieval  召回失败（记忆存在但未检索到）→ 策略侧 boost_stability
+          reason     推理失败（检索到但判断不中）   → 策略侧 downweight_noise
+        """
+        reason = failure.get("reason", "")
+        if "检索" in reason or "无相关" in reason:
+            fail_type = "retrieval"
+        else:
+            fail_type = "reason"
+        source = failure.get("source", "")
+        target = None
+        if source:
+            target = next((a for a in self.state.anchors if a.id == source), None)
+            if not target:
+                ev = next((e for e in self.state.evidences if e.id == source), None)
+                if ev:
+                    target = next((a for a in self.state.anchors if a.id == ev.anchor_id), None)
+        if fail_type == "retrieval":
+            tune = "boost_stability"
+            root = "召回失败：记忆存在但未检索到（权重/描述召回不足）"
+        else:
+            tune = "downweight_noise"
+            root = "推理失败：检索到但关键词判断不中（噪声/描述歧义）"
+        return {"fail_type": fail_type, "target_anchor": target.id if target else None,
+                "root_cause": root, "tune": tune}
+
+    def apply_strategy(self, diag: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """SEAL 双优化 - 策略侧：修复确认→boost_stability；噪声→downweight。"""
+        if not diag.get("target_anchor"):
+            return []
+        a = next((x for x in self.state.anchors if x.id == diag["target_anchor"]), None)
+        if not a:
+            return []
+        if diag["tune"] == "boost_stability":
+            a.seal_adjust = min(0.5, round(a.seal_adjust + 0.1, 3))
+        else:
+            a.seal_adjust = max(-0.5, round(a.seal_adjust - 0.1, 3))
+        base = getattr(a, "base_stability", a.stability)
+        projected = round(min(1.0, max(0.1, base + a.seal_adjust)), 3)
+        return [{"op": diag["tune"], "anchor": a.name, "seal_adjust": a.seal_adjust, "projected_stability": projected}]
+
     def run(self, evidence_ids: List[str] = None) -> Dict[str, Any]:
         """执行完整后向自进化周期。"""
         probes = self.generate_probes(evidence_ids)
@@ -862,10 +921,15 @@ class SelfRefineEngine:
         failures = [r for p, r in zip(probes, results)
                     if not r.get("passed") and p.get("type") != "overview"]
         repairs = self.repair(failures)
+        # SEAL 双优化 - 策略侧：诊断失败 → 调锚点 stability
+        diagnoses = [self.diagnose(f) for f in failures]
+        strategy_actions = []
+        for d in diagnoses:
+            strategy_actions.extend(self.apply_strategy(d))
         self.state.self_refine_probes = probes
         self.state.self_refine_results = results
         self.state.self_refine_repair_count += len(repairs)
-        return {"total": len(probes), "passed": passed, "failed": len(failures), "pass_rate": round(passed / len(probes), 2), "repairs": repairs, "failed_details": [{"q": r.get("question", "")[:60], "reason": r.get("reason", "")} for r in failures[:5]]}
+        return {"total": len(probes), "passed": passed, "failed": len(failures), "pass_rate": round(passed / len(probes), 2), "repairs": repairs, "diagnoses": diagnoses, "strategy_actions": strategy_actions, "failed_details": [{"q": r.get("question", "")[:60], "reason": r.get("reason", "")} for r in failures[:5]]}
 
 
 # ==============================================================================

{liquid_loop-0.6.2 → liquid_loop-0.6.4}/liquid_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: liquid-loop
-Version: 0.6.2
+Version: 0.6.4
 Summary: Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation
 Author: fishbook0001
 Maintainer: fishbook0001

{liquid_loop-0.6.2 → liquid_loop-0.6.4}/liquid_loop.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 liquid_loop/__init__.py
 liquid_loop/__main__.py
 liquid_loop/cli.py
+liquid_loop/cognitive_budget.py
 liquid_loop/entropy.py
 liquid_loop/storage.py
 liquid_loop/workspace.py
@@ -14,5 +15,7 @@ liquid_loop.egg-info/entry_points.txt
 liquid_loop.egg-info/requires.txt
 liquid_loop.egg-info/top_level.txt
 tests/test_entropy.py
+tests/test_peek_seal.py
+tests/test_seal_persistence.py
 tests/test_self_evolve.py
 tests/test_workspace.py

{liquid_loop-0.6.2 → liquid_loop-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "liquid-loop"
-version = "0.6.2"
+version = "0.6.4"
 description = "Self-Organizing Cognitive Memory for AI Agents — Liquid Loop theory implementation"
 readme = "README.md"
 license = {text = "MIT"}

liquid_loop-0.6.4/tests/test_peek_seal.py

@@ -0,0 +1,115 @@
+"""PEEK 预算稳态 + SEAL 双优化 落地测试（液环仓库内）"""
+import pytest
+from liquid_loop.workspace import WorkspaceState, SelfRefineEngine
+from liquid_loop.cognitive_budget import CognitiveBudgetStabilizer
+
+
+# ───────────── PEEK 落地：认知预算稳态器 ─────────────
+
+def test_budget_stabilizer_evicts_low_value(monkeypatch):
+    monkeypatch.setenv("LIQUID_EVIDENCE_BUDGET", "3")
+    st = WorkspaceState()
+    a_hot = st.add_anchor("hot")
+    a_hot.value_score = 0.9
+    a_hot.access_count = 20
+    a_hot.liquidity = "hot"
+    a_cold = st.add_anchor("cold")
+    a_cold.value_score = 0.2
+    a_cold.access_count = 0
+    a_cold.liquidity = "frozen"
+    for i in range(3):
+        st.add_evidence("hot", f"重要证据{i} 液环锚点")
+    for i in range(3):
+        st.add_evidence("cold", f"陈旧证据{i} 旧记忆")
+    # 6 条证据，预算 3 → 应冷归档 3 条最低价值（cold 锚点）
+    arch = [e for e in st.evidences if e.archived]
+    assert len(arch) == 3
+    assert all(e.anchor_id == a_cold.id for e in arch)
+
+
+def test_budget_no_limit_when_unset(monkeypatch):
+    monkeypatch.delenv("LIQUID_EVIDENCE_BUDGET", raising=False)
+    st = WorkspaceState()
+    a = st.add_anchor("x")
+    for i in range(10):
+        st.add_evidence("x", f"证据{i}")
+    arch = [e for e in st.evidences if e.archived]
+    assert arch == []  # 无预算不驱逐
+
+
+def test_budget_stabilizer_direct_call(monkeypatch):
+    monkeypatch.setenv("LIQUID_EVIDENCE_BUDGET", "2")
+    st = WorkspaceState()
+    a = st.add_anchor("x")
+    a.value_score = 0.5
+    for i in range(5):
+        st.add_evidence("x", f"证据{i}")
+    res = CognitiveBudgetStabilizer(st).stabilize()
+    assert res["evicted"] == 3
+    assert res["total"] == 5
+    assert res["budget"] == 2
+
+
+# ───────────── SEAL 落地：失败诊断双优化 ─────────────
+
+def test_seal_diagnose_retrieval():
+    st = WorkspaceState()
+    a = st.add_anchor("液环", description="液环记忆理论")
+    st.add_evidence("液环", "液环锚点结晶")
+    eng = SelfRefineEngine(st)
+    failure = {"source": a.id, "reason": "检索失败，无相关记忆", "question": "?", "gold": "?"}
+    diag = eng.diagnose(failure)
+    assert diag["fail_type"] == "retrieval"
+    assert diag["target_anchor"] == a.id
+    assert diag["tune"] == "boost_stability"
+
+
+def test_seal_diagnose_reason_downweights():
+    st = WorkspaceState()
+    a = st.add_anchor("稳态")
+    eng = SelfRefineEngine(st)
+    failure = {"source": a.id, "reason": "关键词不匹配，gold=稳态"}
+    diag = eng.diagnose(failure)
+    assert diag["fail_type"] == "reason"
+    eng.apply_strategy(diag)
+    # v0.6.4：改 seal_adjust 层，不直接动 stability
+    assert a.seal_adjust == -0.1
+    st.add_evidence(a, "补充证据")  # 触发 _recalc 合成
+    assert a.stability == round(min(1.0, max(0.1, a.base_stability + a.seal_adjust)), 3)
+    assert a.stability < a.base_stability  # 负增量生效，自洽性降权
+
+
+def test_seal_apply_strategy_boost():
+    st = WorkspaceState()
+    a = st.add_anchor("液环")
+    eng = SelfRefineEngine(st)
+    diag = {"fail_type": "retrieval", "target_anchor": a.id, "tune": "boost_stability"}
+    acts = eng.apply_strategy(diag)
+    assert acts[0]["op"] == "boost_stability"
+    assert a.seal_adjust == 0.1
+    st.add_evidence(a, "补充证据")  # 触发 _recalc 合成
+    assert a.stability == round(min(1.0, max(0.1, a.base_stability + a.seal_adjust)), 3)
+    assert a.stability >= a.base_stability  # 正增量生效
+
+
+def test_seal_run_integration_dual_optimize(monkeypatch):
+    st = WorkspaceState()
+    a = st.add_anchor("液环", description="液环")
+    st.add_evidence("液环", "液环锚点")
+    eng = SelfRefineEngine(st)
+
+    def fake_verify(p):
+        if p.get("type") == "fact":
+            # 模拟"检索失败但记忆应存在"：source 指向锚点，gold 为新内容（需补证据）
+            return {"passed": False, "reason": "检索失败，无相关记忆",
+                    "question": p.get("question", ""), "gold": "全新记忆内容需补回",
+                    "source": a.id}
+        return {"passed": True, "reason": "ok"}
+
+    monkeypatch.setattr(eng, "verify", fake_verify)
+    out = eng.run()
+    assert out["failed"] >= 1
+    assert len(out["strategy_actions"]) >= 1
+    assert out["strategy_actions"][0]["op"] == "boost_stability"
+    # 双优化：memory 侧（repairs）与 strategy 侧（strategy_actions）都应存在
+    assert len(out["repairs"]) >= 1

liquid_loop-0.6.4/tests/test_seal_persistence.py

@@ -0,0 +1,63 @@
+"""E8/v0.6.4 — 验证 SEAL 双优化不再被 _recalc_anchor 覆盖（解 v0.6.3 假落地）。
+
+修复核心：stability = base(证据权重均值) + seal_adjust(SEAL 自评层增量)；
+apply_strategy 改 seal_adjust 而非直接动 stability，_recalc 合成时保留。
+
+本测试直接构造诊断（绕过 SelfRefineEngine.verify 的脆弱归因），专注验证
+apply_strategy → seal_adjust → _recalc 合成的持久性。
+"""
+from liquid_loop.workspace import WorkspaceState, SelfRefineEngine
+
+
+def _boost(a, eng):
+    diag = {"fail_type": "retrieval", "target_anchor": a.id,
+            "root_cause": "召回失败", "tune": "boost_stability"}
+    return eng.apply_strategy(diag)
+
+
+def _down(a, eng):
+    diag = {"fail_type": "reason", "target_anchor": a.id,
+            "root_cause": "推理失败", "tune": "downweight_noise"}
+    return eng.apply_strategy(diag)
+
+
+def test_seal_boost_persists_through_recalc():
+    """SEAL boost 后即便再 add_evidence 触发 _recalc，stability 仍含 seal_adjust。"""
+    st = WorkspaceState()
+    eng = SelfRefineEngine(st)
+    a = st.add_anchor("probe_seal")
+    st.add_evidence(a, "初始证据")
+    _boost(a, eng)
+    assert a.seal_adjust == 0.1
+    st.add_evidence(a, "再来一条证据")  # 触发 _recalc_anchor
+    assert a.seal_adjust == 0.1  # 增量持久
+    expected = round(min(1.0, max(0.1, a.base_stability + a.seal_adjust)), 3)
+    assert a.stability == expected
+    assert a.stability >= a.base_stability  # 正增量应 >= base
+
+
+def test_seal_downweight():
+    st = WorkspaceState()
+    eng = SelfRefineEngine(st)
+    a = st.add_anchor("noise")
+    st.add_evidence(a, "x")
+    acts = _down(a, eng)
+    assert a.seal_adjust == -0.1
+    assert acts[0]["op"] == "downweight_noise"
+
+
+def test_seal_adjust_applied_in_recalc():
+    """开 SEAL 的锚点 stability = base + seal_adjust；对照无 SEAL 锚点 adjust=0。"""
+    st = WorkspaceState()
+    eng = SelfRefineEngine(st)
+    a = st.add_anchor("x")
+    st.add_evidence(a, "e1")
+    _boost(a, eng)
+    st.add_evidence(a, "e2")  # 触发 _recalc
+    # 开 SEAL：stability 合成 seal_adjust（含 clamp，与期望值精确匹配）
+    assert a.stability == round(min(1.0, max(0.1, a.base_stability + a.seal_adjust)), 3)
+    # 对照：无 SEAL 的锚点 seal_adjust=0，stability=base
+    b = st.add_anchor("y")
+    st.add_evidence(b, "f1")
+    assert b.seal_adjust == 0.0
+    assert abs(b.stability - b.base_stability) < 1e-6