docsgraph 0.1.0a2__py3-none-any.whl

cairn/tools/get_related.py

@@ -0,0 +1,140 @@
+"""``get_related`` retrieval tool.
+
+Spec: ``docs/specs/mcp-tools.md`` §7.
+
+Returns neighbors of a section across two channels:
+
+- the tree (``sibling`` / ``parent`` / ``child``)
+- the cross-reference graph (``xref``)
+
+Tree neighbors are returned with confidence ``1.0`` and ``relation: null``.
+XRef neighbors carry the extractor's confidence and the edge's ``kind`` as
+the ``relation`` field (``link``, ``textual``, or ``entity``).
+
+Results are sorted by confidence descending, then by destination id, and
+truncated to ``k``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Literal
+
+from cairn.core.errors import IndexNotFoundError, ToolError
+from cairn.tools.base import DocumentIndex, ToolResponse, estimate_tokens_of_payload
+
+Kind = Literal["xref", "sibling", "parent", "child"]
+
+_VALID_KINDS: frozenset[str] = frozenset({"xref", "sibling", "parent", "child"})
+
+
+async def get_related(
+    index: DocumentIndex,
+    *,
+    id: str,
+    kinds: Sequence[Kind] = ("xref",),
+    k: int = 8,
+) -> ToolResponse:
+    """Return up to ``k`` neighbors of section ``id`` across requested channels."""
+    if k < 1 or k > 32:
+        msg = f"k must be in [1, 32]; got {k}"
+        raise ToolError(msg, details={"k": k})
+    if not kinds:
+        msg = "kinds must contain at least one entry"
+        raise ToolError(msg)
+    bad = [x for x in kinds if x not in _VALID_KINDS]
+    if bad:
+        msg = f"invalid kinds: {bad}"
+        raise ToolError(msg, details={"invalid": bad})
+
+    node = index.tree.get(id)
+    if node is None:
+        msg = f"section not found: {id!r}"
+        raise IndexNotFoundError(msg, details={"section_id": id})
+
+    kind_set = set(kinds)
+    neighbors: list[dict[str, Any]] = []
+
+    if "xref" in kind_set and index.xrefs is not None:
+        for xref in index.xrefs.outgoing_from(id):
+            neighbors.append(
+                _neighbor(
+                    index,
+                    section_id=xref.dst,
+                    kind="xref",
+                    relation=xref.kind,
+                    confidence=xref.confidence,
+                )
+            )
+
+    if "child" in kind_set:
+        for child in index.tree.children_of(id):
+            neighbors.append(
+                _neighbor(
+                    index,
+                    section_id=child.id,
+                    kind="child",
+                    relation=None,
+                    confidence=1.0,
+                )
+            )
+
+    if "parent" in kind_set and node.parent is not None:
+        neighbors.append(
+            _neighbor(
+                index,
+                section_id=node.parent,
+                kind="parent",
+                relation=None,
+                confidence=1.0,
+            )
+        )
+
+    if "sibling" in kind_set and node.parent is not None:
+        for sibling in index.tree.children_of(node.parent):
+            if sibling.id == id:
+                continue
+            neighbors.append(
+                _neighbor(
+                    index,
+                    section_id=sibling.id,
+                    kind="sibling",
+                    relation=None,
+                    confidence=1.0,
+                )
+            )
+
+    neighbors.sort(key=lambda n: (-float(n["confidence"]), n["id"]))
+    neighbors = neighbors[:k]
+
+    payload: dict[str, Any] = {
+        "id": id,
+        "neighbors": neighbors,
+    }
+    return ToolResponse(
+        data=payload,
+        tokens_returned=estimate_tokens_of_payload(payload),
+    )
+
+
+def _neighbor(
+    index: DocumentIndex,
+    *,
+    section_id: str,
+    kind: str,
+    relation: str | None,
+    confidence: float,
+) -> dict[str, Any]:
+    node = index.tree.get(section_id)
+    payload: dict[str, Any] = {
+        "id": section_id,
+        "title": node.title if node is not None else section_id,
+        "kind": kind,
+        "relation": relation,
+        "confidence": confidence,
+        "anchor": index.anchor(section_id),
+    }
+    summary = index.summaries.get(section_id)
+    if summary is not None and summary.gist:
+        payload["gist"] = summary.gist
+    return payload

cairn/tools/get_section.py

@@ -0,0 +1,130 @@
+"""``get_section`` and ``expand`` retrieval tools.
+
+Spec: ``docs/specs/mcp-tools.md`` §2 and §3.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from cairn.core.errors import IndexNotFoundError, ToolError
+from cairn.tools.base import DocumentIndex, ToolResponse, estimate_tokens
+
+Level = Literal["gist", "synopsis", "digest", "full"]
+
+_LEVEL_ORDER: dict[str, int] = {"gist": 0, "synopsis": 1, "digest": 2, "full": 3}
+
+
+async def get_section(
+    index: DocumentIndex,
+    *,
+    id: str,
+    level: Level = "synopsis",
+    include_children: bool = False,
+) -> ToolResponse:
+    """Fetch one section at the chosen summary level.
+
+    `include_children` is reserved for v0.2 — passing ``True`` raises
+    :class:`cairn.core.errors.ToolError`.
+    """
+    if include_children:
+        msg = "include_children is reserved for v0.2; pass False in v0.1"
+        raise ToolError(msg, details={"feature": "include_children"})
+
+    node = index.tree.get(id)
+    if node is None:
+        msg = f"section not found: {id!r}"
+        raise IndexNotFoundError(msg, details={"section_id": id})
+
+    content = _content_at_level(index, id, level, node.raw_text)
+
+    next_levels = _levels_deeper_than(level, index, id)
+
+    payload: dict[str, Any] = {
+        "doc": index.doc_id,
+        "id": node.id,
+        "title": node.title,
+        "level": level,
+        "content": content,
+        "anchor": index.anchor(node.id),
+        "path": list(node.path),
+        "has_children": bool(node.children),
+        "next_levels_available": next_levels,
+    }
+    return ToolResponse(
+        data=payload,
+        tokens_returned=estimate_tokens(content),
+    )
+
+
+async def expand(
+    index: DocumentIndex,
+    *,
+    id: str,
+    to: Literal["synopsis", "digest", "full"],
+) -> ToolResponse:
+    """Move from a shallower summary to a deeper one. Convenience over ``get_section``.
+
+    Behaves exactly like ``get_section(id, level=to)`` and exists to make
+    the progressive-disclosure idiom explicit in agent prompts.
+    """
+    return await get_section(index, id=id, level=to)
+
+
+def _content_at_level(
+    index: DocumentIndex,
+    section_id: str,
+    level: str,
+    raw_text: str,
+) -> str:
+    if level == "full":
+        return raw_text
+
+    summary = index.summaries.get(section_id)
+    if summary is None:
+        msg = (
+            f"section {section_id!r} has no summary set; "
+            "the Summaries index may not have been built"
+        )
+        raise IndexNotFoundError(msg, details={"section_id": section_id})
+
+    if level == "gist":
+        return summary.gist
+    if level == "synopsis":
+        return summary.synopsis
+    if level == "digest":
+        if summary.digest is None:
+            msg = (
+                f"digest not available for {section_id!r}; "
+                "v0.1 generates only gist + synopsis"
+            )
+            raise IndexNotFoundError(
+                msg,
+                details={"section_id": section_id, "level": level},
+            )
+        return summary.digest
+
+    msg = f"unknown level: {level!r}"
+    raise ToolError(msg, details={"level": level})
+
+
+def _levels_deeper_than(
+    current: str,
+    index: DocumentIndex,
+    section_id: str,
+) -> list[str]:
+    current_rank = _LEVEL_ORDER[current]
+    deeper = [
+        name for name, rank in _LEVEL_ORDER.items() if rank > current_rank
+    ]
+    # Filter to what is actually available.
+    summary = index.summaries.get(section_id)
+    available: list[str] = []
+    for level in deeper:
+        if level == "full":
+            available.append(level)
+        elif summary is not None and level == "digest" and summary.digest is None:
+            continue
+        else:
+            available.append(level)
+    return available

