dig-client 0.1.0.dev4__tar.gz

dig_client-0.1.0.dev4/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

dig_client-0.1.0.dev4/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: dig-client
+Version: 0.1.0.dev4
+Summary: Python client for a local dig daemon — search, organize, reconcile, and export a knowledge base over HTTP.
+Project-URL: Homepage, https://dig.vllnt.com
+Project-URL: Repository, https://github.com/vllnt/dig
+Author: vllnt
+License-Expression: MIT
+Keywords: ai-agents,dig,knowledge-base,memory,rag,retrieval
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dig-client
+
+Python client for a local [dig](https://github.com/vllnt/dig) daemon — search,
+organize, reconcile, and export a knowledge base over HTTP. Dependency-free
+(standard library only), local-first.
+
+## Install
+
+```sh
+pip install dig-client
+```
+
+Start a daemon next to your KB (dig binary from https://dig.vllnt.com):
+
+```sh
+dig serve            # binds 127.0.0.1:3978 (loopback only)
+```
+
+## Use
+
+```python
+from dig_client import DigClient
+
+dig = DigClient()  # http://127.0.0.1:3978
+
+# search — fts (default), vector, or hybrid (semantic)
+hits = dig.find("invoice acme 2024", mode="hybrid", limit=5)
+
+# agent memory — capture, then recall a token-budgeted pack
+dig.retain(session_markdown, as_="memory/sessions/today.md")
+pack = dig.recall("billing ledger decision", budget=1000)
+
+# reorganize by policy — preview, then apply (reversible)
+dig.org(apply=False)   # preview the plan
+dig.org(apply=True)    # commit it
+dig.undo()             # step back
+
+# reproducible dataset export (JSONL text)
+jsonl = dig.export(filter="label:finance")
+
+# read-only inspection
+dig.drift()
+dig.log()
+```
+
+Target a specific KB with `kb="/path/or/name"` on any call; omit it to use the
+KB at the daemon's working directory. Errors raise `DigError` carrying the HTTP
+status.
+
+The client speaks the same contract as `dig serve`, a thin adapter over the dig
+CLI — so it never drifts from the tool.

dig_client-0.1.0.dev4/README.md

@@ -0,0 +1,51 @@
+# dig-client
+
+Python client for a local [dig](https://github.com/vllnt/dig) daemon — search,
+organize, reconcile, and export a knowledge base over HTTP. Dependency-free
+(standard library only), local-first.
+
+## Install
+
+```sh
+pip install dig-client
+```
+
+Start a daemon next to your KB (dig binary from https://dig.vllnt.com):
+
+```sh
+dig serve            # binds 127.0.0.1:3978 (loopback only)
+```
+
+## Use
+
+```python
+from dig_client import DigClient
+
+dig = DigClient()  # http://127.0.0.1:3978
+
+# search — fts (default), vector, or hybrid (semantic)
+hits = dig.find("invoice acme 2024", mode="hybrid", limit=5)
+
+# agent memory — capture, then recall a token-budgeted pack
+dig.retain(session_markdown, as_="memory/sessions/today.md")
+pack = dig.recall("billing ledger decision", budget=1000)
+
+# reorganize by policy — preview, then apply (reversible)
+dig.org(apply=False)   # preview the plan
+dig.org(apply=True)    # commit it
+dig.undo()             # step back
+
+# reproducible dataset export (JSONL text)
+jsonl = dig.export(filter="label:finance")
+
+# read-only inspection
+dig.drift()
+dig.log()
+```
+
+Target a specific KB with `kb="/path/or/name"` on any call; omit it to use the
+KB at the daemon's working directory. Errors raise `DigError` carrying the HTTP
+status.
+
+The client speaks the same contract as `dig serve`, a thin adapter over the dig
+CLI — so it never drifts from the tool.

dig_client-0.1.0.dev4/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dig-client"
+version = "0.1.0.dev4"
+description = "Python client for a local dig daemon — search, organize, reconcile, and export a knowledge base over HTTP."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["dig", "knowledge-base", "retrieval", "memory", "ai-agents", "rag"]
+authors = [{ name = "vllnt" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://dig.vllnt.com"
+Repository = "https://github.com/vllnt/dig"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dig_client"]

dig_client-0.1.0.dev4/src/dig_client/__init__.py

@@ -0,0 +1,153 @@
+"""dig-client — a dependency-free Python client for a local dig daemon (`dig serve`).
+
+Drives the same surface as the CLI over HTTP: search, drift, history, export
+(read) and organize / reconcile / undo (mutations, preview-by-default).
+Local-first: it talks only to the loopback daemon you run.
+
+Example:
+    from dig_client import DigClient
+
+    dig = DigClient()  # http://127.0.0.1:3978
+    hits = dig.find("invoice acme", mode="hybrid", limit=5)
+    dig.org(apply=True)   # commit a reorg (reversible)
+    dig.undo()
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["DigClient", "DigError"]
+
+DEFAULT_BASE_URL = "http://127.0.0.1:3978"
+
+
+class DigError(Exception):
+    """Raised when the daemon returns a non-2xx response."""
+
+    def __init__(self, message: str, status: int) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class DigClient:
+    """Client for a local dig daemon."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: float = 120.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def health(self) -> dict[str, Any]:
+        """Liveness + daemon version."""
+        return self._request("GET", "/health", {})
+
+    def find(
+        self,
+        query: str,
+        kb: str | None = None,
+        mode: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Search the KB, ranked. ``mode`` is fts (default), vector, or hybrid."""
+        return self._request(
+            "GET", "/find", {"kb": kb, "query": query, "mode": mode, "limit": limit}
+        )
+
+    def recall(
+        self,
+        query: str,
+        kb: str | None = None,
+        mode: str | None = None,
+        budget: int | None = None,
+    ) -> dict[str, Any]:
+        """Load a token-budgeted, provenance-tagged context pack for ``query``.
+
+        The agent-memory recall primitive: snippets land on the matching passage.
+        ``budget`` caps the pack in tokens; ``mode`` is fts (default), vector, or
+        hybrid.
+        """
+        return self._request(
+            "GET", "/recall", {"kb": kb, "query": query, "mode": mode, "budget": budget}
+        )
+
+    def retain(
+        self, content: str, kb: str | None = None, as_: str | None = None
+    ) -> Any:
+        """Capture ``content`` into the KB and index it — the capture primitive.
+
+        Writes to a dated ``memory/`` path by default; pass ``as_`` to choose the
+        path. Reversible with :meth:`undo`.
+        """
+        return self._request(
+            "POST", "/retain", {"kb": kb, "as": as_}, data=content.encode("utf-8")
+        )
+
+    def drift(self, kb: str | None = None) -> Any:
+        """Report how the KB diverges from its policy. Read-only."""
+        return self._request("GET", "/drift", {"kb": kb})
+
+    def log(self, kb: str | None = None) -> Any:
+        """Browse change history, newest first. Read-only."""
+        return self._request("GET", "/log", {"kb": kb})
+
+    def export(
+        self, kb: str | None = None, filter: str | None = None, at: str | None = None
+    ) -> str:
+        """Export a reproducible, provenance-tagged dataset (JSONL text). Read-only."""
+        body = self._request("GET", "/export", {"kb": kb, "filter": filter, "at": at})
+        if isinstance(body, dict):
+            return str(body.get("output", ""))
+        return ""
+
+    def org(self, kb: str | None = None, apply: bool = False) -> Any:
+        """Apply organization policy. Previews unless ``apply`` is True (reversible)."""
+        return self._request("POST", "/org", {"kb": kb, "apply": apply})
+
+    def reconcile(self, kb: str | None = None, apply: bool = False) -> Any:
+        """Converge the KB to policy. Previews unless ``apply`` is True (reversible)."""
+        return self._request("POST", "/reconcile", {"kb": kb, "apply": apply})
+
+    def undo(self, kb: str | None = None) -> Any:
+        """Revert the last changeset."""
+        return self._request("POST", "/undo", {"kb": kb})
+
+    def _request(
+        self, method: str, path: str, params: dict[str, Any], data: bytes | None = None
+    ) -> Any:
+        query = {k: _str(v) for k, v in params.items() if v is not None}
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        req = urllib.request.Request(url, data=data, method=method)  # noqa: S310 (loopback only)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310
+                return _parse(resp.read())
+        except urllib.error.HTTPError as exc:
+            body = exc.read()
+            raise DigError(_error(body) or exc.reason, exc.code) from None
+
+
+def _str(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _parse(raw: bytes) -> Any:
+    if not raw:
+        return None
+    return json.loads(raw.decode("utf-8"))
+
+
+def _error(raw: bytes) -> str | None:
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if isinstance(body, dict) and "error" in body:
+        return str(body["error"])
+    return None

dig_client-0.1.0.dev4/tests/test_client.py

@@ -0,0 +1,119 @@
+"""Integration tests: the SDK drives a REAL `dig serve` against a real temp KB —
+no mocks. The dig binary comes from $DIG_BIN (CI builds it) or `dig` on PATH.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from dig_client import DigClient, DigError  # noqa: E402
+
+DIG = os.environ.get("DIG_BIN", "dig")
+PORT = 3986
+POLICY = """
+[[rule]]
+name  = "invoices"
+match = { ext = ["pdf"], content_matches = "invoice" }
+into  = "finance/invoices"
+label = ["finance"]
+"""
+
+
+def _dig(*args: str) -> None:
+    result = subprocess.run([DIG, *args], capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(f"dig {' '.join(args)} failed: {result.stderr or result.stdout}")
+
+
+class TestDigClient(unittest.TestCase):
+    daemon: subprocess.Popen[bytes]
+    kb: str
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.kb = tempfile.mkdtemp(prefix="dig-py-")
+        inbox = Path(cls.kb) / "inbox"
+        inbox.mkdir(parents=True, exist_ok=True)
+        (inbox / "acme.pdf").write_text("ACME invoice #1007")
+        (inbox / "todo.md").write_text("- [ ] things")
+        _dig("init", cls.kb)
+        (Path(cls.kb) / ".dig" / "policy.toml").write_text(POLICY)
+        _dig("--kb", cls.kb, "scan")
+
+        cls.daemon = subprocess.Popen(
+            [DIG, "serve", "--addr", f"127.0.0.1:{PORT}"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        client = DigClient(base_url=f"http://127.0.0.1:{PORT}")
+        for _ in range(50):
+            try:
+                client.health()
+                break
+            except Exception:  # noqa: BLE001
+                time.sleep(0.1)
+        else:
+            raise RuntimeError("daemon never became healthy")
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.daemon.terminate()
+        cls.daemon.wait(timeout=5)
+
+    def client(self) -> DigClient:
+        return DigClient(base_url=f"http://127.0.0.1:{PORT}")
+
+    def test_health(self) -> None:
+        h = self.client().health()
+        self.assertEqual(h["status"], "ok")
+        self.assertTrue(h["version"])
+
+    def test_find(self) -> None:
+        hits = self.client().find("invoice", kb=self.kb)
+        self.assertTrue(any(h["Path"].endswith("acme.pdf") for h in hits))
+
+    def test_org_preview_apply_undo(self) -> None:
+        moved = lambda: (Path(self.kb) / "finance" / "invoices" / "acme.pdf").exists()  # noqa: E731
+
+        self.client().org(kb=self.kb)  # preview
+        self.assertFalse(moved(), "preview must not move files")
+
+        self.client().org(kb=self.kb, apply=True)
+        self.assertTrue(moved(), "apply must move the file")
+
+        self.client().undo(kb=self.kb)
+        self.assertFalse(moved(), "undo must revert")
+
+    def test_log_and_drift(self) -> None:
+        self.assertIsNotNone(self.client().log(kb=self.kb))
+        self.assertIsNotNone(self.client().drift(kb=self.kb))
+
+    def test_retain_then_recall(self) -> None:
+        fact = "Decision: adopt the new ledger in Q3; Dana owns the migration."
+        retained = self.client().retain(fact, kb=self.kb, as_="memory/py.md")
+        self.assertIn("Retained memory/py.md", retained["output"])
+
+        pack = self.client().recall("ledger migration Dana", kb=self.kb, budget=400)
+        self.assertEqual(pack["budgetTokens"], 400)
+        self.assertTrue(pack["manifest"])
+        self.assertTrue(
+            any("new ledger in Q3" in item["content"] for item in pack["items"]),
+            "recall should surface the retained fact",
+        )
+
+    def test_error_path(self) -> None:
+        with self.assertRaises(DigError) as ctx:
+            self.client().find("anything", kb="/no/such/kb")
+        self.assertGreaterEqual(ctx.exception.status, 400)
+
+
+if __name__ == "__main__":
+    unittest.main()