graph-engine-memory 0.6.1__py3-none-any.whl

graph_engine/access.py

@@ -0,0 +1,202 @@
+"""Opt-in application access control for trusted CLI/MCP and bearer-auth HTTP.
+
+The OS account, policy file and Python caller remain trusted. This does not
+sandbox Python or encrypt a brain against someone who can read its files.
+"""
+from __future__ import annotations
+
+from contextvars import ContextVar
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from .brain import Brain, Edge, Node
+
+request_principal: ContextVar[str | None] = ContextVar("ig_principal", default=None)
+
+
+def policy_path() -> str:
+    return os.environ.get("IG_ACCESS_POLICY", "")
+
+
+def load_policy() -> dict:
+    try:
+        data = json.loads(Path(policy_path()).expanduser().read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or not isinstance(data.get("graphs"), dict):
+            raise ValueError("missing graphs object")
+        for config in data["graphs"].values():
+            if not isinstance(config, dict) or not isinstance(config.get("roles"), dict):
+                raise ValueError("missing roles object")
+            if any(r not in ("admin", "editor", "viewer") for r in config["roles"].values()):
+                raise ValueError("unknown role")
+            for acl in config.get("nodes", {}).values():
+                if not isinstance(acl, dict) or set(acl) - {"read", "write"}:
+                    raise ValueError("invalid node ACL")
+                if any(not isinstance(v, list) or any(not isinstance(p, str) for p in v)
+                       for v in acl.values()):
+                    raise ValueError("ACL must contain principal lists")
+        return data
+    except (OSError, ValueError, TypeError, AttributeError) as exc:
+        raise PermissionError("Access policy unavailable or invalid") from exc
+
+
+def principal() -> str:
+    return request_principal.get() if request_principal.get() is not None else os.environ.get("IG_PRINCIPAL", "")
+
+
+def token_principal(authorization: str) -> str:
+    if not authorization.startswith("Bearer "):
+        raise PermissionError("Bearer authentication required")
+    digest = hashlib.sha256(authorization[7:].encode()).hexdigest()
+    identity = load_policy().get("tokens", {}).get(digest)
+    if not isinstance(identity, str) or not identity:
+        raise PermissionError("Invalid bearer token")
+    return identity
+
+
+def audit(graph: str, identity: str, action: str, allowed: bool,
+          node_id: str | None = None) -> None:
+    # A separate file beside the trusted policy avoids exporting security logs
+    # with a brain git push. Failure to append fails the operation closed.
+    row = {"ts": datetime.now(timezone.utc).isoformat(), "principal": identity,
+           "graph": graph, "action": action, "allowed": allowed, "node_id": node_id}
+    path = Path(policy_path()).expanduser().with_suffix(".audit.jsonl")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    with os.fdopen(fd, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def permitted(graph: str, identity: str, action: str, node_id: str | None = None) -> bool:
+    policy = load_policy()
+    config = policy["graphs"].get(graph, {})
+    role = config.get("roles", {}).get(identity)
+    if not identity or role not in ("admin", "editor", "viewer"):
+        return False
+    if role == "admin":
+        return True
+    if action == "admin" or (action == "write" and role != "editor"):
+        return False
+    if action not in ("read", "write"):
+        return False
+    acl = config.get("nodes", {}).get(node_id, {})
+    readers = acl.get("read")
+    if readers is not None and identity not in readers and "*" not in readers:
+        return False
+    users = acl.get(action)
+    return users is None or identity in users or "*" in users
+
+
+def require(graph: str, identity: str, action: str, node_id: str | None = None) -> None:
+    allowed = permitted(graph, identity, action, node_id)
+    audit(graph, identity, action, allowed, node_id)
+    if not allowed:
+        raise PermissionError("Access denied")
+
+
+class SecuredBrain(Brain):
+    """Filter reads and authorize mutations at the shared storage boundary."""
+
+    def __init__(self, *args, graph_name: str, identity: str, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.graph_name, self.identity = graph_name, identity
+        self._raw = Brain(str(self.path), self.remote, self.mode)
+        self.authorize("read")
+
+    def authorize(self, action: str, node_id: str | None = None) -> None:
+        require(self.graph_name, self.identity, action, node_id)
+
+    def can_access(self, action: str, node_id: str | None = None) -> bool:
+        return permitted(self.graph_name, self.identity, action, node_id)
+
+    def read_nodes(self) -> list[Node]:
+        self.authorize("read")
+        return [n for n in self._raw.read_nodes() if self.can_access("read", n.id)]
+
+    def read_node(self, node_id: str) -> Node | None:
+        self.authorize("read", node_id)
+        return self._raw.read_node(node_id)
+
+    def write_node(self, node: Node) -> None:
+        self.authorize("write", node.id)
+        self._raw.write_node(node)
+
+    def _edge_allowed(self, edge: Edge, action: str) -> bool:
+        # Evidence is embedded text: hiding only the endpoints would leak it.
+        ids = [edge.source, edge.target] + [e.get("node_id") for e in edge.evidence]
+        return all(isinstance(nid, str) and self.can_access(action, nid) for nid in ids)
+
+    def read_edges(self, include_rejected: bool = False) -> list[Edge]:
+        self.authorize("read")
+        return [e for e in self._raw.read_edges(include_rejected) if self._edge_allowed(e, "read")]
+
+    def write_edges(self, edges: list[Edge]) -> None:
+        self.authorize("write")
+        with self._lock:
+            old = {e.id: e for e in self._raw.read_edges(include_rejected=True)}
+            new = {e.id: e for e in edges}
+            for eid in old.keys() | new.keys():
+                before, after = old.get(eid), new.get(eid)
+                if before and after and before.to_dict() == after.to_dict():
+                    continue
+                if before and after is None and not self._edge_allowed(before, "read"):
+                    new[eid] = before  # bulk rewrites must preserve hidden records
+                    continue
+                for edge in (before, after):
+                    if edge is not None and not self._edge_allowed(edge, "write"):
+                        audit(self.graph_name, self.identity, "write_edge", False)
+                        raise PermissionError("Access denied")
+            self._raw.write_edges(list(new.values()))
+
+    def read_vectors(self) -> dict[str, list[float]]:
+        self.authorize("read")
+        return {nid: v for nid, v in self._raw.read_vectors().items() if self.can_access("read", nid)}
+
+    def write_vectors(self, vectors: dict[str, list[float]]) -> None:
+        self.authorize("write")
+        old = self._raw.read_vectors()
+        for nid, vector in vectors.items():
+            if old.get(nid) != vector:
+                self.authorize("write", nid)
+        # Preserve vectors outside the caller's view, including node ACLs.
+        preserved = {nid: v for nid, v in old.items() if not self.can_access("read", nid)}
+        for nid in old.keys() - vectors.keys() - preserved.keys():
+            self.authorize("write", nid)
+        self._raw.write_vectors({**preserved, **vectors})
+
+    def vectors_for(self, node_ids: set[str], embed_fn, batch_fn=None,
+                    persist: bool = True) -> dict[str, list[float]]:
+        # Do not use the global unscoped memo or persist search side effects.
+        nodes = {n.id: n for n in self.read_nodes() if n.id in node_ids}
+        cached = self.read_vectors()
+        missing = sorted(nodes.keys() - cached.keys())
+        values = batch_fn([nodes[n].text for n in missing]) if batch_fn and missing else [embed_fn(nodes[n].text) for n in missing]
+        cached.update(zip(missing, values))
+        return {nid: cached[nid] for nid in nodes if nid in cached}
+
+    def ensure_ready(self) -> None:
+        self.authorize("write")
+        self._raw.ensure_ready()
+
+    def init(self, remote: str | None = None, commit: bool = True) -> None:
+        self.authorize("admin")
+        self._raw.init(remote, commit)
+
+    def clone_if_missing(self) -> None:
+        self.authorize("admin")
+        self._raw.clone_if_missing()
+
+    def pull(self) -> None:
+        self.authorize("write")
+        self._raw.pull()
+
+    def commit_and_push(self, message: str, push: bool = True) -> None:
+        self.authorize("write")
+        self._raw.commit_and_push(message, push)
+
+    def rebuild_index(self) -> None:
+        self.authorize("write")
+        # Generate complete internal derived state, not a filtered INDEX that
+        # would erase other users' entries. INDEX is never served by HTTP/MCP.
+        self._raw.rebuild_index()

graph_engine/agent_memory.py

@@ -0,0 +1,103 @@
+"""The agent-facing write path (Welle C): remember / recall / forget.
+
+The engine had a human write path (`ig ingest`, `ig link`) and a strictly
+read-only MCP surface. An agent that CONSULTS the brain should also be able to
+LEAVE something in it — under its own provenance, never destructively, and only
+when the operator opts in (`ig mcp --write`).
+
+Provenance is the whole point (Welle A): agent-written nodes carry
+`source="agent"` and agent-declared edges `origin="agent"`, so "what did a model
+put in here, and what did it connect?" stays a query instead of a guess.
+
+Never destructive (the house rule): `forget` tombstones the node — it leaves
+every live view (`retrieve`, `graph`, `hygiene`) but stays in the file, and its
+edges are invalidated instead of deleted, so the audit trail survives.
+"""
+from __future__ import annotations
+
+from .brain import Brain, Edge, Node, _now_iso
+from .brain_engine import BrainEngine
+
+AGENT_SOURCE = "agent"          # node provenance: a model wrote this
+AGENT_ORIGIN = "agent"          # edge provenance: a model declared this
+FORGET_STATUS = "tombstone"     # never delete — hide from live views
+
+
+def remember(engine: BrainEngine, text: str, *, tags: list[str] | None = None,
+             ntype: str = "semantic",
+             relations: list[tuple[str, str]] | None = None,
+             allow_duplicates: bool = False) -> dict:
+    """Write one note on an agent's behalf.
+
+    Dedupe-aware (a near-duplicate merges into the existing node instead of
+    creating a second one) and provenance-marked: the node carries
+    `source="agent"`, declared relations carry `origin="agent"`. Commits once
+    (that is `ingest`'s own commit), so an agent write is one history entry.
+    """
+    if not (text or "").strip():
+        raise ValueError("Empty text cannot be remembered.")
+    node, edges, is_dup = engine.ingest(
+        text, source=AGENT_SOURCE, tags=tags, ntype=ntype,
+        relations=relations, allow_duplicates=allow_duplicates,
+        edge_origin=AGENT_ORIGIN)
+    agent_edges = [e for e in edges if e.origin == AGENT_ORIGIN]
+    return {"node_id": node.id, "duplicate": is_dup, "edges": len(edges),
+            "agent_edges": len(agent_edges), "status": node.status,
+            "origin": AGENT_ORIGIN, "written": not is_dup}
+
+
+def recall(engine: BrainEngine, query: str, k: int = 5, *,
+           persist: bool = False) -> list[tuple[str, float]]:
+    """A search that COUNTS AS USE.
+
+    Agent recalls feed the promotion signal (`recall_count`), so a memory the
+    agent actually relied on can later be promoted by the dream pass.
+    `search_brain` stays the side-effect-free variant for exploration.
+    """
+    from .retrieval import retrieve
+    return retrieve(engine, query, k=k, track=True, persist=persist)
+
+
+def forget(brain: Brain, node_id: str, *, reason: str,
+           commit: bool = True, push: bool = True) -> dict:
+    """Hide a node from every live view — without deleting it.
+
+    Sets `status="tombstone"` (out of `retrieve`, `graph`, `hygiene` — the file
+    and its history stay) and invalidates every undecided/live edge touching it, in ONE
+    commit. `reason` is mandatory and lands in the commit message: the record of
+    WHY must survive with the decision. Idempotent: forgetting a tombstone again
+    is a no-op, not an error.
+    """
+    reason = (reason or "").strip()
+    if not reason:
+        raise ValueError("forget requires a reason — it lands in the commit message.")
+    brain.authorize("write", node_id)
+    node = brain.read_node(node_id)
+    if node is None:
+        raise ValueError(f"No node with id {node_id!r}.")
+    if node.status == FORGET_STATUS:
+        return {"node_id": node_id, "status": FORGET_STATUS, "edges_invalidated": 0,
+                "forgotten": False, "already": True, "reason": reason}
+
+    now = _now_iso()
+    edges = brain.read_edges(include_rejected=True)
+    invalidated = 0
+    for e in edges:
+        if not e.is_invalidated and not e.rejected and node_id in (e.source, e.target):
+            # Check every affected record before writing the tombstone. A
+            # readable edge can connect to a node the caller cannot modify.
+            for affected in [e.source, e.target, *(item.get("node_id") for item in e.evidence)]:
+                brain.authorize("write", affected)
+            e.invalidate(now)        # Also invalidate scheduled/expired extracted facts.
+            invalidated += 1
+    node.status = FORGET_STATUS
+    brain.write_node(node)
+    brain.write_edges(edges)
+    brain.rebuild_index()
+    if commit:
+        brain.commit_and_push(
+            f"agent forget: {node_id} — {reason} "
+            f"({invalidated} edge(s) invalidated, node tombstoned)", push=push)
+    return {"node_id": node_id, "status": FORGET_STATUS,
+            "edges_invalidated": invalidated, "forgotten": True,
+            "already": False, "reason": reason, "text": (node.text or "")[:120]}