katalyst-plugin-context 0.1.1a2__tar.gz → 0.2.1a3__tar.gz

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-plugin-context
-Version: 0.1.1a2
+Version: 0.2.1a3
 Summary: Katalyst context plugin — the right context from the taxonomy for an agent working on a node
 Author: eSimplicity
 License: Proprietary

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-plugin-context"
-version = "0.1.1a2"
+version = "0.2.1a3"
 description = "Katalyst context plugin — the right context from the taxonomy for an agent working on a node"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/src/katalyst_plugin_context/cli.py

@@ -94,8 +94,9 @@ def create_command() -> click.Command:
 
         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.
+        whole neighbourhood at depth 1 if it declares none; with --path or --view, those
+        and the always-included views. Policy from the schema, the node and the profile can
+        only narrow a request, and only policy can take an always-included view out.
 
         Examples:
 

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/src/katalyst_plugin_context/domain/context.py

@@ -12,7 +12,7 @@ import json
 import math
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
-from typing import Any, Protocol
+from typing import Any, Protocol, cast
 
 from katalyst_plugin_context.domain.graph import Graph, GraphNode
 from katalyst_plugin_context.domain.paths import OUT, Step, parse_path, path_text
@@ -25,6 +25,7 @@ __all__ = [
     "Schema",
     "build_map",
     "build_result",
+    "content_size",
     "estimate_tokens",
 ]
 
