dig-client 0.1.0.dev4__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+dig_client/__init__.py,sha256=bZ0DnzBVYF1AzJwwkxHWzdRk1vljV0TTGOnwJ61cNGM,5295
+dig_client-0.1.0.dev4.dist-info/METADATA,sha256=LJlXd0lDSSrgmLWjl_cqcLW4p2YqwgAJ-b3VtrOVLxI,1836
+dig_client-0.1.0.dev4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+dig_client-0.1.0.dev4.dist-info/RECORD,,

dig_client-0.1.0.dev4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any