know-do-graph 0.1.3__tar.gz → 0.1.4__tar.gz

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: know-do-graph
-Version: 0.1.3
+Version: 0.1.4
 Summary: A wiki-native, agent-oriented infrastructure for executable knowledge, operational memory, and capability discovery.
 Requires-Python: >=3.10
 Requires-Dist: duckduckgo-search>=6.0
@@ -173,7 +173,8 @@ with KnowDoGraph("data/my_agent.db") as graph:
 Memory review samples only unpromoted `memory` nodes. It classifies each trace
 as L1/L2/L3/L4, noise, or skip. L1/L2 become unverified capability/procedure
 nodes; L3/L4 become heuristic/constraint nodes linked to an existing L1/L2
-node; noise is deleted.
+node. Successful distillation deletes the raw memory node; noise is also
+deleted.
 
 Applications can use the polling API instead of running reviewer logic locally:
 

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/README.md

@@ -150,7 +150,8 @@ with KnowDoGraph("data/my_agent.db") as graph:
 Memory review samples only unpromoted `memory` nodes. It classifies each trace
 as L1/L2/L3/L4, noise, or skip. L1/L2 become unverified capability/procedure
 nodes; L3/L4 become heuristic/constraint nodes linked to an existing L1/L2
-node; noise is deleted.
+node. Successful distillation deletes the raw memory node; noise is also
+deleted.
 
 Applications can use the polling API instead of running reviewer logic locally:
 

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/agents/review_agent/agent.py

@@ -65,11 +65,16 @@ in one session.
    - If a node is a specific application of a broader capability, add a
      `derived_from` or `prerequisite` edge.
 
+5. **Verification limits**
+   - You may only set `verification_status` to `unverified` or `self_tested`.
+   - `peer_reviewed` and `community_tested` are reserved for explicit human edits.
+
 ## Your workflow each session
 1. Call `get_graph_summary` to see overall health and review coverage.
 2. Call `sample_nodes_for_review` to get a batch (default 5).
 3. For each sampled node: call `inspect_node`, assess quality, apply fixes if needed.
-4. After inspecting (and optionally fixing) each node, call `mark_reviewed`.
+4. For each unchanged node, call `mark_reviewed`. Update and merge tools record
+   the review automatically, so do not call `mark_reviewed` after using them.
 5. Summarise what you found and fixed.
 
 Keep changes conservative — prefer targeted fixes over large rewrites.

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/agents/review_agent/tools.py

@@ -92,16 +92,16 @@ def get_graph_summary(graph: Any = None) -> dict:
         all_entries = engine.list_entries(limit=5000)
 
     type_dist = dict(Counter(e.entry_type.value for e in all_entries))
-    reviewed = sum(1 for e in all_entries if e.metadata.review_count > 0)
     total = len(all_entries)
+    unreviewed = stats["unreviewed_nodes"]
 
     return {
         "stats": stats,
         "type_distribution": type_dist,
         "total_nodes": total,
-        "reviewed_nodes": reviewed,
-        "unreviewed_nodes": total - reviewed,
-        "review_coverage_pct": round(100 * reviewed / total, 1) if total else 0,
+        "reviewed_nodes": total - unreviewed,
+        "unreviewed_nodes": unreviewed,
+        "review_coverage_pct": round(100 * (total - unreviewed) / total, 1) if total else 0,
     }
 
 
