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

katalyst_plugin_context/__init__.py

@@ -0,0 +1,8 @@
+"""Katalyst context plugin: the right context from the taxonomy for an agent working on a
+node, over MCP (``taxonomy_context_map``, ``taxonomy_context``), REST (``/ext/context``) and
+the CLI (``kata tax context``).
+"""
+
+from katalyst_plugin_context.plugin import ContextPlugin
+
+__all__ = ["ContextPlugin"]

katalyst_plugin_context/adapters/runtime_graph.py

@@ -0,0 +1,126 @@
+"""The graph one call walks, read from the profile's backends through the port.
+
+Each backend is read once (``load_documents`` and ``list_relationships``, the two calls every
+backend type implements, through the profile's permission gate) and the corpus is narrowed by
+the profile's filters (:func:`katalyst_taxonomy.services.filters.visible_nodes`). An edge is
+kept only when both its ends are visible. A reference into another backend is stored as
+``backend:fqtn`` and keyed that way, so an edge held by one backend can reach a node of
+another.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, cast
+
+from katalyst_engine.model.node import Node
+from katalyst_taxonomy.engine.accessors import (
+    get_extensions_map,
+    get_markdown_body,
+    get_node_backend,
+)
+from katalyst_taxonomy.engine.identity import split_backend_prefix
+from katalyst_taxonomy.ports.backend import TaxonomyBackend
+
+from katalyst_plugin_context.domain.graph import Edge, Graph, GraphNode
+
+__all__ = ["build_graph", "graph_from"]
+
+
+def _graph_node(doc: Node, backend: str, key: str) -> GraphNode:
+    spec = {k: v for k, v in doc.spec.items() if not str(k).startswith("_")}
+    return GraphNode(
+        key=key,
+        kind=doc.kind,
+        name=doc.name,
+        fqn=doc.fqn or doc.name,
+        backend=backend,
+        spec=spec,
+        description=doc.description or str(spec.get("description") or ""),
+        body=get_markdown_body(doc),
+        extensions=cast("dict[str, Any]", get_extensions_map(doc)),
+    )
+
+
+def graph_from(
+    documents: Iterable[tuple[str, Node]],
+    relationships: Iterable[tuple[str, str, str, str]],
+    *,
+    hidden: Iterable[tuple[str, str]] = (),
+) -> Graph:
+    """A graph over *documents* (``(holder backend, node)``) and *relationships*
+    (``(holder backend, source fqtn, rel, target fqtn)``).
+
+    An edge to an address in *hidden* (``(backend, fqtn)`` of nodes the profile's filters
+    hide) is left out silently. Any other edge that reaches no node is counted as dropped.
+    Nothing about a hidden node is counted.
+    """
+    hidden_addresses = set(hidden)
+    by_address: dict[tuple[str, str], list[str]] = {}
+    nodes: list[GraphNode] = []
+    pending: list[tuple[str, str, Node]] = []
+    for holder, doc in documents:
+        backend = get_node_backend(doc) or holder
+        fqn = doc.fqn or doc.name
+        pending.append((backend, fqn, doc))
+        by_address.setdefault((backend, fqn), []).append(doc.kind)
+    for backend, fqn, doc in pending:
+        shared = len(by_address[(backend, fqn)]) > 1
+        key = f"{backend}:{fqn}#{doc.kind}" if shared else f"{backend}:{fqn}"
+        nodes.append(_graph_node(doc, backend, key))
+
+    def key_of(holder: str, address: str) -> str | None:
+        prefix, rest = split_backend_prefix(address)
+        backend = prefix or holder
+        kinds = by_address.get((backend, rest))
+        if kinds is None or len(kinds) != 1:
+            return None
+        return f"{backend}:{rest}"
+
+    edges: list[Edge] = []
+    dropped = 0
+    for holder, source, rel, target in relationships:
+        source_key, target_key = key_of(holder, source), key_of(holder, target)
+        if source_key is None or target_key is None:
+            ends = (_address(holder, source), _address(holder, target))
+            if not any(end in hidden_addresses for end in ends):
+                dropped += 1
+            continue
+        edges.append(Edge(rel=rel, source=source_key, target=target_key))
+    return Graph(nodes, edges, dropped=dropped)
+
+
+def _address(holder: str, value: str) -> tuple[str, str]:
+    prefix, rest = split_backend_prefix(value)
+    return (prefix or holder, rest)
+
+
+def build_graph(
+    sources: Iterable[tuple[str, TaxonomyBackend]], *, profile: str | None = None
+) -> Graph:
+    """Read every backend in *sources* once and build the graph the profile may see.
+
+    Raises:
+        PermissionDeniedError: If the profile may not read a backend (as every read does).
+    """
+    from katalyst_taxonomy.services.filters import visible_nodes
+
+    loaded: list[tuple[str, Node]] = []
+    relationships: list[tuple[str, str, str, str]] = []
+    for name, backend in sources:
+        loaded.extend((name, doc) for doc in backend.load_documents())
+        relationships.extend(
+            (name, rel.source_fqtn, rel.rel_type, rel.target_fqtn)
+            for rel in backend.list_relationships()
+        )
+    visible = {id(doc) for doc in visible_nodes(None, [doc for _, doc in loaded], profile=profile)}
+    hidden = (
+        (get_node_backend(doc) or holder, doc.fqn or doc.name)
+        for holder, doc in loaded
+        if id(doc) not in visible
+    )
+    return graph_from(
+        ((holder, doc) for holder, doc in loaded if id(doc) in visible),
+        relationships,
+        hidden=list(hidden),
+    )

katalyst_plugin_context/cli.py

@@ -0,0 +1,139 @@
+# pyright: reportUnusedFunction=false
+"""``kata tax context NODE`` — what an agent working on a node is given, from the shell."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import click
+
+if TYPE_CHECKING:
+    from katalyst_taxonomy_cli.context import CliContext
+
+    from katalyst_plugin_context.service import ContextService
+
+
+def _service(ctx: CliContext, backend: str | None) -> ContextService:
+    from katalyst_taxonomy.config.backends import load_backends
+    from katalyst_taxonomy.config.routing import BackendAddressError
+    from katalyst_taxonomy.engine.bridge import get_default_registry
+
+    from katalyst_plugin_context.composition import service_for
+
+    try:
+        backends = load_backends(None, profile=ctx.profile)
+        sources = backends.read_set(backend)
+    except (BackendAddressError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    return service_for(get_default_registry(), sources, profile=backends.profile)
+
+
+def _emit(payload: Any, fmt: str, markdown: str | None = None) -> None:
+    if fmt == "json":
+        click.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        click.echo(markdown if markdown is not None else json.dumps(payload, indent=2), nl=False)
+
+
+def create_command() -> click.Command:
+    """Entry point for ``katalyst_taxonomy.cli``: contributes ``kata tax context``."""
+
+    @click.command("context")
+    @click.argument("node")
+    @click.option(
+        "--map", "show_map", is_flag=True, help="Show the map: relationships, views, options."
+    )
+    @click.option(
+        "--policy",
+        "show_policy",
+        is_flag=True,
+        help="Show the effective policy for NODE: layers, limits and notes.",
+    )
+    @click.option(
+        "--path",
+        "paths",
+        multiple=True,
+        metavar="REL[:in|out[:KIND,...]][/...]",
+        help="A path to walk; repeatable.",
+    )
+    @click.option("--view", "views", multiple=True, metavar="NAME", help="A view; repeatable.")
+    @click.option("--depth", type=int, default=None, help="Repetitions of a single-step path.")
+    @click.option(
+        "--detail",
+        type=click.Choice(["refs", "summary", "full"]),
+        default=None,
+        help="Item detail.",
+    )
+    @click.option("--budget", type=int, default=None, metavar="TOKENS", help="Approximate tokens.")
+    @click.option("--inherit/--no-inherit", default=None, help="Also walk from NODE's ancestors.")
+    @click.option("--backend", default=None, help="Read only this backend.")
+    @click.option(
+        "--format",
+        "fmt",
+        type=click.Choice(["markdown", "json"]),
+        default="markdown",
+        show_default=True,
+    )
+    @click.pass_obj
+    def context(
+        ctx: CliContext,
+        node: str,
+        show_map: bool,
+        show_policy: bool,
+        paths: tuple[str, ...],
+        views: tuple[str, ...],
+        depth: int | None,
+        detail: str | None,
+        budget: int | None,
+        inherit: bool | None,
+        backend: str | None,
+        fmt: str,
+    ) -> None:
+        """What the taxonomy holds around NODE, and why each item is relevant.
+
+        NODE is a qualified name, 'backend:fqtn' (or the FQTN when one backend holds it).
+        Without --map or --policy, prints the views NODE's kind always includes, or the
+        whole neighbourhood at depth 1 if it declares none; with --path or --view, exactly
+        those. Policy from the schema, the node and the profile can only narrow a request.
+
+        Examples:
+
+            kata tax context repo:shop.api.web --map
+
+            kata tax context repo:shop.api.web --view some-view --budget 8000
+
+            kata tax context repo:shop.api.web --path 'SOME_REL:in' --detail full --format json
+        """
+        from katalyst_plugin_context.domain.context import ContextError, ContextRequest
+
+        try:
+            service = _service(ctx, backend)
+            if show_policy:
+                _emit(service.explain(node), "json")
+                return
+            if show_map:
+                payload = service.map(node)
+                _emit(
+                    payload, fmt, service.markdown_for_map(payload) if fmt == "markdown" else None
+                )
+                return
+            request = ContextRequest(
+                paths=paths or None,
+                views=views or None,
+                depth=depth,
+                detail=detail,
+                budget=budget,
+                inherit=inherit,
+                format=fmt,
+            )
+            payload = service.query(node, request)
+            _emit(
+                payload,
+                fmt,
+                service.markdown_for_result(node, payload) if fmt == "markdown" else None,
+            )
+        except ContextError as exc:
+            raise click.ClickException(exc.message) from exc
+
+    return context

katalyst_plugin_context/composition.py

@@ -0,0 +1,49 @@
+"""Composition: a :class:`ContextService` for one call, from each host's own objects.
+
+Every host reads the same way: the profile's backends (through its permission gate), its
+filters, the schema registry, and the plugin's config for the active profile, read **per
+call** from the current configuration, so a Settings save or a profile switch takes effect
+on the next call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from katalyst_engine.schema.registry import SchemaRegistry
+from katalyst_taxonomy.ports.backend import TaxonomyBackend
+
+from katalyst_plugin_context.adapters.runtime_graph import build_graph
+from katalyst_plugin_context.service import NAMESPACE, ContextService
+
+__all__ = ["plugin_config", "service_for"]
+
+
+def plugin_config(profile: str | None) -> tuple[Mapping[str, Any], str | None]:
+    """This plugin's ``spec.plugins[].config`` and the active profile's name.
+
+    ``({}, profile)`` when no configuration resolves (nothing configured yet): with nothing
+    declared, nothing narrows.
+    """
+    from katalyst_taxonomy.config.backends import resolve_effective_config
+    from katalyst_taxonomy.config.plugins import selection_from_config
+
+    try:
+        effective = resolve_effective_config(None, profile=profile)
+    except Exception:  # noqa: BLE001 - no config is a normal first-run state
+        return {}, profile
+    selection = selection_from_config(effective.config, effective.selection.profile)
+    return selection.config_for(NAMESPACE), effective.selection.name or profile
+
+
+def service_for(
+    registry: SchemaRegistry,
+    sources: Iterable[tuple[str, TaxonomyBackend]],
+    *,
+    profile: str | None,
+) -> ContextService:
+    """The service over what *sources* hold, under the profile named *profile*."""
+    config, active = plugin_config(profile)
+    graph = build_graph(sources, profile=active)
+    return ContextService(registry, graph, config=config, profile=active)