fred-capability-documents 4.4.3__py3-none-any.whl

fred_capability_documents/document_read_common.py

@@ -0,0 +1,263 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Shared plumbing for the document-reading capability pair (DOCREAD-01):
+`document_verbatim` (verbatim positional read) and `document_extract`
+(exhaustive extraction). Both sit on the SAME `RuntimeServices.document_markdown`
+port and differ only in tool intent and how the pagination footer is worded, so
+the config model, length resolution, error shaping, and page-to-tool-result
+formatting live here once.
+
+`document_tool_failure` has outgrown that pair - `document_similarity` uses it
+too, since the error shaping is about the document ports in general, not about
+paginated reading. It stays here rather than moving to a new module: two other
+capabilities (`document_access`, `document_summarize`) still carry their own
+private copies, and folding all four into one home is a cleanup of its own, not
+something to smuggle into a feature change.
+
+Doctrine (RFC §3.5, §3.8, §10), identical to `document_summarize`:
+- the capability reaches the platform ONLY through the typed
+  `RuntimeServices.document_markdown` port; the per-turn binding and the raw
+  access token NEVER enter `CapabilityContext`;
+- the tool signature exposes ONLY LLM arguments (uid + page window); identity
+  and config reach the tool through the middleware closure, never the schema;
+- `document_uid` is an internal working identifier — tools instruct the model to
+  NEVER repeat it to the end user (answers refer to documents by display name).
+"""
+
+from __future__ import annotations
+
+import time
+
+from fred_sdk.contracts.context import (
+    ToolContentBlock,
+    ToolContentKind,
+    ToolInvocationResult,
+)
+from fred_sdk.contracts.runtime import (
+    DocumentMarkdownResult,
+    DocumentScopeRefusedError,
+    unwrap_run_stop_error,
+)
+from pydantic import BaseModel, Field
+
+_KF_SERVICE = "Knowledge Flow"
+
+# Built-in default page length when neither the caller (the LLM) nor the
+# capability config specifies one. Matches the adapter's default page size.
+DEFAULT_PAGE_MAX_CHARS = 8000
+# Wire bounds clamped client-side so an out-of-range LLM value degrades
+# gracefully instead of a surprising page.
+_PAGE_MAX_CHARS_BOUNDS = (200, 50_000)
+
+
+def _clamp(value: int, bounds: tuple[int, int]) -> int:
+    low, high = bounds
+    return max(low, min(value, high))
+
+
+def resolve_page_max_chars(cap: int | None, requested: int | None) -> int:
+    """
+    Resolve the effective page length from the configured cap and the caller's
+    request.
+
+    The per-agent cap (`page_max_chars` config) is both the default (when the
+    caller asks for nothing) and a hard upper bound on whatever the caller
+    requests; without one, the built-in default applies and the caller's request
+    is honored verbatim (within wire bounds).
+    """
+
+    default = cap if cap is not None else DEFAULT_PAGE_MAX_CHARS
+    effective = requested if requested is not None else default
+    if cap is not None:
+        effective = min(effective, cap)
+    return _clamp(effective, _PAGE_MAX_CHARS_BOUNDS)
+
+
+class DocumentReadConfig(BaseModel):
+    """Shared agent-creation / stored config of the document-reading pair.
+
+    A single knob today: the default AND hard cap for the per-call page length
+    (chars). None = built-in default, caller's request honored verbatim.
+    """
+
+    page_max_chars: int | None = Field(default=None, ge=200, le=50_000)
+
+
+def document_tool_failure(
+    *,
+    tool_ref: str,
+    action: str,
+    exc: Exception,
+    elapsed_s: float,
+    document_uid: str,
+) -> tuple[str, ToolInvocationResult]:
+    """Turn a document-read tool-call failure into a non-empty, actionable error
+    message plus an ``is_error=True`` artifact.
+
+    The v2 ReAct runtime surfaces ``ToolInvocationResult.is_error`` directly to
+    the user (and suppresses LLM hallucination), so a failing tool MUST return
+    such a result instead of raising. Transport detail (timeout, HTTP status)
+    arrives via the SDK-typed ``DocumentPortCallError`` attributes the adapters
+    stamp — this module never imports the adapter's HTTP stack.
+    """
+
+    err_type = type(exc).__name__
+    raw = str(exc).strip()
+    timed_out = bool(getattr(exc, "timed_out", False))
+    status_code = getattr(exc, "status_code", None)
+
+    if timed_out:
+        cause = f"the {_KF_SERVICE} service timed out after {elapsed_s:.0f}s"
+    elif status_code is not None:
+        cause = f"the {_KF_SERVICE} service returned HTTP {status_code}"
+    else:
+        cause = f"the {_KF_SERVICE} service call failed after {elapsed_s:.0f}s"
+
+    detail = f": {raw}" if raw else ""
+    message = (
+        f"Could not {action} (document_uid={document_uid}): {cause} "
+        f"[{err_type}{detail}]."
+    )
+    if status_code in (403, 404):
+        message += (
+            " Likely cause: document_uid was not a document's opaque uid. If you "
+            "passed a file NAME, resolve the uid first — it is in the "
+            "conversation's attached-files list (the bracketed value after the "
+            "file name), in a search hit's 'uid' field, or on a DOCUMENT line of "
+            "the document tree. Then retry with a real document uid. Do not "
+            "repeat the uid to the user."
+        )
+    return message, ToolInvocationResult(
+        tool_ref=tool_ref,
+        is_error=True,
+        blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=message),),
+    )
+
+
+def document_scope_refusal(
+    *,
+    tool_ref: str,
+    action: str,
+    exc: DocumentScopeRefusedError,
+) -> tuple[str, ToolInvocationResult]:
+    """Shape a turn-scope refusal for the model — never as a service failure.
+
+    Nothing failed downstream: the user narrowed this turn to a selection the
+    named document is not in. Told as a transport error the model retries;
+    told as an empty result it reports the document as empty.
+    """
+
+    uids = ", ".join(exc.requested_uids) or "that document"
+    message = (
+        f"Cannot {action} ({uids}): the user has restricted this conversation to "
+        "a specific set of documents, and this one is not in it. Nothing was "
+        "read - this is NOT an empty or unreadable document. Work from a "
+        "document that is in scope (search and the document tree return exactly "
+        "those), or tell the user the document they mean is outside the current "
+        "selection. Never repeat the identifier to the user."
+    )
+    return message, ToolInvocationResult(
+        tool_ref=tool_ref,
+        is_error=True,
+        blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=message),),
+    )
+
+
+def _pagination_footer(result: DocumentMarkdownResult, *, exhaustive: bool) -> str:
+    """Machine-readable page/continuation banner appended to the tool content.
+
+    This is the signal that structurally prevents `document_summarize`'s "half
+    answer" failure mode: the model is told, in-band, exactly how much of the
+    document it has seen and whether it MUST keep paging. `exhaustive` (the
+    `extract` tool) makes the "keep going" directive imperative; the verbatim
+    tool states it as a plain option.
+    """
+
+    end = result.offset + len(result.text)
+    seen = f"chars {result.offset}–{end} of {result.total_chars}"
+    if result.next_offset is not None:
+        if exhaustive:
+            return (
+                f"\n\n[MORE TEXT REMAINS — {seen} read. You have NOT seen the "
+                f"whole document yet; do not conclude. Call this tool again with "
+                f"offset={result.next_offset} and keep accumulating matches until "
+                f"the end is reached.]"
+            )
+        return (
+            f"\n\n[More text remains — {seen} read. You have NOT seen the "
+            f"whole document yet; do not present this page as the complete "
+            f"document. You may call this tool again with "
+            f"offset={result.next_offset} to continue reading.]"
+        )
+    if result.offset == 0 and result.total_chars == 0:
+        return "\n\n[The document has no readable text content.]"
+    if exhaustive:
+        return (
+            f"\n\n[END OF DOCUMENT reached ({result.total_chars} chars total). "
+            f"You now have the complete text — produce your exhaustive answer.]"
+        )
+    return f"\n\n[End of document ({result.total_chars} chars total).]"
+
+
+async def read_document_page(
+    *,
+    port,
+    tool_ref: str,
+    document_uid: str,
+    offset: int,
+    max_chars: int,
+    exhaustive: bool,
+) -> tuple[str, ToolInvocationResult]:
+    """Fetch one page through the `document_markdown` port and format it as a
+    `(content, ToolInvocationResult)` return (shared by both tools).
+
+    `content_and_artifact` convention (see `document_summarize`): the artifact's
+    `blocks` carries the same text as `content` so a Graph agent — which keeps
+    only the artifact half — still sees the page and its continuation footer.
+    """
+
+    if port is None:
+        raise RuntimeError(
+            f"{tool_ref}: RuntimeServices.document_markdown is not available on "
+            "this execution path."
+        )
+
+    started = time.monotonic()
+    action = "extract from the document" if exhaustive else "read the document"
+    try:
+        result = await port.fetch_markdown(
+            document_uid, offset=offset, max_chars=max_chars
+        )
+    except DocumentScopeRefusedError as exc:
+        return document_scope_refusal(tool_ref=tool_ref, action=action, exc=exc)
+    except Exception as exc:
+        run_stop = unwrap_run_stop_error(exc)
+        if run_stop is not None:
+            raise run_stop from None
+        return document_tool_failure(
+            tool_ref=tool_ref,
+            action=action,
+            exc=exc,
+            elapsed_s=time.monotonic() - started,
+            document_uid=document_uid,
+        )
+
+    content = result.text + _pagination_footer(result, exhaustive=exhaustive)
+    artifact = ToolInvocationResult(
+        tool_ref=tool_ref,
+        blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=content),),
+    )
+    return content, artifact

fred_capability_documents/document_similarity/__init__.py

@@ -0,0 +1,27 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+`DocumentSimilarityCapability` — targeted document-to-document comparison.
+
+Installing fred-capability-documents registers it via the `fred.capabilities` entry point
+(`document_similarity`). Sits on `RuntimeServices.document_similarity`, the
+comparison counterpart of the `document_search` port `document_access` uses.
+"""
+
+from __future__ import annotations
+
+from .capability import DocumentSimilarityCapability
+
+__all__ = ["DocumentSimilarityCapability"]

