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

katalyst_plugin_context/service.py

@@ -0,0 +1,319 @@
+"""The context service: the policy for a node, and its map and context, on one call's graph.
+
+It reads each layer of policy from where it is declared (the wing's and kind's
+``plugin_settings["context"]``, the node's ``spec.extensions.context``, the plugin's config),
+checks each against the plugin's schema, folds them, and asks the domain for the payload.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from katalyst_engine.schema.definition import VALUE_FLAG_BLOCKING
+from katalyst_engine.schema.registry import SchemaRegistry
+from katalyst_taxonomy.engine.relationships import CHILD_OF
+
+from katalyst_plugin_context.domain.context import (
+    ContextError,
+    ContextRequest,
+    build_map,
+    build_result,
+    json_size,
+)
+from katalyst_plugin_context.domain.graph import Graph, GraphNode
+from katalyst_plugin_context.domain.markdown import item_size, render_map, render_result
+from katalyst_plugin_context.domain.paths import PathSyntaxError, parse_path
+from katalyst_plugin_context.domain.policy import Layer, Policy, fold
+from katalyst_plugin_context.domain.settings import ItemHints, View, item_hints, views_from
+from katalyst_plugin_context.schema import (
+    CONFIG_SCHEMA,
+    NODE_SETTINGS_SCHEMA,
+    SETTINGS_SCHEMA,
+    check,
+)
+
+__all__ = ["NAMESPACE", "ContextService", "RegistrySchema"]
+
+#: The plugin's name, and so the key of its settings sections everywhere.
+NAMESPACE = "context"
+
+FORMATS = ("json", "markdown")
+
+
+class RegistrySchema:
+    """What the schema registry says about kinds and relationships, for the domain."""
+
+    def __init__(self, registry: SchemaRegistry) -> None:
+        self._registry = registry
+        definition = registry.get_relationship("child_of")
+        self.parent_rel = definition.graph_label if definition is not None else CHILD_OF
+        self._hints: dict[str, ItemHints] = {}
+
+    def sections(self, kind: str) -> tuple[Mapping[str, Any] | None, Mapping[str, Any] | None, str]:
+        """The wing's and the kind's context sections, and the wing's name."""
+        definition = self._registry.get_node_definition(kind)
+        if definition is None:
+            return None, None, ""
+        wing = self._registry.get_wing_definition(definition.wing) if definition.wing else None
+        return (
+            wing.plugin_settings.get(NAMESPACE) if wing is not None else None,
+            definition.plugin_settings.get(NAMESPACE),
+            definition.wing,
+        )
+
+    def kind_label(self, kind: str) -> str:
+        return self._registry.display_label_for(kind) if kind in self._registry else kind
+
+    def hints(self, kind: str) -> ItemHints:
+        if kind not in self._hints:
+            wing, own, _ = self.sections(kind)
+            self._hints[kind] = item_hints(wing, own)
+        return self._hints[kind]
+
+    def declared_fields(self, kind: str) -> Sequence[tuple[str, str]]:
+        definition = self._registry.get_node_definition(kind)
+        return [(f.name, f.field_type) for f in definition.fields] if definition else []
+
+    def blocking(self, kind: str, spec: Mapping[str, Any]) -> list[dict[str, Any]]:
+        definition = self._registry.get_node_definition(kind)
+        if definition is None:
+            return []
+        found: list[dict[str, Any]] = []
+        for field in definition.fields:
+            if not any(meta.flags for meta in field.value_meta):
+                continue
+            # A node that doesn't say holds the field's default, which may block.
+            value = spec.get(field.name, field.default)
+            if not isinstance(value, str) or value not in field.allowed_values:
+                continue
+            meta = field.meta_for(value)
+            found.append(
+                {
+                    "field": field.name,
+                    "value": value,
+                    "blocking": meta is not None and VALUE_FLAG_BLOCKING in meta.flags,
+                }
+            )
+        return found
+
+    def relationship_description(self, rel: str) -> str:
+        definition = self._registry.get_relationship_by_graph_label(rel)
+        return definition.description if definition is not None else ""
+
+    def carried(self, kind: str) -> Sequence[tuple[str, frozenset[str]]]:
+        from katalyst_taxonomy.engine.relationships import carriers_of
+
+        return [(c.rel_type, c.target_kinds) for c in carriers_of(self._registry, kind)]
+
+
+def _glob(pattern: str) -> re.Pattern[str]:
+    """An fqtn glob: ``*`` is one segment, ``**`` any number."""
+    out = ""
+    i = 0
+    while i < len(pattern):
+        if pattern.startswith("**", i):
+            out += ".*"
+            i += 2
+        elif pattern[i] == "*":
+            out += "[^.]*"
+            i += 1
+        else:
+            out += re.escape(pattern[i])
+            i += 1
+    return re.compile(f"^{out}$")
+
+
+def _matches(match: Mapping[str, Any], node: GraphNode, wing: str) -> bool:
+    """Whether a profile rule's ``match`` selects *node*; every declared criterion must hold."""
+
+    def listed(key: str) -> list[str]:
+        return [str(v) for v in cast("list[object]", match.get(key) or [])]
+
+    if listed("backend") and node.backend not in listed("backend"):
+        return False
+    if listed("kind") and node.kind not in listed("kind"):
+        return False
+    if listed("wing") and wing not in listed("wing"):
+        return False
+    if listed("name") and not any(fnmatch.fnmatchcase(node.name, p) for p in listed("name")):
+        return False
+    if listed("fqtn") and not any(
+        _glob(p).match(node.key if ":" in p else node.fqn) for p in listed("fqtn")
+    ):
+        return False
+    labels = cast("Mapping[str, str]", match.get("labels") or {})
+    node_labels = cast("Mapping[str, Any]", node.spec.get("labels") or {})
+    return all(str(node_labels.get(k)) == v for k, v in labels.items())
+
+
+class ContextService:
+    """Map, context and policy for the nodes of one call's graph."""
+
+    def __init__(
+        self,
+        registry: SchemaRegistry,
+        graph: Graph,
+        *,
+        config: Mapping[str, Any] | None = None,
+        profile: str | None = None,
+    ) -> None:
+        self._registry = registry
+        self._schema = RegistrySchema(registry)
+        self._graph = graph
+        self._config = dict(config or {})
+        self._profile = profile
+        check(CONFIG_SCHEMA, self._config, where=f"spec.plugins[{NAMESPACE}].config")
+
+    # ── addressing ──────────────────────────────────────────────────────
+
+    def resolve(self, address: str) -> str:
+        """The graph key *address* names: ``backend:fqtn``, or an FQTN one backend holds.
+
+        Raises:
+            ContextError: ``NOT_FOUND`` (with the qualified names a bare name may mean)
+                or ``INVALID_INPUT`` (an FQTN several backends hold).
+        """
+        text, _, kind = address.strip().partition("#")
+        nodes = self._graph.nodes.values()
+
+        def selected(node: GraphNode) -> bool:
+            return not kind or node.kind == kind
+
+        if ":" in text:
+            found = [n.key for n in nodes if f"{n.backend}:{n.fqn}" == text and selected(n)]
+        else:
+            found = [n.key for n in nodes if n.fqn == text and selected(n)]
+        if len(found) == 1:
+            return found[0]
+        if len(found) > 1:
+            raise ContextError(
+                "INVALID_INPUT",
+                f"{address!r} names more than one node; use one of: {', '.join(sorted(found))}",
+                {"candidates": sorted(found)},
+            )
+        leaf = text.rsplit(":", 1)[-1].rsplit(".", 1)[-1]
+        meant = sorted(n.key for n in nodes if n.name == leaf and selected(n))
+        hint = (
+            f"; a node is named by its qualified name: use {' or '.join(map(repr, meant[:10]))}"
+            if meant
+            else ""
+        )
+        raise ContextError(
+            "NOT_FOUND", f"Node {address!r} not found{hint}", {"node": address, "candidates": meant}
+        )
+
+    # ── policy ──────────────────────────────────────────────────────────
+
+    def policy_for(self, key: str) -> tuple[Policy, dict[str, View]]:
+        """The effective policy for the node at *key*, and the views its kind declares.
+
+        Raises:
+            ContextError: ``VALIDATION_ERROR`` if a layer breaks the plugin's schema.
+        """
+        node = self._graph.nodes[key]
+        wing_section, kind_section, wing = self._schema.sections(node.kind)
+        layers: list[Layer] = []
+        for label, section in ((f"wing:{wing}", wing_section), (f"kind:{node.kind}", kind_section)):
+            if section is None:
+                continue
+            check(SETTINGS_SCHEMA, section, where=f"{label} plugin_settings.{NAMESPACE}")
+            layers.append(_layer(label, section))
+        own = node.extensions.get(NAMESPACE)
+        if own is not None:
+            check(NODE_SETTINGS_SCHEMA, own, where=f"{key} spec.extensions.{NAMESPACE}")
+            layers.append(_layer(f"node:{key}", cast("Mapping[str, Any]", own)))
+        layers.extend(self._profile_layers(node, wing))
+        try:
+            views = views_from(
+                wing_section,
+                kind_section,
+                wing_label=f"wing:{wing}",
+                kind_label=f"kind:{node.kind}",
+            )
+            policy = fold(layers, views=sorted(views))
+        except PathSyntaxError as exc:
+            raise ContextError("VALIDATION_ERROR", str(exc)) from exc
+        return policy, views
+
+    def _profile_layers(self, node: GraphNode, wing: str) -> list[Layer]:
+        config = self._config
+        layers: list[Layer] = []
+        if config.get("policy") or config.get("defaults"):
+            layers.append(_layer("plugin config", config))
+        profiles = cast("Mapping[str, Mapping[str, Any]]", config.get("profiles") or {})
+        section = profiles.get(self._profile or "") if self._profile else None
+        if section is None:
+            return layers
+        label = f"profile:{self._profile}"
+        layers.append(_layer(label, section))
+        for index, rule in enumerate(cast("list[Mapping[str, Any]]", section.get("rules") or [])):
+            if _matches(cast("Mapping[str, Any]", rule.get("match") or {}), node, wing):
+                layers.append(_layer(f"{label}#rules[{index}]", rule))
+        return layers
+
+    # ── payloads ────────────────────────────────────────────────────────
+
+    def map(self, address: str) -> dict[str, Any]:
+        """Everything around the node at *address*: relationships, inheritance, views, options."""
+        key = self.resolve(address)
+        policy, views = self.policy_for(key)
+        return build_map(self._graph, self._schema, key, policy, views)
+
+    def query(self, address: str, request: ContextRequest) -> dict[str, Any]:
+        """The items *request* asks for around the node at *address*."""
+        if request.format not in FORMATS:
+            raise ContextError(
+                "INVALID_INPUT", f"format must be json or markdown; got {request.format!r}"
+            )
+        for text in request.paths or ():
+            try:
+                parse_path(text)
+            except PathSyntaxError as exc:
+                raise ContextError("INVALID_INPUT", str(exc), {"path": text}) from exc
+        key = self.resolve(address)
+        policy, views = self.policy_for(key)
+        size = item_size if request.format == "markdown" else json_size
+        return build_result(self._graph, self._schema, key, policy, views, request, size_of=size)
+
+    def explain(self, address: str) -> dict[str, Any]:
+        """The effective policy for the node at *address*: layers, limits and notes."""
+        key = self.resolve(address)
+        policy, views = self.policy_for(key)
+        return {
+            "node": key,
+            "effective": policy.describe(),
+            "views": {
+                name: {
+                    "paths": view.path_texts,
+                    "declaredBy": view.declared_by,
+                    "title": view.title,
+                }
+                for name, view in sorted(views.items())
+            },
+        }
+
+    def markdown_for_map(self, payload: Mapping[str, Any]) -> str:
+        return render_map(payload)
+
+    def markdown_for_result(self, address: str, payload: Mapping[str, Any]) -> str:
+        key = self.resolve(address)
+        _, views = self.policy_for(key)
+        ancestors = [
+            {"qualifiedName": a, "kind": self._graph.nodes[a].kind}
+            for a in self._graph.ancestors(key, self._schema.parent_rel)
+        ]
+        declared = {
+            name: {"title": v.title, "description": v.description} for name, v in views.items()
+        }
+        return render_result(payload, views=declared, ancestors=ancestors)
+
+
+def _layer(label: str, section: Mapping[str, Any]) -> Layer:
+    return Layer(
+        label=label,
+        policy=cast("Mapping[str, Any]", section.get("policy") or {}),
+        defaults=cast("Mapping[str, Any]", section.get("defaults") or {}),
+    )

