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

katalyst_plugin_context/domain/graph.py

@@ -0,0 +1,97 @@
+"""The relationship graph one call walks: visible nodes and the edges between them.
+
+Built once per call from what the profile's backends hold
+(:mod:`katalyst_plugin_context.adapters.runtime_graph`) and walked in memory. Every node is
+keyed by its qualified name, ``backend:fqtn``. The graph holds only nodes the profile may see,
+and only edges whose both ends it may see, so a walk can never pass through a hidden node.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from katalyst_plugin_context.domain.paths import IN, OUT
+
+__all__ = ["Edge", "Graph", "GraphNode", "Neighbour"]
+
+
+@dataclass(frozen=True, slots=True)
+class GraphNode:
+    """One visible node."""
+
+    key: str
+    """``backend:fqtn``: the node's qualified name."""
+    kind: str
+    name: str
+    fqn: str
+    backend: str
+    spec: Mapping[str, Any] = field(default_factory=lambda: dict[str, Any]())
+    description: str = ""
+    body: str | None = None
+    extensions: Mapping[str, Any] = field(default_factory=lambda: dict[str, Any]())
+    """The node's ``spec.extensions``: each plugin's section."""
+
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    """A relationship between two visible nodes."""
+
+    rel: str
+    source: str
+    target: str
+
+
+@dataclass(frozen=True, slots=True)
+class Neighbour:
+    """An edge seen from one of its ends."""
+
+    rel: str
+    direction: str
+    other: str
+
+
+class Graph:
+    """Visible nodes and the edges between them, indexed both ways."""
+
+    def __init__(
+        self, nodes: Iterable[GraphNode], edges: Iterable[Edge], *, dropped: int = 0
+    ) -> None:
+        self.nodes: dict[str, GraphNode] = {node.key: node for node in nodes}
+        self._out: dict[str, list[Edge]] = defaultdict(list)
+        self._in: dict[str, list[Edge]] = defaultdict(list)
+        seen: set[Edge] = set()
+        self.dropped = dropped
+        """Edges left out because an end is not a visible node (hidden, or not read)."""
+        for edge in edges:
+            if edge.source not in self.nodes or edge.target not in self.nodes:
+                self.dropped += 1
+                continue
+            if edge in seen:
+                continue
+            seen.add(edge)
+            self._out[edge.source].append(edge)
+            self._in[edge.target].append(edge)
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.nodes
+
+    def neighbours(self, key: str) -> Iterator[Neighbour]:
+        """Every edge at *key*, outgoing first, in a stable order."""
+        for edge in sorted(self._out.get(key, ()), key=lambda e: (e.rel, e.target)):
+            yield Neighbour(edge.rel, OUT, edge.target)
+        for edge in sorted(self._in.get(key, ()), key=lambda e: (e.rel, e.source)):
+            yield Neighbour(edge.rel, IN, edge.source)
+
+    def ancestors(self, key: str, parent_rel: str) -> tuple[str, ...]:
+        """*key*'s ancestors, nearest first, along *parent_rel* (outgoing), stopping at a cycle."""
+        chain: list[str] = []
+        current = key
+        while True:
+            parents = sorted(e.target for e in self._out.get(current, ()) if e.rel == parent_rel)
+            if not parents or parents[0] in chain or parents[0] == key:
+                return tuple(chain)
+            current = parents[0]
+            chain.append(current)

katalyst_plugin_context/domain/markdown.py

