katalyst-plugin-context 0.1.1a1__py3-none-any.whl

katalyst_plugin_context/mcp_tools.py

@@ -0,0 +1,132 @@
+# pyright: reportUnusedFunction=false
+# pyright: reportMissingTypeArgument=false, reportUnknownParameterType=false
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false
+# pyright: reportArgumentType=false
+# The MCP SDK's Context is generic over types FastMCP never fills in, so every tool
+# signature is partially unknown by construction (as the harness plugin's tools).
+"""taxonomy_context_map, taxonomy_context — what an agent working on a node is given."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from katalyst_taxonomy_mcp.response import err, guard_backend_errors, ok
+from mcp.server.fastmcp import Context, FastMCP
+
+from katalyst_plugin_context.composition import service_for
+from katalyst_plugin_context.domain.context import ContextError, ContextRequest
+from katalyst_plugin_context.service import ContextService
+
+
+def _service(ctx: Context, backend: str | None) -> ContextService:
+    from katalyst_taxonomy_mcp.server import AppContext
+
+    app = cast("AppContext", ctx.request_context.lifespan_context)
+    return service_for(app.get_registry(), app.read_sources(backend), profile=app.backends.profile)
+
+
+def _refusal(exc: ContextError) -> dict[str, Any]:
+    return err(exc.code, exc.message, exc.details)
+
+
+def register_context_tools(mcp: FastMCP) -> None:
+    """Register the context tools on the MCP server."""
+
+    @mcp.tool()
+    @guard_backend_errors
+    def taxonomy_context_map(
+        node: str,
+        format: str = "json",
+        backend: str | None = None,
+        ctx: Context = None,  # pyright: ignore[reportAssignmentType]
+    ) -> dict[str, Any]:
+        """Start here before working on a node: what the taxonomy holds around it.
+
+        Lists every relationship type around NODE in both directions, with the kinds and
+        counts at the other end, and what NODE inherits from its ancestors (its parent
+        chain), each marked with where it comes from. Also lists the named views its kind
+        declares, and returns ('always') the views it always includes, such as the decisions
+        and standards that govern it. 'options' says what you may ask for next: the steps
+        you may follow, the maximum depth, detail levels and budget. Then call
+        taxonomy_context with only what your task needs.
+
+        Args:
+            node: Qualified name, 'backend:fqtn' (or the FQTN when one backend holds it).
+            format: 'json', or 'markdown' for ready-to-read text in 'markdown'.
+            backend: Read only this backend. Default: every backend the profile reads.
+        """
+        try:
+            service = _service(ctx, backend)
+            payload = service.map(node)
+            if format == "markdown":
+                return ok({"markdown": service.markdown_for_map(payload), "map": payload})
+            return ok(payload)
+        except ContextError as exc:
+            return _refusal(exc)
+
+    @mcp.tool()
+    @guard_backend_errors
+    def taxonomy_context(
+        node: str,
+        paths: list[str] | None = None,
+        views: list[str] | None = None,
+        depth: int | None = None,
+        detail: str | None = None,
+        budget: int | None = None,
+        inherit: bool | None = None,
+        format: str = "json",
+        backend: str | None = None,
+        ctx: Context = None,  # pyright: ignore[reportAssignmentType]
+    ) -> dict[str, Any]:
+        """The nodes around NODE that your task needs, with why each one is relevant.
+
+        With no paths or views, returns the views NODE's kind always includes, or the whole
+        neighbourhood at depth 1 if it declares none. Otherwise returns exactly what you ask
+        for:
+          paths   steps 'REL[:in|out[:kind,...]]' joined by '/' into a walk, e.g.
+                  'SOME_REL:out' or 'A_REL:in/B_REL:in'. Take the steps from
+                  taxonomy_context_map's options.steps.
+          views   names from taxonomy_context_map's views.
+          depth   how many times to follow a single step (default 1).
+          detail  'refs' (names and why), 'summary' (plus a short description and key
+                  fields) or 'full' (every field and the document body).
+          budget  approximate tokens. Lowest-priority items are shortened first, then cut,
+                  and 'truncated' says what was cut and how to get it.
+          inherit also follow paths from NODE's ancestors (default: per policy).
+        Policy set by the schema, the node and the profile can only narrow a request. A
+        narrowed request is still answered, and 'policy' says what was narrowed. Each item
+        says why it is here (the path, and which ancestor it was inherited from) and, when
+        the schema says so, whether it is blocking.
+
+        Args:
+            node: Qualified name, 'backend:fqtn' (or the FQTN when one backend holds it).
+            paths: Paths to walk.
+            views: Views to return.
+            depth: Repetitions of a single-step path.
+            detail: refs, summary or full.
+            budget: Approximate tokens for the items.
+            inherit: Also walk from the node's ancestors.
+            format: 'json', or 'markdown' for ready-to-read text in 'markdown'.
+            backend: Read only this backend. Default: every backend the profile reads.
+        """
+        request = ContextRequest(
+            paths=tuple(paths) if paths is not None else None,
+            views=tuple(views) if views is not None else None,
+            depth=depth,
+            detail=detail,
+            budget=budget,
+            inherit=inherit,
+            format=format,
+        )
+        try:
+            service = _service(ctx, backend)
+            payload = service.query(node, request)
+            if format == "markdown":
+                return ok(
+                    {"markdown": service.markdown_for_result(node, payload), "result": payload}
+                )
+            return ok(payload)
+        except ContextError as exc:
+            return _refusal(exc)
+
+    _ = (taxonomy_context_map, taxonomy_context)

katalyst_plugin_context/plugin.py

@@ -0,0 +1,64 @@
+"""Context plugin: what an agent working on a node gets from the taxonomy.
+
+Contributes the MCP tools (``taxonomy_context_map``, ``taxonomy_context``), the REST routes
+(``/ext/context``) and the ``context-policy`` lint rule. ``kata tax context`` arrives over
+the ``katalyst_taxonomy.cli`` entry point. It ships no kinds: bundles declare what their
+kinds' context is in ``plugin_settings["context"]``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from katalyst_taxonomy.plugins.protocol import PluginContext, PluginManifest
+
+from katalyst_plugin_context.schema import CONFIG_SCHEMA, NODE_SETTINGS_SCHEMA, SETTINGS_SCHEMA
+from katalyst_plugin_context.service import NAMESPACE
+
+
+def _version() -> str:
+    try:
+        return version("katalyst-plugin-context")
+    except PackageNotFoundError:  # pragma: no cover - running from a source tree
+        return ""
+
+
+class ContextPlugin:
+    """The right context for an agent working on a node, over MCP, REST and the CLI."""
+
+    @property
+    def name(self) -> str:
+        return NAMESPACE
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name=NAMESPACE,
+            version=_version(),
+            description=(
+                "Give an agent working on a node the right context: the relationships "
+                "around it, what it inherits, and the views its kind declares, narrowed "
+                "by schema, node and profile policy"
+            ),
+            capabilities=("context", "agents"),
+            config_schema=CONFIG_SCHEMA,
+            settings_schema=SETTINGS_SCHEMA,
+            node_settings_schema=NODE_SETTINGS_SCHEMA,
+        )
+
+    def register(self, context: PluginContext) -> None:
+        from katalyst_plugin_context.lint import ContextPolicyRule
+        from katalyst_plugin_context.rest import ContextRestRoutes
+
+        context.lint_rules.append(ContextPolicyRule(context.schema_registry))
+        context.rest_routes.append(ContextRestRoutes())
+
+        def _register_mcp(mcp: Any) -> None:
+            # Imported only when an MCP server calls this, so a host that never serves
+            # MCP does not need the MCP SDK just to load plugins.
+            from katalyst_plugin_context.mcp_tools import register_context_tools
+
+            register_context_tools(mcp)
+
+        context.mcp_tools.append(_register_mcp)

