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`.