cairn/tools/outline.py

@@ -0,0 +1,75 @@
+"""``outline`` retrieval tool — the cheapest, called first.
+
+Spec: ``docs/specs/mcp-tools.md`` §1.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Container, Sequence
+from typing import Any, Literal
+
+from cairn.core.errors import ToolError
+from cairn.tools.base import DocumentIndex, ToolResponse, estimate_tokens_of_payload
+
+IncludeLevel = Literal["gist", "synopsis"]
+
+_VALID_INCLUDE: frozenset[str] = frozenset({"gist", "synopsis"})
+
+
+async def outline(
+    index: DocumentIndex,
+    *,
+    depth: int = 2,
+    focus: str | None = None,
+    include: Sequence[IncludeLevel] = ("gist",),
+) -> ToolResponse:
+    """Return a truncated outline tree of the document.
+
+    See docs/specs/mcp-tools.md §1 for full semantics.
+    """
+    if depth < 1 or depth > 6:
+        msg = f"depth must be in [1, 6]; got {depth}"
+        raise ToolError(msg, details={"depth": depth})
+
+    if not include:
+        msg = "include must contain at least one summary level"
+        raise ToolError(msg)
+
+    bad = [x for x in include if x not in _VALID_INCLUDE]
+    if bad:
+        msg = f"invalid include values: {bad}"
+        raise ToolError(msg, details={"invalid": bad})
+
+    forest = index.tree.outline(depth=depth, focus=focus)
+    include_set = set(include)
+    _attach_summaries(forest, index, include_set)
+
+    payload: dict[str, Any] = {
+        "doc": index.doc_id,
+        "depth": depth,
+        "focus": focus,
+        "tree": forest,
+    }
+    return ToolResponse(
+        data=payload,
+        tokens_returned=estimate_tokens_of_payload(payload),
+    )
+
+
+def _attach_summaries(
+    nodes: list[dict[str, Any]],
+    index: DocumentIndex,
+    include: Container[str],
+) -> None:
+    """Mutate the outline forest to add gist/synopsis where requested."""
+    for node in nodes:
+        sid = node["id"]
+        summary = index.summaries.get(sid)
+        if summary is not None:
+            if "gist" in include and summary.gist:
+                node["gist"] = summary.gist
+            if "synopsis" in include and summary.synopsis:
+                node["synopsis"] = summary.synopsis
+        children = node.get("children", [])
+        if children:
+            _attach_summaries(children, index, include)

cairn/tools/read_range.py

@@ -0,0 +1,94 @@
+"""``read_range`` retrieval tool.
+
+Spec: ``docs/specs/mcp-tools.md`` §8.
+
+Reads continuous text across consecutive sections in document order. The
+agent gives ``start_id`` and ``end_id``; the tool concatenates each section
+as ``"## {title}\\n\\n{raw_text}"`` separated by blank lines, truncating at
+the ``max_tokens`` budget. When truncated, ``next_id`` points at the first
+section that wasn't included so the agent can continue.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cairn.core.errors import IndexNotFoundError, ToolError
+from cairn.tools.base import DocumentIndex, ToolResponse, estimate_tokens
+
+
+async def read_range(
+    index: DocumentIndex,
+    *,
+    start_id: str,
+    end_id: str,
+    max_tokens: int = 4000,
+) -> ToolResponse:
+    """Read continuous content from ``start_id`` through ``end_id``."""
+    if max_tokens < 1:
+        msg = f"max_tokens must be >= 1; got {max_tokens}"
+        raise ToolError(msg, details={"max_tokens": max_tokens})
+
+    sections = list(index.tree)
+    ids = [s.id for s in sections]
+
+    try:
+        start_idx = ids.index(start_id)
+    except ValueError as exc:
+        msg = f"start_id not found: {start_id!r}"
+        raise IndexNotFoundError(msg, details={"section_id": start_id}) from exc
+
+    try:
+        end_idx = ids.index(end_id)
+    except ValueError as exc:
+        msg = f"end_id not found: {end_id!r}"
+        raise IndexNotFoundError(msg, details={"section_id": end_id}) from exc
+
+    if start_idx > end_idx:
+        msg = (
+            f"start_id {start_id!r} must come before end_id {end_id!r} "
+            "in document order"
+        )
+        raise ToolError(
+            msg,
+            details={"start_id": start_id, "end_id": end_id},
+        )
+
+    parts: list[str] = []
+    tokens_so_far = 0
+    next_id: str | None = None
+
+    for section in sections[start_idx : end_idx + 1]:
+        rendered = _render_section(section.title, section.raw_text)
+        part_tokens = estimate_tokens(rendered)
+        # Allow the first section even if it alone exceeds the budget — the
+        # agent asked for it, and returning nothing is worse than returning
+        # a single oversized chunk.
+        if parts and tokens_so_far + part_tokens > max_tokens:
+            next_id = section.id
+            break
+        parts.append(rendered)
+        tokens_so_far += part_tokens
+
+    content = "\n\n".join(parts)
+
+    payload: dict[str, Any] = {
+        "doc": index.doc_id,
+        "start_id": start_id,
+        "end_id": end_id,
+        "content": content,
+        "anchor_start": index.anchor(start_id),
+        "anchor_end": index.anchor(end_id),
+        "truncated": next_id is not None,
+        "next_id": next_id,
+    }
+    return ToolResponse(
+        data=payload,
+        tokens_returned=tokens_so_far,
+    )
+
+
+def _render_section(title: str, body: str) -> str:
+    if body.strip():
+        return f"## {title}\n\n{body}"
+    return f"## {title}"

