nomem 0.1.0__py3-none-any.whl

nomem/__init__.py

@@ -0,0 +1,86 @@
+"""nomem — No One's Memory Management.
+
+Persistent, self-updating, per-user memory for LLM applications, structured as a
+bi-temporal knowledge graph with an explicit LLM-powered CRUD interface.
+
+    from nomem import MemoryGraph
+
+    graph = MemoryGraph(user_id="u123", backend="sqlite", embedder="nomic")
+    graph.ingest(user="...", assistant="...")
+    result = graph.retrieve("Kira")
+
+Storage, embedding, and extraction are adapter boundaries: SQLite (zero infra),
+PostgreSQL/pgvector, and Neo4j all pass one identical behavioral contract suite,
+the nomic (Ollama) and OpenAI embedders both talk plain HTTP with no extra
+dependency, and any piece can be replaced with your own class or a bare callable.
+Every method has an ``a``-prefixed async twin; the sync API is a thin wrapper over
+the async core.
+
+Capability is extended through the ``nomem.plugins`` entry point rather than by
+subclassing or forking — see ``docs/stability.md`` for what ``>=0.1,<0.2``
+guarantees.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .config import DecayConfig, IngestConfig, MemoryGraphConfig, RetrievalConfig
+from .exceptions import (
+    BackendError,
+    ConfigError,
+    EdgeNotFoundError,
+    EmbedderError,
+    ExtractionError,
+    NodeNotFoundError,
+    NomemError,
+    NotSupportedError,
+    RetrievalBudgetExceededError,
+)
+from .graph import MemoryGraph
+from .models import (
+    DecayResult,
+    Edge,
+    ExtractedEntity,
+    ExtractedRelation,
+    IngestReceipt,
+    Node,
+    PurgeResult,
+    ResolutionOutcome,
+    SubGraph,
+)
+from .plugins import Plugin
+
+try:
+    __version__ = _pkg_version("nomem")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "BackendError",
+    "ConfigError",
+    "DecayConfig",
+    "DecayResult",
+    "Edge",
+    "EdgeNotFoundError",
+    "EmbedderError",
+    "ExtractedEntity",
+    "ExtractedRelation",
+    "ExtractionError",
+    "IngestConfig",
+    "IngestReceipt",
+    "MemoryGraph",
+    "MemoryGraphConfig",
+    "Node",
+    "NodeNotFoundError",
+    "NomemError",
+    "NotSupportedError",
+    "Plugin",
+    "PurgeResult",
+    "ResolutionOutcome",
+    "RetrievalBudgetExceededError",
+    "RetrievalConfig",
+    "SubGraph",
+    "__version__",
+]

nomem/_http.py

@@ -0,0 +1,63 @@
+"""Minimal async JSON-over-HTTP helper (stdlib only).
+
+The default embedder and LLM adapters talk to a local Ollama. nomem's core has
+no third-party runtime dependencies, so this wraps :mod:`urllib.request` and
+offloads the blocking call to a worker thread.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+class HTTPError(RuntimeError):
+    """A non-2xx response or a transport-level failure."""
+
+
+def _post_json_sync(
+    url: str,
+    payload: dict[str, Any],
+    timeout: float,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json", **(headers or {})},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = resp.read()
+    except urllib.error.HTTPError as exc:  # pragma: no cover - network dependent
+        detail = exc.read().decode("utf-8", "replace")
+        raise HTTPError(f"POST {url} -> {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:  # pragma: no cover - network dependent
+        raise HTTPError(f"POST {url} failed: {exc.reason}") from exc
+    try:
+        parsed = json.loads(body)
+    except json.JSONDecodeError as exc:  # pragma: no cover - defensive
+        raise HTTPError(f"POST {url} returned non-JSON body") from exc
+    if not isinstance(parsed, dict):
+        raise HTTPError(f"POST {url} returned a JSON {type(parsed).__name__}, expected an object")
+    return parsed
+
+
+async def post_json(
+    url: str,
+    payload: dict[str, Any],
+    *,
+    timeout: float = 60.0,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """POST ``payload`` as JSON to ``url`` and return the decoded JSON response.
+
+    ``headers`` are merged over the default ``Content-Type`` — that is how the
+    OpenAI embedder passes its ``Authorization``.
+    """
+    return await asyncio.to_thread(_post_json_sync, url, payload, timeout, headers)

nomem/_vector.py

@@ -0,0 +1,58 @@
+"""Vector helpers (stdlib only).
+
+Embeddings are stored as packed 32-bit floats; similarity is computed in Python.
+Fine at SQLite/dev scale — the Postgres and Neo4j backends push this into the
+database.
+"""
+
+from __future__ import annotations
+
+import math
+from array import array
+
+from .models import Vector
+
+_TYPECODE = "f"
+
+
+def pack(vec: Vector) -> bytes:
+    """Pack a float vector into a compact ``bytes`` blob."""
+    return array(_TYPECODE, vec).tobytes()
+
+
+def unpack(blob: bytes) -> Vector:
+    """Reverse :func:`pack`."""
+    out = array(_TYPECODE)
+    out.frombytes(blob)
+    return list(out)
+
+
+def mean(vectors: list[Vector]) -> Vector:
+    """Component-wise mean of equal-length vectors; ``[]`` if the input is empty."""
+    usable = [v for v in vectors if v]
+    if not usable:
+        return []
+    dim = len(usable[0])
+    acc = [0.0] * dim
+    for vec in usable:
+        if len(vec) != dim:
+            continue
+        for i, x in enumerate(vec):
+            acc[i] += x
+    return [x / len(usable) for x in acc]
+
+
+def cosine(a: Vector, b: Vector) -> float:
+    """Cosine similarity in ``[-1, 1]``; ``0.0`` if either vector is empty/zero."""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = 0.0
+    na = 0.0
+    nb = 0.0
+    for x, y in zip(a, b, strict=True):
+        dot += x * y
+        na += x * x
+        nb += y * y
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (math.sqrt(na) * math.sqrt(nb))

nomem/backends/__init__.py

@@ -0,0 +1,49 @@
+"""Backend adapters and the name -> class registry."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..exceptions import ConfigError
+from .base import BaseBackend
+from .neo4j import Neo4jBackend
+from .postgres import PostgresBackend
+from .sqlite import SQLiteBackend
+
+BACKEND_REGISTRY: dict[str, type[BaseBackend]] = {
+    "sqlite": SQLiteBackend,
+    "postgres": PostgresBackend,
+    "neo4j": Neo4jBackend,
+}
+
+
+def resolve_backend(
+    backend: str | BaseBackend,
+    options: dict[str, Any] | None = None,
+) -> BaseBackend:
+    """Turn a config value into a live backend.
+
+    ``backend`` may be a registered name (``"sqlite"``) or an already-built
+    :class:`BaseBackend` instance (which is returned as-is).
+    """
+    if isinstance(backend, BaseBackend):
+        return backend
+    if not isinstance(backend, str):
+        raise ConfigError(f"backend must be a name or a BaseBackend, got {type(backend)!r}")
+    try:
+        cls = BACKEND_REGISTRY[backend]
+    except KeyError:
+        raise ConfigError(
+            f"unknown backend {backend!r}; known: {sorted(BACKEND_REGISTRY)}"
+        ) from None
+    return cls(**(options or {}))
+
+
+__all__ = [
+    "BACKEND_REGISTRY",
+    "BaseBackend",
+    "Neo4jBackend",
+    "PostgresBackend",
+    "SQLiteBackend",
+    "resolve_backend",
+]

nomem/backends/_common.py

@@ -0,0 +1,78 @@
+"""Helpers shared by the concrete backends.
+
+Keeps bi-temporal filtering and graph traversal identical across adapters, so
+switching backends never changes what a query returns.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from ..models import Edge, Node, SubGraph
+
+
+def now_utc() -> datetime:
+    return datetime.now(tz=UTC)
+
+
+def iso(dt: datetime) -> str:
+    """Serialize a datetime as a UTC ISO-8601 string (lexically comparable)."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC).isoformat()
+
+
+def parse_ts(value: str | datetime | None) -> datetime | None:
+    if value is None or isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(value)
+
+
+def aware(dt: datetime) -> datetime:
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=UTC)
+
+
+def active_at(record: Node | Edge, as_of: datetime) -> bool:
+    """True if ``record`` was recorded by ``as_of`` and its window contains it."""
+    as_of = aware(as_of)
+    if aware(record.created_at) > as_of or aware(record.valid_from) > as_of:
+        return False
+    return record.valid_to is None or aware(record.valid_to) > as_of
+
+
+def bfs_subgraph(
+    nodes_by_id: dict[str, Node],
+    edges: list[Edge],
+    seed_ids: list[str],
+    hops: int,
+) -> SubGraph:
+    """Expand ``hops`` undirected edge-steps out from ``seed_ids``.
+
+    ``nodes_by_id`` / ``edges`` must already be filtered to the visible set
+    (active-only, or ``as_of`` a timestamp).
+    """
+    frontier = {sid for sid in seed_ids if sid in nodes_by_id}
+    visited = set(frontier)
+    kept_edges: dict[str, Edge] = {}
+
+    for _ in range(max(hops, 0)):
+        next_frontier: set[str] = set()
+        for edge in edges:
+            if edge.source_id in frontier and edge.target_id in nodes_by_id:
+                kept_edges[edge.id] = edge
+                if edge.target_id not in visited:
+                    next_frontier.add(edge.target_id)
+            if edge.target_id in frontier and edge.source_id in nodes_by_id:
+                kept_edges[edge.id] = edge
+                if edge.source_id not in visited:
+                    next_frontier.add(edge.source_id)
+        if not next_frontier:
+            break
+        visited |= next_frontier
+        frontier = next_frontier
+
+    return SubGraph(
+        nodes=[nodes_by_id[nid] for nid in visited if nid in nodes_by_id],
+        edges=list(kept_edges.values()),
+        metadata={"hops": max(hops, 0), "seed_node_ids": list(seed_ids)},
+    )

nomem/backends/base.py

@@ -0,0 +1,135 @@
+"""Backend adapter interface.
+
+Any object implementing :class:`BaseBackend` is a valid nomem storage backend —
+devs can write their own. Storage is an adapter boundary: swapping a backend
+touches nothing else (AGENT.md "Backend and embedder agnosticism").
+
+Contract notes that apply to every implementation:
+
+* **Bi-temporal, no hard delete.** ``retire_node`` / ``retire_edge`` set
+  ``valid_to = now`` and, when given, ``superseded_by``. Records are never
+  removed.
+* **``as_of`` honesty.** ``get_node`` and ``traverse`` with ``as_of=`` must
+  return the graph as it was *known* at that instant.
+* **User scoping.** Every record carries ``user_id``; a backend instance must
+  never leak rows across users.
+* **Async.** Every method is a coroutine. Blocking drivers must be run in a
+  thread/executor by the adapter.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from ..config import DecayConfig
+from ..exceptions import NotSupportedError
+from ..models import DecayResult, Edge, Node, PurgeResult, SubGraph, Vector
+
+
+class BaseBackend(ABC):
+    """Abstract storage adapter. See module docstring for the shared contract."""
+
+    @abstractmethod
+    async def create_node(self, node: Node) -> Node:
+        """Persist a new node and return the stored record."""
+
+    @abstractmethod
+    async def update_node(self, node_id: str, updates: dict[str, Any]) -> Node:
+        """Apply a partial update to an active node and return the new record."""
+
+    @abstractmethod
+    async def retire_node(self, node_id: str, superseded_by: str | None = None) -> Node:
+        """Retire a node: set ``valid_to = now`` (+ ``superseded_by``). Never delete."""
+
+    @abstractmethod
+    async def get_node(self, node_id: str, as_of: datetime | None = None) -> Node | None:
+        """Return a node as known at ``as_of`` (or now), or ``None`` if absent."""
+
+    @abstractmethod
+    async def upsert_edge(self, edge: Edge) -> Edge:
+        """Create the edge, or bump ``weight`` / metadata if an active one exists."""
+
+    @abstractmethod
+    async def retire_edge(self, edge_id: str, superseded_by: str | None = None) -> Edge:
+        """Retire an edge: set ``valid_to = now`` (+ ``superseded_by``). Never delete."""
+
+    @abstractmethod
+    async def get_edge(self, edge_id: str, as_of: datetime | None = None) -> Edge | None:
+        """Return an edge as known at ``as_of`` (or now), or ``None`` if absent.
+
+        The node-side counterpart is :meth:`get_node`; the temporal rule is the
+        same one :func:`nomem.backends._common.active_at` implements.
+        """
+
+    @abstractmethod
+    async def vector_search(self, embedding: Vector, top_k: int) -> list[Node]:
+        """Return the ``top_k`` active nodes most similar to ``embedding``."""
+
+    @abstractmethod
+    async def list_nodes(
+        self,
+        *,
+        active_only: bool = True,
+        context: list[str] | None = None,
+        as_of: datetime | None = None,
+    ) -> list[Node]:
+        """Enumerate this user's nodes.
+
+        ``context`` keeps only nodes whose ``metadata["context"]`` intersects the
+        given tags. ``as_of`` applies the same temporal filter as ``get_node``.
+        Used by hierarchical retrieval and by callers that need the whole set.
+        """
+
+    @abstractmethod
+    async def list_edges(
+        self,
+        *,
+        active_only: bool = True,
+        as_of: datetime | None = None,
+    ) -> list[Edge]:
+        """Enumerate this user's edges.
+
+        ``as_of`` applies the same temporal filter as :meth:`get_edge` and takes
+        precedence over ``active_only``; ``active_only=False`` without ``as_of``
+        returns every edge on record, retired ones included. Enumeration — not
+        seed-based :meth:`traverse` — is what a full graph dump needs to
+        round-trip retired records.
+        """
+
+    @abstractmethod
+    async def traverse(
+        self, seed_ids: list[str], hops: int, as_of: datetime | None = None
+    ) -> SubGraph:
+        """Expand ``hops`` edges out from ``seed_ids``; honor ``as_of`` if given."""
+
+    @abstractmethod
+    async def cross_reference(self, node: Node, threshold: float) -> list[tuple[Node, float]]:
+        """Return active nodes whose similarity to ``node`` is >= ``threshold``."""
+
+    @abstractmethod
+    async def run_decay(self, config: DecayConfig) -> DecayResult:
+        """Run one decay/pruning pass over this user's nodes per ``config``."""
+
+    # --- the one hard-delete path ----------------------------------
+
+    async def purge_user(self, user_id: str) -> PurgeResult:
+        """Really delete every row for ``user_id``. **Not** part of retirement.
+
+        This is the single exception to "nomem never hard-deletes", and it
+        exists so GDPR right-to-forget can be built as a plugin instead of a
+        fork. It is deliberately fenced:
+
+        * it is **not abstract** — a custom backend may leave this default body,
+          which raises :class:`~nomem.exceptions.NotSupportedError`;
+        * implementations must raise :class:`~nomem.exceptions.BackendError`
+          unless ``user_id`` matches the backend's own user;
+        * it is **unreachable from** :class:`nomem.MemoryGraph` and
+          ``GraphCRUD``, and a guard test asserts it stays that way. A backend
+          handle is not the public API.
+        """
+        raise NotSupportedError(
+            f"{type(self).__name__} does not implement purge_user; "
+            "nomem retires records via valid_to and never hard-deletes"
+        )