@@ -0,0 +1,201 @@
+"""Agent-ready markdown for a context result or map, built from the same payload as JSON.
+
+The two formats always agree because the markdown is rendered from the result object.
+Item blocks are also what the budget measures when the markdown format is asked for
+(:func:`item_size`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from katalyst_plugin_context.domain.context import estimate_tokens
+
+__all__ = ["item_block", "item_size", "render_map", "render_result"]
+
+
+def _blocking_marker(item: Mapping[str, Any]) -> str:
+    blocking = item.get("blocking")
+    entries = (
+        cast("list[Mapping[str, Any]]", blocking)
+        if isinstance(blocking, list)
+        else ([cast("Mapping[str, Any]", blocking)] if isinstance(blocking, Mapping) else [])
+    )
+    if not entries:
+        return ""
+    if any(e.get("blocking") for e in entries):
+        return "⛔ blocking · "
+    return "_advisory_ · "
+
+
+def item_block(item: Mapping[str, Any]) -> str:
+    """One item as a markdown list entry."""
+    head = f"- {_blocking_marker(item)}**{item['title']}** `{item['qualifiedName']}`"
+    fields = cast("Mapping[str, Any]", item.get("fields") or {})
+    shown = [f"{k}: {v}" for k, v in fields.items() if not isinstance(v, (list, dict))]
+    lines = [head + (" · " + " · ".join(shown) if shown else "")]
+    description = item.get("description")
+    if description:
+        length = int(item.get("descriptionLength") or 0)
+        more = (
+            f" _({length:,} chars; detail=full for all)_"
+            if item.get("detail") != "full" and length > len(str(description))
+            else ""
+        )
+        lines.append(f"  {str(description).strip()}{more}")
+    for why in cast("list[Mapping[str, Any]]", item.get("why") or []):
+        lines.append(f"  why: {why['text']}")
+    if item.get("detail") == "full":
+        spec = cast("Mapping[str, Any]", item.get("spec") or {})
+        extra = {k: v for k, v in spec.items() if k not in fields}
+        for key, value in extra.items():
+            lines.append(f"  {key}: {value}")
+        body = item.get("body")
+        if body:
+            lines.append("")
+            lines.extend(f"  {line}" for line in str(body).strip().splitlines())
+    return "\n".join(lines)
+
+
+def item_size(item: dict[str, Any]) -> int:
+    """The item's markdown block, in estimated tokens."""
+    return estimate_tokens(item_block(item))
+
+
+def _heading(node: Mapping[str, Any]) -> list[str]:
+    lines = [f"# Context: {node['kind']} `{node['qualifiedName']}`"]
+    if node.get("description"):
+        lines.append(str(node["description"]))
+    return lines
+
+
+def _ancestors(ancestors: Sequence[Mapping[str, Any]]) -> list[str]:
+    if not ancestors:
+        return []
+    chain = " ← ".join(f"{a['kind']} `{a['qualifiedName']}`" for a in ancestors)
+    return [f"Ancestors: {chain}"]
+
+
+def render_result(
+    result: Mapping[str, Any],
+    *,
+    views: Mapping[str, Mapping[str, Any]] | None = None,
+    ancestors: Sequence[Mapping[str, Any]] = (),
+    level: int = 1,
+) -> str:
+    """A context result as markdown: grouped by view (then kind), then by asked path."""
+    lines: list[str] = []
+    if level == 1:
+        lines += _heading(cast("Mapping[str, Any]", result["node"]))
+        lines += _ancestors(ancestors)
+    items = cast("list[Mapping[str, Any]]", result.get("items") or [])
+    groups: dict[tuple[str | None, str], list[Mapping[str, Any]]] = {}
+    for item in items:
+        key = (item.get("view"), str(item.get("path")) if not item.get("view") else "")
+        groups.setdefault(key, []).append(item)
+    h = "#" * (level + 1)
+    for (view, path), members in groups.items():
+        lines.append("")
+        if view:
+            declared = (views or {}).get(view, {})
+            title = declared.get("title") or view
+            lines.append(f"{h} {title}  _(view: {view})_")
+            if declared.get("description"):
+                lines.append(str(declared["description"]))
+        else:
+            lines.append(f"{h} `{path}`")
+        by_kind: dict[str, list[Mapping[str, Any]]] = {}
+        for item in members:
+            by_kind.setdefault(str(item["kind"]), []).append(item)
+        for kind, kind_items in by_kind.items():
+            lines.append(f"{h}# {kind}")
+            lines.extend(item_block(item) for item in kind_items)
+    if not items:
+        lines.append("")
+        lines.append("_Nothing here._")
+    truncated = cast("Mapping[str, Any] | None", result.get("truncated"))
+    if truncated:
+        lines.append("")
+        lines.append(
+            f"{h} Cut by the budget ({truncated['budget']:,} tokens; {truncated['used']:,} used)"
+        )
+        for group in cast("list[Mapping[str, Any]]", truncated.get("cut") or []):
+            names = ", ".join(f"`{n}`" for n in cast("list[str]", group["qualifiedNames"]))
+            where = f"view {group['view']}, " if group.get("view") else ""
+            lines.append(f"- {where}`{group['path']}`: {group['count']} cut — {names}")
+        downgraded = cast("list[Any]", truncated.get("downgraded") or [])
+        if downgraded:
+            lines.append(f"- {len(downgraded)} shown with less detail than asked")
+        hint = cast("Mapping[str, Any]", truncated.get("hint") or {})
+        if hint.get("budget"):
+            lines.append(f"More: ask again with budget {hint['budget']}.")
+    policy = cast("Mapping[str, Any]", result.get("policy") or {})
+    lines.extend(_policy_lines(policy))
+    return "\n".join(lines).strip() + "\n"
+
+
+def _policy_lines(policy: Mapping[str, Any]) -> list[str]:
+    said: list[str] = []
+    for key in ("notes", "clamped", "refused"):
+        for entry in cast("list[Mapping[str, Any]]", policy.get(key) or []):
+            text = entry.get("text") or (
+                f"{entry.get('control')}: asked {entry.get('requested')}, got "
+                f"{entry.get('effective')} ({entry.get('limitedBy')})"
+            )
+            said.append(f"- {text}")
+    layers = " → ".join(cast("list[str]", policy.get("layers") or []))
+    if not said:
+        return ["", f"_Policy: {layers}; nothing narrowed._"] if layers else []
+    return ["", f"_Policy: {layers}_", *said]
+
+
+def render_map(context_map: Mapping[str, Any]) -> str:
+    """A context map as markdown."""
+    lines = _heading(cast("Mapping[str, Any]", context_map["node"]))
+    lines += _ancestors(cast("list[Mapping[str, Any]]", context_map.get("ancestors") or []))
+    lines.append("")
+    lines.append("## Relationships")
+    rows = cast("list[Mapping[str, Any]]", context_map.get("relationships") or [])
+    if not rows:
+        lines.append("_None._")
+    for row in rows:
+        kinds = ", ".join(f"{k} ×{n}" for k, n in cast("Mapping[str, int]", row["kinds"]).items())
+        origin = "" if row["from"] == "self" else f" — inherited from `{row['from']}`"
+        lines.append(f"- `{row['path']}` → {kinds}{origin}")
+    hidden = cast("list[Mapping[str, Any]]", context_map.get("hiddenByPolicy") or [])
+    if hidden:
+        lines.append(
+            "- hidden by policy: " + ", ".join(f"`{h['path']}` ({h['limitedBy']})" for h in hidden)
+        )
+    view_rows = cast("list[Mapping[str, Any]]", context_map.get("views") or [])
+    if view_rows:
+        lines.append("")
+        lines.append("## Views")
+        for view in view_rows:
+            flag = " (always included)" if view.get("always") else ""
+            lines.append(f"- **{view['name']}**{flag}: {view['title']} — {view['count']} item(s)")
+    options = cast("Mapping[str, Any]", context_map.get("options") or {})
+    lines.append("")
+    lines.append("## Options")
+    steps = cast("list[str]", options.get("steps") or [])
+    lines.append(f"- steps: {', '.join(f'`{s}`' for s in steps) or 'none'}")
+    lines.append(
+        f"- max depth {options.get('maxDepth')}; detail {', '.join(options.get('detail') or [])}; "
+        f"budget {cast('Mapping[str, Any]', options.get('budget') or {}).get('default')} "
+        f"(max {cast('Mapping[str, Any]', options.get('budget') or {}).get('max')}); "
+        f"inheritance {'on' if options.get('inheritance') else 'off'}"
+    )
+    always = cast("Mapping[str, Any] | None", context_map.get("always"))
+    if always:
+        lines.append("")
+        lines.append("## Always included")
+        declared = {str(v["name"]): v for v in view_rows}
+        lines.append(render_result(always, views=declared, level=2).rstrip())
+    else:
+        lines.extend(_policy_lines(cast("Mapping[str, Any]", context_map.get("policy") or {})))
+    nxt = cast("list[str]", context_map.get("next") or [])
+    if nxt:
+        lines.append("")
+        lines.append("Next: " + "; ".join(f"`{n}`" for n in nxt))
+    return "\n".join(lines).strip() + "\n"

