know-do-graph 0.1.6__tar.gz → 0.1.7__tar.gz

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: know-do-graph
-Version: 0.1.6
+Version: 0.1.7
 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
@@ -17,7 +17,7 @@ Requires-Dist: rich>=13.0
 Requires-Dist: sentence-transformers>=2.7
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: sqlite-vec>=0.1.6
-Requires-Dist: typer[all]
+Requires-Dist: typer>=0.24.1
 Requires-Dist: uvicorn[standard]
 Description-Content-Type: text/markdown
 
@@ -84,6 +84,16 @@ graph.connect(skill.id, procedure.id, relation=EdgeRelation.decomposes_to)
 planner_context = graph.plan("relax this crystal")
 execution_context = graph.expand(skill.slug, stages=["decomposition"])
 
+selected = planner_context[0]
+attached = graph.count_attached(selected.id)
+if attached["heuristics"]:
+    heuristics, total = graph.search_attached(
+        selected.id,
+        kind="heuristics",
+        query="force convergence",
+        mode="hybrid",
+    )
+
 memory = graph.memory("run-42")
 first = memory.add(
     "FIRE converged at fmax=0.03.",
@@ -96,10 +106,13 @@ graph.close()
 ```
 
 The main methods are `add`, `get`, `list`, `search`, `update`, `delete`,
-`connect`, `related`, `plan`, `heuristics`, `constraints`, `expand`, and
-`memory`. IDs, slugs, and aliases are accepted anywhere an entry identifier is
-required. Each client owns its database engine, so multiple graph databases can
-be used safely in the same process.
+`connect`, `related`, `plan`, `heuristics`, `constraints`, `count_attached`,
+`search_attached`, `expand`, and `memory`. IDs, slugs, and aliases are accepted
+anywhere an entry identifier is required. `count_attached()` and
+`search_attached()` provide embedded clients the same scoped L3/L4 progressive
+retrieval as `GET /remote/entry/{id}`, `/heuristics`, and `/constraints`.
+Each client owns its database engine, so multiple graph databases can be used
+safely in the same process.
 
 ### Python chat API
 
@@ -573,7 +586,9 @@ curl http://<host>:<port>/remote
 | `POST` | `/remote/chat` | Chat with the orchestrator agent (read-only; agents and humans) |
 | `GET` | `/remote/search` | Search entries (`?q=&tags=&entry_type=&limit=`) |
 | `GET` | `/remote/graph` | Graph stats + full node/edge dump |
-| `GET` | `/remote/entry/{id}` | Entry by ID, slug, or alias |
+| `GET` | `/remote/entry/{id}` | Entry by ID, slug, or alias, including attached L3/L4 counts |
+| `GET` | `/remote/entry/{id}/heuristics` | Query-filtered L3 heuristics attached to one entry |
+| `GET` | `/remote/entry/{id}/constraints` | Query-filtered L4 constraints attached to one entry |
 | `GET` | `/remote/entry/{id}/related` | Related entries via BFS (`?depth=1&relation=`) |
 | `POST` | `/remote/feedback` | Free-form feedback trace; optionally also updates an entry's verification (pass `entry_id` + `verdict`) |
 | `POST` | `/entries/{id}/feedback` | Direct per-entry verification feedback |

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/README.md

@@ -61,6 +61,16 @@ graph.connect(skill.id, procedure.id, relation=EdgeRelation.decomposes_to)
 planner_context = graph.plan("relax this crystal")
 execution_context = graph.expand(skill.slug, stages=["decomposition"])
 
+selected = planner_context[0]
+attached = graph.count_attached(selected.id)
+if attached["heuristics"]:
+    heuristics, total = graph.search_attached(
+        selected.id,
+        kind="heuristics",
+        query="force convergence",
+        mode="hybrid",
+    )
+
 memory = graph.memory("run-42")
 first = memory.add(
     "FIRE converged at fmax=0.03.",
@@ -73,10 +83,13 @@ graph.close()
 ```
 
 The main methods are `add`, `get`, `list`, `search`, `update`, `delete`,
-`connect`, `related`, `plan`, `heuristics`, `constraints`, `expand`, and
-`memory`. IDs, slugs, and aliases are accepted anywhere an entry identifier is
-required. Each client owns its database engine, so multiple graph databases can
-be used safely in the same process.
+`connect`, `related`, `plan`, `heuristics`, `constraints`, `count_attached`,
+`search_attached`, `expand`, and `memory`. IDs, slugs, and aliases are accepted
+anywhere an entry identifier is required. `count_attached()` and
+`search_attached()` provide embedded clients the same scoped L3/L4 progressive
+retrieval as `GET /remote/entry/{id}`, `/heuristics`, and `/constraints`.
+Each client owns its database engine, so multiple graph databases can be used
+safely in the same process.
 
 ### Python chat API
 
@@ -550,7 +563,9 @@ curl http://<host>:<port>/remote
 | `POST` | `/remote/chat` | Chat with the orchestrator agent (read-only; agents and humans) |
 | `GET` | `/remote/search` | Search entries (`?q=&tags=&entry_type=&limit=`) |
 | `GET` | `/remote/graph` | Graph stats + full node/edge dump |
-| `GET` | `/remote/entry/{id}` | Entry by ID, slug, or alias |
+| `GET` | `/remote/entry/{id}` | Entry by ID, slug, or alias, including attached L3/L4 counts |
+| `GET` | `/remote/entry/{id}/heuristics` | Query-filtered L3 heuristics attached to one entry |
+| `GET` | `/remote/entry/{id}/constraints` | Query-filtered L4 constraints attached to one entry |
 | `GET` | `/remote/entry/{id}/related` | Related entries via BFS (`?depth=1&relation=`) |
 | `POST` | `/remote/feedback` | Free-form feedback trace; optionally also updates an entry's verification (pass `entry_id` + `verdict`) |
 | `POST` | `/entries/{id}/feedback` | Direct per-entry verification feedback |

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/core/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.6'
-__version_tuple__ = version_tuple = (0, 1, 6)
+__version__ = version = '0.1.7'
+__version_tuple__ = version_tuple = (0, 1, 7)
 
 __commit_id__ = commit_id = None

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/examples/python_api.py

@@ -17,14 +17,35 @@ def main() -> None:
             content="Attach a calculator and run an ASE optimizer.",
             tags=["atomistic", "execution"],
         )