katalyst_plugin_context/rest.py

@@ -0,0 +1,133 @@
+# pyright: reportUnusedFunction=false
+#
+# The routes are nested functions registered by their decorators and never referenced by
+# name; the REST app mounts the router this returns.
+"""``/ext/context`` — the context map, a context query and the effective policy over REST.
+
+==============================  ==========================================================
+Route                           Answers
+==============================  ==========================================================
+``GET  /ext/context/map``       the map around ``node`` (``format=markdown`` adds text)
+``POST /ext/context/query``     the items a request asks for (``paths``, ``views``, ...)
+``GET  /ext/context/policy``    the effective policy for ``node``: layers, limits, notes
+==============================  ==========================================================
+
+Every route only reads. Each needs the API's bearer token, as every route does.
+"""
+
+# No `from __future__ import annotations`: FastAPI reads the handlers' annotations, and
+# the request model is local to router(), so they must be evaluated where it is in scope.
+from typing import Any
+
+
+class ContextRestRoutes:
+    """Implements :class:`~katalyst_taxonomy.plugins.extensions.RestRoutes`."""
+
+    @property
+    def name(self) -> str:
+        return "context"
+
+    def router(self) -> Any:
+        from fastapi import APIRouter, Request
+        from fastapi.responses import JSONResponse
+        from katalyst_engine.schema.registry import SchemaRegistry
+        from katalyst_taxonomy.config.routing import BackendAddressError
+        from katalyst_taxonomy.engine.bridge import get_default_registry
+        from katalyst_taxonomy_mcp.response import ErrorCode, backend_failure, err, ok
+        from pydantic import BaseModel, Field
+
+        from katalyst_plugin_context.composition import service_for
+        from katalyst_plugin_context.domain.context import ContextError, ContextRequest
+        from katalyst_plugin_context.service import ContextService
+
+        router = APIRouter()
+        status_of = {"NOT_FOUND": 404, "INVALID_INPUT": 422, "VALIDATION_ERROR": 422}
+
+        class QueryBody(BaseModel):
+            node: str = Field(description="Qualified name, 'backend:fqtn'.")
+            paths: list[str] | None = None
+            views: list[str] | None = None
+            depth: int | None = None
+            detail: str | None = None
+            budget: int | None = None
+            inherit: bool | None = None
+            format: str = "json"
+            backend: str | None = None
+
+        def service(request: Request, backend: str | None) -> ContextService | JSONResponse:
+            registry = request.app.state.backend_registry
+            if registry is None:
+                reason = request.app.state.backend_error or "No backend is configured."
+                return JSONResponse(
+                    status_code=409,
+                    content=err(ErrorCode.NO_BACKEND_CONFIGURED, reason, {"configured": False}),
+                )
+            schema: SchemaRegistry | None = getattr(request.app.state, "schema_registry", None)
+            try:
+                sources = registry.read_set(backend)
+            except BackendAddressError as exc:
+                return JSONResponse(status_code=422, content=backend_failure(exc))
+            try:
+                return service_for(
+                    schema or get_default_registry(), sources, profile=registry.profile
+                )
+            except ContextError as exc:
+                return refuse(exc)
+
+        def refuse(exc: ContextError) -> JSONResponse:
+            return JSONResponse(
+                status_code=status_of.get(exc.code, 422),
+                content=err(exc.code, exc.message, exc.details),
+            )
+
+        @router.get("/map", response_model=None)
+        def get_map(
+            request: Request, node: str, format: str = "json", backend: str | None = None
+        ) -> dict[str, Any] | JSONResponse:
+            found = service(request, backend)
+            if isinstance(found, JSONResponse):
+                return found
+            try:
+                payload = found.map(node)
+            except ContextError as exc:
+                return refuse(exc)
+            if format == "markdown":
+                return ok({"markdown": found.markdown_for_map(payload), "map": payload})
+            return ok(payload)
+
+        @router.post("/query", response_model=None)
+        def post_query(request: Request, body: QueryBody) -> dict[str, Any] | JSONResponse:
+            found = service(request, body.backend)
+            if isinstance(found, JSONResponse):
+                return found
+            asked = ContextRequest(
+                paths=tuple(body.paths) if body.paths is not None else None,
+                views=tuple(body.views) if body.views is not None else None,
+                depth=body.depth,
+                detail=body.detail,
+                budget=body.budget,
+                inherit=body.inherit,
+                format=body.format,
+            )
+            try:
+                payload = found.query(body.node, asked)
+                if body.format == "markdown":
+                    markdown = found.markdown_for_result(body.node, payload)
+                    return ok({"markdown": markdown, "result": payload})
+            except ContextError as exc:
+                return refuse(exc)
+            return ok(payload)
+
+        @router.get("/policy", response_model=None)
+        def get_policy(
+            request: Request, node: str, backend: str | None = None
+        ) -> dict[str, Any] | JSONResponse:
+            found = service(request, backend)
+            if isinstance(found, JSONResponse):
+                return found
+            try:
+                return ok(found.explain(node))
+            except ContextError as exc:
+                return refuse(exc)
+
+        return router

