memex-python 0.13.0__py3-none-any.whl

memex/errors.py

@@ -0,0 +1,51 @@
+"""Domain errors for the memory graph.
+
+Score-bound violations surface as ``pydantic.ValidationError`` (see D2/D7 in
+PLAN.md); ``cost_fn`` contract violations surface as ``ValueError``. The typed
+exceptions below mirror the named error classes thrown by the reducer layer in
+the TypeScript library. Intent/Task graphs add their own typed errors in their
+respective modules.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "MemexError",
+    "MemoryNotFoundError",
+    "EdgeNotFoundError",
+    "DuplicateMemoryError",
+    "DuplicateEdgeError",
+    "InvalidTimestampError",
+]
+
+
+class MemexError(Exception):
+    """Base class for all memex domain errors."""
+
+
+class MemoryNotFoundError(MemexError):
+    def __init__(self, item_id: str) -> None:
+        super().__init__(f"Memory item not found: {item_id}")
+        self.item_id = item_id
+
+
+class EdgeNotFoundError(MemexError):
+    def __init__(self, edge_id: str) -> None:
+        super().__init__(f"Edge not found: {edge_id}")
+        self.edge_id = edge_id
+
+
+class DuplicateMemoryError(MemexError):
+    def __init__(self, item_id: str) -> None:
+        super().__init__(f"Memory item already exists: {item_id}")
+        self.item_id = item_id
+
+
+class DuplicateEdgeError(MemexError):
+    def __init__(self, edge_id: str) -> None:
+        super().__init__(f"Edge already exists: {edge_id}")
+        self.edge_id = edge_id
+
+
+class InvalidTimestampError(MemexError):
+    """Raised when a timestamp cannot be extracted or parsed from input."""

memex/factories.py

@@ -0,0 +1,97 @@
+"""Factories that mint ids/timestamps, mirroring ``helpers.ts``.
+
+``create_memory_item`` / ``create_edge`` validate score bounds at construction
+(via the Pydantic ``Field`` constraints on the models). ``created_at`` is
+derived from an explicit value, else the UUIDv7 timestamp, else the wall clock.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import _time
+from ._uuid import safe_extract_timestamp, uuid7
+from .models import Edge, EventEnvelope, MemoryItem
+
+__all__ = ["create_memory_item", "create_edge", "create_event_envelope"]
+
+
+def create_memory_item(
+    *,
+    scope: str,
+    kind: str,
+    content: dict[str, Any],
+    author: str,
+    source_kind: str,
+    authority: float,
+    id: str | None = None,
+    parents: list[str] | None = None,
+    conviction: float | None = None,
+    importance: float | None = None,
+    created_at: int | None = None,
+    intent_id: str | None = None,
+    task_id: str | None = None,
+    meta: dict[str, Any] | None = None,
+) -> MemoryItem:
+    item_id = id if id is not None else uuid7()
+    ts = created_at if created_at is not None else (safe_extract_timestamp(item_id) or _time.now_ms())
+    return MemoryItem(
+        id=item_id,
+        scope=scope,
+        kind=kind,
+        content=content,
+        author=author,
+        source_kind=source_kind,
+        parents=parents,
+        authority=authority,
+        conviction=conviction,
+        importance=importance,
+        created_at=ts,
+        intent_id=intent_id,
+        task_id=task_id,
+        meta=meta,
+    )
+
+
+def create_edge(
+    *,
+    from_: str,
+    to: str,
+    kind: str,
+    author: str,
+    source_kind: str,
+    authority: float,
+    edge_id: str | None = None,
+    active: bool | None = None,
+    weight: float | None = None,
+    meta: dict[str, Any] | None = None,
+) -> Edge:
+    return Edge(
+        edge_id=edge_id if edge_id is not None else uuid7(),
+        from_=from_,
+        to=to,
+        kind=kind,
+        weight=weight,
+        author=author,
+        source_kind=source_kind,
+        authority=authority,
+        active=active if active is not None else True,
+        meta=meta,
+    )
+
+
+def create_event_envelope(
+    type: str,
+    payload: Any,
+    *,
+    trace_id: str | None = None,
+    namespace: str = "memory",
+) -> EventEnvelope[Any]:
+    return EventEnvelope(
+        id=uuid7(),
+        namespace=namespace,
+        type=type,
+        ts=_time.now_iso(),
+        trace_id=trace_id,
+        payload=payload,
+    )

