erubus 0.2.0__tar.gz

erubus-0.2.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: erubus
+Version: 0.2.0
+Summary: Client for Erubus — temporal knowledge graph for AI agents and robots
+Author: Ashraf Galib Shaik
+License: MIT
+Project-URL: Homepage, https://github.com/AshrafGalibShaik/Erubus
+Project-URL: Source, https://github.com/AshrafGalibShaik/Erubus
+Project-URL: Issues, https://github.com/AshrafGalibShaik/Erubus/issues
+Keywords: knowledge-graph,temporal,robotics,agents,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# erubus (Python client)
+
+Stdlib-only client for [Erubus](https://github.com/AshrafGalibShaik/Erubus), a
+temporal knowledge graph for AI agents and robots. No dependencies.
+
+```bash
+pip install -e .          # or just copy erubus.py next to your code
+erubus serve &            # the Rust binary, anywhere on your PATH
+python test_erubus.py     # smoke test against it
+```
+
+```python
+from erubus import Erubus
+
+kg = Erubus()                                  # http://127.0.0.1:8080
+# Auth / namespace (optional; when set, sent on every request):
+# kg = Erubus(token="abc123", ns="prod")       # Authorization: Bearer …, X-Erubus-Ns: …
+
+kg.set_decay("vision:", half_life_secs=5)      # sensor beliefs go stale
+kg.assert_fact("pallet-7", "at", "bay-3", confidence=0.9, source="vision:cam1")
+
+kg.value_at("pallet-7", "at")
+# {'value': 'bay-3', 'effective_confidence': 0.87, 'server_time': ...}
+
+# What did the robot believe when it decided, not what was true:
+kg.value_at("pallet-7", "at", t=20.0, known_at=decision_wall_clock)
+
+kg.merge("bay 3", "Bay-03")                    # same entity, two spellings
+kg.suggest_merge(q="bay 3")                    # fuzzy candidates (does not merge)
+kg.context("pallet-7", depth=2)                # everything reachable, as of now
+
+kg.set_schema("located_in", functional=True)   # schema registry
+kg.get_schema()                                # {"relations": [...]}
+kg.retention(86400)                            # drop closed edges older than 1d
+kg.backup("/tmp/erubus.db")                    # consistent snapshot → local file
+
+for fact in kg.watch("pallet-7", reconnect=True):   # live SSE stream
+    print(fact)
+```
+
+High-rate sensors should batch — one HTTP round-trip per fact is what makes a
+30Hz loop expensive:
+
+```python
+with kg.batch(max_size=256) as b:              # flushes at max_size and on exit
+    for det in detections:
+        b.add(det.id, "at", det.bay, confidence=det.score, source="vision:cam1")
+```
+
+Batches are all-or-nothing: if any fact is invalid (e.g. a clock-skewed
+timestamp) the server rejects the whole batch and nothing lands, so retrying is
+safe.
+
+All times are **UTC epoch seconds** — `time.time()` is already correct. Omit
+`t` and the server stamps it. Writes with a timestamp far in the future are
+rejected; call `kg.clock_skew()` to check your clock against the server's.

erubus-0.2.0/README.md

@@ -0,0 +1,56 @@
+# erubus (Python client)
+
+Stdlib-only client for [Erubus](https://github.com/AshrafGalibShaik/Erubus), a
+temporal knowledge graph for AI agents and robots. No dependencies.
+
+```bash
+pip install -e .          # or just copy erubus.py next to your code
+erubus serve &            # the Rust binary, anywhere on your PATH
+python test_erubus.py     # smoke test against it
+```
+
+```python
+from erubus import Erubus
+
+kg = Erubus()                                  # http://127.0.0.1:8080
+# Auth / namespace (optional; when set, sent on every request):
+# kg = Erubus(token="abc123", ns="prod")       # Authorization: Bearer …, X-Erubus-Ns: …
+
+kg.set_decay("vision:", half_life_secs=5)      # sensor beliefs go stale
+kg.assert_fact("pallet-7", "at", "bay-3", confidence=0.9, source="vision:cam1")
+
+kg.value_at("pallet-7", "at")
+# {'value': 'bay-3', 'effective_confidence': 0.87, 'server_time': ...}
+
+# What did the robot believe when it decided, not what was true:
+kg.value_at("pallet-7", "at", t=20.0, known_at=decision_wall_clock)
+
+kg.merge("bay 3", "Bay-03")                    # same entity, two spellings
+kg.suggest_merge(q="bay 3")                    # fuzzy candidates (does not merge)
+kg.context("pallet-7", depth=2)                # everything reachable, as of now
+
+kg.set_schema("located_in", functional=True)   # schema registry
+kg.get_schema()                                # {"relations": [...]}
+kg.retention(86400)                            # drop closed edges older than 1d
+kg.backup("/tmp/erubus.db")                    # consistent snapshot → local file
+
+for fact in kg.watch("pallet-7", reconnect=True):   # live SSE stream
+    print(fact)
+```
+
+High-rate sensors should batch — one HTTP round-trip per fact is what makes a
+30Hz loop expensive:
+
+```python
+with kg.batch(max_size=256) as b:              # flushes at max_size and on exit
+    for det in detections:
+        b.add(det.id, "at", det.bay, confidence=det.score, source="vision:cam1")
+```
+
+Batches are all-or-nothing: if any fact is invalid (e.g. a clock-skewed
+timestamp) the server rejects the whole batch and nothing lands, so retrying is
+safe.
+
+All times are **UTC epoch seconds** — `time.time()` is already correct. Omit
+`t` and the server stamps it. Writes with a timestamp far in the future are
+rejected; call `kg.clock_skew()` to check your clock against the server's.

erubus-0.2.0/erubus.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: erubus
+Version: 0.2.0
+Summary: Client for Erubus — temporal knowledge graph for AI agents and robots
+Author: Ashraf Galib Shaik
+License: MIT
+Project-URL: Homepage, https://github.com/AshrafGalibShaik/Erubus
+Project-URL: Source, https://github.com/AshrafGalibShaik/Erubus
+Project-URL: Issues, https://github.com/AshrafGalibShaik/Erubus/issues
+Keywords: knowledge-graph,temporal,robotics,agents,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# erubus (Python client)
+
+Stdlib-only client for [Erubus](https://github.com/AshrafGalibShaik/Erubus), a
+temporal knowledge graph for AI agents and robots. No dependencies.
+
+```bash
+pip install -e .          # or just copy erubus.py next to your code
+erubus serve &            # the Rust binary, anywhere on your PATH
+python test_erubus.py     # smoke test against it
+```
+
+```python
+from erubus import Erubus
+
+kg = Erubus()                                  # http://127.0.0.1:8080
+# Auth / namespace (optional; when set, sent on every request):
+# kg = Erubus(token="abc123", ns="prod")       # Authorization: Bearer …, X-Erubus-Ns: …
+
+kg.set_decay("vision:", half_life_secs=5)      # sensor beliefs go stale
+kg.assert_fact("pallet-7", "at", "bay-3", confidence=0.9, source="vision:cam1")
+
+kg.value_at("pallet-7", "at")
+# {'value': 'bay-3', 'effective_confidence': 0.87, 'server_time': ...}
+
+# What did the robot believe when it decided, not what was true:
+kg.value_at("pallet-7", "at", t=20.0, known_at=decision_wall_clock)
+
+kg.merge("bay 3", "Bay-03")                    # same entity, two spellings
+kg.suggest_merge(q="bay 3")                    # fuzzy candidates (does not merge)
+kg.context("pallet-7", depth=2)                # everything reachable, as of now
+
+kg.set_schema("located_in", functional=True)   # schema registry
+kg.get_schema()                                # {"relations": [...]}
+kg.retention(86400)                            # drop closed edges older than 1d
+kg.backup("/tmp/erubus.db")                    # consistent snapshot → local file
+
+for fact in kg.watch("pallet-7", reconnect=True):   # live SSE stream
+    print(fact)
+```
+
+High-rate sensors should batch — one HTTP round-trip per fact is what makes a
+30Hz loop expensive:
+
+```python
+with kg.batch(max_size=256) as b:              # flushes at max_size and on exit
+    for det in detections:
+        b.add(det.id, "at", det.bay, confidence=det.score, source="vision:cam1")
+```
+
+Batches are all-or-nothing: if any fact is invalid (e.g. a clock-skewed
+timestamp) the server rejects the whole batch and nothing lands, so retrying is
+safe.
+
+All times are **UTC epoch seconds** — `time.time()` is already correct. Omit
+`t` and the server stamps it. Writes with a timestamp far in the future are
+rejected; call `kg.clock_skew()` to check your clock against the server's.

erubus-0.2.0/erubus.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+erubus.py
+pyproject.toml
+erubus.egg-info/PKG-INFO
+erubus.egg-info/SOURCES.txt
+erubus.egg-info/dependency_links.txt
+erubus.egg-info/top_level.txt

erubus-0.2.0/erubus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

erubus-0.2.0/erubus.egg-info/top_level.txt

@@ -0,0 +1 @@
+erubus

erubus-0.2.0/erubus.py

@@ -0,0 +1,270 @@
+"""Erubus client — temporal knowledge graph for agents and robots.
+
+Stdlib only, no dependencies. All times are UTC UNIX epoch seconds; `time.time()`
+is already correct, so pass nothing and the server stamps `now`.
+
+    from erubus import Erubus
+    kg = Erubus()
+    kg.assert_fact("pallet-7", "at", "bay-3", confidence=0.9, source="vision:cam1")
+    kg.value_at("pallet-7", "at")            # -> {"value": "bay-3", "effective_confidence": 0.87, ...}
+    for fact in kg.watch("pallet-7"):        # blocking SSE stream
+        print(fact)
+"""
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__all__ = ["Erubus", "Batch", "ErubusError"]
+
+
+class ErubusError(RuntimeError):
+    """Server rejected the request (e.g. clock skew, bad params)."""
+
+
+class Erubus:
+    def __init__(self, url="http://127.0.0.1:8080", timeout=10.0, token=None, ns=None):
+        """`token` → Authorization: Bearer; `ns` → X-Erubus-Ns on every request."""
+        self.url = url.rstrip("/")
+        self.timeout = timeout
+        self.token = token
+        self.ns = ns
+
+    # -- internals ---------------------------------------------------------
+    def _auth_headers(self):
+        headers = {}
+        if self.token is not None:
+            headers["Authorization"] = "Bearer %s" % self.token
+        if self.ns is not None:
+            headers["X-Erubus-Ns"] = self.ns
+        return headers
+
+    def _raise_http(self, path, e):
+        detail = e.read().decode(errors="replace")
+        try:
+            detail = json.loads(detail).get("error", detail)
+        except ValueError:
+            pass
+        raise ErubusError("%s %s: %s" % (e.code, path, detail)) from None
+
+    def _request(self, method, path, params=None, body=None, timeout=None):
+        target = self.url + path
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                target += "?" + urllib.parse.urlencode(clean)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(target, data=data, method=method)
+        for k, v in self._auth_headers().items():
+            req.add_header(k, v)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as r:
+                return json.loads(r.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            self._raise_http(path, e)
+
+    # -- writes ------------------------------------------------------------
+    def assert_fact(self, subject, rel, obj, confidence=1.0, source="python", t=None):
+        """Record `subject --rel--> obj`. `t` defaults to server-side now (UTC)."""
+        body = {
+            "subject": subject,
+            "rel": rel,
+            "object": obj,
+            "confidence": confidence,
+            "source": source,
+        }
+        if t is not None:
+            body["t"] = float(t)
+        return self._request("POST", "/fact", body=body)
+
+    def assert_facts(self, facts):
+        """Record many facts in one request. Returns the accepted count.
+
+        `facts` is an iterable of dicts (`subject`/`rel`/`object` required;
+        `confidence`, `source`, `t` optional) or 3-tuples. All-or-nothing: if
+        any element is invalid the whole batch is rejected and nothing lands,
+        so retrying is safe.
+        """
+        body = []
+        for f in facts:
+            if isinstance(f, dict):
+                item = dict(f)
+            else:
+                subject, rel, obj = f
+                item = {"subject": subject, "rel": rel, "object": obj}
+            item.setdefault("confidence", 1.0)
+            item.setdefault("source", "python")
+            body.append(item)
+        return self._request("POST", "/facts", body=body).get("accepted", 0)
+
+    def batch(self, max_size=256):
+        """Buffered writer for high-rate sensors. Use as a context manager:
+
+            with kg.batch() as b:
+                for det in detections:
+                    b.add(det.id, "at", det.bay, confidence=det.score)
+        """
+        return Batch(self, max_size)
+
+    def merge(self, alias, canonical):
+        """Declare `alias` and `canonical` the same entity; rewrites history."""
+        return self._request("POST", "/merge", body={"alias": alias, "canonical": canonical})
+
+    def set_decay(self, source_prefix, half_life_secs):
+        """Beliefs from sources matching `source_prefix` lose half their
+        confidence every `half_life_secs` since last observation."""
+        return self._request(
+            "POST", "/decay",
+            body={"source_prefix": source_prefix, "half_life_secs": float(half_life_secs)},
+        )
+
+    def set_schema(self, rel, functional=False):
+        """Register (or upsert) relation `rel` in the schema registry."""
+        return self._request(
+            "POST", "/schema",
+            body={"rel": rel, "functional": bool(functional)},
+        )
+
+    def retention(self, older_than_secs):
+        """Delete closed edges older than `older_than_secs` (server minimum 1h)."""
+        return self._request(
+            "POST", "/retention",
+            body={"older_than_secs": float(older_than_secs)},
+        )
+
+    # -- reads -------------------------------------------------------------
+    def value_at(self, subject, rel, t=None, known_at=None):
+        """What we believe(d) `subject --rel--> ?` at valid time `t`.
+
+        `known_at` restricts to facts learned by then — "what did the robot
+        believe at the moment it decided", as distinct from what was true.
+        """
+        return self._request("GET", "/value", params={
+            "subject": subject, "rel": rel, "t": t, "known_at": known_at,
+        })
+
+    def context(self, root, depth=2, t=None):
+        """Everything reachable from `root` within `depth` hops, as of `t`."""
+        return self._request("GET", "/context", params={"root": root, "depth": depth, "t": t})
+
+    def get_schema(self):
+        """List registered relations (`{"relations": [{"rel", "functional"}, ...]}`)."""
+        return self._request("GET", "/schema")
+
+    def suggest_merge(self, q=None):
+        """Fuzzy merge candidates (suggestions only — does not merge).
+
+        Returns a list of dicts with `canonical_guess` and `members`. Optional
+        `q` restricts to the normalized form of that entity id.
+        """
+        return self._request("GET", "/suggest_merge", params={"q": q}).get("suggestions", [])
+
+    def backup(self, dest_path):
+        """Stream a consistent DB snapshot (`GET /backup`) to `dest_path`.
+
+        Returns the number of bytes written.
+        """
+        target = self.url + "/backup"
+        req = urllib.request.Request(target, method="GET")
+        for k, v in self._auth_headers().items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                written = 0
+                with open(dest_path, "wb") as f:
+                    while True:
+                        chunk = r.read(65536)
+                        if not chunk:
+                            break
+                        f.write(chunk)
+                        written += len(chunk)
+                return written
+        except urllib.error.HTTPError as e:
+            self._raise_http("/backup", e)
+
+    def health(self):
+        return self._request("GET", "/health")
+
+    def clock_skew(self):
+        """Seconds this client's clock is ahead of the server's. Writes whose
+        `t` exceeds the server's skew window are rejected, so check this if
+        `assert_fact` raises about future timestamps."""
+        return time.time() - float(self.health()["server_time"])
+
+    # -- streaming ---------------------------------------------------------
+    def watch(self, subject=None, timeout=None, reconnect=False, retry_secs=1.0):
+        """Yield facts as they are ingested. Blocking generator over SSE.
+
+        `subject=None` streams everything. With `reconnect=True` the stream is
+        re-established after a dropped connection; facts produced while
+        disconnected are missed, so re-read state with `context()` on resume if
+        you need a consistent view.
+        """
+        while True:
+            try:
+                yield from self._watch_once(subject, timeout)
+            except (urllib.error.URLError, ConnectionError, TimeoutError):
+                if not reconnect:
+                    raise
+            if not reconnect:
+                return
+            time.sleep(retry_secs)
+
+    def _watch_once(self, subject, timeout):
+        target = self.url + "/watch"
+        if subject is not None:
+            target += "?" + urllib.parse.urlencode({"subject": subject})
+        headers = {"Accept": "text/event-stream"}
+        headers.update(self._auth_headers())
+        req = urllib.request.Request(target, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                for raw in r:
+                    line = raw.decode(errors="replace").strip()
+                    if line.startswith("data:"):
+                        payload = line[5:].strip()
+                        if payload:
+                            yield json.loads(payload)
+        except urllib.error.HTTPError as e:
+            self._raise_http("/watch", e)
+
+
+class Batch:
+    """Accumulates facts and flushes them in one request.
+
+    Auto-flushes at `max_size`; flushes on exit. A 30Hz sensor writing one fact
+    per HTTP round-trip is bound by network latency — batching is what makes
+    that workload cheap.
+    """
+
+    def __init__(self, client, max_size=256):
+        self.client = client
+        self.max_size = max_size
+        self.pending = []
+
+    def add(self, subject, rel, obj, confidence=1.0, source="python", t=None):
+        item = {"subject": subject, "rel": rel, "object": obj,
+                "confidence": confidence, "source": source}
+        if t is not None:
+            item["t"] = float(t)
+        self.pending.append(item)
+        if len(self.pending) >= self.max_size:
+            return self.flush()
+        return 0
+
+    def flush(self):
+        if not self.pending:
+            return 0
+        batch, self.pending = self.pending, []
+        return self.client.assert_facts(batch)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.flush()
+        return False

erubus-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "erubus"
+version = "0.2.0"
+description = "Client for Erubus — temporal knowledge graph for AI agents and robots"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Ashraf Galib Shaik" }]
+keywords = ["knowledge-graph", "temporal", "robotics", "agents", "memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/AshrafGalibShaik/Erubus"
+Source = "https://github.com/AshrafGalibShaik/Erubus"
+Issues = "https://github.com/AshrafGalibShaik/Erubus/issues"
+
+[tool.setuptools]
+py-modules = ["erubus"]

erubus-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+