+        heuristic = graph.add(
+            "Prefer FIRE for noisy forces",
+            entry_type=EntryType.heuristic,
+            content="FIRE is often robust when force convergence is noisy.",
+            tags=["atomistic", "optimizer"],
+        )
         graph.connect(
             capability.id,
             procedure.id,
             relation=EdgeRelation.decomposes_to,
         )
+        graph.connect(
+            heuristic.id,
+            capability.id,
+            relation=EdgeRelation.heuristic_for,
+        )
 
         candidates = graph.plan("relax this crystal")
-        context = graph.expand(capability.slug, stages=["decomposition"])
+        selected = candidates[0]
+        attached = graph.count_attached(selected.id)
+        sidecars = []
+        if attached["heuristics"]:
+            sidecars, total = graph.search_attached(
+                selected.id,
+                kind="heuristics",
+                query="force convergence",
+            )
+            print(f"Showing {len(sidecars)} of {total} attached heuristics")
+
         graph.memory("run-42").add(
             "Relaxation converged with FIRE at fmax=0.03.",
             tags=["success"],
@@ -32,7 +53,7 @@ def main() -> None:
         )
 
         print([entry.title for entry in candidates])
-        print(context)
+        print([entry.title for entry in sidecars])
 
 
 if __name__ == "__main__":

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/know_do_graph/client.py

@@ -244,6 +244,32 @@ class KnowDoGraph:
         with self._session() as db:
             return ProgressiveRetriever(db, self._graph).constraints_for(skill, k=limit)
 
