rememberstack 0.1.0__py3-none-any.whl

rememberstack/surfaces/__init__.py

@@ -0,0 +1,110 @@
+"""Agent-facing surfaces, imported lazily to keep the client wheel light."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rememberstack.model.client import ToolDescriptor as ToolDescriptor
+    from rememberstack.surfaces.cli import main as cli_main  # noqa: F401
+    from rememberstack.surfaces.consumption_skill import (
+        ConsumptionSkillSurface as ConsumptionSkillSurface,
+    )
+    from rememberstack.surfaces.graph_queries import GraphQueries as GraphQueries
+    from rememberstack.surfaces.http_api import build_api as build_api
+    from rememberstack.surfaces.mcp import RecipeMcpServer as RecipeMcpServer
+    from rememberstack.surfaces.query_engine import QueryEngine as QueryEngine
+    from rememberstack.surfaces.recipe_executor import EXECUTABLE_OPS as EXECUTABLE_OPS
+    from rememberstack.surfaces.recipe_executor import (
+        RecipeExecutionError as RecipeExecutionError,
+    )
+    from rememberstack.surfaces.recipe_executor import RecipeExecutor as RecipeExecutor
+    from rememberstack.surfaces.recipe_surface import (
+        InvalidArgumentError as InvalidArgumentError,
+    )
+    from rememberstack.surfaces.recipe_surface import (
+        MissingArgumentError as MissingArgumentError,
+    )
+    from rememberstack.surfaces.recipe_surface import RecipeSurface as RecipeSurface
+    from rememberstack.surfaces.recipe_surface import (
+        UnknownRecipeError as UnknownRecipeError,
+    )
+    from rememberstack.surfaces.remote_mcp import (
+        RemoteRecipeMcpServer as RemoteRecipeMcpServer,
+    )
+    from rememberstack.surfaces.remote_mcp import serve_mcp_stdio as serve_mcp_stdio
+    from rememberstack.surfaces.sdk import MemoryApiError as MemoryApiError
+    from rememberstack.surfaces.sdk import MemoryClient as MemoryClient
+
+_EXPORTS = {
+    "EXECUTABLE_OPS": ("rememberstack.surfaces.recipe_executor", "EXECUTABLE_OPS"),
+    "ConsumptionSkillSurface": (
+        "rememberstack.surfaces.consumption_skill",
+        "ConsumptionSkillSurface",
+    ),
+    "GraphQueries": ("rememberstack.surfaces.graph_queries", "GraphQueries"),
+    "InvalidArgumentError": (
+        "rememberstack.surfaces.recipe_surface",
+        "InvalidArgumentError",
+    ),
+    "MemoryApiError": ("rememberstack.surfaces.sdk", "MemoryApiError"),
+    "MemoryClient": ("rememberstack.surfaces.sdk", "MemoryClient"),
+    "MissingArgumentError": (
+        "rememberstack.surfaces.recipe_surface",
+        "MissingArgumentError",
+    ),
+    "QueryEngine": ("rememberstack.surfaces.query_engine", "QueryEngine"),
+    "RecipeExecutionError": (
+        "rememberstack.surfaces.recipe_executor",
+        "RecipeExecutionError",
+    ),
+    "RecipeExecutor": ("rememberstack.surfaces.recipe_executor", "RecipeExecutor"),
+    "RecipeMcpServer": ("rememberstack.surfaces.mcp", "RecipeMcpServer"),
+    "RecipeSurface": ("rememberstack.surfaces.recipe_surface", "RecipeSurface"),
+    "RemoteRecipeMcpServer": (
+        "rememberstack.surfaces.remote_mcp",
+        "RemoteRecipeMcpServer",
+    ),
+    "ToolDescriptor": ("rememberstack.model.client", "ToolDescriptor"),
+    "UnknownRecipeError": (
+        "rememberstack.surfaces.recipe_surface",
+        "UnknownRecipeError",
+    ),
+    "build_api": ("rememberstack.surfaces.http_api", "build_api"),
+    "cli_main": ("rememberstack.surfaces.cli", "main"),
+    "serve_mcp_stdio": ("rememberstack.surfaces.remote_mcp", "serve_mcp_stdio"),
+}
+
+__all__ = (
+    "EXECUTABLE_OPS",
+    "ConsumptionSkillSurface",
+    "GraphQueries",
+    "InvalidArgumentError",
+    "MemoryApiError",
+    "MemoryClient",
+    "MissingArgumentError",
+    "QueryEngine",
+    "RecipeExecutionError",
+    "RecipeExecutor",
+    "RecipeMcpServer",
+    "RecipeSurface",
+    "RemoteRecipeMcpServer",
+    "ToolDescriptor",
+    "UnknownRecipeError",
+    "build_api",
+    "cli_main",
+    "serve_mcp_stdio",
+)
+
+
+def __getattr__(name: str) -> Any:
+    """Load each surface only when callers request it."""
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError as error:
+        raise AttributeError(name) from error
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value

rememberstack/surfaces/cli.py

@@ -0,0 +1,447 @@
+"""The ``remember`` CLI: a dependency-light client plus optional local admin commands.
+
+Query, ingest, connector management, and MCP all talk to the deployment HTTP
+API. ``remember review``, ``remember budget``, and ``remember ops`` import the server extra
+and connect to the spine.
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from importlib import import_module
+import json
+from pathlib import Path
+import sys
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+import httpx
+from pydantic import JsonValue
+
+from rememberstack import __version__
+from rememberstack.model.adjudication import ReviewDecisionError
+from rememberstack.model.client import ConnectorCreate
+from rememberstack.surfaces.remote_mcp import RemoteRecipeMcpServer
+from rememberstack.surfaces.remote_mcp import serve_mcp_stdio
+from rememberstack.surfaces.sdk import MemoryApiError
+from rememberstack.surfaces.sdk import MemoryClient
+
+if TYPE_CHECKING:
+    from rememberstack.spine.review import ReviewQueue
+    from rememberstack.spine.work_ledger import WorkLedger
+
+_MERGE_VERDICTS = ("merge", "not_merge")
+_TRIAGE_VERDICTS = ("restore_support", "invalidate_fact", "uncertain")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """The ``remember`` entry point; returns the process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "review":
+            return _run_review(args)
+        if args.command == "budget":
+            return _run_budget(args)
+        if args.command == "ops":
+            return _run_ops(args)
+        if args.command == "query":
+            return _run_query(args)
+        if args.command == "ingest":
+            return _run_ingest(args)
+        if args.command == "connectors":
+            return _run_connectors(args)
+        if args.command == "mcp":
+            return _run_mcp()
+    except MemoryApiError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    parser.print_help()
+    return 2
+
+
+def _run_review(args: argparse.Namespace) -> int:
+    """Compose the optional local ReviewQueue over the spine."""
+    try:
+        from sqlalchemy import create_engine
+
+        from rememberstack.spine.review import ReviewQueue
+        from rememberstack.spine.settings import load_database_settings
+    except ModuleNotFoundError:
+        print(
+            "error: review commands require the 'rememberstack[server]' extra",
+            file=sys.stderr,
+        )
+        return 1
+
+    engine = create_engine(load_database_settings().sqlalchemy_url())
+    try:
+        queue = ReviewQueue(engine=engine)
+        if args.review_command == "list":
+            return _list(queue=queue, deployment_id=args.deployment)
+        return _decide(
+            queue=queue,
+            deployment_id=args.deployment,
+            review_id=args.review_id,
+            verdict=args.verdict,
+            reviewer=args.reviewer,
+            note=args.note,
+        )
+    finally:
+        engine.dispose()
+
+
+def _run_budget(args: argparse.Namespace) -> int:
+    """Compose the local WorkLedger and print configured budget state."""
+    try:
+        from sqlalchemy import create_engine
+
+        from rememberstack.spine.settings import load_database_settings
+        from rememberstack.spine.work_ledger import WorkLedger
+        from rememberstack.spine.work_ledger import WorkLedgerSettings
+    except ModuleNotFoundError:
+        print(
+            "error: budget commands require the 'rememberstack[server]' extra",
+            file=sys.stderr,
+        )
+        return 1
+
+    engine = create_engine(load_database_settings().sqlalchemy_url())
+    try:
+        ledger = WorkLedger(engine=engine, settings=WorkLedgerSettings())
+        return _inspect_budgets(ledger=ledger, deployment_id=args.deployment)
+    finally:
+        engine.dispose()
+
+
+def _run_ops(args: argparse.Namespace) -> int:
+    """Compose bounded local inspection, one-row replay, or an existing rebuild."""
+    try:
+        from rememberstack.model import ProcessingLane
+        from rememberstack.model import WorkLedgerError
+
+        operations_type = import_module(
+            "rememberstack.profiles.selfhost_operations"
+        ).SelfHostOperations
+    except ModuleNotFoundError:
+        print(
+            "error: ops commands require the 'rememberstack[server]' extra",
+            file=sys.stderr,
+        )
+        return 1
+
+    operations = operations_type.from_settings()
+    try:
+        if args.ops_command == "inspect":
+            report = operations.inspect(deployment_id=args.deployment)
+            print(report.model_dump_json())
+            return 0
+        if args.ops_command == "replay":
+            replayed = operations.replay(
+                deployment_id=args.deployment,
+                processing_id=args.processing_id,
+                attempt_allowance=args.attempts,
+                lane=None if args.lane is None else ProcessingLane(args.lane),
+                not_before=args.not_before,
+            )
+            print(replayed.model_dump_json())
+            return 0
+        result = operations.rebuild(
+            plane=args.plane,
+            deployment_id=args.deployment,
+            snapshot_root=args.snapshot_root,
+            workdir=args.workdir,
+            version=args.version,
+        )
+        print(json.dumps(result, default=str, sort_keys=True))
+        return 0
+    except (WorkLedgerError, ValueError, OSError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    finally:
+        operations.close()
+
+
+def _run_query(args: argparse.Namespace) -> int:
+    """Run a query command through the typed remote SDK."""
+    with MemoryClient.from_settings() as client:
+        if args.query_command == "list":
+            for descriptor in client.recipes():
+                print(descriptor.model_dump_json())
+            return 0
+        try:
+            arguments = dict(_split_arg(pair) for pair in args.arg)
+        except ValueError as error:
+            print(f"error: {error}", file=sys.stderr)
+            return 2
+        print(
+            client.run_recipe(name=args.recipe, arguments=arguments).model_dump_json()
+        )
+        return 0
+
+
+def _run_ingest(args: argparse.Namespace) -> int:
+    """Push one local file to the deployment's E0 ingress."""
+    try:
+        with MemoryClient.from_settings() as client:
+            result = client.ingest(
+                args.file,
+                mime=args.mime,
+                title=args.title,
+                source_kind=args.source_kind,
+                source_ref=args.source_ref,
+                source_modified_at=args.source_modified_at,
+                versioning_mode=args.versioning_mode,
+                source_version_ref=args.source_version_ref,
+            )
+    except OSError as error:
+        print(f"error: could not read {args.file}: {error}", file=sys.stderr)
+        return 1
+    except ValueError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    print(result.model_dump_json())
+    return 0
+
+
+def _run_connectors(args: argparse.Namespace) -> int:
+    """Manage connector configuration on the deployment API."""
+    with MemoryClient.from_settings() as client:
+        if args.connector_command == "list":
+            for connector in client.connectors():
+                print(connector.model_dump_json())
+            return 0
+        if args.connector_command == "add":
+            try:
+                configuration: dict[str, JsonValue] = dict(
+                    _split_arg(pair) for pair in args.config
+                )
+                connector = ConnectorCreate(
+                    kind=args.kind,
+                    name=args.name,
+                    configuration=configuration,
+                    credential_ref=args.credential_ref,
+                )
+            except ValueError as error:
+                print(f"error: {error}", file=sys.stderr)
+                return 2
+            result = client.add_connector(connector=connector)
+        elif args.connector_command == "pause":
+            result = client.pause_connector(connector_id=args.connector_id)
+        else:
+            result = client.connector_status(connector_id=args.connector_id)
+    print(result.model_dump_json())
+    return 0
+
+
+def _run_mcp() -> int:
+    """Expose the remote deployment recipe registry over MCP stdio."""
+    with MemoryClient.from_settings() as client:
+        return serve_mcp_stdio(server=RemoteRecipeMcpServer(client=client))
+
+
+def query_list(*, client: httpx.Client) -> int:
+    """Print recipes from an injected client (the parity-testable CLI seam)."""
+    try:
+        for descriptor in MemoryClient(client=client).recipes():
+            print(descriptor.model_dump_json())
+    except MemoryApiError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def query_run(*, client: httpx.Client, name: str, arg_pairs: list[str]) -> int:
+    """Run one recipe through an injected client and print its envelope."""
+    try:
+        arguments = dict(_split_arg(pair) for pair in arg_pairs)
+    except ValueError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    try:
+        envelope = MemoryClient(client=client).run_recipe(
+            name=name, arguments=arguments
+        )
+    except MemoryApiError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    print(envelope.model_dump_json())
+    return 0
+
+
+def _split_arg(pair: str) -> tuple[str, str]:
+    """Split one ``key=value`` argument, or raise a clear error."""
+    key, separator, value = pair.partition("=")
+    if not separator or not key:
+        raise ValueError(f"argument {pair!r} is not key=value")
+    return key, value
+
+
+def _list(*, queue: ReviewQueue, deployment_id: UUID) -> int:
+    """Print open items ranked by expected impact, one JSON line each."""
+    for item in queue.pending(deployment_id=deployment_id):
+        print(
+            json.dumps(
+                {
+                    "review_id": str(item.review_id),
+                    "kind": item.item_kind,
+                    "expected_impact": item.expected_impact,
+                    "blast_radius": item.blast_radius,
+                    "status": item.status,
+                    "candidate": item.candidate,
+                },
+                default=str,
+            )
+        )
+    return 0
+
+
+def _inspect_budgets(*, ledger: WorkLedger, deployment_id: UUID) -> int:
+    """Print one current-window JSON record per configured deployment budget."""
+    for status in ledger.budget_status(deployment_id=deployment_id):
+        print(status.model_dump_json())
+    return 0
+
+
+def _decide(
+    *,
+    queue: ReviewQueue,
+    deployment_id: UUID,
+    review_id: UUID,
+    verdict: str,
+    reviewer: str,
+    note: str | None,
+) -> int:
+    """Apply one verdict; the verdict picks the decision path by its name."""
+    try:
+        if verdict in _MERGE_VERDICTS:
+            events = queue.decide_merge(
+                deployment_id=deployment_id,
+                review_id=review_id,
+                verdict=verdict,
+                reviewer=reviewer,
+                note=note,
+            )
+            print(
+                json.dumps(
+                    {"verdict": verdict, "merge_events": [str(e) for e in events]}
+                )
+            )
+        else:
+            queue.decide_support_withdrawn(
+                deployment_id=deployment_id,
+                review_id=review_id,
+                verdict=verdict,
+                reviewer=reviewer,
+                note=note,
+            )
+            print(json.dumps({"verdict": verdict}))
+    except ReviewDecisionError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the client-first command grammar."""
+    parser = argparse.ArgumentParser(
+        prog="remember", description="RememberStack command-line interface"
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"RememberStack {__version__}"
+    )
+    commands = parser.add_subparsers(dest="command")
+
+    review = commands.add_parser("review", help="the D24 local review queue")
+    review_commands = review.add_subparsers(dest="review_command", required=True)
+    listing = review_commands.add_parser("list", help="open items, impact-ranked")
+    listing.add_argument("--deployment", type=UUID, required=True)
+    decide = review_commands.add_parser("decide", help="apply one verdict")
+    decide.add_argument("review_id", type=UUID)
+    decide.add_argument("--deployment", type=UUID, required=True)
+    decide.add_argument(
+        "--verdict", required=True, choices=(*_MERGE_VERDICTS, *_TRIAGE_VERDICTS)
+    )
+    decide.add_argument("--reviewer", required=True)
+    decide.add_argument("--note", default=None)
+
+    budget = commands.add_parser("budget", help="inspect configured spend ceilings")
+    budget_commands = budget.add_subparsers(dest="budget_command", required=True)
+    inspect = budget_commands.add_parser(
+        "inspect", help="current spend, tier attribution, and parked work"
+    )
+    inspect.add_argument("--deployment", type=UUID, required=True)
+
+    ops = commands.add_parser(
+        "ops", help="inspect durable state, replay one DLQ row, or rebuild"
+    )
+    ops_commands = ops.add_subparsers(dest="ops_command", required=True)
+    ops_inspect = ops_commands.add_parser(
+        "inspect", help="bounded pipeline, DLQ, projection, and currency report"
+    )
+    ops_inspect.add_argument("--deployment", type=UUID, required=True)
+    replay = ops_commands.add_parser("replay", help="reopen one dead-letter row")
+    replay.add_argument("processing_id", type=UUID)
+    replay.add_argument("--deployment", type=UUID, required=True)
+    replay.add_argument(
+        "--attempts",
+        type=int,
+        default=1,
+        help="additional handler attempts to grant (default: 1)",
+    )
+    replay.add_argument("--lane", choices=("steady", "backfill"))
+    replay.add_argument("--not-before", type=datetime.fromisoformat)
+    rebuild = ops_commands.add_parser(
+        "rebuild", help="invoke the existing P2 or P3 full-rebuild path"
+    )
+    rebuild.add_argument("--plane", choices=("p2", "p3"), required=True)
+    rebuild.add_argument("--deployment", type=UUID, required=True)
+    rebuild.add_argument("--snapshot-root", type=Path, required=True)
+    rebuild.add_argument("--workdir", type=Path, required=True)
+    rebuild.add_argument("--version", required=True)
+
+    query = commands.add_parser("query", help="query deployment recipes")
+    query_commands = query.add_subparsers(dest="query_command", required=True)
+    query_commands.add_parser("list", help="list the remote recipe tools")
+    run = query_commands.add_parser("run", help="run one recipe by name")
+    run.add_argument("recipe", help="the recipe name (see `remember query list`)")
+    run.add_argument(
+        "--arg", action="append", default=[], metavar="KEY=VALUE", help="repeatable"
+    )
+
+    ingest = commands.add_parser("ingest", help="push a file through E0")
+    ingest.add_argument("file", type=Path)
+    ingest.add_argument("--mime")
+    ingest.add_argument("--title")
+    ingest.add_argument("--source-kind")
+    ingest.add_argument("--source-ref")
+    ingest.add_argument("--source-modified-at", type=datetime.fromisoformat)
+    ingest.add_argument(
+        "--versioning-mode", choices=("snapshot", "living"), default="snapshot"
+    )
+    ingest.add_argument("--source-version-ref")
+
+    connectors = commands.add_parser(
+        "connectors", help="manage deployment-side connectors"
+    )
+    connector_commands = connectors.add_subparsers(
+        dest="connector_command", required=True
+    )
+    connector_commands.add_parser("list", help="list connectors")
+    add = connector_commands.add_parser("add", help="add connector configuration")
+    add.add_argument("kind")
+    add.add_argument("--name", required=True)
+    add.add_argument("--config", action="append", default=[], metavar="KEY=VALUE")
+    add.add_argument("--credential-ref")
+    pause = connector_commands.add_parser("pause", help="pause a connector")
+    pause.add_argument("connector_id", type=UUID)
+    status = connector_commands.add_parser("status", help="show connector status")
+    status.add_argument("connector_id", type=UUID)
+
+    commands.add_parser("mcp", help="serve remote recipes over MCP stdio")
+    return parser
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised via the entry point
+    raise SystemExit(main())

rememberstack/surfaces/consumption_skill.py

@@ -0,0 +1,87 @@
+"""Deployment surface for rendering and publishing the D51 consumption skill."""
+
+from pathlib import Path
+from uuid import UUID
+from uuid import uuid4
+
+from rememberstack.core import render_consumption_skill
+from rememberstack.model import ConsumptionRecipe
+from rememberstack.model import ConsumptionSkillContext
+from rememberstack.model import PublishedMounts
+from rememberstack.model import Recipe
+from rememberstack.model import RenderedConsumptionSkill
+from rememberstack.spine.consumption import ConsumptionCatalog
+from rememberstack.spine.recipes import RecipeRegistry
+
+
+class ConsumptionSkillSurface:
+    """Render the skill from one deployment's live registries and mounts."""
+
+    def __init__(
+        self,
+        *,
+        catalog: ConsumptionCatalog,
+        recipes: RecipeRegistry,
+        deployment_id: UUID,
+    ) -> None:
+        """Bind the renderer to one deployment and its two spine read models."""
+        self._catalog = catalog
+        self._recipes = recipes
+        self._deployment_id = deployment_id
+
+    @property
+    def deployment_id(self) -> UUID:
+        """The one deployment this skill surface renders."""
+        return self._deployment_id
+
+    def render(
+        self, *, mounts: PublishedMounts | None = None
+    ) -> RenderedConsumptionSkill:
+        """Render the current deployment-specific skill without writing it."""
+        if mounts is not None and mounts.deployment_id != self._deployment_id:
+            raise ValueError(
+                "the mount set and consumption skill serve different deployments"
+            )
+        recipes = tuple(
+            ConsumptionRecipe(
+                name=recipe.name,
+                description=recipe.description,
+                output_grain=recipe.output_grain,
+                answer_intent=recipe.answer_intent,
+            )
+            for recipe in _latest_recipes(
+                recipes=self._recipes.active(deployment_id=self._deployment_id)
+            )
+        )
+        return render_consumption_skill(
+            context=ConsumptionSkillContext(
+                deployment=self._catalog.deployment(deployment_id=self._deployment_id),
+                recipes=recipes,
+                mounts=mounts,
+            )
+        )
+
+    def publish(self, *, directory: Path, rendered: RenderedConsumptionSkill) -> Path:
+        """Atomically publish one already-rendered ``SKILL.md`` artifact."""
+        if rendered.deployment_id != self._deployment_id:
+            raise ValueError(
+                "the rendered skill and publisher serve different deployments"
+            )
+        directory.mkdir(parents=True, exist_ok=True)
+        destination = directory / rendered.filename
+        staging = directory / f".{rendered.filename}.{uuid4().hex}.tmp"
+        staging.write_text(data=rendered.content, encoding="utf-8")
+        staging.replace(target=destination)
+        return destination
+
+
+def _latest_recipes(*, recipes: tuple[Recipe, ...]) -> tuple[Recipe, ...]:
+    """Keep one latest active recipe per name from registry-ordered rows."""
+    seen: set[str] = set()
+    latest: list[Recipe] = []
+    for recipe in recipes:
+        if recipe.name in seen:
+            continue
+        seen.add(recipe.name)
+        latest.append(recipe)
+    return tuple(latest)