fred_capability_documents/document_similarity/capability.py

@@ -0,0 +1,280 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+`DocumentSimilarityCapability` — find the passages most similar to an anchor
+passage, inside documents named on the call.
+
+Separate from `document_access` because it COMPARES rather than answers, and
+sits on its own port: its targeting comes from the model per call, not from
+the conversation. Read-only, so no HITL gate; `ADMIN_GATED` by class default.
+Full rationale: RUNTIME-EXECUTION-CONTRACT.md §8.60.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Sequence
+
+from fred_core.store.vector_search import select_citable_sources
+from fred_sdk.contracts.capability import (
+    AgentCapability,
+    CapabilityContext,
+    CapabilityManifest,
+    EmptyModel,
+)
+from fred_sdk.contracts.context import (
+    ToolContentBlock,
+    ToolContentKind,
+    ToolInvocationResult,
+)
+from fred_sdk.contracts.models import FieldSpec, UIHints
+from fred_sdk.contracts.runtime import (
+    DocumentScopeRefusedError,
+    DocumentSearchResult,
+    unwrap_run_stop_error,
+)
+from langchain_core.tools import BaseTool, tool
+from pydantic import BaseModel, Field
+
+from fred_capability_documents.document_read_common import document_tool_failure
+
+DOCUMENT_SIMILARITY_TOOL_REF = "document_similarity"
+
+# Same LLM-visible slice the sibling document tools use: citation and reasoning
+# fields only, never URLs or operational paths the model could echo back. `uid`
+# stays - it is the working identifier for chaining into the reading tools.
+_LLM_FIELDS = frozenset(
+    {"uid", "title", "content", "file_name", "page", "section", "score"}
+)
+
+# Wire bounds, clamped capability-side so an out-of-range model value degrades
+# instead of failing the call downstream.
+_TOP_K_BOUNDS = (1, 50)
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentSimilarityConfig(BaseModel):
+    """Per-agent-instance tuning. Targeting is deliberately absent: the whole
+    point of this mode is that the model names its targets per call, and the
+    adapter bounds them by the session binding."""
+
+    default_top_k: int = Field(default=10, ge=1, le=50)
+    rerank: bool = Field(default=True)
+    min_score: float | None = Field(default=None, ge=0.0, le=1.0)
+
+
+class DocumentSimilarityCapability(
+    AgentCapability[DocumentSimilarityConfig, DocumentSimilarityConfig, EmptyModel]
+):
+    """Targeted comparison search. Single tool, no chat controls, no turn
+    options, no HITL (read-only)."""
+
+    manifest = CapabilityManifest(
+        id="document_similarity",
+        # Pre-GA: version stays 0.1.0 while the platform has not shipped.
+        version="0.1.0",
+        name="capability.document_similarity.name",
+        description="capability.document_similarity.description",
+        icon="sync_alt",
+        config_fields=[
+            FieldSpec(
+                key="default_top_k",
+                type="integer",
+                title="capability.document_similarity.fields.default_top_k.title",
+                description="capability.document_similarity.fields.default_top_k.description",
+                min=1,
+                max=50,
+                ui=UIHints(group="retrieval"),
+            ),
+            FieldSpec(
+                key="rerank",
+                type="boolean",
+                title="capability.document_similarity.fields.rerank.title",
+                description="capability.document_similarity.fields.rerank.description",
+                ui=UIHints(group="retrieval", advanced=True),
+            ),
+            FieldSpec(
+                key="min_score",
+                type="number",
+                title="capability.document_similarity.fields.min_score.title",
+                description="capability.document_similarity.fields.min_score.description",
+                min=0.0,
+                max=1.0,
+                ui=UIHints(group="retrieval", advanced=True),
+            ),
+        ],
+        # team_scope left at the class default (ADMIN_GATED).
+    )
+    ConfigModel = DocumentSimilarityConfig
+
+    def tools(
+        self,
+        ctx: CapabilityContext[DocumentSimilarityConfig, EmptyModel],
+    ) -> Sequence[BaseTool]:
+        config = ctx.config
+        services = ctx.services
+        default_top_k = config.default_top_k
+        rerank = config.rerank
+        min_score = config.min_score
+
+        @tool("find_similar_passages", response_format="content_and_artifact")
+        async def find_similar_passages(
+            anchor: str,
+            document_uids: list[str],
+            top_k: int | None = None,
+        ) -> tuple[str, ToolInvocationResult]:
+            """Find the passages most similar to an anchor passage, inside specific documents.
+
+            This is a COMPARISON tool, not a question-answering one. `anchor` is
+            a passage of text to match against - a sentence, a paragraph, a
+            requirement - NOT a question. Use it to compare one document against
+            another: "does the operations manual cover what the architecture
+            document requires here?", "what in document B corresponds to this
+            section of document A?", "is this requirement contradicted anywhere
+            in that spec?".
+
+            To compare two documents end to end, call this once per passage of
+            the first document with `document_uids` set to the second - each call
+            is aimed independently, which is what this tool is for.
+
+            When to use a different tool instead:
+            - to answer a question from the corpus at large -> use the vector
+              search tool, which is not restricted to named documents;
+            - to read a document's own text in order -> use the verbatim read
+              tool.
+
+            `document_uids` is REQUIRED and must name at least one document: the
+            search runs ONLY inside those documents. They must be opaque
+            document uids, not file names - take them from a search hit's 'uid'
+            or from the document tree. This tool searches the document corpus
+            only: a file attached to this conversation is NOT searchable here,
+            so its uid would return nothing. Those uids are internal working
+            identifiers for YOUR tool calls: NEVER repeat one in your answer,
+            always refer to a document by its display name.
+
+            `top_k` bounds how many matches come back, best-first (leave unset
+            for the agent's default). An empty result means nothing in those
+            documents resembles the anchor - report that, do not invent a match.
+            """
+
+            port = services.document_similarity
+            if port is None:
+                # No platform port injected (e.g. a bare test harness). Fail
+                # LOUD rather than silently returning nothing.
+                raise RuntimeError(
+                    "document_similarity: RuntimeServices.document_similarity is "
+                    "not available on this execution path."
+                )
+
+            if not isinstance(anchor, str) or not anchor.strip():
+                return _bad_call(
+                    "`anchor` must be a non-empty passage of text to match "
+                    "against (not a question, and not empty)."
+                )
+            if not isinstance(document_uids, list) or not document_uids:
+                return _bad_call(
+                    "`document_uids` must name at least one document to search "
+                    "inside - this tool never searches the whole corpus. Resolve "
+                    "a document's uid from a search hit, the document tree, or "
+                    "the conversation's attached files, then retry."
+                )
+
+            uids = [str(uid) for uid in document_uids]
+            effective_top_k = (
+                _clamp(top_k, _TOP_K_BOUNDS)
+                if isinstance(top_k, int) and not isinstance(top_k, bool) and top_k > 0
+                else default_top_k
+            )
+
+            started = time.monotonic()
+            try:
+                result: DocumentSearchResult = await port.find_similar(
+                    anchor,
+                    document_uids=uids,
+                    top_k=effective_top_k,
+                    rerank=rerank,
+                    min_score=min_score,
+                )
+            except DocumentScopeRefusedError as exc:
+                # Nothing was searched, so this must never reach the model as an
+                # empty result - it would report "nothing matches" about a
+                # document it never looked at.
+                return _bad_call(
+                    "Cannot search "
+                    f"{', '.join(exc.requested_uids) or 'those documents'}: they "
+                    "are not part of this conversation's document scope, so "
+                    "nothing was searched. This is NOT a 'no matches' answer. "
+                    "Use a document that is in scope - resolve one from a search "
+                    "hit or the document tree - or tell the user the document is "
+                    "out of scope."
+                )
+            except Exception as exc:
+                run_stop = unwrap_run_stop_error(exc)
+                if run_stop is not None:
+                    raise run_stop from None
+                # Degrade rather than raise: the default ToolNode handler
+                # re-raises, killing the turn with an empty error detail.
+                return document_tool_failure(
+                    tool_ref=DOCUMENT_SIMILARITY_TOOL_REF,
+                    action="find similar passages",
+                    exc=exc,
+                    elapsed_s=time.monotonic() - started,
+                    document_uid=", ".join(uids),
+                )
+
+            hits = result.hits
+            content = {
+                "anchor": anchor,
+                "document_uids": uids,
+                "hits": [
+                    {
+                        k: v
+                        for k, v in hit.model_dump(mode="json").items()
+                        if k in _LLM_FIELDS
+                    }
+                    for hit in hits
+                ],
+            }
+            # Keeps the dataset-pointer exclusion, drops the score-ratio one:
+            # the caller named these documents, so a weak match is a real
+            # finding, not corpus noise (RUNTIME-EXECUTION-CONTRACT.md §8.60).
+            artifact = ToolInvocationResult(
+                tool_ref=DOCUMENT_SIMILARITY_TOOL_REF,
+                blocks=(ToolContentBlock(kind=ToolContentKind.JSON, data=content),),
+                sources=select_citable_sources(hits, min_score_ratio=0.0),
+            )
+            return json.dumps(content), artifact
+
+        return [find_similar_passages]
+
+
+def _clamp(value: int, bounds: tuple[int, int]) -> int:
+    low, high = bounds
+    return max(low, min(value, high))
+
+
+def _bad_call(message: str) -> tuple[str, ToolInvocationResult]:
+    """A malformed tool call, answered as an `is_error` artifact the model can
+    act on. Not `document_tool_failure`: nothing failed downstream, so its
+    transport wording ("the Knowledge Flow service ...") would be a lie."""
+
+    return message, ToolInvocationResult(
+        tool_ref=DOCUMENT_SIMILARITY_TOOL_REF,
+        is_error=True,
+        blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=message),),
+    )

fred_capability_documents/document_summarize/__init__.py

@@ -0,0 +1,38 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+`DocumentSummarizeCapability` (RFC §10) — on-demand document summarization,
+split out of the `document_access` pilot.
+
+Installing fred-capability-documents registers it via the `fred.capabilities` entry point
+(`document_summarize`), separate from `document_access` so a team admin opts
+into it explicitly.
+"""
+
+from __future__ import annotations
+
+from .capability import (
+    DEFAULT_SUMMARIZE_MAX_CHARS,
+    DocumentSummarizeCapability,
+    DocumentSummarizeConfig,
+    resolve_summarize_max_chars,
+)
+
+__all__ = [
+    "DEFAULT_SUMMARIZE_MAX_CHARS",
+    "DocumentSummarizeCapability",
+    "DocumentSummarizeConfig",
+    "resolve_summarize_max_chars",
+]