@@ -164,8 +164,9 @@ def distill_memory(
     """Apply one reviewed memory decision.
 
     L1/L2 create unverified capability/procedure nodes. L3/L4 create
-    heuristic/constraint nodes and require an existing L1/L2 target. Noise is
-    deleted. ``skip`` retains the memory for a later review.
+    heuristic/constraint nodes and require an existing L1/L2 target. Successful
+    distillation consumes the source memory; noise is deleted. ``skip`` retains
+    the memory for a later review.
     """
     from core import app_state
     from core.retrieval.retrieval import RetrievalEngine
@@ -278,35 +279,17 @@ def distill_memory(
             entry_type=distilled_type,
             tags=list(dict.fromkeys((tags or []) + memory.tags)),
             metadata=EntryMetadata(
-                source_provenance=f"memory:{memory_id}",
                 extraction_method="review_agent_memory_distillation",
                 refinement_status=RefinementStatus.raw,
                 verification_status=VerificationStatus.unverified,
                 skill_level=level,
                 applicability={"distillation_reason": reason} if reason else {},
-                custom={
-                    "distilled_from_memory": {
-                        "memory_id": memory_id,
-                        "session_id": memory_data.get("session_id", "default"),
-                    }
-                },
             ),
         )
         saved = entry_repo.create(distilled)
         g.add_entry(saved)
 
         created_edges = []
-        source_edge = edge_repo.create(
-            Edge(
-                source_id=memory.id,
-                target_id=saved.id,
-                relation=EdgeRelation.refinement_of,
-                metadata={"source": "review_agent_memory_distillation"},
-            )
-        )
-        g.add_edge(source_edge)
-        created_edges.append(source_edge.id)
-
         if target is not None and relation is not None:
             target_edge = edge_repo.create(
                 Edge(
@@ -327,21 +310,8 @@ def distill_memory(
                 if updated_target is not None:
                     g.add_entry(updated_target)
 
-        memory_data.update(
-            {
-                "promoted": True,
-                "promotion_target_id": saved.id,
-                "distilled_level": normalized,
-                "distillation_status": "completed",
-                "distillation_reason": reason,
-            }
-        )
-        memory.metadata.custom["memory"] = memory_data
-        memory.metadata.review_count += 1
-        memory.metadata.last_reviewed_at = datetime.now(timezone.utc)
-        updated_memory = entry_repo.update(memory)
-        if updated_memory is not None:
-            g.add_entry(updated_memory)
+        entry_repo.delete(memory.id)
+        g.remove_entry(memory.id)
 
     return {
         "memory_id": memory_id,
@@ -357,6 +327,7 @@ def distill_memory(
         },
         "target_id": target.id if target is not None else None,
         "edge_ids": created_edges,
+        "source_memory_deleted": True,
         "reason": reason,
     }
 
@@ -442,7 +413,9 @@ def mark_reviewed(entry_id: str, was_modified: bool = False, graph: Any = None)
         if was_modified:
             entry.metadata.modify_count += 1
 
-        EntryRepository(db).update(entry)
+        saved = EntryRepository(db).update(entry)
+        if saved is not None:
+            g.add_entry(saved)
 
     return {
         "entry_id": entry_id,
@@ -463,23 +436,65 @@ def update_entry(
     entry_type: str | None = None,
     tags: list[str] | None = None,
     aliases: list[str] | None = None,
+    verification_status: str | None = None,
     graph: Any = None,
 ) -> dict:
-    """Update fields on an existing entry and bump modify_count."""
-    from agents.graph_agent.tools import update_entry as _update_entry
-
-    result = _update_entry(
-        entry_id=entry_id,
-        title=title,
-        content=content,
-        entry_type=entry_type,
-        tags=tags,
-        aliases=aliases,
-        graph=graph,
-    )
-    if "error" not in result:
-        mark_reviewed(result["id"], was_modified=True, graph=graph)
-    return result
+    """Update an entry and record one modified review.
+
+    The review agent may only assign low-confidence verification states.
+    """
+    from core import app_state
+    from core.retrieval.retrieval import RetrievalEngine
+    from core.schemas.entry import EntryType, VerificationStatus
+    from core.storage.database import SessionLocal
+    from core.storage.repository import EntryRepository
+
+    allowed_statuses = {
+        VerificationStatus.unverified.value,
+        VerificationStatus.self_tested.value,
+    }
+    if verification_status is not None and verification_status not in allowed_statuses:
+        return {
+            "error": (
+                "ReviewAgent may only set verification_status to "
+                "'unverified' or 'self_tested'."
+            )
+        }
+
+    g = graph or app_state.graph
+    with SessionLocal() as db:
+        entry = RetrievalEngine(db, g).resolve_identifier(entry_id)
+        if entry is None:
+            return {"error": f"Entry '{entry_id}' not found."}
+        if title is not None:
+            entry.title = title
+        if content is not None:
+            entry.content = content
+            entry.refresh_refs()
+        if entry_type is not None:
+            entry.entry_type = EntryType(entry_type)
+        if tags is not None:
+            entry.tags = tags
+        if aliases is not None:
+            entry.aliases = aliases
+        if verification_status is not None:
+            entry.metadata.verification_status = VerificationStatus(verification_status)
+        entry.metadata.review_count += 1
+        entry.metadata.modify_count += 1
+        entry.metadata.last_reviewed_at = datetime.now(timezone.utc)
+        saved = EntryRepository(db).update(entry)
+
+    if saved is None:
+        return {"error": "Update failed."}
+    g.add_entry(saved)
+    return {
+        "id": saved.id,
+        "slug": saved.slug,
+        "title": saved.title,
+        "verification_status": saved.metadata.verification_status.value,
+        "review_count": saved.metadata.review_count,
+        "modify_count": saved.metadata.modify_count,
+    }
 
 
 def merge_entries(
@@ -588,7 +603,7 @@ REVIEW_TOOL_SCHEMAS: list[dict] = [
             "name": "mark_reviewed",
             "description": (
                 "Record that you have reviewed a node. "
-                "Must be called for every node you inspect, even if no changes were made. "
+                "Call this only when no update or merge tool recorded the review. "
                 "Set was_modified=True if you also edited the node."
             ),
             "parameters": {
@@ -606,7 +621,8 @@ REVIEW_TOOL_SCHEMAS: list[dict] = [
         "function": {
             "name": "update_entry",
             "description": (
-                "Update title, tags, aliases, content, or type of a node. "
+                "Update title, tags, aliases, content, type, or verification status of a node. "
+                "This records the node as reviewed, so do not call mark_reviewed afterward. "
                 "Use to: fix titles containing parenthetical acronyms (move acronym to aliases), "
                 "normalise tags to lowercase-hyphenated, remove redundant prefixes from titles, "
                 "or correct the entry_type."
@@ -624,6 +640,10 @@ REVIEW_TOOL_SCHEMAS: list[dict] = [
                     },
                     "tags": {"type": "array", "items": {"type": "string"}},
                     "aliases": {"type": "array", "items": {"type": "string"}},
+                    "verification_status": {
+                        "type": "string",
+                        "enum": ["unverified", "self_tested"],
+                    },
                 },
                 "required": ["entry_id"],
             },

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/api/routes/graph.py

@@ -60,6 +60,7 @@ def get_full_graph() -> dict:
     """Return all nodes and edges in the graph."""
     g = _graph._g
     return {
+        "metadata": dict(g.graph),
         "nodes": [{"id": n, **d} for n, d in g.nodes(data=True)],
         "edges": [
             {"source": u, "target": v, **d}

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/core/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.3'
-__version_tuple__ = version_tuple = (0, 1, 3)
+__version__ = version = '0.1.4'
+__version_tuple__ = version_tuple = (0, 1, 4)
 
 __commit_id__ = commit_id = None

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/core/graph/graph.py

@@ -21,6 +21,7 @@ class KnowDoGraph:
 
     def __init__(self) -> None:
         self._g: nx.DiGraph = nx.DiGraph()
+        self._g.graph["unreviewed_nodes"] = 0
 
     # ------------------------------------------------------------------
     # Nodes
@@ -28,6 +29,15 @@ class KnowDoGraph:
 
     def add_entry(self, entry: Entry) -> None:
         md = entry.metadata
+        existed = self._g.has_node(entry.id)
+        was_unreviewed = (
+            existed and self._g.nodes[entry.id].get("review_count", 0) == 0
+        )
+        is_unreviewed = md.review_count == 0
+        if not existed and is_unreviewed:
+            self._g.graph["unreviewed_nodes"] += 1
+        elif existed and was_unreviewed != is_unreviewed:
+            self._g.graph["unreviewed_nodes"] += 1 if is_unreviewed else -1
         timestamp = md.timestamp.isoformat() if getattr(md, "timestamp", None) else None
         verification = (
             md.verification_status.value
@@ -49,11 +59,14 @@ class KnowDoGraph:
             usage_count=md.usage_count,
             trust_score=md.trust_score,
             verification_status=verification,
+            review_count=md.review_count,
             skill_level=level_value,
         )
 
     def remove_entry(self, entry_id: str) -> None:
         if self._g.has_node(entry_id):
+            if self._g.nodes[entry_id].get("review_count", 0) == 0:
+                self._g.graph["unreviewed_nodes"] -= 1
             self._g.remove_node(entry_id)
 
     # ------------------------------------------------------------------
@@ -193,6 +206,7 @@ class KnowDoGraph:
             "nodes": self._g.number_of_nodes(),
             "edges": self._g.number_of_edges(),
             "is_dag": nx.is_directed_acyclic_graph(self._g),
+            "unreviewed_nodes": self._g.graph["unreviewed_nodes"],
         }
 
     def rebuild_from_db(self, entries: list[Entry], edges: list[Edge]) -> None:
@@ -204,6 +218,7 @@ class KnowDoGraph:
         are never allowed to materialise ghost nodes in the in-memory graph.
         """
         self._g.clear()
+        self._g.graph["unreviewed_nodes"] = 0
         for entry in entries:
             self.add_entry(entry)
         skipped = 0

{know_do_graph-0.1.3 → know_do_graph-0.1.4}/core/storage/repository.py

@@ -89,6 +89,10 @@ class EntryRepository:
     def create(self, entry: Entry) -> Entry:
         from core.storage.models import EntryModel
 
+        # A newly-created node always starts with no review history.
+        entry.metadata.review_count = 0
+        entry.metadata.modify_count = 0
+        entry.metadata.last_reviewed_at = None
         slug = _unique_slug(self._db, entry.slug or _slug(entry.title), entry.id)
         model = EntryModel(
             id=entry.id,