foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/learning/knowledge_graph.py

@@ -0,0 +1,144 @@
+"""
+Foxclaw 学习子系统 — 知识图谱(连接层)
+把分散的知识点串成网。三种边:
+  manual(手动标注)、same_topic(同主题/标签自动)、semantic(语义相近自动)
+核心思想:学习不只是记住单点,更是发现知识之间的连接。
+"""
+
+import hashlib
+from collections import defaultdict
+from .models import KnowledgeItem, KnowledgeEdge
+
+
+class KnowledgeGraph:
+    """轻量知识图谱。语义相似度优先用外部 embedder(HMR),
+    不可用时降级为字符 n-gram 哈希向量余弦(与 Harness 同思路)。"""
+
+    DIM = 256
+
+    def __init__(self, embedder=None):
+        self.items: dict = {}
+        self.edges: list = []
+        self._embedder = embedder
+
+    def add_item(self, item: KnowledgeItem):
+        self.items[item.id] = item
+
+    def remove_item(self, item_id: str):
+        """移除一个知识点及其相关的所有边。"""
+        self.items.pop(item_id, None)
+        self.edges = [e for e in self.edges
+                      if e.source_id != item_id and e.target_id != item_id]
+
+    def link_manual(self, source_id: str, target_id: str, reason: str = ""):
+        self.edges.append(KnowledgeEdge(
+            source_id=source_id, target_id=target_id,
+            edge_type="manual", weight=1.0, reason=reason or "手动关联"))
+
+    def auto_link_by_topic(self):
+        """同主题 / 共享标签的知识点自动连接。"""
+        ids = list(self.items.keys())
+        new_edges = 0
+        for i in range(len(ids)):
+            for j in range(i + 1, len(ids)):
+                a, b = self.items[ids[i]], self.items[ids[j]]
+                shared_tags = set(a.tags) & set(b.tags)
+                if a.topic == b.topic and a.topic != "general":
+                    self.edges.append(KnowledgeEdge(
+                        source_id=a.id, target_id=b.id, edge_type="same_topic",
+                        weight=0.7, reason=f"同主题:{a.topic}"))
+                    new_edges += 1
+                elif shared_tags:
+                    self.edges.append(KnowledgeEdge(
+                        source_id=a.id, target_id=b.id, edge_type="same_topic",
+                        weight=0.5, reason=f"共享标签:{','.join(shared_tags)}"))
+                    new_edges += 1
+        return new_edges
+
+    def auto_link_by_semantic(self, threshold: float = 0.55):
+        """语义相近的知识点自动连接(余弦相似度)。"""
+        ids = list(self.items.keys())
+        vecs = {i: self._embed(self.items[i].content) for i in ids}
+        new_edges = 0
+        for i in range(len(ids)):
+            for j in range(i + 1, len(ids)):
+                sim = self._cosine(vecs[ids[i]], vecs[ids[j]])
+                if sim >= threshold:
+                    self.edges.append(KnowledgeEdge(
+                        source_id=ids[i], target_id=ids[j], edge_type="semantic",
+                        weight=round(sim, 3),
+                        reason=f"语义相近({sim:.2f})"))
+                    new_edges += 1
+        return new_edges
+
+    def neighbors(self, item_id: str) -> list:
+        """某知识点的所有关联点。"""
+        out = []
+        for e in self.edges:
+            if e.source_id == item_id:
+                out.append((e.target_id, e.edge_type, e.weight, e.reason))
+            elif e.target_id == item_id:
+                out.append((e.source_id, e.edge_type, e.weight, e.reason))
+        return sorted(out, key=lambda x: -x[2])
+
+    def clusters(self) -> list:
+        """连通分量 = 知识簇。返回每个簇的成员 id 列表。"""
+        adj = defaultdict(set)
+        for e in self.edges:
+            adj[e.source_id].add(e.target_id)
+            adj[e.target_id].add(e.source_id)
+        seen, result = set(), []
+        for node in self.items:
+            if node in seen:
+                continue
+            stack, comp = [node], []
+            while stack:
+                n = stack.pop()
+                if n in seen:
+                    continue
+                seen.add(n)
+                comp.append(n)
+                stack.extend(adj[n] - seen)
+            result.append(comp)
+        return result
+
+    def stats(self) -> dict:
+        type_count: defaultdict[str, int] = defaultdict(int)
+        for e in self.edges:
+            type_count[e.edge_type] += 1
+        return {
+            "items": len(self.items),
+            "edges": len(self.edges),
+            "edge_types": dict(type_count),
+            "clusters": len(self.clusters()),
+        }
+
+    def _embed(self, text: str):
+        if self._embedder is not None:
+            try:
+                return self._embedder(text)
+            except Exception:
+                pass
+        return self._hash_embed(text)
+
+    def _hash_embed(self, text: str):
+        import math
+        vec = [0.0] * self.DIM
+        text = (text or "").lower().strip()
+        grams = [text[i:i+3] for i in range(max(len(text) - 2, 1))]
+        for g in grams:
+            h = int(hashlib.md5(g.encode("utf-8")).hexdigest(), 16)
+            idx = h % self.DIM
+            vec[idx] += 1.0 if (h // self.DIM) % 2 == 0 else -1.0
+        norm = math.sqrt(sum(v * v for v in vec))
+        return [v / norm for v in vec] if norm > 0 else vec
+
+    @staticmethod
+    def _cosine(a, b) -> float:
+        import math
+        dot = sum(x * y for x, y in zip(a, b))
+        na = math.sqrt(sum(x * x for x in a))
+        nb = math.sqrt(sum(x * x for x in b))
+        if na == 0 or nb == 0:
+            return 0.0
+        return max(0.0, min(1.0, dot / (na * nb)))

package/python/foxclaw/learning/models.py

@@ -0,0 +1,93 @@
+"""
+Foxclaw 学习子系统 — 数据模型
+学习行为操作系统的四类结构:
+  KnowledgeItem(知识条目)、ReviewState(间隔重复状态)、
+  KnowledgeEdge(知识图谱边)、LearningVerdict(学习策略裁决)
+核心思想:学习 = 可追踪的记忆行为轨迹(纵向掌握度 + 横向知识连接)。
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Optional, Literal
+import uuid
+
+
+EdgeType = Literal["same_topic", "concept_ref", "semantic", "manual"]
+Grade = Literal[0, 1, 2, 3, 4, 5]
+
+
+@dataclass
+class KnowledgeItem:
+    """一个知识条目 = 一次学习采集"""
+    content: str
+    topic: str = "general"
+    source: str = ""
+    tags: list = field(default_factory=list)
+    notes: list = field(default_factory=list)
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    id: str = field(default_factory=lambda: f"ki_{uuid.uuid4().hex[:10]}")
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ReviewState:
+    """SM-2 间隔重复状态(固化层核心)"""
+    item_id: str
+    repetitions: int = 0
+    interval: int = 0
+    ease_factor: float = 2.5
+    due_date: str = field(default_factory=lambda: datetime.now().isoformat())
+    last_review: Optional[str] = None
+    total_reviews: int = 0
+    lapses: int = 0
+
+    @property
+    def mastery(self) -> float:
+        """掌握度 0~1:综合连续正确次数和难度因子。"""
+        rep_score = min(self.repetitions / 6.0, 1.0)
+        ease_score = (self.ease_factor - 1.3) / (2.5 - 1.3)
+        ease_score = max(0.0, min(1.0, ease_score))
+        return round(0.6 * rep_score + 0.4 * ease_score, 3)
+
+    @property
+    def is_due(self) -> bool:
+        return datetime.fromisoformat(self.due_date) <= datetime.now()
+
+    @property
+    def days_until_due(self) -> int:
+        delta = datetime.fromisoformat(self.due_date) - datetime.now()
+        return delta.days
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d.update(mastery=self.mastery, is_due=self.is_due,
+                 days_until_due=self.days_until_due)
+        return d
+
+
+@dataclass
+class KnowledgeEdge:
+    """知识图谱的一条边(连接层核心)"""
+    source_id: str
+    target_id: str
+    edge_type: EdgeType
+    weight: float = 1.0
+    reason: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class LearningVerdict:
+    """学习策略裁决(对应财务守门人)"""
+    rule_id: str
+    action: Literal["review_due", "weak_topic_alert", "overload_warn", "suggest_connect"]
+    message: str
+    severity: Literal["info", "warn"] = "info"
+    payload: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)

package/python/foxclaw/learning/reasoner.py

@@ -0,0 +1,67 @@
+"""
+LearningReviewReasoner —— 学习复习推理的认知化(v2 ③ Step4)。
+
+把 SpacedRepetition.forgetting_risk / learning_load 的规则裁决,形式化为
+    观察 → 假设 → 证据 → 裁决,
+**规则永远权威**(存在高遗忘风险知识点 → confirm=建议立即复习,绝不被 LLM 推翻);
+可选 LLM 层(默认关)只对"无高风险、但负荷偏重"的微妙情形**升级** approve→confirm。
+裁决带证据链(可审计)。顾问域(非治理闸口):LLM 出错→维持规则裁决。
+"""
+from __future__ import annotations
+from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
+from .spaced_repetition import SpacedRepetition
+
+HEAVY_DAILY = 20.0
+
+
+class LearningReviewReasoner(DomainReasoner):
+    """subject = states(list[ReviewState])。裁决:approve(学习状态健康) / confirm(需干预)。"""
+
+    def __init__(self, horizon_days: int = 3, llm=None, llm_enabled: bool = False):
+        self.horizon_days = horizon_days
+        self.llm = llm
+        self.llm_enabled = llm_enabled
+
+    def observe(self, states) -> dict:
+        load = SpacedRepetition.learning_load(states)
+        return {"total": len(states), "overdue": load["overdue"],
+                "daily_avg": load["daily_avg"], "total_due": load["total_due"]}
+
+    def hypothesize(self, obs: dict) -> list:
+        h = []
+        if obs["overdue"]:
+            h.append("可能有逾期未复习")
+        if obs["daily_avg"] >= HEAVY_DAILY:
+            h.append("可能复习负荷过重")
+        return h or ["学习状态可能健康"]
+
+    def gather_evidence(self, states, obs: dict) -> list:
+        risky = SpacedRepetition.forgetting_risk(states, self.horizon_days)
+        ev = [Evidence(factor="forgetting_risk",
+                       detail=r["reason"] + f"(item {r['item_id']})", weight=1.0, raw=r)
+              for r in risky]
+        if not risky:
+            ev.append(Evidence("no_urgent_risk", "无即将到期且掌握度低的知识点", 0.5))
+        ev.append(Evidence("learning_load",
+                           f"未来窗口共 {obs['total_due']} 项待复习,日均 {obs['daily_avg']}", 0.3))
+        return ev
+
+    def arbitrate(self, states, obs, hyps, ev) -> ReasonedVerdict:
+        triggered = [e for e in ev if e.raw is not None]
+        if triggered:
+            top = triggered[:3]
+            return ReasonedVerdict(
+                "confirm", f"发现 {len(triggered)} 个高遗忘风险知识点,建议优先复习:"
+                + "；".join(e.detail for e in top),
+                ev, hyps, "rules")
+        if DomainReasoner.llm_available(self.llm, self.llm_enabled) and obs["daily_avg"] >= HEAVY_DAILY:
+            if DomainReasoner.llm_should_escalate(self.llm, *self._llm_prompt(obs, ev)):
+                return ReasonedVerdict("confirm", "复习负荷偏重,LLM 建议调整计划", ev, hyps, "llm")
+        return ReasonedVerdict("approve", "学习状态健康:无高遗忘风险知识点", ev, hyps, "rules")
+
+    def _llm_prompt(self, obs, ev):
+        ev_text = "\n".join(f"- {e.factor}: {e.detail}" for e in ev) or "(无)"
+        system = ("你是学习助手。当前无高遗忘风险知识点,但复习负荷偏重。"
+                  "判断是否建议用户调整复习计划。只回答 CONFIRM(建议调整)或 OK(无需)。")
+        user = f"负荷:日均 {obs['daily_avg']} 项。\n证据:\n{ev_text}\n\n只回答一个词:CONFIRM 或 OK。"
+        return system, user

package/python/foxclaw/learning/runtime.py

@@ -0,0 +1,351 @@
+"""
+Foxclaw 学习子系统 — Learning Runtime
+学习行为操作系统:采集 → 沉淀(HMR + 双结构) → 固化(间隔重复) → 连接(知识图谱)。
+对应财务 Runtime,office Agent 的"赫尔墨斯式自学"内核。
+"""
+
+import csv
+import json
+import threading
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+
+from .models import KnowledgeItem, ReviewState, LearningVerdict
+from .spaced_repetition import SpacedRepetition
+from .knowledge_graph import KnowledgeGraph
+
+
+class LearningRuntime:
+    """office Agent 的学习内核。"""
+
+    def __init__(self, hmr=None, hkc_provider=None, persist_path=None):
+        self.items: dict = {}
+        self.review_states: dict = {}
+        self.sr = SpacedRepetition()
+        self.hmr = hmr
+        self._hkc_provider = hkc_provider
+        self._lock = threading.RLock()
+        embedder = None
+        if hmr is not None and hasattr(hmr, "_hmr"):
+            embedder = self._make_embedder(hmr)
+        self.graph = KnowledgeGraph(embedder=embedder)
+        self._persist_path = Path(persist_path) if persist_path else None
+        self._hkc_loaded = False
+        self._load_file()
+        self._ensure_hkc_loaded()
+
+    def _make_embedder(self, hmr):
+        """尝试复用 HMR 的 embedding;失败则返回 None(图谱自动降级哈希)。"""
+        try:
+            store = getattr(hmr._hmr, "vector_store", None)
+            if store and hasattr(store, "_embed"):
+                return lambda t: list(store._embed(t))
+        except Exception:
+            pass
+        return None
+
+    def _graph_store(self):
+        """惰性拿 HKC 的 graph_store。拿不到(HKC 未装配/未配/异常)返回 None。"""
+        if not self._hkc_provider:
+            return None
+        try:
+            hkc = self._hkc_provider()
+            c = getattr(hkc, "container", None) if hkc else None
+            return getattr(c, "graph_store", None) if c else None
+        except Exception:
+            return None
+
+    def _item_to_ku(self, item):
+        """KnowledgeItem → 一个连续的 ConceptKU:source_text=全文;notes/复习状态/kind 存 extra。"""
+        from hkc_core.models.ku import ConceptKU
+        rs = self.review_states.get(item.id)
+        ku = ConceptKU(
+            ku_id=item.id,
+            name=(item.topic or "学习知识点")[:80],
+            summary=(item.content or "")[:200],
+            tags=list(item.tags or []) + ["learning_note"],
+            domain=item.topic or "learning",
+            source_text=item.content or "",
+        )
+        ku.extra.update({
+            "kind": "learning_note",
+            "notes": list(item.notes or []),
+            "note_source": item.source or "",
+            "learn_created_at": item.created_at,
+            "review": asdict(rs) if rs is not None else None,
+        })
+        return ku
+
+    def _ku_to_item(self, ku):
+        """HKC 的 learning_note KU → (KnowledgeItem, review_dict)。"""
+        ex = getattr(ku, "extra", {}) or {}
+        content = getattr(ku, "source_text", "") or ex.get("source_text", "") or ku.summary
+        tags = [t for t in (ku.tags or []) if t != "learning_note"]
+        item = KnowledgeItem(
+            content=content,
+            topic=ku.name or ku.domain or "general",
+            source=ex.get("note_source", ""),
+            tags=tags,
+            notes=list(ex.get("notes", []) or []),
+            created_at=ex.get("learn_created_at") or ku.created_at,
+            id=ku.ku_id,
+        )
+        return item, ex.get("review")
+
+    def _load_file(self):
+        """把离线队列 / 旧 learning.json 载入内存(__init__ 时 HKC 常未就绪,先撑住 UI)。"""
+        if not (self._persist_path and self._persist_path.exists()):
+            return
+        try:
+            data = json.loads(self._persist_path.read_text(encoding="utf-8"))
+            fields = KnowledgeItem.__dataclass_fields__
+            for d in data.get("items", []):
+                item = KnowledgeItem(**{k: v for k, v in d.items() if k in fields})
+                if item.id in self.items:
+                    continue
+                self.items[item.id] = item
+                self.graph.add_item(item)
+            for d in data.get("reviews", []):
+                try:
+                    rs = ReviewState(**d)
+                    self.review_states.setdefault(rs.item_id, rs)
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+    def _ensure_hkc_loaded(self):
+        """惰性从 HKC(知识真源)载入 learning_note KU —— 只成功一次。
+        铁律要点:HKC 惰性初始化,__init__ 时(_hkc_api_key 尚未设)常拿不到 gs,
+        故必须在后续任意读写(analyze 轮询/learn/...)里重试载入,否则迁移删文件后
+        重启会「知识凭空消失」(真源仍在 hkc.db,只是没被读回)。加载后把内存里
+        文件残留的条目回迁 HKC 并删本地队列文件。"""
+        if self._hkc_loaded:
+            return
+        gs = self._graph_store()
+        if gs is None:
+            return
+        try:
+            for ku in gs.query_all(limit=5000):
+                ex = getattr(ku, "extra", {}) or {}
+                if ex.get("kind") != "learning_note":
+                    continue
+                if getattr(ku, "status", "active") == "deleted":
+                    continue
+                item, review = self._ku_to_item(ku)
+                if item.id in self.items:
+                    continue
+                self.items[item.id] = item
+                self.graph.add_item(item)
+                if review:
+                    try:
+                        self.review_states.setdefault(item.id, ReviewState(**review))
+                    except Exception:
+                        pass
+        except Exception:
+            return
+        self._hkc_loaded = True
+        if self._persist_path and self._persist_path.exists():
+            self._save()
+
+    def _save(self):
+        """把所有知识点 put 进 HKC(真源,upsert)。HKC 拿不到 → 写离线队列文件(兜底 A)。"""
+        with self._lock:
+            items = list(self.items.values())
+        gs = self._graph_store()
+        if gs is not None:
+            ok = True
+            for it in items:
+                try:
+                    gs.put(self._item_to_ku(it))
+                except Exception:
+                    ok = False
+            if ok:
+                if self._persist_path and self._persist_path.exists():
+                    try:
+                        self._persist_path.unlink()
+                    except Exception:
+                        pass
+                return
+        if self._persist_path:
+            try:
+                data = {
+                    "items": [asdict(it) for it in items],
+                    "reviews": [asdict(rs) for rs in self.review_states.values()],
+                }
+                self._persist_path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self._persist_path.with_suffix(".tmp")
+                tmp.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+                tmp.replace(self._persist_path)
+            except Exception:
+                pass
+
+    def learn(self, content: str, topic: str = "general",
+              source: str = "", tags: list | None = None) -> dict:
+        """采集一个知识点 → 存进 HKC(知识真源)+ 间隔重复队列 + 图谱。
+        铁律:知识内容+笔记归 HKC,不进 HMR(HMR 只装 token 上下文/工作运行记忆)。"""
+        self._ensure_hkc_loaded()
+        item = KnowledgeItem(content=content, topic=topic,
+                             source=source, tags=tags or [])
+        with self._lock:
+            self.items[item.id] = item
+            self.review_states[item.id] = ReviewState(item_id=item.id)
+            self.graph.add_item(item)
+        self._save()
+        return {"item": item.to_dict(),
+                "review": self.review_states[item.id].to_dict()}
+
+    def import_csv(self, path: str) -> int:
+        """从 CSV 导入知识点。列:content,topic,source,tags
+        外部工具(Readwise/Obsidian/Anki MCP)接口可在此扩展。"""
+        count = 0
+        with open(Path(path), encoding="utf-8") as f:
+            for row in csv.DictReader(f):
+                tags = [t.strip() for t in (row.get("tags") or "").split("|") if t.strip()]
+                self.learn(content=row["content"],
+                           topic=row.get("topic", "general"),
+                           source=row.get("source", ""), tags=tags)
+                count += 1
+        return count
+
+    def review(self, item_id: str, grade: int) -> dict:
+        """复习一个知识点,提交回忆质量评分(0~5),更新掌握度。"""
+        self._ensure_hkc_loaded()
+        state = self.review_states.get(item_id)
+        if not state:
+            return {"error": "未知知识点"}
+        self.sr.review(state, grade)
+        self._save()
+        return state.to_dict()
+
+    def delete(self, item_id: str) -> bool:
+        """删除一个知识点(内存 + 复习状态 + 图谱)并落盘。返回是否命中。"""
+        self._ensure_hkc_loaded()
+        with self._lock:
+            found = item_id in self.items
+            self.items.pop(item_id, None)
+            self.review_states.pop(item_id, None)
+            try:
+                self.graph.remove_item(item_id)
+            except Exception:
+                pass
+        gs = self._graph_store()
+        if gs is not None:
+            try:
+                gs.delete(item_id)
+            except Exception:
+                pass
+        if found:
+            self._save()
+        return found
+
+    def add_note(self, item_id: str, text: str) -> dict:
+        """给一个知识点追加一条笔记(有内容才写盘;没新增就不存)。"""
+        self._ensure_hkc_loaded()
+        text = (text or "").strip()
+        if not text:
+            return {"error": "笔记为空"}
+        with self._lock:
+            item = self.items.get(item_id)
+            if item is None:
+                return {"error": "未知知识点"}
+            item.notes.append({"text": text, "ts": datetime.now().isoformat()})
+            notes = list(item.notes)
+        self._save()
+        return {"notes": notes}
+
+    def due_today(self) -> list:
+        """今天该复习的知识点(最弱的优先)。"""
+        due = self.sr.due_items(list(self.review_states.values()))
+        return [{"item": self.items[s.item_id].to_dict(),
+                 "review": s.to_dict()} for s in due]
+
+    def build_connections(self, semantic_threshold: float = 0.55) -> dict:
+        """自动构建知识连接(同主题 + 语义)。"""
+        topic_edges = self.graph.auto_link_by_topic()
+        semantic_edges = self.graph.auto_link_by_semantic(semantic_threshold)
+        return {"topic_edges": topic_edges,
+                "semantic_edges": semantic_edges,
+                "graph": self.graph.stats()}
+
+    def related(self, item_id: str) -> list:
+        """某知识点的关联知识(连接发现)。"""
+        out = []
+        for nid, etype, weight, reason in self.graph.neighbors(item_id):
+            if nid in self.items:
+                out.append({"item": self.items[nid].to_dict(),
+                            "edge_type": etype, "weight": weight, "reason": reason})
+        return out
+
+    def strategy_check(self, daily_cap: int = 20) -> list:
+        """学习策略裁决:复习提醒、薄弱主题、负荷预警、连接建议。"""
+        verdicts = []
+        states = list(self.review_states.values())
+
+        due = self.sr.due_items(states)
+        if due:
+            verdicts.append(LearningVerdict(
+                rule_id="review_due", action="review_due", severity="info",
+                message=f"今天有 {len(due)} 个知识点待复习",
+                payload={"count": len(due)}))
+
+        risky = self.sr.forgetting_risk(states)
+        if risky:
+            verdicts.append(LearningVerdict(
+                rule_id="weak_alert", action="weak_topic_alert", severity="warn",
+                message=f"{len(risky)} 个知识点处于高遗忘风险,建议优先复习",
+                payload={"risky": risky[:5]}))
+
+        load = self.sr.learning_load(states)
+        if load["total_due"] > daily_cap:
+            verdicts.append(LearningVerdict(
+                rule_id="overload", action="overload_warn", severity="warn",
+                message=f"未来复习量 {load['total_due']} 超过每日上限 {daily_cap},建议分批",
+                payload=load))
+
+        connected = set()
+        for e in self.graph.edges:
+            connected.add(e.source_id)
+            connected.add(e.target_id)
+        isolated = [i for i in self.items if i not in connected]
+        if isolated:
+            verdicts.append(LearningVerdict(
+                rule_id="suggest_connect", action="suggest_connect", severity="info",
+                message=f"{len(isolated)} 个知识点尚无关联,可建立连接以加深理解",
+                payload={"isolated_count": len(isolated)}))
+        return verdicts
+
+    def analyze(self) -> dict:
+        self._ensure_hkc_loaded()
+        states = list(self.review_states.values())
+        masteries = [s.mastery for s in states]
+        avg_mastery = round(sum(masteries) / len(masteries), 3) if masteries else 0.0
+
+        from collections import defaultdict
+        topic_mastery = defaultdict(list)
+        for iid, item in self.items.items():
+            st = self.review_states.get(iid)
+            if st:
+                topic_mastery[item.topic].append(st.mastery)
+        topics = {t: round(sum(m) / len(m), 3) for t, m in topic_mastery.items()}
+
+        return {
+            "total_items": len(self.items),
+            "avg_mastery": avg_mastery,
+            "topic_mastery": topics,
+            "weakest_topic": (min(topics, key=lambda t: topics[t]) if topics else None),
+            "due_today": len(self.sr.due_items(states)),
+            "forgetting_risk": self.sr.forgetting_risk(states),
+            "learning_load": self.sr.learning_load(states),
+            "graph": self.graph.stats(),
+            "strategy": [v.to_dict() for v in self.strategy_check()],
+        }
+
+    def status(self) -> dict:
+        self._ensure_hkc_loaded()
+        return {
+            "items": len(self.items),
+            "reviews_tracked": len(self.review_states),
+            "graph": self.graph.stats(),
+        }