fred-capability-document-access 4.4.3__py3-none-any.whl

fred_capability_document_access/__init__.py

@@ -0,0 +1,36 @@
+# 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.
+
+"""Scoped document access over the Knowledge Flow corpus (`document_access`).
+
+Installing this package registers the capability through its
+`fred.capabilities` entry point; see `capability.py` for the scoping
+precedence and the deliberate deferrals.
+"""
+
+from fred_capability_document_access.capability import (
+    DOCUMENT_ACCESS_TOOL_REF,
+    DocumentAccessCapability,
+    DocumentAccessConfig,
+    DocumentAccessTurnOptions,
+    narrow_scope_ids,
+)
+
+__all__ = [
+    "DOCUMENT_ACCESS_TOOL_REF",
+    "DocumentAccessCapability",
+    "DocumentAccessConfig",
+    "DocumentAccessTurnOptions",
+    "narrow_scope_ids",
+]

fred_capability_document_access/capability.py

@@ -0,0 +1,781 @@
+# 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.
+
+"""
+`DocumentAccessCapability` (RFC §3, §10) — the canonical real capability.
+
+Why this module exists:
+- it is the first REAL (non-tracer) capability: live document tools wired to
+  platform services through typed SDK ports, plus static config-field scoping
+  and one computed chat-turn narrowing control
+- it doubles as the canonical in-tree reference a capability author copies
+
+What this capability ships (and deliberately does NOT):
+- `search_documents_using_vectorization`, the vector-search tool, wired live
+  through `ctx.services.document_search`
+- `list_document_tree`: wired live through `ctx.services.document_tree`,
+  backed by Knowledge Flow's document tree endpoint. Failures surface as
+  `is_error` tool results with actionable detail (timeout/HTTP status), never
+  raised exceptions.
+- NOT `summarize_document` — that tool is its own capability,
+  `document_summarize` (`fred-capability-documents`, its own package),
+  admin-gated and HITL-gated separately (RFC §10.1). `list_document_tree`'s
+  emitted uids are commonly chained into that capability's tool, but the two
+  are independently selectable — this capability does not depend on it.
+- still deferred: the tree's trailing "Session attachments" section — a
+  pod-reachable session-attachment enumeration does not exist yet
+  (attachments are only a *search* scope today). The tree tool therefore lists
+  the corpus only, and is registered only while `team_documents` is on.
+
+Identifier hygiene (hard rule): document uids and tag ids are internal working
+identifiers for the agent's own tool calls (scope filters, cross-capability
+chaining into `document_summarize`). The agent uses them freely, but every
+LLM-facing docstring instructs the model to NEVER repeat them to the end
+user — answers refer to documents by display name only.
+
+Doctrine (RFC §3.5, §3.8, §10):
+- the capability reaches the platform ONLY through typed optional ports on
+  `RuntimeServices`; the per-turn binding and the raw access token NEVER enter
+  `CapabilityContext`
+- the tool signature exposes ONLY LLM arguments (`question`, `top_k`); scope and
+  identity reach the tool through the middleware closure, never the tool schema
+
+Scoping precedence (`turn_option ⊆ capability_config ⊆ session_binding`):
+- HERE both tools narrow their stored-config scope (`config.library_tag_ids` /
+  `config.document_uids`) by the per-turn `document_scope` selection
+  (`turn_options`), enforcing `turn_option ⊆ capability_config`; a library pick
+  and a document pick each narrow on their own, and UNION when both are made -
+  "that library, plus that file", the rule Knowledge Flow already applies to
+  search hits;
+- the runtime adapter then bounds the result by the session binding's own scope,
+  enforcing `⊆ session_binding` (see `DocumentSearchAdapter`).
+
+The builtin `knowledge.search` (`TOOL_REF_KNOWLEDGE_SEARCH`) also exposes vector
+search, scoped from `RuntimeContext`. Prefer this capability for per-capability
+configuration and turn scoping; do not wire both search tools on one instance.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Sequence
+
+from fred_core.store.vector_search import (
+    DEFAULT_MIN_SOURCE_SCORE_RATIO,
+    select_citable_sources,
+)
+from fred_sdk.contracts.capability import (
+    AgentCapability,
+    CapabilityContext,
+    CapabilityManifest,
+    ChatControlSpec,
+    ScopePrivate,
+    TeamScopePolicy,
+)
+from fred_sdk.contracts.context import (
+    ToolContentBlock,
+    ToolContentKind,
+    ToolInvocationResult,
+)
+from fred_sdk.contracts.models import (
+    DocumentScopeControlParams,
+    FieldSpec,
+    RagScopeControlParams,
+    SearchPolicyControlParams,
+    UIHints,
+)
+from fred_sdk.contracts.runtime import (
+    DocumentSearchResult,
+    DocumentTreeResult,
+    unwrap_run_stop_error,
+)
+from langchain_core.tools import BaseTool, tool
+from pydantic import BaseModel, Field, TypeAdapter, model_validator
+
+# The tool-result `tool_ref` this capability stamps on its artifact — distinct
+# from the builtin `knowledge.search` ref so the two paths stay traceable apart.
+DOCUMENT_ACCESS_TOOL_REF = "document_access"
+
+# Vector-search policy values Knowledge Flow accepts (mirrors the MCP catalog's
+# `chat_options.search_policy` enum). None on the config means "let the session
+# binding decide".
+_SEARCH_POLICIES = ("strict", "hybrid", "semantic")
+_RAG_SCOPES = ("corpus_only", "hybrid", "general_only")
+
+# Only the fields the LLM needs for citation, reasoning, and tool chaining are
+# exposed to the model. URL and operational fields are excluded so the model
+# cannot reproduce broken or internal paths. `uid` stays: it is the working
+# identifier the (separate) document_summarize capability's tool takes —
+# internal to the agent, never repeated to the end user (each tool docstring
+# says so).
+_LLM_FIELDS = frozenset(
+    {"uid", "title", "content", "file_name", "page", "section", "score"}
+)
+
+_KF_SERVICE = "Knowledge Flow"
+
+logger = logging.getLogger(__name__)
+
+_TREE_MAX_CHARS_BOUNDS = (500, 20_000)
+
+
+def _clamp(value: int, bounds: tuple[int, int]) -> int:
+    low, high = bounds
+    return max(low, min(value, high))
+
+
+def _document_tool_failure(
+    *,
+    tool_ref: str,
+    action: str,
+    exc: Exception,
+    elapsed_s: float,
+    document_uid: str | None = None,
+) -> tuple[str, ToolInvocationResult]:
+    """Turn any document 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 — a raised exception is re-raised by the
+    default ``ToolNode`` handler, which leaves the tool call pending in the
+    trace and yields an empty error detail to the UI.
+
+    Transport detail (timeout, HTTP status) arrives via the SDK-typed
+    `DocumentPortCallError` attributes the adapters stamp — this module never
+    imports the adapter's HTTP stack.
+    """
+
+    # Server-side, with the stack: the model-facing message below deliberately
+    # compresses the failure, so without this line a programming error caught
+    # by the broad handlers (a TypeError from a renamed port kwarg, say) would
+    # degrade into a plausible "service call failed" and never surface anywhere
+    # a developer looks. Degrading is right for the turn; being silent about
+    # WHY is not.
+    logger.error(
+        "Document tool failure (%s, %.1fs) — degraded to an is_error artifact.",
+        action,
+        elapsed_s,
+        exc_info=exc,
+    )
+
+    err_type = type(exc).__name__
+    raw = str(exc).strip()
+    timed_out = bool(getattr(exc, "timed_out", False))
+    status_code = getattr(exc, "status_code", None)
+
+    # `structured` means the adapter identified the failure, so `cause` below
+    # already states it precisely and `raw` only repeats it — for a 401 that
+    # produced "returned HTTP 401 [DocumentPortCallError: Client error '401
+    # Unauthorized' for url ...]". Since the adapter now redacts URLs out of
+    # `raw`, what survived was worse than redundant: an unbalanced quote and
+    # "For more information check:" pointing at nothing.
+    #
+    # The unstructured branch keeps both, because there `raw` is the only
+    # information there is ("All connection attempts failed") and `err_type`
+    # is how an unexpected exception — a TypeError from a renamed port kwarg,
+    # the case the logger above exists for — reaches someone who can act on it.
+    structured = timed_out or status_code is not 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"
+
+    target = f" (document_uid={document_uid})" if document_uid else ""
+    if structured:
+        message = f"Could not {action}{target}: {cause}."
+    else:
+        detail = f": {raw}" if raw else ""
+        message = f"Could not {action}{target}: {cause} [{err_type}{detail}]."
+    # `blocks` carries the same diagnostic as `content` (CAPAB-02, same reason
+    # as the success-path artifacts above): a Graph agent's plain-dict
+    # invocation keeps only the artifact half of a `content_and_artifact`
+    # return — an artifact with `is_error=True` but no message tells a Graph
+    # node THAT the call failed but not WHY.
+    return message, ToolInvocationResult(
+        tool_ref=tool_ref,
+        is_error=True,
+        blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=message),),
+    )
+
+
+def narrow_scope_ids(
+    outer: Sequence[str] | None, inner: Sequence[str] | None
+) -> list[str] | None:
+    """
+    Bound one scope level (`inner`) by a broader one (`outer`) — the capability
+    half of the scoping precedence.
+
+    Semantics (empty/None = "no bound at this level"):
+    - `inner` empty → inherit `outer` unchanged;
+    - `outer` empty → `outer` is unbounded, so keep `inner` as-is;
+    - both present  → intersection, so the result is a subset of BOTH.
+
+    Used here as `narrow_scope_ids(capability_config, turn_option)` to enforce
+    `turn_option ⊆ capability_config`; the adapter applies the SAME primitive as
+    `narrow_scope_ids(session_binding, params)` to complete
+    `turn_option ⊆ capability_config ⊆ session_binding`.
+    """
+
+    if not inner:
+        return list(outer) if outer else None
+    if not outer:
+        return list(inner)
+    allowed = set(outer)
+    return [value for value in inner if value in allowed]
+
+
+# Legacy keys parse like the fields they replace: "false" must stay false.
+_LEGACY_BOOL = TypeAdapter(bool)
+
+
+class DocumentAccessConfig(BaseModel):
+    """
+    Agent-creation / stored config of the document-access capability (RFC §3.2),
+    mirroring the legacy MCP search tool's configuration surface exactly.
+
+    `bind_libraries` + `library_tag_ids` pin the agent to a fixed library set
+    (the bound ids are IGNORED while `bind_libraries` is off, like the legacy
+    tool); `document_uids` NARROWS to specific documents. An empty list means
+    "no capability-side narrowing at this level" (the session binding still
+    bounds it). `default_top_k` and `search_policy` set retrieval defaults;
+    `attachments` and `team_documents` are the two document sources (at least
+    one must stay on); the `show_*` toggles pick which computed chat controls
+    the composer shows (library/document scope, search policy, RAG scope). When
+    the search-policy picker is shown, `search_policy` acts as the picker's
+    DEFAULT and the per-turn choice (RuntimeContext) wins at search time;
+    when hidden, it is enforced as-is. `min_source_score_ratio` bounds what's
+    citable as a "source" in the chat UI (RAG-DATASET-DISCOVERY-RFC.md §7) —
+    it never narrows what the model itself sees, only what a human is shown
+    as evidence.
+    """
+
+    library_tag_ids: ScopePrivate[list[str]] = []
+    document_uids: ScopePrivate[list[str]] = []
+    default_top_k: int = 8
+    search_policy: str | None = None
+    # The switch and its list form one team-owned setting: a copy that kept the
+    # switch on with an empty list would hide the library picker for nothing.
+    bind_libraries: ScopePrivate[bool] = False
+    show_library_selection: bool = True
+    show_document_selection: bool = True
+    # Sources: `attachments` drives the paperclip and the session search scope,
+    # `team_documents` the corpus scope, the scope pickers and the tree tool.
+    attachments: bool = True
+    team_documents: bool = True
+    show_search_policy_control: bool = True
+    show_rag_scope_control: bool = True
+    default_rag_scope: str | None = None
+    min_source_score_ratio: float = Field(
+        default=DEFAULT_MIN_SOURCE_SCORE_RATIO,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "A hit must score at least this fraction of the best hit in the "
+            "same search call to be citable as a source. Does not affect what "
+            "the model itself can read — only the human-facing Sources panel."
+        ),
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _upgrade_legacy_slices(cls, data: object) -> object:
+        """Older slices revalidate without behavior change: the single scope
+        toggle maps onto the split library/document toggles, a pre-`bind_libraries`
+        library scope stays binding, and the paperclip/attachments-only pair maps
+        onto the two sources (legacy keys are dropped so they never round-trip)."""
+
+        if isinstance(data, dict):
+            data = dict(data)
+            paperclip = _LEGACY_BOOL.validate_python(
+                data.pop("show_attach_files_control", True)
+            )
+            only_attached = _LEGACY_BOOL.validate_python(
+                data.pop("search_attachments_only", False)
+            )
+            if "attachments" not in data and "team_documents" not in data:
+                data["attachments"] = paperclip
+                data["team_documents"] = not (paperclip and only_attached)
+            if (
+                "show_document_scope_control" in data
+                and "show_library_selection" not in data
+                and "show_document_selection" not in data
+            ):
+                shown = bool(data.get("show_document_scope_control"))
+                data["show_library_selection"] = shown
+                data["show_document_selection"] = shown
+            if "bind_libraries" not in data and data.get("library_tag_ids"):
+                data["bind_libraries"] = True
+        return data
+
+    @model_validator(mode="after")
+    def _require_a_source(self) -> DocumentAccessConfig:
+        if not (self.attachments or self.team_documents):
+            raise ValueError(
+                "document_access needs at least one source: attachments or "
+                "team_documents."
+            )
+        return self
+
+
+class DocumentAccessTurnOptions(BaseModel):
+    """
+    Per-turn narrowing carried by the `document_scope` chat control (RFC §3.5).
+
+    Each field is `None` when the turn does not narrow that level; a present list
+    is intersected with the capability config scope (never widening it).
+    """
+
+    library_tag_ids: list[str] | None = None
+    document_uids: list[str] | None = None
+
+
+class DocumentAccessCapability(
+    AgentCapability[
+        DocumentAccessConfig, DocumentAccessConfig, DocumentAccessTurnOptions
+    ]
+):
+    """
+    Document access over the platform corpus: vector search and tree listing,
+    wired through the `document_search` / `document_tree` ports. Config-field
+    scoping + one computed chat-turn narrowing control. See the module
+    docstring for the remaining deferral (session-attachment enumeration),
+    the duplicate-search-tool decision, and why `summarize_document` is a
+    separate capability (`document_summarize`).
+    """
+
+    manifest = CapabilityManifest(
+        id="document_access",
+        # Bump on every config-surface change: the version keys the stored-slice
+        # schema_version and the control-plane chat-controls cache.
+        version="0.2.0",
+        name="capability.document_access.name",
+        description="capability.document_access.description",
+        icon="find_in_page",
+        config_fields=[
+            FieldSpec(
+                key="attachments",
+                type="boolean",
+                title="capability.document_access.fields.attachments.title",
+                description="capability.document_access.fields.attachments.description",
+                default=True,
+                # `ui.group` drives the form's visual sections: the renderer
+                # draws a thin divider whenever the group changes between two
+                # consecutive visible fields.
+                ui=UIHints(group="sources"),
+            ),
+            FieldSpec(
+                key="team_documents",
+                type="boolean",
+                title="capability.document_access.fields.team_documents.title",
+                description="capability.document_access.fields.team_documents.description",
+                default=True,
+                ui=UIHints(group="sources"),
+            ),
+            FieldSpec(
+                key="show_library_selection",
+                type="boolean",
+                title="capability.document_access.fields.show_library_selection.title",
+                description="capability.document_access.fields.show_library_selection.description",
+                default=True,
+                ui=UIHints(group="scope", visible_when="team_documents"),
+            ),
+            FieldSpec(
+                key="bind_libraries",
+                type="boolean",
+                title="capability.document_access.fields.bind_libraries.title",
+                description="capability.document_access.fields.bind_libraries.description",
+                default=False,
+                ui=UIHints(group="scope", visible_when="team_documents"),
+            ),
+            FieldSpec(
+                key="library_tag_ids",
+                type="array",
+                item_type="string",
+                title="capability.document_access.fields.library_tag_ids.title",
+                description="capability.document_access.fields.library_tag_ids.description",
+                # Library/document tree picker, only shown while the binding
+                # toggle above is on (the ids are ignored otherwise).
+                ui=UIHints(
+                    widget="document_libraries",
+                    visible_when="bind_libraries",
+                    group="scope",
+                ),
+            ),
+            FieldSpec(
+                key="show_document_selection",
+                type="boolean",
+                title="capability.document_access.fields.show_document_selection.title",
+                description="capability.document_access.fields.show_document_selection.description",
+                default=True,
+                ui=UIHints(group="scope", visible_when="team_documents"),
+            ),
+            FieldSpec(
+                key="default_top_k",
+                type="integer",
+                title="capability.document_access.fields.default_top_k.title",
+                description="capability.document_access.fields.default_top_k.description",
+                default=8,
+                min=1,
+                ui=UIHints(group="retrieval", advanced=True),
+            ),
+            FieldSpec(
+                key="min_source_score_ratio",
+                type="number",
+                title="capability.document_access.fields.min_source_score_ratio.title",
+                description="capability.document_access.fields.min_source_score_ratio.description",
+                default=DEFAULT_MIN_SOURCE_SCORE_RATIO,
+                min=0.0,
+                max=1.0,
+                ui=UIHints(group="retrieval", advanced=True),
+            ),
+            FieldSpec(
+                key="show_search_policy_control",
+                type="boolean",
+                title="capability.document_access.fields.show_search_policy_control.title",
+                description="capability.document_access.fields.show_search_policy_control.description",
+                default=True,
+                ui=UIHints(group="search_policy", advanced=True),
+            ),
+            FieldSpec(
+                key="search_policy",
+                type="select",
+                enum=list(_SEARCH_POLICIES),
+                title="capability.document_access.fields.search_policy.title",
+                description="capability.document_access.fields.search_policy.description",
+                ui=UIHints(group="search_policy", advanced=True),
+            ),
+            FieldSpec(
+                key="show_rag_scope_control",
+                type="boolean",
+                title="capability.document_access.fields.show_rag_scope_control.title",
+                description="capability.document_access.fields.show_rag_scope_control.description",
+                default=True,
+                ui=UIHints(group="rag_scope", advanced=True),
+            ),
+            FieldSpec(
+                key="default_rag_scope",
+                type="select",
+                enum=list(_RAG_SCOPES),
+                title="capability.document_access.fields.default_rag_scope.title",
+                description="capability.document_access.fields.default_rag_scope.description",
+                ui=UIHints(group="rag_scope", advanced=True),
+            ),
+        ],
+        # No new chat part / side panel / router / owned table — the pilot's
+        # smallest real surface (RFC §10). team_scope=default_on: baseline
+        # document access should work without a per-team admin gate (RFC §8.3).
+        team_scope=TeamScopePolicy.DEFAULT_ON,
+    )
+    ConfigModel = DocumentAccessConfig
+    TurnOptionsModel = DocumentAccessTurnOptions
+
+    def chat_controls(self, config: DocumentAccessConfig) -> list[ChatControlSpec]:
+        """
+        The stock composer controls (RFC §3.3), each behind its config toggle —
+        the same widget set the legacy MCP search tool emits, so both paths
+        offer the same chat surface. `bound_library_ids` pins the scope picker
+        to the capability's configured library scope (read-only) when one is
+        set. Search-policy/RAG-scope choices travel on `RuntimeContext`, which
+        the document-search adapter already honors.
+        """
+
+        controls: list[ChatControlSpec] = []
+        if config.attachments:
+            controls.append(ChatControlSpec(widget="attach_files"))
+        # Same visibility algebra as the legacy MCP tool: binding replaces the
+        # free library picker with a read-only pinned list; the document picker
+        # is independent. Without team documents there is no corpus to scope.
+        corpus = config.team_documents
+        bound = (
+            (config.library_tag_ids or None)
+            if corpus and config.bind_libraries
+            else None
+        )
+        show_libraries = (
+            corpus and not config.bind_libraries and config.show_library_selection
+        )
+        show_documents = corpus and config.show_document_selection
+        if show_libraries or show_documents or bound:
+            controls.append(
+                ChatControlSpec(
+                    widget="document_scope",
+                    params=DocumentScopeControlParams(
+                        libraries=show_libraries or bool(bound),
+                        documents=show_documents,
+                        bound_library_ids=bound,
+                    ),
+                )
+            )
+        if config.show_search_policy_control:
+            controls.append(
+                ChatControlSpec(
+                    widget="search_policy",
+                    params=(
+                        SearchPolicyControlParams(default=config.search_policy)  # type: ignore[arg-type]
+                        if config.search_policy in _SEARCH_POLICIES
+                        else SearchPolicyControlParams()
+                    ),
+                )
+            )
+        if config.show_rag_scope_control:
+            default = config.default_rag_scope
+            controls.append(
+                ChatControlSpec(
+                    widget="rag_scope",
+                    params=RagScopeControlParams(
+                        default=default if default in _RAG_SCOPES else "hybrid",  # type: ignore[arg-type]
+                    ),
+                )
+            )
+        return controls
+
+    def tools(
+        self,
+        ctx: CapabilityContext[DocumentAccessConfig, DocumentAccessTurnOptions],
+    ) -> Sequence[BaseTool]:
+        """
+        Build the single vector-search tool, bound to the turn's typed
+        context (RFC §3.2, §5). This is the ONLY runtime contribution of this
+        capability — `AgentCapability.middleware()`'s default wraps this for
+        `create_agent()`; no ReAct-loop-specific hook is needed.
+
+        Return-convention note:
+        kept as `@tool(..., response_format="content_and_artifact")` returning
+        a `(content, ToolInvocationResult)` tuple. Verified empirically
+        (`test_capability_tool_return_convention.py`) that this is correct for the only
+        execution path this tool goes through today — `create_agent()`'s real
+        ToolCall-based tool-calling loop, which builds a `ToolMessage` whose
+        `.artifact` carries the `ToolInvocationResult` (and its `.sources`)
+        intact. A plain-dict `.ainvoke()` call (the shape Graph's
+        `invoke_runtime_tool` and the MCP runtime-provider resolver both use)
+        does NOT preserve this: LangChain collapses a `content_and_artifact`
+        response to the bare content string with NO tuple and NO artifact at
+        all when there is no `ToolCall` to attach it to — worse than the
+        tuple-collapse the original plan assumed. Switching to a bare
+        `ToolInvocationResult` return (the runtime-provider convention)
+        would fix that path but breaks THIS one: without
+        `response_format="content_and_artifact"`, `create_agent()`'s ToolCall
+        loop stringifies the whole model into `ToolMessage.content` and never
+        populates `.artifact`. Since Phase 1 does not wire this tool into any
+        plain-dict invocation path (that's Phase 4), the existing convention
+        is correct as-is; Phase 2+ must adapt at the tool-carrier/assembly
+        seam rather than change this tool's return shape again.
+        """
+
+        config = ctx.config
+        turn = ctx.turn_options
+        services = ctx.services
+
+        # Capability-config ∩ turn-option → the params handed to the port. This
+        # enforces `turn_option ⊆ capability_config`; the adapter then bounds the
+        # result by the session binding (`⊆ session_binding`).
+        # Bound library ids only apply while the binding toggle is on — same
+        # semantics as the legacy tool (the tree's value is kept but inert
+        # when unbound).
+        bound_library_ids = (
+            (config.library_tag_ids or None)
+            if config.team_documents and config.bind_libraries
+            else None
+        )
+        scoped_library_tag_ids = narrow_scope_ids(
+            bound_library_ids, turn.library_tag_ids
+        )
+        scoped_document_uids = narrow_scope_ids(
+            config.document_uids or None, turn.document_uids
+        )
+        default_top_k = config.default_top_k if config.default_top_k > 0 else 8
+        # With the search-policy picker shown, the configured policy is only
+        # the picker's DEFAULT: pass None so the adapter falls back to the
+        # per-turn RuntimeContext value (which carries that default anyway).
+        # With the picker hidden, the configured policy is enforced.
+        search_policy = (
+            None if config.show_search_policy_control else config.search_policy
+        )
+        min_source_score_ratio = config.min_source_score_ratio
+
+        @tool(
+            "search_documents_using_vectorization",
+            response_format="content_and_artifact",
+        )
+        async def search_documents_using_vectorization(
+            question: str,
+            top_k: int | None = None,
+        ) -> tuple[str, ToolInvocationResult]:
+            """Search the selected document libraries using semantic similarity
+            (RAG) — call this BEFORE answering any factual, technical, or
+            domain-specific question.
+
+            The corpus may hold more specific or more recent information than
+            you already know. Skip this tool only for purely conversational
+            exchanges (greetings, thanks, clarifying what was just said).
+
+            Covers prose/text documents. If a hit describes a structured/tabular
+            dataset (a "dataset pointer"), do not answer from it directly — pivot
+            to the tabular/SQL tool it names instead.
+
+            Returns ranked hits with title and content. Only use information
+            actually present in the returned hits; never invent facts beyond
+            them.
+            """
+
+            port = services.document_search
+            if port is None:
+                # No platform port injected (e.g. a bare test harness). Fail
+                # LOUD in the tool result rather than silently returning nothing.
+                raise RuntimeError(
+                    "document_access: RuntimeServices.document_search is not "
+                    "available on this execution path."
+                )
+
+            effective_top_k = top_k if isinstance(top_k, int) and top_k > 0 else None
+            started = time.monotonic()
+            try:
+                result: DocumentSearchResult = await port.search(
+                    question,
+                    top_k=effective_top_k or default_top_k,
+                    library_tag_ids=scoped_library_tag_ids,
+                    document_uids=scoped_document_uids,
+                    search_policy=search_policy,
+                    include_attachments=config.attachments,
+                    include_team_documents=config.team_documents,
+                )
+            except Exception as exc:
+                run_stop = unwrap_run_stop_error(exc)
+                if run_stop is not None:
+                    raise run_stop from None
+                # Same contract as the sibling tools: a failing tool returns an
+                # `is_error=True` artifact rather than raising, or the default
+                # ToolNode handler re-raises and the whole turn dies with an
+                # empty error detail. Observed live on an expired-token 401
+                # (#2073 Item 3) — this is the most-used RAG tool, so it was
+                # the one that took the turn down.
+                return _document_tool_failure(
+                    tool_ref=DOCUMENT_ACCESS_TOOL_REF,
+                    action="search documents",
+                    exc=exc,
+                    elapsed_s=time.monotonic() - started,
+                )
+            hits = result.hits
+
+            content = {
+                "query": question,
+                "hits": [
+                    {
+                        k: v
+                        for k, v in hit.model_dump(mode="json").items()
+                        if k in _LLM_FIELDS
+                    }
+                    for hit in hits
+                ],
+            }
+            # `blocks` feed the LLM the full hit set (the model needs to see a
+            # dataset pointer to know to pivot to the tabular tool, and every
+            # hit to reason with) — `sources` (the chat Sources panel) is
+            # narrowed separately: never a pointer chunk (no real content to
+            # cite), and never a hit that's noise relative to the best match
+            # in this call (found live citing near-zero-relevance paragraphs
+            # from an unrelated document, RAG-DATASET-DISCOVERY-RFC.md §7).
+            artifact = ToolInvocationResult(
+                tool_ref=DOCUMENT_ACCESS_TOOL_REF,
+                blocks=(ToolContentBlock(kind=ToolContentKind.JSON, data=content),),
+                sources=select_citable_sources(
+                    hits, min_score_ratio=min_source_score_ratio
+                ),
+            )
+            return json.dumps(content), artifact
+
+        @tool("list_document_tree", response_format="content_and_artifact")
+        async def list_document_tree(
+            working_directory: str | None = None,
+            max_chars: int = 6000,
+        ) -> tuple[str, ToolInvocationResult]:
+            """List the folders and documents in the user's document scope as a tree.
+
+            Call this first to orient on what's available before searching or
+            summarizing — it shows folder structure and, for each document, its
+            name, uid, and upload date, not its content.
+
+            Documents are rendered as "name [document_uid] (uploaded date)" —
+            use that uid as the `document_uid` argument to summarize_document.
+            Folder lines end with "/" and are rendered as "name [folder:id]/":
+            a folder id is NOT a document_uid — never pass it to
+            summarize_document (the call will fail). To summarize a folder's
+            content, summarize each document leaf under it instead. The
+            bracketed identifiers are internal working ids for YOUR tool
+            calls only: NEVER repeat them in your answer to the user — always
+            refer to documents by their display name.
+
+            `working_directory` narrows the listing to a specific folder (e.g.
+            "Sales/HR"); omit it to start from the root. The tree is rendered as
+            indented text, with documents appearing as leaves under every folder
+            they belong to (a document can be in more than one folder).
+
+            If the corpus is too large to show in full, the deepest branches are
+            pruned and a note tells you how many items were omitted — when that
+            happens, narrow `working_directory` or switch to
+            search_documents_using_vectorization instead of trying to browse
+            everything.
+            """
+
+            port = services.document_tree
+            if port is None:
+                raise RuntimeError(
+                    "document_access: RuntimeServices.document_tree is not "
+                    "available on this execution path."
+                )
+
+            effective_max_chars = _clamp(max_chars, _TREE_MAX_CHARS_BOUNDS)
+            started = time.monotonic()
+            try:
+                result: DocumentTreeResult = await port.tree(
+                    working_directory=working_directory,
+                    library_tag_ids=scoped_library_tag_ids,
+                    document_uids=scoped_document_uids,
+                    max_chars=effective_max_chars,
+                )
+            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="list_document_tree",
+                    action="list the document tree",
+                    exc=exc,
+                    elapsed_s=time.monotonic() - started,
+                )
+            # `blocks` carries the same tree text as `content` (CAPAB-02): a
+            # Graph agent's plain-dict invocation keeps only the artifact half
+            # of a `content_and_artifact` return (`_adapt_capability_tool_for_graph`,
+            # `graph_runtime.py`) — an artifact with no payload silently loses
+            # the tree for a Graph node, exactly the "never silently degrade"
+            # failure RFC §3.9 forbids. ReAct is unaffected: `content` is
+            # still what the model reads.
+            artifact = ToolInvocationResult(
+                tool_ref="list_document_tree",
+                blocks=(ToolContentBlock(kind=ToolContentKind.TEXT, text=result.tree),),
+            )
+            return result.tree, artifact
+
+        tools: list[BaseTool] = [search_documents_using_vectorization]
+        # The tree lists the corpus only (no session-attachment enumeration yet,
+        # see module docstring), so it is dropped rather than registered-but-empty.
+        if config.team_documents:
+            tools.append(list_document_tree)
+        return tools

fred_capability_document_access-4.4.3.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: fred-capability-document-access
+Version: 4.4.3
+Summary: Fred agent capability: scoped vector search and document-tree listing over the Knowledge Flow corpus (document_access).
+Author-email: Thales <noreply@thalesgroup.com>
+License: Apache-2.0
+Project-URL: Homepage, https://site.fredlab.dev
+Project-URL: Repository, https://github.com/ThalesGroup/fred
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fred-core>=4.4.3
+Requires-Dist: fred-sdk[agents]>=4.4.3
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.8.6; extra == "dev"
+Requires-Dist: basedpyright==1.31.0; extra == "dev"
+Requires-Dist: detect-secrets>=1.5.0; extra == "dev"
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: pytest-socket>=0.7.0; extra == "dev"
+Requires-Dist: ruff<0.16,>=0.15.22; extra == "dev"
+
+# fred-capability-document-access
+
+Fred agent capability giving an agent scoped access to the Knowledge Flow
+document corpus: `search_documents_using_vectorization` (semantic/RAG search)
+and `list_document_tree` (folder and document listing, names and uids only).
+
+It is the reference implementation a capability author copies: real tools wired
+to platform services through typed SDK ports, static config-field scoping, and
+one computed chat-turn narrowing control — with no HTTP stack, no access token
+and no per-turn binding anywhere in the capability.
+
+## Scoping
+
+Three levels narrow each other, never widen:
+
+    turn_option  ⊆  capability_config  ⊆  session_binding
+
+The capability enforces the first (`narrow_scope_ids`, in `capability.py`); the
+runtime's `DocumentSearchAdapter` enforces the second. The tool signature the
+model sees carries only `question` / `top_k` — scope and identity travel in the
+middleware closure and can never be widened by the model.
+
+## Chat controls
+
+`chat_controls(config)` emits up to four stock composer widgets behind their
+config toggles: `attach_files`, `document_scope`, `search_policy`, `rag_scope`.
+Their params are SDK models (`fred_sdk.contracts.models`) and carry the widget's
+*default* only — the value the user picks travels on `RuntimeContext`.
+
+## Tests
+
+`make test` runs offline: the ports are faked, no service is contacted. The dev
+group depends on `fred-runtime` for `CapabilityRegistry` (entry-point discovery)
+and `build_capability_context`; the capability itself depends only on
+`fred-core` and `fred-sdk`.

fred_capability_document_access-4.4.3.dist-info/RECORD

@@ -0,0 +1,8 @@
+fred_capability_document_access/__init__.py,sha256=X6RAL-lmFQV3uiUR3DuvRzTUsr7HnKWMUXLHtQO7DB8,1188
+fred_capability_document_access/capability.py,sha256=95-V-MD5zX5HZhs4MLz3-HsRpa8jQeGiluJLnY18HyE,36092
+fred_capability_document_access/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fred_capability_document_access-4.4.3.dist-info/METADATA,sha256=4Q_ITVcDyrRFHUvP_A9lMFvLIj32wiXj78Xus8-loBU,2808
+fred_capability_document_access-4.4.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fred_capability_document_access-4.4.3.dist-info/entry_points.txt,sha256=DWjm5ABec9HPVlM2GQWFgXoM1_I_eOJWvfZwvsTdOsE,106
+fred_capability_document_access-4.4.3.dist-info/top_level.txt,sha256=t-N9Y97OGCjsBMG6mGSsvw6bqC9VvgvnIlA_lZPsLz0,32
+fred_capability_document_access-4.4.3.dist-info/RECORD,,

fred_capability_document_access-4.4.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fred_capability_document_access-4.4.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[fred.capabilities]
+document_access = fred_capability_document_access.capability:DocumentAccessCapability

fred_capability_document_access-4.4.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+fred_capability_document_access