memex/graph.py

@@ -0,0 +1,30 @@
+"""Graph state container.
+
+``GraphState`` is a lightweight frozen dataclass holding plain dicts — NOT a
+Pydantic model (D3). The reducer clones the relevant dict on every command
+(``dict(state.items)`` mirrors the TS ``new Map(state.items)``); a validated
+model here would re-validate every item per command and be unusably slow.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .models import Edge, MemoryItem
+
+__all__ = ["GraphState", "create_graph_state", "clone_graph_state"]
+
+
+@dataclass(frozen=True, slots=True)
+class GraphState:
+    items: dict[str, MemoryItem] = field(default_factory=dict)
+    edges: dict[str, Edge] = field(default_factory=dict)
+
+
+def create_graph_state() -> GraphState:
+    return GraphState(items={}, edges={})
+
+
+def clone_graph_state(state: GraphState) -> GraphState:
+    """Shallow clone — new dicts, shared (immutable) item/edge instances."""
+    return GraphState(items=dict(state.items), edges=dict(state.edges))

memex/integrity.py

@@ -0,0 +1,317 @@
+"""Contradiction & alias integrity, stale detection, cascade retraction, budget packing."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any, NamedTuple
+
+from .commands import EdgeCreate
+from .factories import create_edge
+from .graph import GraphState
+from .models import Edge, MemoryFilter, MemoryItem, MemoryLifecycleEvent, ScoredItem, ScoreWeights
+from .query import get_children, get_edges, get_scored_items
+from .reducer import CommandResult, apply_command
+
+__all__ = [
+    "Contradiction",
+    "StaleItem",
+    "CascadeResult",
+    "get_contradictions",
+    "mark_contradiction",
+    "resolve_contradiction",
+    "get_stale_items",
+    "get_dependents",
+    "cascade_retract",
+    "mark_alias",
+    "get_aliases",
+    "get_alias_group",
+    "get_items_by_budget",
+]
+
+
+# ---------------------------------------------------------------------------
+# 1. Contradiction detection & resolution
+# ---------------------------------------------------------------------------
+
+
+class Contradiction(NamedTuple):
+    a: MemoryItem
+    b: MemoryItem
+    edge: Edge | None = None
+
+
+def get_contradictions(state: GraphState) -> list[Contradiction]:
+    contradict_edges = get_edges(state, {"kind": "CONTRADICTS", "active_only": True})
+    results: list[Contradiction] = []
+    for edge in contradict_edges:
+        a = state.items.get(edge.from_)
+        b = state.items.get(edge.to)
+        if a is not None and b is not None:
+            results.append(Contradiction(a=a, b=b, edge=edge))
+    return results
+
+
+def mark_contradiction(
+    state: GraphState,
+    item_id_a: str,
+    item_id_b: str,
+    author: str,
+    meta: dict[str, Any] | None = None,
+) -> CommandResult:
+    # A self-CONTRADICTS edge is meaningful (an internally inconsistent item);
+    # downstream annotation already skips self-edges, so it's safe to record.
+    edge = create_edge(
+        from_=item_id_a, to=item_id_b, kind="CONTRADICTS", author=author,
+        source_kind="derived_deterministic", authority=1, meta=meta,
+    )
+    return apply_command(state, EdgeCreate(edge=edge))
+
+
+def resolve_contradiction(
+    state: GraphState,
+    winner_id: str,
+    loser_id: str,
+    author: str,
+    reason: str | None = None,
+) -> CommandResult:
+    current = state
+    all_events: list[MemoryLifecycleEvent] = []
+
+    to_retract: list[str] = []
+    for edge in current.edges.values():
+        if (
+            edge.kind == "CONTRADICTS"
+            and edge.active
+            and (
+                (edge.from_ == winner_id and edge.to == loser_id)
+                or (edge.from_ == loser_id and edge.to == winner_id)
+            )
+        ):
+            to_retract.append(edge.edge_id)
+
+    for edge_id in to_retract:
+        r = apply_command(
+            current, {"type": "edge.retract", "edge_id": edge_id, "author": author, "reason": reason}
+        )
+        current = r.state
+        all_events.extend(r.events)
+
+    if not to_retract:
+        # Stale/duplicate call — no-op rather than crash the fold.
+        return CommandResult(current, all_events)
+
+    supersedes = create_edge(
+        from_=winner_id, to=loser_id, kind="SUPERSEDES", author=author,
+        source_kind="derived_deterministic", authority=1,
+        meta={"reason": reason} if reason else None,
+    )
+    r1 = apply_command(current, EdgeCreate(edge=supersedes))
+    current = r1.state
+    all_events.extend(r1.events)
+
+    loser = current.items.get(loser_id)
+    if loser is not None:
+        r2 = apply_command(
+            current,
+            {"type": "memory.update", "item_id": loser_id,
+             "partial": {"authority": loser.authority * 0.1}, "author": author, "reason": reason},
+        )
+        current = r2.state
+        all_events.extend(r2.events)
+
+    return CommandResult(current, all_events)
+
+
+# ---------------------------------------------------------------------------
+# 2. Stale detection & cascade
+# ---------------------------------------------------------------------------
+
+
+class StaleItem(NamedTuple):
+    item: MemoryItem
+    missing_parents: list[str]
+
+
+def get_stale_items(state: GraphState) -> list[StaleItem]:
+    results: list[StaleItem] = []
+    for item in state.items.values():
+        if not item.parents:
+            continue
+        missing = [pid for pid in item.parents if pid not in state.items]
+        if missing:
+            results.append(StaleItem(item=item, missing_parents=missing))
+    return results
+
+
+def get_dependents(state: GraphState, item_id: str, transitive: bool = False) -> list[MemoryItem]:
+    direct = get_children(state, item_id)
+    if not transitive:
+        return direct
+
+    visited: set[str] = set()
+    result: list[MemoryItem] = []
+    queue = list(direct)
+    while queue:
+        item = queue.pop()
+        if item.id in visited:
+            continue
+        visited.add(item.id)
+        result.append(item)
+        queue.extend(get_children(state, item.id))
+    return result
+
+
+class CascadeResult(NamedTuple):
+    state: GraphState
+    events: list[MemoryLifecycleEvent]
+    retracted: list[str]
+
+
+def cascade_retract(
+    state: GraphState,
+    item_id: str,
+    author: str,
+    reason: str | None = None,
+) -> CascadeResult:
+    """Retract an item and all transitive dependents in post-order (leaves first).
+
+    Iterative post-order DFS: cycle-safe, DAG-safe (shared children), and does
+    not consume the call stack on deep dependency chains. The root is pre-marked
+    visited so a cycle pointing back to it is ignored — it's retracted last.
+    """
+    visited: set[str] = {item_id}
+    order: list[str] = []
+
+    stack: list[tuple[str, str]] = [(child.id, "enter") for child in get_children(state, item_id)]
+    while stack:
+        frame_id, phase = stack.pop()
+        if phase == "exit":
+            order.append(frame_id)
+            continue
+        if frame_id in visited:
+            continue
+        visited.add(frame_id)
+        stack.append((frame_id, "exit"))  # processed after all children (post-order)
+        for child in get_children(state, frame_id):
+            if child.id not in visited:
+                stack.append((child.id, "enter"))
+
+    current = state
+    all_events: list[MemoryLifecycleEvent] = []
+    retracted: list[str] = []
+
+    for dep_id in order:
+        if dep_id not in current.items:
+            continue
+        r = apply_command(
+            current,
+            {"type": "memory.retract", "item_id": dep_id, "author": author,
+             "reason": reason if reason is not None else f"parent {item_id} retracted"},
+        )
+        current = r.state
+        all_events.extend(r.events)
+        retracted.append(dep_id)
+
+    if item_id in current.items:
+        r = apply_command(
+            current, {"type": "memory.retract", "item_id": item_id, "author": author, "reason": reason}
+        )
+        current = r.state
+        all_events.extend(r.events)
+        retracted.append(item_id)
+
+    return CascadeResult(current, all_events, retracted)
+
+
+# ---------------------------------------------------------------------------
+# 3. Identity / aliasing
+# ---------------------------------------------------------------------------
+
+
+def mark_alias(
+    state: GraphState,
+    item_id_a: str,
+    item_id_b: str,
+    author: str,
+    meta: dict[str, Any] | None = None,
+) -> CommandResult:
+    if item_id_a == item_id_b:
+        # Self-alias is redundant — no-op rather than throw.
+        return CommandResult(state, [])
+
+    current = state
+    all_events: list[MemoryLifecycleEvent] = []
+
+    e1 = create_edge(
+        from_=item_id_a, to=item_id_b, kind="ALIAS", author=author,
+        source_kind="derived_deterministic", authority=1, meta=meta,
+    )
+    r1 = apply_command(current, EdgeCreate(edge=e1))
+    current = r1.state
+    all_events.extend(r1.events)
+
+    e2 = create_edge(
+        from_=item_id_b, to=item_id_a, kind="ALIAS", author=author,
+        source_kind="derived_deterministic", authority=1, meta=meta,
+    )
+    r2 = apply_command(current, EdgeCreate(edge=e2))
+    current = r2.state
+    all_events.extend(r2.events)
+
+    return CommandResult(current, all_events)
+
+
+def get_aliases(state: GraphState, item_id: str) -> list[MemoryItem]:
+    alias_edges = get_edges(state, {"from": item_id, "kind": "ALIAS", "active_only": True})
+    results: list[MemoryItem] = []
+    for edge in alias_edges:
+        item = state.items.get(edge.to)
+        if item is not None:
+            results.append(item)
+    return results
+
+
+def get_alias_group(state: GraphState, item_id: str) -> list[MemoryItem]:
+    visited: set[str] = set()
+    result: list[MemoryItem] = []
+    queue = [item_id]
+    while queue:
+        node_id = queue.pop()
+        if node_id in visited:
+            continue
+        visited.add(node_id)
+        item = state.items.get(node_id)
+        if item is not None:
+            result.append(item)
+        for edge in get_edges(state, {"from": node_id, "kind": "ALIAS", "active_only": True}):
+            queue.append(edge.to)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 4. Budget-aware retrieval
+# ---------------------------------------------------------------------------
+
+
+def get_items_by_budget(
+    state: GraphState,
+    *,
+    budget: float,
+    cost_fn: Callable[[MemoryItem], float],
+    weights: ScoreWeights | dict[str, Any],
+    filter: MemoryFilter | dict[str, Any] | None = None,
+) -> list[ScoredItem]:
+    """Retrieve the highest-scoring items that fit within a budget (greedy pack)."""
+    scored = get_scored_items(state, weights, {"pre": filter})
+
+    results: list[ScoredItem] = []
+    remaining = budget
+    for entry in scored:
+        cost = cost_fn(entry.item)
+        if cost < 0 or not math.isfinite(cost):
+            raise ValueError(f"cost_fn must return a finite non-negative number, got {cost}")
+        if cost <= remaining:
+            results.append(entry)
+            remaining -= cost
+    return results