katalyst_plugin_context/schema.py

@@ -0,0 +1,200 @@
+"""The JSON Schemas the context plugin publishes for its three kinds of settings.
+
+- :data:`CONFIG_SCHEMA`: its ``spec.plugins[].config`` in config.yaml (``PluginManifest.config_schema``);
+- :data:`SETTINGS_SCHEMA`: its ``plugin_settings["context"]`` section on a wing or kind;
+- :data:`NODE_SETTINGS_SCHEMA`: a node's ``spec.extensions.context``.
+
+``kata tax lint`` checks bundle and node sections against the last two. A config save checks
+the first. The plugin checks all three again on every call, and a section that fails is
+refused rather than ignored, because ignoring a narrowing would widen what an agent sees.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from katalyst_plugin_context.domain.context import ContextError
+from katalyst_plugin_context.domain.paths import STEP_RE
+
+__all__ = [
+    "CONFIG_SCHEMA",
+    "NODE_SETTINGS_SCHEMA",
+    "SETTINGS_SCHEMA",
+    "check",
+]
+
+_DRAFT = "https://json-schema.org/draft/2020-12/schema"
+_DETAIL = {"enum": ["refs", "summary", "full"]}
+_STEP = {"type": "string", "pattern": f"^{STEP_RE}$"}
+_PATH = {"type": "string", "pattern": f"^{STEP_RE}(/{STEP_RE})*$"}
+_NAME = "^[a-z][a-z0-9-]*$"
+
+_POLICY: dict[str, Any] = {
+    "type": "object",
+    "title": "Policy",
+    "description": "Limits that can only narrow what an agent is given.",
+    "additionalProperties": False,
+    "properties": {
+        "paths": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "allow": {
+                    "type": "array",
+                    "items": _STEP,
+                    "description": "Only steps these patterns match are visible.",
+                },
+                "deny": {
+                    "type": "array",
+                    "items": _STEP,
+                    "description": "Steps these patterns match are hidden.",
+                },
+            },
+        },
+        "max_depth": {"type": "integer", "minimum": 0, "description": "Most hops from the node."},
+        "detail": {
+            "type": "array",
+            "items": _DETAIL,
+            "description": "Detail levels allowed (refs is always allowed).",
+        },
+        "budget": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {"max": {"type": "integer", "minimum": 1}},
+        },
+        "inheritance": {"type": "boolean", "description": "Whether anything may be inherited."},
+        "always_include": {
+            "type": "array",
+            "items": {"type": "string", "pattern": _NAME},
+            "description": "Views returned without being asked; only declared views count.",
+        },
+    },
+}
+
+_DEFAULTS: dict[str, Any] = {
+    "type": "object",
+    "title": "Defaults",
+    "description": "Used when an agent does not say; clamped into the policy.",
+    "additionalProperties": False,
+    "properties": {
+        "depth": {"type": "integer", "minimum": 0},
+        "detail": _DETAIL,
+        "budget": {"type": "integer", "minimum": 1},
+        "inherit": {"type": "boolean"},
+    },
+}
+
+_VIEW: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["paths"],
+    "properties": {
+        "title": {"type": "string"},
+        "description": {"type": "string"},
+        "paths": {"type": "array", "items": _PATH, "minItems": 1},
+        "inherit": {"type": "boolean"},
+        "detail": _DETAIL,
+        "priority": {"type": "integer"},
+        "order": {"enum": ["blocking-first"]},
+    },
+}
+
+_RULE: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "match": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "backend": {"type": "array", "items": {"type": "string"}},
+                "kind": {"type": "array", "items": {"type": "string"}},
+                "wing": {"type": "array", "items": {"type": "string"}},
+                "fqtn": {"type": "array", "items": {"type": "string"}},
+                "name": {"type": "array", "items": {"type": "string"}},
+                "labels": {"type": "object", "additionalProperties": {"type": "string"}},
+            },
+        },
+        "policy": _POLICY,
+        "defaults": _DEFAULTS,
+    },
+}
+
+CONFIG_SCHEMA: dict[str, Any] = {
+    "$schema": _DRAFT,
+    "type": "object",
+    "title": "Context",
+    "additionalProperties": False,
+    "properties": {
+        "policy": _POLICY,
+        "defaults": _DEFAULTS,
+        "profiles": {
+            "type": "object",
+            "description": "Stricter policy for one profile, by profile name.",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": False,
+                "properties": {
+                    "policy": _POLICY,
+                    "defaults": _DEFAULTS,
+                    "rules": {"type": "array", "items": _RULE},
+                },
+            },
+        },
+    },
+}
+
+SETTINGS_SCHEMA: dict[str, Any] = {
+    "$schema": _DRAFT,
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "title_field": {"type": "string", "description": "Spec field holding an item's title."},
+        "summary_fields": {"type": "array", "items": {"type": "string"}},
+        "priority": {"type": "integer"},
+        "views": {
+            "type": "object",
+            "propertyNames": {"pattern": _NAME},
+            "additionalProperties": _VIEW,
+        },
+        "policy": _POLICY,
+        "defaults": _DEFAULTS,
+    },
+}
+
+NODE_SETTINGS_SCHEMA: dict[str, Any] = {
+    "$schema": _DRAFT,
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {"policy": _POLICY, "defaults": _DEFAULTS},
+}
+
+
+def _location(parts: list[object]) -> str:
+    return "".join(f"[{p}]" if isinstance(p, int) else f".{p}" for p in parts)
+
+
+def check(schema: Mapping[str, Any], instance: object, *, where: str) -> None:
+    """Refuse *instance* when *schema* does not accept it.
+
+    Raises:
+        ContextError: ``VALIDATION_ERROR``, naming *where* and the first problem's key.
+    """
+    from jsonschema import validators
+
+    validator_class = cast("Any", validators.validator_for(dict(schema)))
+    errors = sorted(
+        validator_class(dict(schema)).iter_errors(instance),
+        key=lambda e: [str(p) for p in e.absolute_path],
+    )
+    if errors:
+        first = errors[0]
+        raise ContextError(
+            "VALIDATION_ERROR",
+            f"{where}{_location(list(first.absolute_path))}: {first.message}",
+            {
+                "where": where,
+                "problems": [f"{_location(list(e.absolute_path))}: {e.message}" for e in errors],
+            },
+        )