katalyst_plugin_context-0.1.1a1.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: katalyst-plugin-context
+Version: 0.1.1a1
+Summary: Katalyst context plugin — the right context from the taxonomy for an agent working on a node
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: jsonschema>=4
+Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-taxonomy-cli<3,>=2
+Requires-Dist: katalyst-taxonomy-mcp<5,>=4
+Requires-Dist: katalyst-taxonomy<6,>=5

katalyst_plugin_context-0.1.1a1.dist-info/RECORD

@@ -0,0 +1,23 @@
+katalyst_plugin_context/__init__.py,sha256=L3hMpS4HTRZa1wuRAOLcmhuwTMkcGuKhwS8gM12zMZQ,306
+katalyst_plugin_context/cli.py,sha256=ZULcaiaKuKmkXhtGjv-mnK_k8GF4EmiFvaubtzoojzY,4889
+katalyst_plugin_context/composition.py,sha256=FdlswZYtQzNwAHbjlQ-J1DQM7IGFyUM6sujAgRnGa4w,1980
+katalyst_plugin_context/lint.py,sha256=ag7sr-QNcgRg6-npC8pVD9f9idySzlFvSR_dxQWsIdw,6258
+katalyst_plugin_context/mcp_tools.py,sha256=L8ITnVb4Yzxk8MCCBwe5llvNIbcDyBJU5lD1dosrjZQ,6035
+katalyst_plugin_context/plugin.py,sha256=yrw7bT0X4TCJRMVJlxJXShCQnp7DKSJeZqEZalVXXZk,2432
+katalyst_plugin_context/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+katalyst_plugin_context/rest.py,sha256=5GcLdfEaY7ntbwevt6op1b82pDJGvAOMlGCGLclgXTs,5898
+katalyst_plugin_context/schema.py,sha256=vI_tfLmVtuioCv_KgXmiqKSx1sa2wLvcrYjunFBNLsk,6755
+katalyst_plugin_context/service.py,sha256=sQttBS95ZmfXeTwOVOWe517piofwo9Y5Z2DcEnCOAMU,13375
+katalyst_plugin_context/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+katalyst_plugin_context/adapters/runtime_graph.py,sha256=gOqCsC_zs1glLcMhZEhCZOsG1-uomhDqDnYzmXjuCcU,4847
+katalyst_plugin_context/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+katalyst_plugin_context/domain/context.py,sha256=xe-7ASwIsnagrC53o4QxtJeOOU2rvMNQ3CItLkfbbIQ,27411
+katalyst_plugin_context/domain/graph.py,sha256=bknXgiof25-2j4I2GPsIv-u0s76LqzHajsXCU5utYPA,3425
+katalyst_plugin_context/domain/markdown.py,sha256=KbHhg8VWQuVEU7t1LT26Ie6cSEJfhkJCiP-o8XGaaBw,8779
+katalyst_plugin_context/domain/paths.py,sha256=VhVHEkPdfi-gdD4SmnjSX3ybUddM0Lw64zprR9u9CJ4,3830
+katalyst_plugin_context/domain/policy.py,sha256=8yLiYrhBSoIs3YKTTgDb5MjfF3dXWh-MirNJ65QfR7Q,13771
+katalyst_plugin_context/domain/settings.py,sha256=PH-t52j3s-X0bOl5vcc9ZMqvxW2CTUa0nyqW-hrnens,3153
+katalyst_plugin_context-0.1.1a1.dist-info/METADATA,sha256=qf13Dtxc0hOySDIRYUm-k8bdhe95HjTlVFpGTkHB5VI,455
+katalyst_plugin_context-0.1.1a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+katalyst_plugin_context-0.1.1a1.dist-info/entry_points.txt,sha256=0kZT_Rlbx8YcvLb2L_Heo4JPILmpERHySD-op6LDvpc,154
+katalyst_plugin_context-0.1.1a1.dist-info/RECORD,,

katalyst_plugin_context-0.1.1a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

katalyst_plugin_context-0.1.1a1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[katalyst_taxonomy.cli]
+context = katalyst_plugin_context.cli:create_command
+
+[katalyst_taxonomy.plugins]
+context = katalyst_plugin_context:ContextPlugin