+    def count_attached(self, skill: str) -> dict:
+        """Count L3/L4 nodes directly attached to an L1/L2 entry."""
+        with self._session() as db:
+            return ProgressiveRetriever(db, self._graph).count_attached(skill)
+
+    def search_attached(
+        self,
+        skill: str,
+        *,
+        kind: str,
+        query: str | None = None,
+        tags: list[str] | None = None,
+        limit: int = 10,
+        mode: str = "hybrid",
+    ) -> tuple[list[Entry], int]:
+        """Search heuristics or constraints attached to one selected entry."""
+        with self._session() as db:
+            return ProgressiveRetriever(db, self._graph).search_attached(
+                skill=skill,
+                kind=kind,
+                query=query,
+                tags=tags,
+                limit=limit,
+                mode=mode,
+            )
+
     def expand(
         self,
         skill: str,

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
     "networkx>=3.0",
     "fastapi>=0.100",
     "uvicorn[standard]",
-    "typer[all]",
+    "typer>=0.24.1",
     "sqlalchemy>=2.0",
     "rich>=13.0",
     "pyyaml>=6.0",

{know_do_graph-0.1.6 → know_do_graph-0.1.7}/tests/test_public_api.py

@@ -89,6 +89,97 @@ class PublicApiTests(unittest.TestCase):
         self.assertEqual(edge.relation, EdgeRelation.related_memory)
         self.assertEqual(memory.edges(trace.id)[0].target_id, follow_up.id)
 
+    def test_attached_counts_and_scoped_search(self) -> None:
+        selected = self.graph.add(
+            "Relax Crystal",
+            content="Relax an atomic crystal structure.",
+            entry_type=EntryType.capability,
+        )
+        other = self.graph.add(
+            "Build Interface",
+            content="Build an atomistic interface.",
+            entry_type=EntryType.capability,
+        )
+        popular = self.graph.add(
+            "Prefer FIRE",
+            content="FIRE handles noisy force convergence.",
+            entry_type=EntryType.heuristic,
+            tags=["optimizer"],
+            metadata=EntryMetadata(usage_count=8),
+        )
+        strain = self.graph.add(
+            "Reduce strain first",
+            content="Reduce lattice strain before relaxation.",
+            entry_type=EntryType.heuristic,
+            tags=["stability"],
+            metadata=EntryMetadata(usage_count=2),
+        )
+        unrelated = self.graph.add(
+            "Interface strain guidance",
+            content="Reduce lattice strain when building an interface.",
+            entry_type=EntryType.heuristic,
+            tags=["stability"],
+        )
+        hard_limit = self.graph.add(
+            "Force threshold limit",
+            content="Do not use loose force thresholds.",
+            entry_type=EntryType.constraint,
+        )
+        warning = self.graph.add(
+            "Unstable cell warning",
+            content="Variable-cell relaxation can become unstable.",
+            entry_type=EntryType.constraint,
+        )
+
+        for sidecar, relation in (
+            (popular, EdgeRelation.heuristic_for),
+            (strain, EdgeRelation.heuristic_for),
+            (hard_limit, EdgeRelation.constraint_on),
+            (warning, EdgeRelation.warning_about),
+        ):
+            self.graph.connect(sidecar.id, selected.id, relation=relation)
+        self.graph.connect(
+            unrelated.id,
+            other.id,
+            relation=EdgeRelation.heuristic_for,
+        )
+
+        self.assertEqual(
+            self.graph.count_attached(selected.slug),
+            {
+                "resolved": True,
+                "anchor_id": selected.id,
+                "heuristics": 2,
+                "constraints": 2,
+            },
+        )
+
+        usage_ranked, total = self.graph.search_attached(
+            selected.id,
+            kind="heuristics",
+            limit=1,
+        )
+        self.assertEqual([entry.id for entry in usage_ranked], [popular.id])
+        self.assertEqual(total, 2)
+
+        filtered, total = self.graph.search_attached(
+            selected.slug,
+            kind="heuristics",
+            query="strain",
+            tags=["stability"],
+            mode="keyword",
+        )
+        self.assertEqual([entry.id for entry in filtered], [strain.id])
+        self.assertEqual(total, 2)
+        self.assertNotIn(unrelated.id, {entry.id for entry in filtered})
+
+        constraints, total = self.graph.search_attached(
+            selected.id,
+            kind="constraints",
+        )
+        self.assertEqual({entry.id for entry in constraints}, {hard_limit.id, warning.id})
+        self.assertEqual(total, 2)
+
     def test_clients_are_isolated_by_database_path(self) -> None:
         other_path = Path(self.temp_dir.name) / "other.db"
         with KnowDoGraph(other_path) as other: