rememberstack 0.1.0__py3-none-any.whl

rememberstack/surfaces/recipe_executor.py

@@ -0,0 +1,185 @@
+"""The recipe executor (D50): replay a registry chain over the primitives.
+
+A recipe is *exactly* its chain — it adds no capability an agent could not
+compose from the §3 primitives itself. This executor is where that becomes
+literally true: it walks the chain, calls each named primitive on the
+`QueryEngine` with the recipe's frozen settings and the caller's bound
+arguments, threads earlier steps' rankings into `fuse`, and returns the last
+step's envelope. Because the executor calls the same public methods an agent
+would, "recipe ≡ hand-composed chain" is a property the eval harness proves by
+running both and diffing (retrieval §4).
+
+The executor implements a handler per op in use; the linter (`core`) has
+already rejected any chain that names an unknown op or misreports its grain,
+so a chain that reaches the executor is well-formed.
+"""
+
+from typing import Any
+from uuid import UUID
+
+from rememberstack.model import Envelope
+from rememberstack.model import Recipe
+from rememberstack.model import RecipeStep
+from rememberstack.surfaces.query_engine import QueryEngine
+
+
+class RecipeExecutionError(Exception):
+    """A chain reached the executor with an op it has no handler for."""
+
+
+class RecipeExecutor:
+    """Replay a recipe's frozen chain over the zero-LLM query primitives."""
+
+    def __init__(self, *, query_engine: QueryEngine) -> None:
+        """Bind the executor to the query engine whose primitives it composes."""
+        self._engine = query_engine
+
+    def execute(
+        self, *, deployment_id: UUID, recipe: Recipe, arguments: dict[str, object]
+    ) -> Envelope:
+        """Run the recipe's chain and return the final step's envelope.
+
+        Each step's settings (frozen by the recipe) and bound arguments
+        (supplied by the caller) become the primitive's keywords; `fuse`
+        pulls the orderings of the steps it references. The last step's
+        envelope is the recipe's answer.
+        """
+        envelopes: list[Envelope] = []
+        rankings: list[list[UUID]] = []
+        for step in recipe.chain:
+            envelope = self._run_step(
+                deployment_id=deployment_id,
+                step=step,
+                arguments=arguments,
+                rankings=rankings,
+            )
+            envelopes.append(envelope)
+            rankings.append(_ranking_of(envelope))
+        return envelopes[-1]
+
+    def _run_step(
+        self,
+        *,
+        deployment_id: UUID,
+        step: RecipeStep,
+        arguments: dict[str, object],
+        rankings: list[list[UUID]],
+    ) -> Envelope:
+        """Dispatch one chain step to its primitive with resolved keywords.
+
+        A bound argument the caller omitted is simply not passed — the
+        primitive's own default applies, so an optional recipe parameter
+        (a missing `predicate`, say) behaves exactly as calling the
+        primitive without it, never a KeyError.
+        """
+        kwargs: dict[str, Any] = dict(step.settings)
+        for primitive_kw, argument_name in step.bind.items():
+            if argument_name in arguments:
+                kwargs[primitive_kw] = arguments[argument_name]
+        if step.op == "fuse":
+            return self._engine.fuse(
+                rankings=[rankings[index] for index in step.inputs], **kwargs
+            )
+        handler = _SINGLE_OP_HANDLERS.get(step.op)
+        if handler is None:
+            raise RecipeExecutionError(
+                f"the executor has no handler for op {step.op!r}"
+            )
+        return handler(self._engine, deployment_id, kwargs)
+
+
+def _ranking_of(envelope: Envelope) -> list[UUID]:
+    """The ordered ids of an envelope's payload — what `fuse` consumes.
+
+    A step's downstream ranking is whichever id list the envelope carries, in
+    the order it carries it: a fused/reranked order, then evidence, facts,
+    entities, graph nodes, changes, or pages. This is what lets `fuse`
+    compose the outputs of heterogeneous upstream primitives.
+    """
+    if envelope.ranking:
+        return [item.item_id for item in envelope.ranking]
+    if envelope.evidence:
+        return [record.claim_id for record in envelope.evidence]
+    if envelope.facts:
+        return [fact.fact_id for fact in envelope.facts]
+    if envelope.entities:
+        return [candidate.entity_id for candidate in envelope.entities]
+    if envelope.nodes:
+        return [node.entity_id for node in envelope.nodes]
+    if envelope.changes:
+        return [change.id for change in envelope.changes]
+    if envelope.pages:
+        return [page.artifact_id for page in envelope.pages]
+    return []
+
+
+def _lookup_relations(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `lookup_relations` op."""
+    return engine.lookup_relations(deployment_id=deployment_id, **kwargs)
+
+
+def _lookup_observations(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `lookup_observations` op."""
+    return engine.lookup_observations(deployment_id=deployment_id, **kwargs)
+
+
+def _aggregate(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `aggregate` op."""
+    return engine.aggregate(deployment_id=deployment_id, **kwargs)
+
+
+def _search_claims(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `search_claims` op."""
+    return engine.search_claims(deployment_id=deployment_id, **kwargs)
+
+
+def _hydrate_relation(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `hydrate_relation` op."""
+    return engine.hydrate_relation(deployment_id=deployment_id, **kwargs)
+
+
+def _transcript(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `transcript` op."""
+    return engine.transcript(deployment_id=deployment_id, **kwargs)
+
+
+def _delta(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `delta` op."""
+    return engine.delta(deployment_id=deployment_id, **kwargs)
+
+
+def _pages_about(
+    engine: QueryEngine, deployment_id: UUID, kwargs: dict[str, Any]
+) -> Envelope:
+    """The `pages_about` op."""
+    return engine.pages_about(deployment_id=deployment_id, **kwargs)
+
+
+_SINGLE_OP_HANDLERS = {
+    "lookup_relations": _lookup_relations,
+    "lookup_observations": _lookup_observations,
+    "aggregate": _aggregate,
+    "search_claims": _search_claims,
+    "hydrate_relation": _hydrate_relation,
+    "transcript": _transcript,
+    "delta": _delta,
+    "pages_about": _pages_about,
+}
+
+EXECUTABLE_OPS = frozenset(_SINGLE_OP_HANDLERS) | {"fuse"}
+"""Every op the executor can run. Kept equal to the linter's `KNOWN_OPS` (a
+test enforces it), so no chain ever lints clean only to fail at execution."""

rememberstack/surfaces/recipe_surface.py

@@ -0,0 +1,219 @@
+"""The recipe surface (retrieval §7): one rendering of the registry for all.
+
+The API, CLI, and MCP surfaces must expose the SAME recipes — "the MCP tool
+list renders from the recipe registry; the CLI mirrors the API 1:1" — so the
+rendering and dispatch live here, once, and each surface is a thin transport
+over it. That is how parity is a property, not a promise: there is a single
+place that turns a registry row into a callable tool.
+
+Two responsibilities:
+
+- **Render** each active recipe as a `ToolDescriptor` — name, description,
+  and a real JSON-Schema `input_schema` built from the recipe's typed
+  parameters (this is what an MCP `tools/list` returns, and what the API
+  advertises at `/recipes`).
+- **Run** a recipe by name: coerce the caller's string-ish arguments to the
+  types the primitives need (a uuid string to a UUID, an ISO instant to a
+  datetime), then hand them to the `RecipeExecutor`. Coercion is the surface's
+  job precisely because every transport delivers arguments as text.
+"""
+
+from datetime import datetime
+from datetime import UTC
+from typing import Any
+from uuid import UUID
+
+from rememberstack.model import Envelope
+from rememberstack.model import Recipe
+from rememberstack.model.client import ToolDescriptor
+from rememberstack.spine.recipes import RecipeRegistry
+from rememberstack.surfaces.recipe_executor import RecipeExecutor
+
+
+class UnknownRecipeError(Exception):
+    """A recipe name the registry has no active row for."""
+
+
+class MissingArgumentError(Exception):
+    """A required recipe parameter the caller did not supply."""
+
+
+class InvalidArgumentError(Exception):
+    """An argument the caller supplied is the wrong type or not a parameter."""
+
+
+# How a recipe's declared parameter type renders into JSON Schema, and how a
+# transport's text argument coerces back to what the primitives expect.
+_TYPE_SCHEMA: dict[str, dict[str, object]] = {
+    "uuid": {"type": "string", "format": "uuid"},
+    "string": {"type": "string"},
+    "integer": {"type": "integer"},
+    "timestamp": {"type": "string", "format": "date-time"},
+}
+
+
+def _coerce_uuid(value: object) -> UUID:
+    """Coerce a transport argument to a UUID."""
+    return value if isinstance(value, UUID) else UUID(str(value))
+
+
+def _coerce_integer(value: object) -> int:
+    """Coerce a transport argument to an int without a silent truncation."""
+    if isinstance(value, bool):  # bool is an int subclass — never a count
+        raise ValueError("expected an integer, got a boolean")
+    if isinstance(value, float):
+        if not value.is_integer():
+            raise ValueError(f"expected an integer, got {value!r}")
+        return int(value)
+    return int(str(value))
+
+
+def _coerce_timestamp(value: object) -> datetime:
+    """Coerce a transport argument to a UTC datetime (ISO 8601).
+
+    The envelope's timestamps are UTC-only, so a naive instant is read as
+    UTC and an offset instant is normalized to UTC — never passed through
+    with a stray offset that a downstream model would reject.
+    """
+    parsed = (
+        value if isinstance(value, datetime) else datetime.fromisoformat(str(value))
+    )
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+_COERCERS: dict[str, Any] = {
+    "uuid": _coerce_uuid,
+    "string": str,
+    "integer": _coerce_integer,
+    "timestamp": _coerce_timestamp,
+}
+
+
+class RecipeSurface:
+    """Render and run the deployment's recipes — the shared surface logic."""
+
+    def __init__(
+        self, *, registry: RecipeRegistry, executor: RecipeExecutor, deployment_id: UUID
+    ) -> None:
+        """Bind the surface to the registry, the executor, and the deployment."""
+        self._registry = registry
+        self._executor = executor
+        self._deployment_id = deployment_id
+
+    @property
+    def deployment_id(self) -> UUID:
+        """The one deployment this surface serves (a composition guard, D50)."""
+        return self._deployment_id
+
+    def descriptors(self) -> tuple[ToolDescriptor, ...]:
+        """The recipe tool list: ONE tool per name — the latest active version.
+
+        `run` resolves a name to its latest active version, so the tool list
+        advertises exactly that: a deployment with v1 and v2 both active shows
+        one `relation_current`, whose schema is the one that will execute.
+        """
+        seen: set[str] = set()
+        descriptors: list[ToolDescriptor] = []
+        for recipe in self._registry.active(deployment_id=self._deployment_id):
+            if recipe.name in seen:  # active() is name, version DESC — first wins
+                continue
+            seen.add(recipe.name)
+            descriptors.append(_descriptor(recipe))
+        return tuple(descriptors)
+
+    def run(self, *, name: str, arguments: dict[str, object]) -> Envelope:
+        """Run one recipe by name over coerced arguments.
+
+        Raises `UnknownRecipeError` if no active row exists,
+        `MissingArgumentError` if a required parameter is absent, and
+        `InvalidArgumentError` if an argument is not a declared parameter or
+        will not coerce to its declared type — the surfaces map each to a
+        typed failure (a 404/422, or an MCP error result), never a crash.
+        """
+        recipe = self._registry.by_name(deployment_id=self._deployment_id, name=name)
+        if recipe is None:
+            raise UnknownRecipeError(name)
+        return self._executor.execute(
+            deployment_id=self._deployment_id,
+            recipe=recipe,
+            arguments=_coerce_arguments(recipe=recipe, arguments=arguments),
+        )
+
+
+def _descriptor(recipe: Recipe) -> ToolDescriptor:
+    """Render one recipe as a JSON-Schema-carrying tool descriptor.
+
+    Each property carries its type plus any declared facets (`default`,
+    `enum`) so a client sees the whole contract; `additionalProperties` is
+    false so a mistyped argument name (`predciate`) is a schema violation a
+    validating client rejects, never a silently-dropped filter.
+    """
+    properties: dict[str, object] = {}
+    required: list[str] = []
+    for name, spec in recipe.parameters.items():
+        declared = spec if isinstance(spec, dict) else {}
+        rendered = dict(_TYPE_SCHEMA.get(str(declared.get("type")), {"type": "string"}))
+        for facet in ("default", "enum", "description"):
+            if facet in declared:
+                rendered[facet] = declared[facet]
+        properties[name] = rendered
+        if declared.get("required"):
+            required.append(name)
+    schema: dict[str, object] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return ToolDescriptor(
+        name=recipe.name,
+        description=recipe.description,
+        input_schema=schema,
+        output_grain=recipe.output_grain.value,
+        answer_intent=recipe.answer_intent.value,
+    )
+
+
+def _coerce_arguments(
+    *, recipe: Recipe, arguments: dict[str, object]
+) -> dict[str, object]:
+    """Coerce transport arguments to the types the primitives expect.
+
+    Every rule fails loudly rather than silently changing the query: an
+    argument that is not a declared parameter is an InvalidArgumentError (a
+    typo never broadens the query); a required parameter absent (or null) is
+    a MissingArgumentError; a declared optional's `default` is applied when
+    the caller omits it; and a value that will not coerce to its declared
+    type is an InvalidArgumentError, never an uncaught crash.
+    """
+    declared_names = set(recipe.parameters)
+    unknown = set(arguments) - declared_names
+    if unknown:
+        raise InvalidArgumentError(
+            f"recipe {recipe.name!r} has no parameter(s) {sorted(unknown)}"
+        )
+    coerced: dict[str, object] = {}
+    for name, spec in recipe.parameters.items():
+        declared = spec if isinstance(spec, dict) else {}
+        value = arguments.get(name)
+        if value is None:
+            if declared.get("required"):
+                raise MissingArgumentError(
+                    f"recipe {recipe.name!r} requires argument {name!r}"
+                )
+            if "default" in declared:
+                value = declared["default"]
+            else:
+                continue
+        coerce = _COERCERS.get(str(declared.get("type")), str)
+        try:
+            coerced[name] = coerce(value)
+        except (ValueError, TypeError) as error:
+            raise InvalidArgumentError(
+                f"argument {name!r} of recipe {recipe.name!r} is not a valid"
+                f" {declared.get('type', 'string')}: {value!r}"
+            ) from error
+    return coerced

rememberstack/surfaces/remote_mcp.py

@@ -0,0 +1,133 @@
+"""MCP protocol logic backed by the remote typed SDK, safe in the base wheel."""
+
+import json
+import sys
+from typing import TextIO
+
+from rememberstack import __version__
+from rememberstack.surfaces.sdk import MemoryApiError
+from rememberstack.surfaces.sdk import MemoryClient
+
+MCP_PROTOCOL_VERSION = "2025-11-25"
+
+
+class RemoteRecipeMcpServer:
+    """Render remote deployment recipes as MCP tools and proxy calls to it."""
+
+    def __init__(self, *, client: MemoryClient) -> None:
+        self._client = client
+
+    def list_tools(self) -> dict[str, object]:
+        """The MCP ``tools/list`` result from the deployment registry."""
+        return {
+            "tools": [
+                {
+                    "name": descriptor.name,
+                    "description": descriptor.description,
+                    "inputSchema": descriptor.input_schema,
+                }
+                for descriptor in self._client.recipes()
+            ]
+        }
+
+    def call_tool(
+        self, *, name: str, arguments: dict[str, object]
+    ) -> dict[str, object]:
+        """The MCP ``tools/call`` result containing one envelope JSON block."""
+        try:
+            envelope = self._client.run_recipe(name=name, arguments=arguments)
+        except (MemoryApiError, ValueError) as error:
+            return {"content": [{"type": "text", "text": str(error)}], "isError": True}
+        return {
+            "content": [{"type": "text", "text": envelope.model_dump_json()}],
+            "isError": False,
+        }
+
+
+def serve_mcp_stdio(
+    *,
+    server: RemoteRecipeMcpServer,
+    input_stream: TextIO = sys.stdin,
+    output_stream: TextIO = sys.stdout,
+) -> int:
+    """Serve the minimal MCP JSON-RPC lifecycle over newline-delimited stdio."""
+    for line in input_stream:
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as error:
+            response = {
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32700, "message": str(error)},
+            }
+        else:
+            if not isinstance(request, dict):
+                response = _rpc_error(
+                    request_id=None, code=-32600, message="request is not an object"
+                )
+            else:
+                try:
+                    response = _dispatch(server=server, request=request)
+                except (MemoryApiError, ValueError, TypeError) as error:
+                    response = _rpc_error(
+                        request_id=request.get("id"), code=-32603, message=str(error)
+                    )
+        if response is not None:
+            output_stream.write(json.dumps(response) + "\n")
+            output_stream.flush()
+    return 0
+
+
+def _dispatch(
+    *, server: RemoteRecipeMcpServer, request: dict[str, object]
+) -> dict[str, object] | None:
+    """Dispatch one MCP request; notifications deliberately have no response."""
+    request_id = request.get("id")
+    method = request.get("method")
+    if request.get("jsonrpc") != "2.0" or not isinstance(method, str):
+        return _rpc_error(
+            request_id=request_id, code=-32600, message="invalid JSON-RPC request"
+        )
+    if "id" not in request:
+        return None
+    if method == "initialize":
+        params = request.get("params")
+        if not isinstance(params, dict) or not isinstance(
+            params.get("protocolVersion"), str
+        ):
+            return _rpc_error(
+                request_id=request_id, code=-32602, message="bad initialize params"
+            )
+        result: dict[str, object] = {
+            "protocolVersion": MCP_PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "rememberstack", "version": __version__},
+        }
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = server.list_tools()
+    elif method == "tools/call":
+        params = request.get("params")
+        if not isinstance(params, dict) or not isinstance(params.get("name"), str):
+            return _rpc_error(request_id=request_id, code=-32602, message="bad params")
+        arguments = params.get("arguments", {})
+        if not isinstance(arguments, dict):
+            return _rpc_error(
+                request_id=request_id, code=-32602, message="bad arguments"
+            )
+        result = server.call_tool(name=params["name"], arguments=arguments)
+    else:
+        return _rpc_error(
+            request_id=request_id, code=-32601, message=f"unknown method {method!r}"
+        )
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _rpc_error(*, request_id: object, code: int, message: str) -> dict[str, object]:
+    """Build one JSON-RPC error response."""
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": code, "message": message},
+    }