katalyst_plugin_context/domain/paths.py

@@ -0,0 +1,114 @@
+"""Steps, paths and patterns: how a walk through the relationship graph is written.
+
+A **step** follows one relationship type in one direction, optionally only to some kinds:
+``REL[:DIR[:KIND[,KIND...]]]``. ``REL`` is a graph label (``SOME_REL``) or ``*``. ``DIR`` is
+``out`` (the node is the source) or ``in`` (the node is the target), and empty or omitted
+means both. ``KIND`` restricts the node at the far end. A **path** is steps joined by
+``/``, walked in order. A **pattern** is a single step used as a filter in a policy's
+``paths.allow`` / ``paths.deny``.
+
+The strings are data a bundle, a profile or an agent writes. Nothing here knows any
+relationship or kind.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = [
+    "DIRECTIONS",
+    "IN",
+    "OUT",
+    "STEP_RE",
+    "PathSyntaxError",
+    "Step",
+    "parse_path",
+    "parse_step",
+    "path_text",
+]
+
+OUT = "out"
+IN = "in"
+DIRECTIONS = (OUT, IN)
+
+#: One step. Mirrored by the ``step`` definition of the plugin's JSON Schemas.
+STEP_RE = r"(\*|[A-Z][A-Z0-9_]*)(:(in|out)?(:[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*)?)?"
+_STEP = re.compile(rf"^{STEP_RE}$")
+
+
+class PathSyntaxError(ValueError):
+    """A step or path that does not follow ``REL[:in|out[:KIND,...]]``, joined by ``/``."""
+
+
+@dataclass(frozen=True, slots=True)
+class Step:
+    """One relationship type, one direction (or both), optionally only to some kinds."""
+
+    rel: str
+    direction: str | None = None
+    kinds: frozenset[str] = frozenset()
+
+    def matches(self, rel: str, direction: str, kind: str) -> bool:
+        """Whether traversing *rel* in *direction* to a node of *kind* is this step."""
+        return (
+            self.rel in ("*", rel)
+            and (self.direction is None or self.direction == direction)
+            and (not self.kinds or kind in self.kinds)
+        )
+
+    def overlaps(self, other: Step) -> bool:
+        """Whether some traversal matches both steps."""
+        return (
+            (self.rel == "*" or other.rel == "*" or self.rel == other.rel)
+            and (
+                self.direction is None
+                or other.direction is None
+                or self.direction == other.direction
+            )
+            and (not self.kinds or not other.kinds or bool(self.kinds & other.kinds))
+        )
+
+    @property
+    def text(self) -> str:
+        """The step written back: ``REL``, ``REL:out``, ``REL::kind`` or ``REL:in:a,b``."""
+        if self.kinds:
+            return f"{self.rel}:{self.direction or ''}:{','.join(sorted(self.kinds))}"
+        if self.direction:
+            return f"{self.rel}:{self.direction}"
+        return self.rel
+
+
+def parse_step(text: str) -> Step:
+    """Parse ``REL[:DIR[:KIND,...]]``.
+
+    Raises:
+        PathSyntaxError: If *text* is not a step.
+    """
+    if not isinstance(text, str) or not _STEP.match(text.strip()):  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise PathSyntaxError(
+            f"{text!r} is not a step: write REL[:in|out[:kind,...]], e.g. 'SOME_REL:out'"
+        )
+    rel, _, rest = text.strip().partition(":")
+    direction, _, kinds = rest.partition(":")
+    return Step(
+        rel=rel,
+        direction=direction or None,
+        kinds=frozenset(k for k in kinds.split(",") if k),
+    )
+
+
+def parse_path(text: str) -> tuple[Step, ...]:
+    """Parse steps joined by ``/``.
+
+    Raises:
+        PathSyntaxError: If any part is not a step.
+    """
+    if not isinstance(text, str) or not text.strip():  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise PathSyntaxError(f"{text!r} is not a path: write steps joined by '/'")
+    return tuple(parse_step(part) for part in text.strip().split("/"))
+
+
+def path_text(steps: tuple[Step, ...]) -> str:
+    """A path written back."""
+    return "/".join(step.text for step in steps)