cairn/tools/search_keyword.py

@@ -0,0 +1,94 @@
+"""``search_keyword`` retrieval tool.
+
+Spec: ``docs/specs/mcp-tools.md`` §5.
+
+v0.1 uses a linear scan over loaded sections. For documents up to a few
+thousand sections this comfortably stays under the spec's latency target.
+A proper inverted index is a v0.2+ optimization.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from cairn.core.errors import ToolError
+from cairn.tools.base import DocumentIndex, ToolResponse, estimate_tokens_of_payload
+
+Mode = Literal["any", "all"]
+
+_HEAD_CHARS: int = 200
+
+
+async def search_keyword(
+    index: DocumentIndex,
+    *,
+    terms: list[str],
+    scope: str | None = None,
+    k: int = 12,
+    mode: Mode = "any",
+) -> ToolResponse:
+    """Exact (case-insensitive) lexical search across the document."""
+    if not 1 <= len(terms) <= 8:
+        msg = f"terms must contain 1-8 entries; got {len(terms)}"
+        raise ToolError(msg, details={"count": len(terms)})
+    if any(not t.strip() for t in terms):
+        msg = "terms must be non-empty strings"
+        raise ToolError(msg)
+    if k < 1 or k > 32:
+        msg = f"k must be in [1, 32]; got {k}"
+        raise ToolError(msg, details={"k": k})
+    if mode not in ("any", "all"):
+        msg = f"mode must be 'any' or 'all'; got {mode!r}"
+        raise ToolError(msg, details={"mode": mode})
+
+    lc_terms = [t.lower() for t in terms]
+
+    scored: list[tuple[int, dict[str, Any]]] = []
+    for node in index.tree:
+        if scope is not None and not _matches_scope(node.id, scope):
+            continue
+
+        text_lc = (node.title + "\n" + node.raw_text).lower()
+        matches: list[dict[str, Any]] = []
+        total_score = 0
+        for orig, lc in zip(terms, lc_terms, strict=True):
+            count = text_lc.count(lc)
+            if count > 0:
+                matches.append({"term": orig, "count": count})
+                total_score += count * len(orig)
+
+        if not matches:
+            continue
+        if mode == "all" and len(matches) != len(terms):
+            continue
+
+        scored.append(
+            (
+                total_score,
+                {
+                    "id": node.id,
+                    "title": node.title,
+                    "score": total_score,
+                    "anchor": index.anchor(node.id),
+                    "matches": matches,
+                    "head": node.raw_text[:_HEAD_CHARS],
+                },
+            )
+        )
+
+    scored.sort(key=lambda x: (-x[0], x[1]["id"]))
+    top = [d for _, d in scored[:k]]
+
+    payload: dict[str, Any] = {
+        "terms": terms,
+        "mode": mode,
+        "hits": top,
+    }
+    return ToolResponse(
+        data=payload,
+        tokens_returned=estimate_tokens_of_payload(payload),
+    )
+
+
+def _matches_scope(section_id: str, scope: str) -> bool:
+    return section_id == scope or section_id.startswith(scope + "/")