Retrieval¶
The retriever port, documents with sources, callable, embedding, LlamaIndex and LangChain retrievers, and retriever_tool. Concepts: Retrieval (RAG).
Retrieval (RAG): the RetrieverPort, Document, backends and a cited retriever_tool.
FilterValue = str | int | float | bool
module-attribute
¶
Filters = Mapping[str, FilterValue]
module-attribute
¶
MAX_K = 100
module-attribute
¶
RETRIEVAL_KIND = 'retrieval'
module-attribute
¶
RetrieveFn = Callable[[str, int, dict[str, FilterValue]], Any]
module-attribute
¶
ToolFilters = Filters | Callable[[ToolContext], Filters]
module-attribute
¶
CallableRetriever
¶
Bases: GuardedRetriever
Wraps fn(query, k, filters); a sync fn runs in a worker thread with the contextvars.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
|
ConfigError
|
a bad |
Document
¶
Bases: BaseModel
One retrieved passage: a stable id, its text, a score (higher is better) and its source.
cited(*, include_metadata=False, max_chars=None)
¶
The JSON shape a model sees: id, text, score and source (metadata only if asked).
EmbeddingRetriever
¶
Bases: GuardedRetriever
In-memory cosine search; with scope_key, documents and searches need a non-empty scope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scope_key
|
str | None
|
Metadata key every document must carry and every search must filter on. |
None
|
add(documents, *, ctx=None)
async
¶
Embed documents (and any still queued) now; how many were added.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
a bad document, a repeated id, a missing scope or too many documents. |
ModelError
|
the embedder failed. |
add_sync(documents, *, timeout=None, **kw)
¶
add from sync code.
GuardedRetriever
¶
Bases: ABC
A RetrieverPort that checks its inputs and never returns a document outside filters.
Backends implement _retrieve. Every result is re-checked here: a document whose
metadata does not match the filters is dropped, so a backend that ignores filters fails
closed (fewer results), never open.
retrieve(query, *, k=5, filters=None, ctx=None)
async
¶
Up to k documents for query whose metadata matches every filter, best first.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
bad query, k or filters, or the backend returned a non-document. |
IntegrationError
|
the backend failed or timed out (the cause is chained). |
retrieve_sync(query, *, timeout=None, **kw)
¶
retrieve from sync code, on the process-wide loop.
LangChainRetriever
¶
Bases: GuardedRetriever
Calls retriever.ainvoke(query, **search_kwargs(k, filters)) (or invoke in a thread).
LangChain retrievers take no k or filters by default, so none are sent unless you give
search_kwargs (a vector-store retriever accepts {"k": k, "filter": filters}). Results
are cut to k and re-checked against filters: a mismatch is dropped, never returned.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
|
LlamaIndexRetriever
¶
Bases: GuardedRetriever
Searches an index (as_retriever(similarity_top_k=k, filters=...)) or a retriever.
An index gets k and the filters natively (MetadataFilters by default, or your
native_filters(filters)). A bare retriever keeps its own top-k and filters; the
results are still re-checked against filters, so a mismatch is dropped, never returned.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
the object has neither |
RetrieverPort
¶
Bases: Protocol
Finds up to k documents for query that match filters, best first.
Source
¶
Bases: BaseModel
Where a document came from, for citations: a link or path and a title.
retriever_tool(retriever, *, name='search_docs', description=DEFAULT_DESCRIPTION, k=5, filters=None, include_metadata=False, max_chars=None, cache_ttl=None, cache_scope='run', timeout=None, tags=())
¶
A tool (kind "retrieval") that searches retriever for the model's query.
The model chooses only the query. k and filters are the host's, so a prompt can never
widen a search to another scope. Calls run through the executor like any tool.
Raises:
| Type | Description |
|---|---|
ConfigError
|
a bad |
ToolUsageError
|
|