memex-python 0.13.0__py3-none-any.whl

memex/store.py

@@ -0,0 +1,222 @@
+"""``MemexStore`` — an optional stateful, OO facade over the functional core.
+
+The functional API (``apply_command`` / ``get_items`` / ...) is the backbone and
+stays pure. ``MemexStore`` holds the three graph states, rebinds them on each
+mutation, and returns the emitted lifecycle events — convenient for agents and
+daemons that don't want to thread ``state =`` through every call.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import bulk, integrity, query, retrieval, serialization, stats
+from .factories import create_edge, create_memory_item
+from .graph import GraphState, create_graph_state
+from .integrity import Contradiction, StaleItem
+from .intent import (
+    Intent,
+    IntentLifecycleEvent,
+    IntentState,
+    apply_intent_command,
+    create_intent,
+    create_intent_state,
+    get_intents,
+)
+from .models import Edge, MemoryItem, MemoryLifecycleEvent, ScoredItem
+from .reducer import apply_command
+from .retrieval import SupportNode
+from .stats import GraphStats
+from .task import (
+    Task,
+    TaskLifecycleEvent,
+    TaskState,
+    apply_task_command,
+    create_task,
+    create_task_state,
+    get_tasks,
+)
+from .transplant import ImportReport, MemexExport, export_slice, import_slice
+
+__all__ = ["MemexStore"]
+
+
+class MemexStore:
+    """A mutable container over the Memory / Intent / Task graphs."""
+
+    def __init__(
+        self,
+        mem: GraphState | None = None,
+        intents: IntentState | None = None,
+        tasks: TaskState | None = None,
+    ) -> None:
+        self.mem = mem if mem is not None else create_graph_state()
+        self.intents = intents if intents is not None else create_intent_state()
+        self.tasks = tasks if tasks is not None else create_task_state()
+
+    # -- memory mutations ---------------------------------------------------
+
+    def apply(self, cmd: Any) -> list[MemoryLifecycleEvent]:
+        result = apply_command(self.mem, cmd)
+        self.mem = result.state
+        return result.events
+
+    def create(self, **kwargs: Any) -> MemoryItem:
+        item = create_memory_item(**kwargs)
+        self.apply({"type": "memory.create", "item": item})
+        return item
+
+    def add(self, item: MemoryItem) -> MemoryItem:
+        self.apply({"type": "memory.create", "item": item})
+        return item
+
+    def update(self, item_id: str, partial: dict[str, Any], author: str, reason: str | None = None) -> list[MemoryLifecycleEvent]:
+        return self.apply({"type": "memory.update", "item_id": item_id, "partial": partial, "author": author, "reason": reason})
+
+    def retract(self, item_id: str, author: str, reason: str | None = None) -> list[MemoryLifecycleEvent]:
+        return self.apply({"type": "memory.retract", "item_id": item_id, "author": author, "reason": reason})
+
+    def add_edge(self, **kwargs: Any) -> Edge:
+        edge = create_edge(**kwargs)
+        self.apply({"type": "edge.create", "edge": edge})
+        return edge
+
+    # -- memory queries -----------------------------------------------------
+
+    def items(self, filter: Any = None, options: Any = None) -> list[MemoryItem]:
+        return query.get_items(self.mem, filter, options)
+
+    def item(self, id: str) -> MemoryItem | None:
+        return query.get_item_by_id(self.mem, id)
+
+    def scored(self, weights: Any, options: Any = None) -> list[ScoredItem]:
+        return query.get_scored_items(self.mem, weights, options)
+
+    def edges(self, filter: Any = None) -> list[Edge]:
+        return query.get_edges(self.mem, filter)
+
+    def parents(self, item_id: str) -> list[MemoryItem]:
+        return query.get_parents(self.mem, item_id)
+
+    def children(self, item_id: str) -> list[MemoryItem]:
+        return query.get_children(self.mem, item_id)
+
+    def related(self, item_id: str, direction: str = "both") -> list[MemoryItem]:
+        return query.get_related_items(self.mem, item_id, direction)
+
+    def smart_retrieve(self, **kwargs: Any) -> list[ScoredItem]:
+        return retrieval.smart_retrieve(self.mem, **kwargs)
+
+    def support_tree(self, item_id: str) -> SupportNode | None:
+        return retrieval.get_support_tree(self.mem, item_id)
+
+    def support_set(self, item_id: str) -> list[MemoryItem]:
+        return retrieval.get_support_set(self.mem, item_id)
+
+    def stats(self) -> GraphStats:
+        return stats.get_stats(self.mem)
+
+    # -- integrity ----------------------------------------------------------
+
+    def mark_contradiction(self, a: str, b: str, author: str, meta: dict[str, Any] | None = None) -> list[MemoryLifecycleEvent]:
+        result = integrity.mark_contradiction(self.mem, a, b, author, meta)
+        self.mem = result.state
+        return result.events
+
+    def resolve_contradiction(self, winner: str, loser: str, author: str, reason: str | None = None) -> list[MemoryLifecycleEvent]:
+        result = integrity.resolve_contradiction(self.mem, winner, loser, author, reason)
+        self.mem = result.state
+        return result.events
+
+    def mark_alias(self, a: str, b: str, author: str, meta: dict[str, Any] | None = None) -> list[MemoryLifecycleEvent]:
+        result = integrity.mark_alias(self.mem, a, b, author, meta)
+        self.mem = result.state
+        return result.events
+
+    def cascade_retract(self, item_id: str, author: str, reason: str | None = None) -> list[str]:
+        result = integrity.cascade_retract(self.mem, item_id, author, reason)
+        self.mem = result.state
+        return result.retracted
+
+    def contradictions(self) -> list[Contradiction]:
+        return integrity.get_contradictions(self.mem)
+
+    def stale_items(self) -> list[StaleItem]:
+        return integrity.get_stale_items(self.mem)
+
+    def aliases(self, item_id: str) -> list[MemoryItem]:
+        return integrity.get_aliases(self.mem, item_id)
+
+    def alias_group(self, item_id: str) -> list[MemoryItem]:
+        return integrity.get_alias_group(self.mem, item_id)
+
+    # -- bulk ---------------------------------------------------------------
+
+    def apply_many(self, filter: Any, transform: Any, author: str, reason: str | None = None, options: Any = None) -> list[MemoryLifecycleEvent]:
+        result = bulk.apply_many(self.mem, filter, transform, author, reason, options)
+        self.mem = result.state
+        return result.events
+
+    def bulk_adjust_scores(self, criteria: Any, delta: Any, author: str, reason: str | None = None) -> list[MemoryLifecycleEvent]:
+        result = bulk.bulk_adjust_scores(self.mem, criteria, delta, author, reason)
+        self.mem = result.state
+        return result.events
+
+    def decay_importance(self, older_than_ms: int, factor: float, author: str, reason: str | None = None) -> list[MemoryLifecycleEvent]:
+        result = bulk.decay_importance(self.mem, older_than_ms, factor, author, reason)
+        self.mem = result.state
+        return result.events
+
+    # -- intent graph -------------------------------------------------------
+
+    def apply_intent(self, cmd: Any) -> list[IntentLifecycleEvent]:
+        result = apply_intent_command(self.intents, cmd)
+        self.intents = result.state
+        return result.events
+
+    def create_intent(self, **kwargs: Any) -> Intent:
+        intent = create_intent(**kwargs)
+        self.apply_intent({"type": "intent.create", "intent": intent})
+        return intent
+
+    def get_intents(self, filter: Any = None) -> list[Intent]:
+        return get_intents(self.intents, filter)
+
+    # -- task graph ---------------------------------------------------------
+
+    def apply_task(self, cmd: Any) -> list[TaskLifecycleEvent]:
+        result = apply_task_command(self.tasks, cmd)
+        self.tasks = result.state
+        return result.events
+
+    def create_task(self, **kwargs: Any) -> Task:
+        task = create_task(**kwargs)
+        self.apply_task({"type": "task.create", "task": task})
+        return task
+
+    def get_tasks(self, filter: Any = None) -> list[Task]:
+        return get_tasks(self.tasks, filter)
+
+    # -- transplant ---------------------------------------------------------
+
+    def export_slice(self, **kwargs: Any) -> MemexExport:
+        return export_slice(self.mem, self.intents, self.tasks, **kwargs)
+
+    def import_slice(self, slice: MemexExport | dict[str, Any], **kwargs: Any) -> ImportReport:
+        result = import_slice(self.mem, self.intents, self.tasks, slice, **kwargs)
+        self.mem = result.mem_state
+        self.intents = result.intent_state
+        self.tasks = result.task_state
+        return result.report
+
+    # -- serialization (memory graph) --------------------------------------
+
+    def to_json(self) -> serialization.SerializedGraphState:
+        return serialization.to_json(self.mem)
+
+    def dumps(self, pretty: bool = False) -> str:
+        return serialization.stringify(self.mem, pretty)
+
+    @classmethod
+    def loads(cls, json_str: str) -> MemexStore:
+        return cls(mem=serialization.parse(json_str))

memex/task.py

@@ -0,0 +1,361 @@
+"""Task graph — units of work tied to intents, with a status machine.
+
+``pending → running → completed`` (``running → failed → running`` retry,
+``cancel`` from any non-terminal state). Invalid transitions raise
+``InvalidTaskTransitionError``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Annotated, Any, Literal, NamedTuple
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+from ._uuid import uuid7
+from .errors import MemexError
+
+__all__ = [
+    "TaskStatus",
+    "Task",
+    "TaskState",
+    "TaskCommand",
+    "TaskLifecycleEvent",
+    "TaskFilter",
+    "TaskResult",
+    "TaskNotFoundError",
+    "DuplicateTaskError",
+    "InvalidTaskTransitionError",
+    "create_task_state",
+    "create_task",
+    "apply_task_command",
+    "get_tasks",
+    "get_task_by_id",
+    "get_tasks_by_intent",
+    "get_child_tasks",
+]
+
+TaskStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+
+
+class Task(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    intent_id: str
+    parent_id: str | None = None
+
+    action: str
+    label: str | None = None
+
+    status: TaskStatus
+    priority: float = Field(ge=0, le=1)
+
+    context: dict[str, Any] | None = None
+    result: dict[str, Any] | None = None
+    error: str | None = None
+
+    input_memory_ids: list[str] | None = None
+    output_memory_ids: list[str] | None = None
+
+    agent_id: str | None = None
+    attempt: int | None = None
+
+    meta: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TaskState:
+    tasks: dict[str, Task] = field(default_factory=dict)
+
+
+def create_task_state() -> TaskState:
+    return TaskState(tasks={})
+
+
+def create_task(
+    *,
+    intent_id: str,
+    action: str,
+    priority: float,
+    id: str | None = None,
+    parent_id: str | None = None,
+    label: str | None = None,
+    status: TaskStatus | None = None,
+    context: dict[str, Any] | None = None,
+    result: dict[str, Any] | None = None,
+    error: str | None = None,
+    input_memory_ids: list[str] | None = None,
+    output_memory_ids: list[str] | None = None,
+    agent_id: str | None = None,
+    attempt: int | None = None,
+    meta: dict[str, Any] | None = None,
+) -> Task:
+    return Task(
+        id=id if id is not None else uuid7(),
+        intent_id=intent_id,
+        parent_id=parent_id,
+        action=action,
+        label=label,
+        status=status if status is not None else "pending",
+        priority=priority,
+        context=context,
+        result=result,
+        error=error,
+        input_memory_ids=input_memory_ids,
+        output_memory_ids=output_memory_ids,
+        agent_id=agent_id,
+        attempt=attempt if attempt is not None else 0,
+        meta=meta,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+class TaskCreate(BaseModel):
+    type: Literal["task.create"] = "task.create"
+    task: Task
+
+
+class TaskUpdate(BaseModel):
+    type: Literal["task.update"] = "task.update"
+    task_id: str
+    partial: dict[str, Any]
+    author: str
+
+
+class TaskStart(BaseModel):
+    type: Literal["task.start"] = "task.start"
+    task_id: str
+    agent_id: str | None = None
+
+
+class TaskComplete(BaseModel):
+    type: Literal["task.complete"] = "task.complete"
+    task_id: str
+    result: dict[str, Any] | None = None
+    output_memory_ids: list[str] | None = None
+
+
+class TaskFail(BaseModel):
+    type: Literal["task.fail"] = "task.fail"
+    task_id: str
+    error: str
+    retryable: bool | None = None
+
+
+class TaskCancel(BaseModel):
+    type: Literal["task.cancel"] = "task.cancel"
+    task_id: str
+    reason: str | None = None
+
+
+TaskCommand = Annotated[
+    TaskCreate | TaskUpdate | TaskStart | TaskComplete | TaskFail | TaskCancel,
+    Field(discriminator="type"),
+]
+
+_TASK_COMMAND_ADAPTER: TypeAdapter[TaskCommand] = TypeAdapter(TaskCommand)
+
+
+TaskEventType = Literal[
+    "task.created",
+    "task.updated",
+    "task.started",
+    "task.completed",
+    "task.failed",
+    "task.cancelled",
+]
+
+
+class TaskLifecycleEvent(BaseModel):
+    namespace: Literal["task"] = "task"
+    type: TaskEventType
+    task: Task
+    cause_type: str
+
+
+class TaskResult(NamedTuple):
+    state: TaskState
+    events: list[TaskLifecycleEvent]
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class TaskNotFoundError(MemexError):
+    def __init__(self, task_id: str) -> None:
+        super().__init__(f"Task not found: {task_id}")
+        self.task_id = task_id
+
+
+class DuplicateTaskError(MemexError):
+    def __init__(self, task_id: str) -> None:
+        super().__init__(f"Task already exists: {task_id}")
+        self.task_id = task_id
+
+
+class InvalidTaskTransitionError(MemexError):
+    def __init__(self, task_id: str, from_status: str, to_status: str) -> None:
+        super().__init__(f"Invalid task transition: {task_id} from {from_status} to {to_status}")
+        self.task_id = task_id
+        self.from_status = from_status
+        self.to_status = to_status
+
+
+# ---------------------------------------------------------------------------
+# Reducer
+# ---------------------------------------------------------------------------
+
+
+def _event(task: Task, event_type: TaskEventType, cause_type: str) -> TaskLifecycleEvent:
+    return TaskLifecycleEvent(type=event_type, task=task, cause_type=cause_type)
+
+
+def apply_task_command(state: TaskState, cmd: TaskCommand | dict[str, Any]) -> TaskResult:
+    command = cmd if isinstance(cmd, BaseModel) else _TASK_COMMAND_ADAPTER.validate_python(cmd)
+
+    match command:
+        case TaskCreate(task=task):
+            if task.id in state.tasks:
+                raise DuplicateTaskError(task.id)
+            tasks = {**state.tasks, task.id: task}
+            return TaskResult(TaskState(tasks), [_event(task, "task.created", "task.create")])
+
+        case TaskUpdate(task_id=task_id, partial=partial):
+            existing = state.tasks.get(task_id)
+            if existing is None:
+                raise TaskNotFoundError(task_id)
+            update = {k: v for k, v in partial.items() if k not in ("id", "status")}
+            updated = existing.model_copy(update=update)
+            tasks = {**state.tasks, task_id: updated}
+            return TaskResult(TaskState(tasks), [_event(updated, "task.updated", "task.update")])
+
+        case TaskStart(task_id=task_id, agent_id=agent_id):
+            existing = state.tasks.get(task_id)
+            if existing is None:
+                raise TaskNotFoundError(task_id)
+            if existing.status not in ("pending", "failed"):
+                raise InvalidTaskTransitionError(task_id, existing.status, "running")
+            updated = existing.model_copy(update={
+                "status": "running",
+                "agent_id": agent_id if agent_id is not None else existing.agent_id,
+                "attempt": (existing.attempt or 0) + 1,
+            })
+            tasks = {**state.tasks, task_id: updated}
+            return TaskResult(TaskState(tasks), [_event(updated, "task.started", "task.start")])
+
+        case TaskComplete(task_id=task_id, result=result, output_memory_ids=output_memory_ids):
+            existing = state.tasks.get(task_id)
+            if existing is None:
+                raise TaskNotFoundError(task_id)
+            if existing.status != "running":
+                raise InvalidTaskTransitionError(task_id, existing.status, "completed")
+            updated = existing.model_copy(update={
+                "status": "completed",
+                "result": result if result is not None else existing.result,
+                "output_memory_ids": output_memory_ids if output_memory_ids is not None else existing.output_memory_ids,
+            })
+            tasks = {**state.tasks, task_id: updated}
+            return TaskResult(TaskState(tasks), [_event(updated, "task.completed", "task.complete")])
+
+        case TaskFail(task_id=task_id, error=error):
+            existing = state.tasks.get(task_id)
+            if existing is None:
+                raise TaskNotFoundError(task_id)
+            if existing.status != "running":
+                raise InvalidTaskTransitionError(task_id, existing.status, "failed")
+            updated = existing.model_copy(update={"status": "failed", "error": error})
+            tasks = {**state.tasks, task_id: updated}
+            return TaskResult(TaskState(tasks), [_event(updated, "task.failed", "task.fail")])
+
+        case TaskCancel(task_id=task_id):
+            existing = state.tasks.get(task_id)
+            if existing is None:
+                raise TaskNotFoundError(task_id)
+            if existing.status in ("completed", "cancelled"):
+                raise InvalidTaskTransitionError(task_id, existing.status, "cancelled")
+            updated = existing.model_copy(update={"status": "cancelled"})
+            tasks = {**state.tasks, task_id: updated}
+            return TaskResult(TaskState(tasks), [_event(updated, "task.cancelled", "task.cancel")])
+
+        case _:  # pragma: no cover
+            raise TypeError(f"Unknown task command: {command!r}")
+
+
+# ---------------------------------------------------------------------------
+# Query
+# ---------------------------------------------------------------------------
+
+
+class TaskFilter(BaseModel):
+    intent_id: str | None = None
+    action: str | None = None
+    status: TaskStatus | None = None
+    statuses: list[TaskStatus] | None = None
+    agent_id: str | None = None
+    min_priority: float | None = None
+    has_input_memory_id: str | None = None
+    has_output_memory_id: str | None = None
+    parent_id: str | None = None
+    is_root: bool | None = None
+
+
+def _coerce_task_filter(f: TaskFilter | dict[str, Any] | None) -> TaskFilter | None:
+    if f is None or isinstance(f, TaskFilter):
+        return f
+    return TaskFilter.model_validate(f)
+
+
+def get_tasks(state: TaskState, filter: TaskFilter | dict[str, Any] | None = None) -> list[Task]:
+    f = _coerce_task_filter(filter)
+    if f is None:
+        return list(state.tasks.values())
+
+    results: list[Task] = []
+    for task in state.tasks.values():
+        if f.intent_id is not None and task.intent_id != f.intent_id:
+            continue
+        if f.action is not None and task.action != f.action:
+            continue
+        if f.status is not None and task.status != f.status:
+            continue
+        if f.statuses is not None and task.status not in f.statuses:
+            continue
+        if f.agent_id is not None and task.agent_id != f.agent_id:
+            continue
+        if f.min_priority is not None and task.priority < f.min_priority:
+            continue
+        if f.has_input_memory_id is not None:
+            if not task.input_memory_ids or f.has_input_memory_id not in task.input_memory_ids:
+                continue
+        if f.has_output_memory_id is not None:
+            if not task.output_memory_ids or f.has_output_memory_id not in task.output_memory_ids:
+                continue
+        if f.parent_id is not None and task.parent_id != f.parent_id:
+            continue
+        if f.is_root is not None:
+            has_parent = task.parent_id is not None
+            if f.is_root and has_parent:
+                continue
+            if not f.is_root and not has_parent:
+                continue
+        results.append(task)
+    return results
+
+
+def get_task_by_id(state: TaskState, id: str) -> Task | None:
+    return state.tasks.get(id)
+
+
+def get_tasks_by_intent(state: TaskState, intent_id: str) -> list[Task]:
+    return get_tasks(state, {"intent_id": intent_id})
+
+
+def get_child_tasks(state: TaskState, parent_id: str) -> list[Task]:
+    return get_tasks(state, {"parent_id": parent_id})