@@ -290,19 +291,50 @@ def _item_payload(
     return payload
 
 
+def _higher(a: str, b: str) -> str:
+    return max(a, b, key=DETAIL_LEVELS.index)
+
+
 def _lower(level: str) -> list[str]:
     """*level* and every level below it, highest first."""
     return list(reversed(DETAIL_LEVELS[: DETAIL_LEVELS.index(level) + 1]))
 
 
-# ── markdown sizes (shared with the renderer) ───────────────────────────
+# ── the budget's measure ─────────────────────────────────────────────────
 
 
 SizeOf = Callable[[dict[str, Any]], int]
 
 
-def json_size(item: dict[str, Any]) -> int:
-    return estimate_tokens(json.dumps(item, separators=(",", ":"), default=str))
+def _text(value: object) -> str:
+    return value if isinstance(value, str) else json.dumps(value, default=str, ensure_ascii=False)
+
+
+def content_size(item: Mapping[str, Any]) -> int:
+    """The item's content in estimated tokens, whatever format the answer is given in.
+
+    Counts what a reader reads: the qualified name, kind and title, each ``why``, each
+    blocking value, the description, the fields, and at ``full`` the spec and the body.
+    No keys, punctuation or markup, so a JSON and a markdown answer hold the same items
+    for the same budget.
+    """
+    parts: list[str] = [str(item["qualifiedName"]), str(item["kind"]), str(item["title"])]
+    parts.extend(str(why["text"]) for why in item.get("why") or ())
+    blocking = item.get("blocking")
+    entries = cast(
+        "list[Mapping[str, Any]]",
+        blocking if isinstance(blocking, list) else [blocking] if blocking else [],
+    )
+    parts.extend(f"{entry['field']}: {entry['value']}" for entry in entries)
+    if item.get("description"):
+        parts.append(str(item["description"]))
+    fields: Mapping[str, Any] = item.get("fields") or {}
+    parts.extend(f"{name}: {_text(value)}" for name, value in fields.items())
+    spec: Mapping[str, Any] = item.get("spec") or {}
+    parts.extend(f"{name}: {_text(value)}" for name, value in spec.items() if name not in fields)
+    if item.get("body"):
+        parts.append(str(item["body"]))
+    return estimate_tokens("\n".join(parts))
 
 
 # ── the result ───────────────────────────────────────────────────────────
@@ -319,10 +351,20 @@ def _sources(
     inherit: bool,
     refused: list[dict[str, Any]],
     notes: list[dict[str, Any]],
+    dropped: list[dict[str, Any]],
 ) -> list[_Source]:
+    """What to walk: the always-included views first, then what the request names.
+
+    An always-included view the request does not name keeps its own detail and
+    inheritance (clamped by policy): the request's ``detail`` and ``inherit`` apply to what
+    it names. A bare request names the always-included views.
+    """
     sources: list[_Source] = []
 
-    def add_view(view: View, section: int) -> None:
+    def add_view(view: View, section: int, *, detail: str, walks_up: bool) -> str | None:
+        """Add *view*'s paths; the layer that left it none, or ``None``."""
+        limited: str | None = None
+        kept = False
         for index, steps in enumerate(view.paths):
             hidden = next(
                 (by for by in (policy.step_hidden_by(s) for s in steps) if by is not None), None
@@ -336,6 +378,7 @@ def _sources(
                         "text": f"view {view.name!r} path {path_text(steps)!r} is hidden by {hidden}",
                     }
                 )
+                limited = limited or hidden
                 continue
             if len(steps) > policy.max_depth:
                 notes.append(
@@ -349,29 +392,58 @@ def _sources(
                 )
                 steps = steps[: policy.max_depth]
                 if not steps:
+                    limited = limited or policy.max_depth_by
                     continue
+            kept = True
             sources.append(
                 _Source(
                     section=section,
                     view=view,
                     steps=steps,
                     path_index=index,
-                    detail=detail_for(request.detail or view.detail),
-                    inherit=view.inherit and inherit,
+                    detail=detail,
+                    inherit=walks_up,
                     repeat=1,
                 )
             )
-
-    if request.names_nothing:
-        for name in sorted(always, key=lambda n: -views[n].priority):
-            add_view(views[name], 0)
-        if not sources and not always:
+        return None if kept else limited
+
+    bare = request.names_nothing
+    named = set(request.views or ())
+    default_inherit, _ = policy.clamp_inherit(None)
+    for name in sorted(always, key=lambda n: -views[n].priority):
+        view = views[name]
+        asked = bare or name in named
+        limited = add_view(
+            view,
+            0,
+            detail=detail_for(request.detail or view.detail) if asked else detail_for(view.detail),
+            walks_up=view.inherit and (inherit if asked else default_inherit),
+        )
+        if limited is not None:
+            dropped.append(
+                {
+                    "view": name,
+                    "limitedBy": limited,
+                    "text": f"always-included view {name!r} has no path left by {limited}",
+                }
+            )
+    if bare:
+        if not always:
             sources.append(
                 _Source(3, None, (Step("*"),), 0, detail_for(request.detail), inherit, depth)
             )
         return sources
     for name in sorted(request.views or (), key=lambda n: -views[n].priority):
-        add_view(views[name], 1)
+        if name in always:
+            continue
+        view = views[name]
+        add_view(
+            view,
+            1,
+            detail=detail_for(request.detail or view.detail),
+            walks_up=view.inherit and inherit,
+        )
     for index, text in enumerate(request.paths or ()):
         steps = parse_path(text)
         hidden = next(
@@ -413,12 +485,19 @@ def _collect(
     ancestors: Sequence[str],
     policy: Policy,
     sources: Sequence[_Source],
+    *,
+    inherit: bool,
 ) -> tuple[dict[str, _Entry], list[dict[str, Any]]]:
+    """Every item *sources* reach, at its best rank, and each view's and path's members.
+
+    The ancestors are never items of a source that inherits, or of any source when the
+    call inherits; otherwise (inheritance off) they can be.
+    """
     entries: dict[str, _Entry] = {}
-    exclude = frozenset({focus, *ancestors})
     group_members: dict[tuple[str | None, str], set[str]] = {}
     for source in sources:
         starts = [focus, *(ancestors if source.inherit else ())]
+        exclude = frozenset({focus, *(ancestors if source.inherit or inherit else ())})
         steps = source.steps * source.repeat if source.repeat > 1 else source.steps
         text = path_text(source.steps)
         group = group_members.setdefault((source.view.name if source.view else None, text), set())
@@ -456,6 +535,8 @@ def _collect(
                 )
                 group.add(node.key)
                 entry = entries.get(node.key)
+                # The best-ranked source places the item; the highest detail asked shows it.
+                detail = _higher(entry.detail, source.detail) if entry else source.detail
                 if entry is None or rank < entry.rank:
                     previous = entry.whys if entry is not None else []
                     entry = _Entry(
@@ -463,13 +544,14 @@ def _collect(
                         rank=rank,
                         view=source.view.name if source.view else None,
                         path=text,
-                        detail=source.detail,
+                        detail=detail,
                         inherited_from=None if start == focus else start,
                         depth=len(arrival.hops),
                         whys=previous,
                         blocking=blocking,
                     )
                     entries[node.key] = entry
+                entry.detail = detail
                 if not any(w[1].hops == arrival.hops for w in entry.whys):
                     entry.whys.append((rank, arrival, text))
     groups = [
@@ -479,6 +561,10 @@ def _collect(
     return entries, groups
 
 
+def _blocks(entry: _Entry) -> bool:
+    return any(b.get("blocking") for b in entry.blocking)
+
+
 def build_result(
     graph: Graph,
     schema: Schema,
@@ -487,9 +573,16 @@ def build_result(
     views: Mapping[str, View],
     request: ContextRequest,
     *,
-    size_of: SizeOf = json_size,
+    size_of: SizeOf = content_size,
+    include_always: bool = True,
 ) -> dict[str, Any]:
-    """The items *request* asks for around *focus*, budgeted, with why each is here."""
+    """The items *request* asks for around *focus*, budgeted, with why each is here.
+
+    The always-included views are in every answer, whatever the request names; policy
+    alone can take them out. The budget places blocking items first, then the rest, each
+    in rank order (so always-included items first): no blocking item is cut while a
+    non-blocking one stays. *include_always* is off only for the map's per-view counts.
+    """
     unknown = [name for name in request.views or () if name not in views]
     if unknown:
         raise ContextError(
@@ -520,8 +613,20 @@ def build_result(
             requested_detail_note.append(note)
         return level
 
-    ancestors = graph.ancestors(focus, schema.parent_rel) if inherit else ()
-    always = [name for name in policy.always or () if name in views]
+    always = [name for name in policy.always or () if name in views] if include_always else []
+    dropped_always: list[dict[str, Any]] = (
+        [
+            {
+                "view": name,
+                "limitedBy": by,
+                "text": f"{by} takes {name!r} out of the always-included views",
+            }
+            for name, by in policy.always_dropped
+            if name in views
+        ]
+        if include_always
+        else []
+    )
     sources = _sources(
         request,
         policy,
@@ -532,39 +637,43 @@ def build_result(
         inherit=inherit,
         refused=refused,
         notes=notes,
+        dropped=dropped_always,
     )
     clamped.extend(requested_detail_note)
-    entries, groups = _collect(graph, schema, focus, ancestors, policy, sources)
+    walks_up = inherit or any(s.inherit for s in sources)
+    ancestors = graph.ancestors(focus, schema.parent_rel) if walks_up else ()
+    entries, groups = _collect(graph, schema, focus, ancestors, policy, sources, inherit=inherit)
     ordered = sorted(entries.values(), key=lambda e: e.rank)
+    placing = sorted(ordered, key=lambda e: (not _blocks(e), e.rank))
 
-    items: list[dict[str, Any]] = []
+    placed: dict[str, dict[str, Any]] = {}
     downgraded: list[dict[str, Any]] = []
     cut: list[_Entry] = []
     used = 0
-    for position, entry in enumerate(ordered):
-        placed = False
+    for position, entry in enumerate(placing):
+        fits = False
         for level in _lower(entry.detail):
             payload = _item_payload(entry, level, graph, schema, focus)
             cost = size_of(payload)
             if used + cost <= budget:
-                items.append(payload)
+                placed[entry.node.key] = payload
                 used += cost
                 if level != entry.detail:
                     downgraded.append(
                         {"qualifiedName": entry.node.key, "from": entry.detail, "to": level}
                     )
-                placed = True
+                fits = True
                 break
-        if not placed:
-            cut = ordered[position:]
+        if not fits:
+            cut = sorted(placing[position:], key=lambda e: e.rank)
             break
+    items = [placed[e.node.key] for e in ordered if e.node.key in placed]
 
-    returned = {item["qualifiedName"] for item in items}
     for group in groups:
         group["returned"] = sum(
             1
             for e in entries.values()
-            if e.node.key in returned and (e.view, e.path) == (group["view"], group["path"])
+            if e.node.key in placed and (e.view, e.path) == (group["view"], group["path"])
         )
     truncated: dict[str, Any] | None = None
     if cut or downgraded:
@@ -586,13 +695,16 @@ def build_result(
                 for (view, path), names in by_group.items()
             ],
             "cutTotal": len(cut),
+            "cutBlocking": sum(1 for e in cut if _blocks(e)),
             "hint": {"budget": min(max(whole, budget + 1), policy.budget_max)},
         }
+    included = list(dict.fromkeys(s.view.name for s in sources if s.view is not None))
     return {
         "node": _node_payload(graph, schema, focus),
         "request": request.as_payload(),
         "effective": {
-            "views": list(dict.fromkeys(s.view.name for s in sources if s.view is not None)),
+            "views": included,
+            "always": [name for name in always if name in included],
             "paths": [path_text(s.steps) for s in sources if s.view is None],
             "depth": depth,
             "detail": detail_for(request.detail) if request.detail else None,
@@ -603,7 +715,7 @@ def build_result(
         "groups": groups,
         "truncated": truncated,
         "used": used,
-        "dropped": {"unresolved": graph.dropped},
+        "dropped": {"unresolved": graph.dropped, "always": dropped_always},
         "policy": {
             "layers": list(policy.layers),
             "notes": notes,
@@ -633,8 +745,6 @@ def build_map(
     focus: str,
     policy: Policy,
     views: Mapping[str, View],
-    *,
-    size_of: SizeOf = json_size,
 ) -> dict[str, Any]:
     """Every relationship around *focus*, what it inherits, its views and the options."""
     ancestors = graph.ancestors(focus, schema.parent_rel) if policy.inheritance else ()
@@ -686,6 +796,7 @@ def build_map(
 
     view_rows: list[dict[str, Any]] = []
     always = [name for name in policy.always or () if name in views]
+    dropped_by = dict(policy.always_dropped)
     for name, view in sorted(views.items(), key=lambda kv: (-kv[1].priority, kv[0])):
         counted = build_result(
             graph,
@@ -695,6 +806,7 @@ def build_map(
             views,
             ContextRequest(views=(name,), detail=REFS, budget=policy.budget_max),
             size_of=lambda _item: 0,
+            include_always=False,
         )
         view_rows.append(
             {
@@ -705,13 +817,12 @@ def build_map(
                 "inherit": view.inherit,
                 "detail": view.detail,
                 "always": name in always,
+                "droppedBy": dropped_by.get(name),
                 "count": len(counted["items"]),
             }
         )
     always_result = (
-        build_result(graph, schema, focus, policy, views, ContextRequest(), size_of=size_of)
-        if always
-        else None
+        build_result(graph, schema, focus, policy, views, ContextRequest()) if always else None
     )
     address = focus
     suggestions = [

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/src/katalyst_plugin_context/domain/markdown.py

@@ -1,8 +1,8 @@
 """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`).
+The two formats always agree because the markdown is rendered from the result object,
+and the budget measures an item's content, not either format
+(:func:`~katalyst_plugin_context.domain.context.content_size`).
 """
 
 from __future__ import annotations
@@ -10,9 +10,7 @@ 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"]
+__all__ = ["item_block", "render_map", "render_result"]
 
 
 def _blocking_marker(item: Mapping[str, Any]) -> str:
@@ -58,11 +56,6 @@ def item_block(item: Mapping[str, Any]) -> str:
     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"):
@@ -124,6 +117,8 @@ def render_result(
             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}")
+        if truncated.get("cutBlocking"):
+            lines.append(f"- ⛔ {truncated['cutBlocking']} of them blocking")
         downgraded = cast("list[Any]", truncated.get("downgraded") or [])
         if downgraded:
             lines.append(f"- {len(downgraded)} shown with less detail than asked")
@@ -131,12 +126,17 @@ def render_result(
         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))
+    dropped = cast("Mapping[str, Any]", result.get("dropped") or {})
+    lines.extend(
+        _policy_lines(policy, cast("list[Mapping[str, Any]]", dropped.get("always") or []))
+    )
     return "\n".join(lines).strip() + "\n"
 
 
-def _policy_lines(policy: Mapping[str, Any]) -> list[str]:
-    said: list[str] = []
+def _policy_lines(
+    policy: Mapping[str, Any], dropped_always: Sequence[Mapping[str, Any]] = ()
+) -> list[str]:
+    said: list[str] = [f"- {entry['text']}" for entry in dropped_always]
     for key in ("notes", "clamped", "refused"):
         for entry in cast("list[Mapping[str, Any]]", policy.get(key) or []):
             text = entry.get("text") or (
@@ -173,7 +173,13 @@ def render_map(context_map: Mapping[str, Any]) -> str:
         lines.append("")
         lines.append("## Views")
         for view in view_rows:
-            flag = " (always included)" if view.get("always") else ""
+            flag = (
+                " (always included)"
+                if view.get("always")
+                else f" (taken out of always-included by {view['droppedBy']})"
+                if view.get("droppedBy")
+                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("")

{katalyst_plugin_context-0.1.1a2 → katalyst_plugin_context-0.2.1a3}/src/katalyst_plugin_context/domain/policy.py

@@ -14,6 +14,9 @@ Each control narrows in its own way:
 ``always_include`` the first declaring layer sets it; later layers intersect
 =================  ===========================================================
 
+A view a later layer takes out of ``always_include`` is recorded (:attr:`Policy.always_dropped`)
+so an answer can say which layer excluded it: the operator's control, not a widening.
+
 A layer that tries to widen is not an error. Its declaration has no effect, and the
 effective policy records a note saying which layer limited it. Defaults (``depth``,
 ``detail``, ``budget``, ``inherit``) are not limits: a later layer's default replaces an
@@ -73,6 +76,8 @@ class Policy:
     inheritance_by: str = BUILTIN
     always: tuple[str, ...] | None = None
     always_by: str = ""
+    always_dropped: list[tuple[str, str]] = field(default_factory=lambda: list[tuple[str, str]]())
+    """Views an earlier layer always included and a later one took out, with that layer."""
     default_depth: int = _BUILTIN_DEPTH
     default_detail: str | None = None
     default_budget: int = _BUILTIN_BUDGET
@@ -160,6 +165,7 @@ class Policy:
             },
             "inheritance": self.inheritance,
             "alwaysInclude": list(self.always or ()),
+            "alwaysDropped": [{"view": v, "limitedBy": by} for v, by in self.always_dropped],
             "notes": list(self.notes),
         }
 
@@ -327,6 +333,8 @@ def _fold_limits(policy: Policy, layer: Layer, declared_views: set[str]) -> None
                     )
                 )
         kept = tuple(n for n in names if n in declared_views)
+        if policy.always is not None:
+            policy.always_dropped.extend((n, layer.label) for n in policy.always if n not in kept)
         policy.always = (
             kept if policy.always is None else tuple(n for n in policy.always if n in kept)
         )