enterprise_ai.rag
Source: sdks/python/src/enterprise_ai/rag/__init__.py. Back to the Python SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class RagClient
/v1/knowledge-bases.
Resource
RagClient.chunks
chunks(kb_id: str, doc_id: str, include_content: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any
List the chunks of a document. Chunks of the current version of a document in position order, paginated with cursor: chunk_id, ordinal, content (decrypted for sealed chunks), classification, sealed, active, generation, fts_config (text search configuration) and metadata (source_page, section_title, element_type, language, char_start, char_end, bbox, document_version, content_hash, embedding_model, token_count, structure with the table split marks). Only the chunks whose readers and classification the caller passes are listed. A quarantined or rejected document is shown only to tenant_admin, security_officer or data_steward (403 forbidden). Needs the ReBAC relation viewer; 404 not_found for a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/chunks (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
doc_id | str | yes | Identifier (UUID) of the current document. | |
include_content | bool | None | None | no | When false, content is null (metadata only). Default true. |
limit | int | None | None | no | Maximum number of items in one page. The server caps the value; read the next page with cursor. |
cursor | str | None | None | no | Opaque cursor returned as next_cursor by the previous page. Omit it to read the first page. |
Returns: Any. Decoded JSON answer of the operation "List the chunks of a document".
Raises: the typed errors of the transport (Errors).
RagClient.cite
cite(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
query | str | yes | Text of the query (at least 1 character). | |
top_k | int | 5 | no | Number of results (1 to 100, default 5). |
**params | Any | no | Extra fields merged into the request. |
Returns: Any. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.create
create(name: str, description: str | None = None, classification: str = 'internal', embedding_model: str | None = None, dimensions: int | None = None, chunking: str | None = None, retrieval: dict[str, Any] | None = None, **extra: Any) -> Any
Create a knowledge base. Creates a knowledge base with its embedding model (default: the platform RAG embedding model), which must be approved, have the embeddings capability and accept the classification. chunk_overlap must be lower than chunk_size (400 invalid_request); an unknown classification answers 400. A name already used in the tenant answers 409 conflict. Needs tenant_admin or developer; the caller becomes ReBAC owner. Audited as knowledge_base.create.
Route: /v1/knowledge-bases (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | str | yes | Name, unique in the tenant (1 to 120 characters). | |
description | str | None | None | no | Free description. Default empty. |
classification | str | 'internal' | no | Default classification of the documents: public, internal (default), confidential, restricted or secret. |
embedding_model | str | None | None | no | Registry model with the embeddings capability (default: the platform RAG embedding model). |
dimensions | int | None | None | no | Vector size, one of the sizes the model declares (1 to 16384; default: its native size). |
chunking | str | None | None | no | words (default: word chunks of chunk_size with chunk_overlap, each located in the text with its page, section and element type, a chunk boundary inside a table marked table_split) or structure (chunks follow titles, paragraphs, lists, tables and code; a table stays whole up to 3 chunk sizes, a longer one is split between rows with its header row repeated). |
retrieval | dict[str, Any] | None | None | no | Retrieval strategy of the knowledge base (see RetrievalIn). Default: every field at its default. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Create a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.delete
delete(kb_id: str) -> Any
Delete a knowledge base. Deletes the knowledge base, its documents and their vectors in the vector store. Needs the ReBAC relation owner, and the caller must be tenant_admin or its creator (403 forbidden). 404 not_found; 503 vector_store_unavailable. Audited as knowledge_base.delete.
Route: /v1/knowledge-bases/{kb_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. |
Returns: Any. Decoded JSON answer of the operation "Delete a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.delete_document
delete_document(kb_id: str, doc_id: str) -> Any
Delete a document. Deletes the document and its vectors. Needs the ReBAC relation editor and write access by the ACL: tenant_admin, an identity listed in writers, or, when writers is empty, developer or agent (else 403 not_permitted_acl). 404 not_found. Audited as knowledge.document.delete.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
doc_id | str | yes | Identifier (UUID) of the document. |
Returns: Any. Decoded JSON answer of the operation "Delete a document".
Raises: the typed errors of the transport (Errors).
RagClient.diagnostics
diagnostics(kb_id: str, diagnostics_id: str | None = None, limit: int | None = None) -> Any
List the diagnostics of the queries. Recorded diagnostics of the queries on the knowledge base, newest first, diagnostics_id of an answer to select one: mode, effective strategy, stages (stage name, duration in milliseconds, candidates in and out), counts (filtered documents, dense and lexical candidates, fused, screened, deduplicated, dropped by the revalidation, final, context neighbours, cache hit) and results (rank, chunk, document, named scores). The query text is not stored, only its SHA-256. A caller sees its own queries; tenant_admin, security_officer, data_steward and auditor see every query. Needs the ReBAC relation viewer; 404 not_found for a caller outside the ACL or a diagnostics_id it cannot see.
Route: /v1/knowledge-bases/{kb_id}/query-diagnostics (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
diagnostics_id | str | None | None | no | Identifier (UUID) of one recorded diagnostics, the diagnostics_id of a query answer. Optional. |
limit | int | None | None | no | Maximum number of diagnostics returned (1 to 100, default 20). |
Returns: Any. Decoded JSON answer of the operation "List the diagnostics of the queries".
Raises: the typed errors of the transport (Errors).
RagClient.document_status
document_status(kb_id: str, doc_id: str) -> Any
Read the status of a document. Status of one document version: document_id, document_key, version, version_state (current, superseded or deleted), document_status (uploaded, active, quarantined, rejected, failed...), searchable (true only for the current active version), chunks, extractor, and ingestion, the last ingestion job (job_id, state, attempts, last_error, updated_at) or null for a synchronous ingestion. Needs the ReBAC relation viewer; 404 not_found for a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/status (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
doc_id | str | yes | Identifier (UUID) of the document version, the document_id of the upload answer. |
Returns: Any. Decoded JSON answer of the operation "Read the status of a document".
Raises: the typed errors of the transport (Errors).
RagClient.documents
documents(kb_id: str, **page: Any) -> Any
List the documents of a knowledge base. Documents the caller may read (one of its identities in the document readers, classification within its clearance), paginated with cursor. Needs the ReBAC relation viewer and read access to the knowledge base.
Route: /v1/knowledge-bases/{kb_id}/documents (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
**page | Any | no | Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor. |
Returns: Any. Decoded JSON answer of the operation "List the documents of a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.get
get(kb_id: str) -> Any
Get a knowledge base. Returns the knowledge base with its document count, its ingestion and retrieval pipeline, the running reindex job if any and the datasets the caller may see. Needs the ReBAC relation viewer and read access by the ACL; otherwise 404 not_found.
Route: /v1/knowledge-bases/{kb_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. |
Returns: Any. Decoded JSON answer of the operation "Get a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.ingest
ingest(kb_id: str, content: str | None = None, title: str | None = None, uri: str | None = None, classification: str | None = None, mime_type: str | None = None, metadata: dict[str, Any] | None = None, collection: str | None = None, language: str | None = None, **extra: Any) -> Any
Add a document. Ingests a document (201). Needs the ReBAC relation editor and write access by the ACL (403 not_permitted_acl). Steps: 1. The content (content or content_base64, one is required, else 400) is scanned by ClamAV and YARA-X (422 file_blocked, 503 file_scan_unavailable), then the text is extracted by Docling (422 unsupported_media). 2. Personal data detection may raise the classification; a source_connector must be active. 3. A document with the same uri replaces the previous version (version + 1). 4. The text is chunked, embedded and stored; the poisoning screening may put the document in quarantine (status: quarantined). 409 knowledge_base_reindexing while a reindex runs; 409 embedding_dimension_mismatch; 503 vector_store_unavailable. Audited as knowledge.document.ingest.
Route: /v1/knowledge-bases/{kb_id}/documents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
content | str | None | None | no | Content as text. Takes precedence over content_base64. |
title | str | None | None | no | Title of the document, also used as file name for the scan and the extraction. Default empty. |
uri | str | None | None | no | Source URI. A new document with the same URI replaces the previous version. |
classification | str | None | None | no | public, internal, confidential, restricted or secret. Default: the classification of the knowledge base; raised when personal data is detected. |
mime_type | str | None | None | no | Media type of the content. Default text/plain. |
metadata | dict[str, Any] | None | None | no | Free key-value pairs stored with the object and returned as they are; the platform never interprets them. |
collection | str | None | None | no | Collection of the document inside the knowledge base (1 to 200 characters), used by the collections query filter. Default none. |
language | str | None | None | no | Language of the document (ISO 639-1 code such as fr or en). Default: detected from the text; each chunk also gets its own detected language, which picks its full text configuration (simple when unknown). |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Add a document".
Raises: the typed errors of the transport (Errors).
RagClient.ingestion_job
ingestion_job(kb_id: str, job_id: str) -> Any
Read an ingestion job. An asynchronous ingestion job: job_id, kb_id, document_id, document_key, version, state (uploaded, quarantined, scanning, rejected, extracting, normalizing, chunking, embedding, indexing, enriching_memory, ready, partially_ready, failed, reindexing, deleting or deleted), attempts, lease_owner, lease_expires_at, next_attempt_at, last_error, title, file name, media type, detected_format, size_bytes, sha256, scan_id, extractor (the one that ran), storage (profile and quarantine or permanent location), creation, update and end, and history: every transition with from_state, to_state, at and detail (scan verdict, extractor, chunk count, retry with its backoff, OCR failure, memory skipped). Needs the ReBAC relation viewer; 404 not_found for a job of another knowledge base or a document the caller cannot read.
Route: /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
job_id | str | yes | Identifier (UUID) of the ingestion job, the job_id of the upload answer. |
Returns: Any. Decoded JSON answer of the operation "Read an ingestion job".
Raises: the typed errors of the transport (Errors).
RagClient.list
list(**page: Any) -> Any
List the knowledge bases. Knowledge bases of the tenant that the caller may read by their ACL, in name order, paginated with cursor.
Route: /v1/knowledge-bases (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**page | Any | no | Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor. |
Returns: Any. Decoded JSON answer of the operation "List the knowledge bases".
Raises: the typed errors of the transport (Errors).
RagClient.quarantine
quarantine(kb_id: str) -> Any
List the quarantined documents. Documents isolated by the poisoning screening (data steward review queue), oldest first, at most 200, each with the screening reasons in quarantine. Their chunks are not searchable. Needs tenant_admin, security_officer or data_steward and the ReBAC relation viewer.
Route: /v1/knowledge-bases/{kb_id}/quarantine (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. |
Returns: Any. Decoded JSON answer of the operation "List the quarantined documents".
Raises: the typed errors of the transport (Errors).
RagClient.query
query(kb_id: str, query: str, top_k: int = 5, min_score: float | None = None, mode: str | None = None, rerank: bool | None = None, rerank_model: str | None = None, filters: dict[str, Any] | None = None, diagnostics: bool | None = None, **extra: Any) -> Any
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
query | str | yes | Text of the query (at least 1 character). | |
top_k | int | 5 | no | Number of results (1 to 100, default 5). |
min_score | float | None | None | no | Minimum vector similarity score of a result. Default 0. |
mode | str | None | None | no | vector or dense (cosine similarity), lexical (PostgreSQL full text) or hybrid (fusion of both). Default: the mode of the knowledge base strategy, else vector. |
rerank | bool | None | None | no | When true, order the results with a rerank model. Default: the strategy of the knowledge base, else false. |
rerank_model | str | None | None | no | Registry model with the rerank capability (default: the platform rerank model). Without one, warnings reports reranker_not_configured. |
filters | dict[str, Any] | None | None | no | Filters by collection, document, metadata, element type and language (see QueryFilters). |
diagnostics | bool | None | None | no | When true, the answer adds diagnostics (stages with timing, candidate counts, strategy, filters); the retrieval cache is not read. Default false; the diagnostics are recorded in any case. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.reindex
reindex(kb_id: str, embedding_model: str, dimensions: int | None = None) -> Any
Reindex with another embedding model. Queues the move of the knowledge base to another embedding model (worker job embeddings_reindex) and answers 202 with the job. The model must be approved, have the embeddings capability and accept the highest classification of the knowledge base and its documents (422 otherwise). The new vectors form a new generation; the two spaces are never mixed. Needs tenant_admin or developer, the ReBAC relation owner and write access. 409 knowledge_base_reindexing if a job is already running. Audited as knowledge_base.reindex.request.
Route: /v1/knowledge-bases/{kb_id}/reindex (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
embedding_model | str | yes | Registry model with the embeddings capability (1 to 200 characters). | |
dimensions | int | None | None | no | Vector size, one of the sizes the model declares (1 to 16384; default: native). |
Returns: Any. Decoded JSON answer of the operation "Reindex with another embedding model".
Raises: the typed errors of the transport (Errors).
RagClient.reindex_jobs
reindex_jobs(kb_id: str) -> Any
List the reindex jobs. Reindex jobs of the knowledge base: status, source and target model, dimensions and generation, progress in documents and chunks, attempts, error and dates. Needs the ReBAC relation viewer and read access.
Route: /v1/knowledge-bases/{kb_id}/reindex-jobs (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. |
Returns: Any. Decoded JSON answer of the operation "List the reindex jobs".
Raises: the typed errors of the transport (Errors).
RagClient.retrieve
retrieve(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
query | str | yes | Text of the query (at least 1 character). | |
top_k | int | 5 | no | Number of results (1 to 100, default 5). |
**params | Any | no | Extra fields merged into the request. |
Returns: Any. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.retry_ingestion
retry_ingestion(kb_id: str, job_id: str, reason: str | None = None) -> Any
Retry a failed ingestion job. Puts a failed job back in the queue: to extracting when its scan already released the file (never scanned twice), else to quarantined; the attempts start again from zero. Any other state is refused with 409 ingestion_job_not_failed (a rejected file is never retried). Answers the job with its history. Audited knowledge.ingestion.retry. Needs the ReBAC relation editor.
Route: /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id}/retry (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
job_id | str | yes | Identifier (UUID) of the failed ingestion job. | |
reason | str | None | None | no | Why the action is taken. Written to the audit trail with the actor and the time. |
Returns: Any. Decoded JSON answer of the operation "Retry a failed ingestion job".
Raises: the typed errors of the transport (Errors).
RagClient.review
review(kb_id: str, doc_id: str, decision: str, reason: str | None = None) -> Any
Review a quarantined document. Releases (chunks searchable again, status: active) or rejects (status: rejected) a quarantined document. Needs tenant_admin, security_officer or data_steward; the policy knowledge.document.review is evaluated. 409 document_not_quarantined; 404 not_found. The decision is recorded and audited as knowledge.document.release or knowledge.document.reject.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/review (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
doc_id | str | yes | Identifier (UUID) of the document. | |
decision | str | yes | release (searchable again) or reject. | |
reason | str | None | None | no | Why (up to 2000 characters). Default empty. |
Returns: Any. Decoded JSON answer of the operation "Review a quarantined document".
Raises: the typed errors of the transport (Errors).
RagClient.search
search(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Query a knowledge base. Searches the knowledge base and returns results (chunk, score, injection risk, classification, provenance), citations and a lineage_run_id. Needs the ReBAC relation can_invoke. Steps: 1. The policy knowledge.query is evaluated and a quota reservation is taken. 2. The query is embedded with the model of the knowledge base; only chunks whose readers match the caller identities and whose classification fits its clearance are searched. 3. Retrieved chunks are screened for prompt injection (dropped in block mode) and checked against active sources. 4. hybrid re-scores the candidates with keyword overlap; rerank orders them with a rerank model (a refusal is reported in warnings, never hidden). A caller outside the ACL gets an empty result, audited as a denial. Audited as knowledge.query; usage is metered.
Route: /v1/knowledge-bases/{kb_id}/query (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
query | str | yes | Text of the query (at least 1 character). | |
top_k | int | 5 | no | Number of results (1 to 100, default 5). |
**params | Any | no | Extra fields merged into the request. |
Returns: Any. Decoded JSON answer of the operation "Query a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.set_acl
set_acl(kb_id: str, readers: list[str] | None = None, writers: list[str] | None = None, apply_to_documents: bool | None = None) -> Any
Replace the ACL of a knowledge base. Replaces the readers and writers of the knowledge base. With apply_to_documents, the documents that inherit the knowledge base ACL (no readers of their own) and their chunks get the new readers; documents_updated gives their number. Needs the ReBAC relation owner, and the caller must be tenant_admin, security_officer or the creator. Audited as knowledge_base.acl.update; the retrieval cache is invalidated.
Route: /v1/knowledge-bases/{kb_id}/acl (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
readers | list[str] | None | None | no | Identities allowed to read and query. Default ["*"]. |
writers | list[str] | None | None | no | Identities allowed to write. Empty: tenant_admin, developer and agent. |
apply_to_documents | bool | None | None | no | When true (default), the documents that inherit the knowledge base ACL get the new readers. |
Returns: Any. Decoded JSON answer of the operation "Replace the ACL of a knowledge base".
Raises: the typed errors of the transport (Errors).
RagClient.set_retrieval
set_retrieval(kb_id: str, **strategy: Any) -> Any
Set the retrieval strategy. Replaces the retrieval strategy of the knowledge base: default mode, fusion and its rrf_k, candidates per result, reranking and its model, deduplication, context window and token budget, conflict signal. A field left out takes its default; the options of a query override the strategy for that query. Needs the ReBAC relation owner and write access by the ACL (403 not_permitted_acl); 404 not_found for a caller outside the ACL. Audited as knowledge_base.retrieval.update; the retrieval cache is invalidated. Answers the knowledge base with its retrieval.
Route: /v1/knowledge-bases/{kb_id}/retrieval (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
**strategy | Any | no | Fields of the retrieval strategy (mode, fusion, rerank, token_budget...); a field left out takes its default. |
Returns: Any. Decoded JSON answer of the operation "Set the retrieval strategy".
Raises: the typed errors of the transport (Errors).
RagClient.upload_document
upload_document(kb_id: str, content: bytes, mime_type: str, filename: str = '', title: str = '', uri: str | None = None, classification: str | None = None, readers: list[str] | None = None, metadata: dict[str, Any] | None = None, collection: str | None = None, language: str | None = None, idempotency_key: str | None = None) -> Any
Upload a document for asynchronous ingestion. Checks the size (413 payload_too_large, limit EAI_RAG_UPLOAD_MAX_BYTES), the declared mime_type against the real signature of the bytes (PDF, DOCX, XLSX and PPTX as ZIP packages with the right content types, PNG, JPEG, TIFF; text formats must be valid UTF-8 without NUL) and the extension of filename: 422 unsupported_format, format_mismatch, extension_mismatch or archive_refused (archive bomb, nested archive, too large once decompressed). The bytes are stored in the quarantine prefix of the documents storage profile (409 ingestion_storage_required without one, 503 ingestion_storage_unavailable), the document version is recorded with document_status uploaded and a durable job is created. Answers 202 with job_id, kb_id, document_id, document_key, version, state (uploaded), detected_format, size_bytes and sha256, and a Location header. The worker job knowledge_ingestion then scans the file through the file security domain (fail closed), extracts, chunks, embeds and indexes it. The same Idempotency-Key replays the same answer (header Idempotency-Replayed); with another body it is refused with 409 idempotency_conflict. Needs the ReBAC relation editor.
Route: /v1/knowledge-bases/{kb_id}/documents/uploads (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
content | bytes | yes | Raw bytes of the document, encoded in base64 by the SDK and checked against mime_type by the server. | |
mime_type | str | yes | Declared media type, checked against the real signature of the bytes. | |
filename | str | '' | no | Original file name (up to 500 characters); its extension must match the declared format. Default: the title. |
title | str | '' | no | Title of the document (up to 500 characters). Default empty. |
uri | str | None | None | no | Source URI. A document with the URI of an existing one becomes its next version. |
classification | str | None | None | no | public, internal, confidential, restricted or secret. Default: the classification of the knowledge base. |
readers | list[str] | None | None | no | Readers of this document. Omitted: the readers of the knowledge base. |
metadata | dict[str, Any] | None | None | no | Free metadata kept with the document. |
collection | str | None | None | no | Collection of the document inside the knowledge base (1 to 200 characters). Default none. |
language | str | None | None | no | Language of the document (ISO 639-1 code). Default: detected from the extracted text. |
idempotency_key | str | None | None | no | Idempotency-Key header: a retry with the same key replays the first answer. |
Returns: Any. Decoded JSON answer of the operation "Upload a document for asynchronous ingestion".
Raises: the typed errors of the transport (Errors).
RagClient.versions
versions(kb_id: str, doc_id: str) -> Any
List the versions of a document. Version history of a document, newest first: document_key (stable across versions) and items with document_id, version, state (current, superseded or deleted), searchable (only the current active version is searched), title, URI, media type, classification, content_hash, size, chunk count, extractor, language, collection, document_status, creation, superseded_by and superseded_at, deleted_at, and the Docling artifacts (kind, storage profile, object key, size, SHA-256). doc_id may be the current document or any past version. A version is listed only when the caller is among its readers and its classification fits the clearance. Needs the ReBAC relation viewer; 404 not_found otherwise.
Route: /v1/knowledge-bases/{kb_id}/documents/{doc_id}/versions (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
kb_id | str | yes | Identifier (UUID) of the knowledge base. | |
doc_id | str | yes | Identifier (UUID) of the document or of one of its past versions. |
Returns: Any. Decoded JSON answer of the operation "List the versions of a document".
Raises: the typed errors of the transport (Errors).
Functions
to_segments
to_segments(builder: Any, kb_id: str, result: Any, priority: int = 60) -> list[Any]
Add query hits to a ContextBuilder as rag_document segments with provenance.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
builder | Any | yes | ContextBuilder receiving the segments through its add method. | |
kb_id | str | yes | Knowledge base of the hits, used in the provenance kb:<kb_id>/<document>#<chunk>. | |
result | Any | yes | Answer of the query (items or hits) or a list of hits. | |
priority | int | 60 | no | Priority of the first hit (default 60), lowered by 1 per rank, never below 0. |
Returns: list[Any]. The segments added, in rank order; each keeps the classification of its hit (default internal).