enterprise_ai.rag
Source : sdks/python/src/enterprise_ai/rag/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe RagClient
Bases de connaissances. Bases de connaissances pour la génération augmentée par récupération (RAG) : les documents sont analysés, extraits, contrôlés pour les données personnelles et l'empoisonnement, découpés, vectorisés via le Model Gateway et recherchés avec des filtres d'ACL et d'habilitation.
Resource
RagClient.chunks
chunks(kb_id: str, doc_id: str, include_content: bool | None = None, limit: int | None = None, cursor: str | None = None) -> Any
Lister les fragments d'un document. Fragments de la version courante d'un document dans l'ordre de leur position, paginés avec cursor : chunk_id, ordinal, content (déchiffré pour les fragments scellés), classification, sealed, active, generation, fts_config (configuration de recherche plein texte) et metadata (source_page, section_title, element_type, language, char_start, char_end, bbox, document_version, content_hash, embedding_model, token_count, structure avec les marques de découpe des tableaux). Seuls les fragments dont l'appelant passe les lecteurs et la classification sont listés. Un document en quarantaine ou rejeté n'est montré qu'à tenant_admin, security_officer ou data_steward (403 forbidden). Demande la relation ReBAC viewer ; 404 not_found pour un document que l'appelant ne peut pas lire.
Route : /v1/knowledge-bases/{kb_id}/documents/{doc_id}/chunks (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
doc_id | str | oui | Identifiant (UUID) du document courant. | |
include_content | bool | None | None | non | Si faux, content vaut null (métadonnées seules). Vrai par défaut. |
limit | int | None | None | non | Nombre maximal d'éléments dans une page. Le serveur plafonne la valeur ; lisez la page suivante avec cursor. |
cursor | str | None | None | non | Curseur opaque renvoyé dans next_cursor par la page précédente. Omettez-le pour lire la première page. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les fragments d'un document ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.cite
cite(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Interroger une base de connaissances. Recherche dans la base et renvoie results (fragment, score, risque d'injection, classification, provenance), citations et un lineage_run_id. Demande la relation ReBAC can_invoke. Étapes : 1. La politique knowledge.query est évaluée et une réservation de quota est prise. 2. La requête est vectorisée avec le modèle de la base ; seuls les fragments dont les lecteurs correspondent aux identités de l'appelant et dont la classification respecte son habilitation sont recherchés. 3. Les fragments trouvés sont contrôlés contre l'injection de prompt (écartés en mode blocage) et vérifiés par rapport aux sources actives. 4. hybrid recalcule le score des candidats avec le recouvrement de mots-clés ; rerank les ordonne avec un modèle de reranking (un refus est signalé dans warnings, jamais caché). Un appelant hors ACL obtient un résultat vide, audité comme refus. Audité sous knowledge.query ; l'usage est mesuré.
Route : /v1/knowledge-bases/{kb_id}/query (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
query | str | oui | Texte de la requête (au moins 1 caractère). | |
top_k | int | 5 | non | Nombre de résultats (1 à 100, 5 par défaut). |
**params | Any | non | Champs supplémentaires fusionnés dans la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Interroger une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
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
Créer une base de connaissances. Crée une base avec son modèle d'embedding (par défaut : le modèle d'embedding RAG de la plateforme), qui doit être approuvé, avoir la capacité embeddings et accepter la classification. chunk_overlap doit être inférieur à chunk_size (400 invalid_request) ; une classification inconnue répond 400. Un nom déjà utilisé dans le tenant répond 409 conflict. Demande tenant_admin ou developer ; l'appelant devient propriétaire ReBAC. Audité sous knowledge_base.create.
Route : /v1/knowledge-bases (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | str | oui | Nom, unique dans le tenant (1 à 120 caractères). | |
description | str | None | None | non | Description libre. Vide par défaut. |
classification | str | 'internal' | non | Classification par défaut des documents : public, internal (par défaut), confidential, restricted ou secret. |
embedding_model | str | None | None | non | Modèle du registre avec la capacité embeddings (par défaut : le modèle d'embedding RAG de la plateforme). |
dimensions | int | None | None | non | Taille des vecteurs, l'une des tailles déclarées par le modèle (1 à 16384 ; par défaut : sa taille native). |
chunking | str | None | None | non | words (par défaut : fragments de chunk_size mots avec chunk_overlap, chacun situé dans le texte avec sa page, sa section et son type d'élément, une coupure dans un tableau marquée table_split) ou structure (les fragments suivent titres, paragraphes, listes, tableaux et code ; un tableau reste entier jusqu'à 3 tailles de fragment, un plus long est découpé entre les lignes avec sa ligne d'en-tête répétée). |
retrieval | dict[str, Any] | None | None | non | Stratégie de recherche de la base (voir RetrievalIn). Par défaut : chaque champ à sa valeur par défaut. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Créer une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.delete
delete(kb_id: str) -> Any
Supprimer une base de connaissances. Supprime la base, ses documents et leurs vecteurs dans le magasin vectoriel. Demande la relation ReBAC owner, et l'appelant doit être tenant_admin ou son créateur (403 forbidden). 404 not_found ; 503 vector_store_unavailable. Audité sous knowledge_base.delete.
Route : /v1/knowledge-bases/{kb_id} (DELETE).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. |
Retour : Any. Réponse JSON décodée de l'opération « Supprimer une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.delete_document
delete_document(kb_id: str, doc_id: str) -> Any
Supprimer un document. Supprime le document et ses vecteurs. Demande la relation ReBAC editor et le droit d'écriture par l'ACL : tenant_admin, une identité listée dans writers, ou, si writers est vide, developer ou agent (sinon 403 not_permitted_acl). 404 not_found. Audité sous knowledge.document.delete.
Route : /v1/knowledge-bases/{kb_id}/documents/{doc_id} (DELETE).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
doc_id | str | oui | Identifiant (UUID) du document. |
Retour : Any. Réponse JSON décodée de l'opération « Supprimer un document ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.diagnostics
diagnostics(kb_id: str, diagnostics_id: str | None = None, limit: int | None = None) -> Any
Lister les diagnostics des requêtes. Diagnostics enregistrés des requêtes sur la base, du plus récent au plus ancien, diagnostics_id d'une réponse pour en choisir un : mode, stratégie effective, stages (nom de l'étape, durée en millisecondes, candidats en entrée et en sortie), counts (documents filtrés, candidats denses et lexicaux, fusionnés, contrôlés, dédoublonnés, écartés par la revalidation, finaux, voisins de contexte, cache utilisé) et results (rang, fragment, document, scores nommés). Le texte de la requête n'est pas conservé, seulement son SHA-256. Un appelant voit ses propres requêtes ; tenant_admin, security_officer, data_steward et auditor voient toutes les requêtes. Demande la relation ReBAC viewer ; 404 not_found pour un appelant hors ACL ou un diagnostics_id qu'il ne peut pas voir.
Route : /v1/knowledge-bases/{kb_id}/query-diagnostics (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
diagnostics_id | str | None | None | non | Identifiant (UUID) de diagnostics enregistrés, le diagnostics_id d'une réponse de requête. Facultatif. |
limit | int | None | None | non | Nombre maximal de diagnostics renvoyés (1 à 100, 20 par défaut). |
Retour : Any. Réponse JSON décodée de l'opération « Lister les diagnostics des requêtes ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.document_status
document_status(kb_id: str, doc_id: str) -> Any
Lire l'état d'un document. État d'une version de document : document_id, document_key, version, version_state (current, superseded ou deleted), document_status (uploaded, active, quarantined, rejected, failed...), searchable (vrai seulement pour la version courante active), chunks, extractor, et ingestion, le dernier travail d'ingestion (job_id, state, attempts, last_error, updated_at) ou null pour une ingestion synchrone. Demande la relation ReBAC viewer ; 404 not_found pour un document que l'appelant ne peut pas lire.
Route : /v1/knowledge-bases/{kb_id}/documents/{doc_id}/status (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
doc_id | str | oui | Identifiant (UUID) de la version du document, le document_id de la réponse d'envoi. |
Retour : Any. Réponse JSON décodée de l'opération « Lire l'état d'un document ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.documents
documents(kb_id: str, **page: Any) -> Any
Lister les documents d'une base. Documents lisibles par l'appelant (une de ses identités dans les readers du document, classification dans les limites de son habilitation), paginés avec cursor. Demande la relation ReBAC viewer et le droit de lecture sur la base.
Route : /v1/knowledge-bases/{kb_id}/documents (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
**page | Any | non | Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les documents d'une base ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.get
get(kb_id: str) -> Any
Lire une base de connaissances. Renvoie la base avec son nombre de documents, son pipeline d'ingestion et de recherche, le travail de réindexation (reindex) en cours le cas échéant et les datasets visibles par l'appelant. Demande la relation ReBAC viewer et le droit de lecture par l'ACL ; sinon 404 not_found.
Route : /v1/knowledge-bases/{kb_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. |
Retour : Any. Réponse JSON décodée de l'opération « Lire une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
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
Ajouter un document. Ingère un document (201). Demande la relation ReBAC editor et le droit d'écriture par l'ACL (403 not_permitted_acl). Étapes : 1. Le contenu (content ou content_base64, l'un est requis, sinon 400) est analysé par ClamAV et YARA-X (422 file_blocked, 503 file_scan_unavailable), puis le texte est extrait par Docling (422 unsupported_media). 2. La détection de données personnelles peut relever la classification ; un source_connector doit être actif. 3. Un document de même uri remplace la version précédente (version + 1). 4. Le texte est découpé, vectorisé et enregistré ; le contrôle d'empoisonnement peut mettre le document en quarantaine (status: quarantined). 409 knowledge_base_reindexing pendant une réindexation ; 409 embedding_dimension_mismatch ; 503 vector_store_unavailable. Audité sous knowledge.document.ingest.
Route : /v1/knowledge-bases/{kb_id}/documents (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
content | str | None | None | non | Contenu sous forme de texte. Prioritaire sur content_base64. |
title | str | None | None | non | Titre du document, utilisé aussi comme nom de fichier pour l'analyse et l'extraction. Vide par défaut. |
uri | str | None | None | non | URI source. Un nouveau document de même URI remplace la version précédente. |
classification | str | None | None | non | public, internal, confidential, restricted ou secret. Par défaut : la classification de la base ; relevée si des données personnelles sont détectées. |
mime_type | str | None | None | non | Type de média du contenu. text/plain par défaut. |
metadata | dict[str, Any] | None | None | non | Paires clé-valeur libres enregistrées avec l'objet et renvoyées telles quelles ; la plateforme ne les interprète jamais. |
collection | str | None | None | non | Collection du document dans la base (1 à 200 caractères), utilisée par le filtre de requête collections. Aucune par défaut. |
language | str | None | None | non | Langue du document (code ISO 639-1 comme fr ou en). Par défaut : détectée dans le texte ; chaque fragment reçoit aussi sa propre langue détectée, qui choisit sa configuration plein texte (simple si inconnue). |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Ajouter un document ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.ingestion_job
ingestion_job(kb_id: str, job_id: str) -> Any
Lire un travail d'ingestion. Un travail d'ingestion asynchrone : 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 ou deleted), attempts, lease_owner, lease_expires_at, next_attempt_at, last_error, titre, nom de fichier, type de média, detected_format, size_bytes, sha256, scan_id, extractor (celui qui a tourné), storage (profil et emplacement quarantine ou permanent), création, mise à jour et fin, et history : chaque transition avec from_state, to_state, at et detail (verdict d'analyse, extracteur, nombre de fragments, nouvelle tentative et son délai, échec de l'OCR, mémoire skipped). Demande la relation ReBAC viewer ; 404 not_found pour un travail d'une autre base ou un document que l'appelant ne peut pas lire.
Route : /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
job_id | str | oui | Identifiant (UUID) du travail d'ingestion, le job_id de la réponse d'envoi. |
Retour : Any. Réponse JSON décodée de l'opération « Lire un travail d'ingestion ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.list
list(**page: Any) -> Any
Lister les bases de connaissances. Bases de connaissances du tenant que l'appelant peut lire selon leur ACL, dans l'ordre des noms, paginées avec cursor.
Route : /v1/knowledge-bases (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**page | Any | non | Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les bases de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.quarantine
quarantine(kb_id: str) -> Any
Lister les documents en quarantaine. Documents isolés par le contrôle d'empoisonnement (file de revue du data steward), du plus ancien au plus récent, 200 au plus, chacun avec les raisons du contrôle dans quarantine. Leurs fragments ne sont pas recherchables. Demande tenant_admin, security_officer ou data_steward et la relation ReBAC viewer.
Route : /v1/knowledge-bases/{kb_id}/quarantine (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les documents en quarantaine ».
Erreurs levées : les erreurs typées du transport (Erreurs).
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
Interroger une base de connaissances. Recherche dans la base et renvoie results (fragment, score, risque d'injection, classification, provenance), citations et un lineage_run_id. Demande la relation ReBAC can_invoke. Étapes : 1. La politique knowledge.query est évaluée et une réservation de quota est prise. 2. La requête est vectorisée avec le modèle de la base ; seuls les fragments dont les lecteurs correspondent aux identités de l'appelant et dont la classification respecte son habilitation sont recherchés. 3. Les fragments trouvés sont contrôlés contre l'injection de prompt (écartés en mode blocage) et vérifiés par rapport aux sources actives. 4. hybrid recalcule le score des candidats avec le recouvrement de mots-clés ; rerank les ordonne avec un modèle de reranking (un refus est signalé dans warnings, jamais caché). Un appelant hors ACL obtient un résultat vide, audité comme refus. Audité sous knowledge.query ; l'usage est mesuré.
Route : /v1/knowledge-bases/{kb_id}/query (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
query | str | oui | Texte de la requête (au moins 1 caractère). | |
top_k | int | 5 | non | Nombre de résultats (1 à 100, 5 par défaut). |
min_score | float | None | None | non | Score minimal de similarité vectorielle d'un résultat. 0 par défaut. |
mode | str | None | None | non | vector ou dense (similarité cosinus), lexical (plein texte PostgreSQL) ou hybrid (fusion des deux). Par défaut : le mode de la stratégie de la base, sinon vector. |
rerank | bool | None | None | non | Si vrai, ordonne les résultats avec un modèle de reranking. Par défaut : la stratégie de la base, sinon faux. |
rerank_model | str | None | None | non | Modèle du registre avec la capacité rerank (par défaut : le modèle de reranking de la plateforme). Sans modèle, warnings signale reranker_not_configured. |
filters | dict[str, Any] | None | None | non | Filtres par collection, document, métadonnées, type d'élément et langue (voir QueryFilters). |
diagnostics | bool | None | None | non | Si vrai, la réponse ajoute diagnostics (étapes avec leur durée, nombres de candidats, stratégie, filtres) ; le cache de recherche n'est pas lu. Faux par défaut ; les diagnostics sont enregistrés dans tous les cas. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Interroger une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.reindex
reindex(kb_id: str, embedding_model: str, dimensions: int | None = None) -> Any
Réindexer avec un autre modèle d'embedding. Met en file le passage de la base à un autre modèle d'embedding (travail embeddings_reindex) et répond 202 avec le travail. Le modèle doit être approuvé, avoir la capacité embeddings et accepter la classification la plus haute de la base et de ses documents (422 sinon). Les nouveaux vecteurs forment une nouvelle génération ; les deux espaces ne sont jamais mélangés. Demande tenant_admin ou developer, la relation ReBAC owner et le droit d'écriture. 409 knowledge_base_reindexing si un travail est déjà en cours. Audité sous knowledge_base.reindex.request.
Route : /v1/knowledge-bases/{kb_id}/reindex (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
embedding_model | str | oui | Modèle du registre avec la capacité embeddings (1 à 200 caractères). | |
dimensions | int | None | None | non | Taille des vecteurs, l'une des tailles déclarées par le modèle (1 à 16384 ; par défaut : native). |
Retour : Any. Réponse JSON décodée de l'opération « Réindexer avec un autre modèle d'embedding ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.reindex_jobs
reindex_jobs(kb_id: str) -> Any
Lister les travaux de réindexation. Travaux de réindexation de la base : statut, modèle, dimensions et génération source et cible, progression en documents et fragments, tentatives, erreur et dates. Demande la relation ReBAC viewer et le droit de lecture.
Route : /v1/knowledge-bases/{kb_id}/reindex-jobs (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les travaux de réindexation ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.retrieve
retrieve(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Interroger une base de connaissances. Recherche dans la base et renvoie results (fragment, score, risque d'injection, classification, provenance), citations et un lineage_run_id. Demande la relation ReBAC can_invoke. Étapes : 1. La politique knowledge.query est évaluée et une réservation de quota est prise. 2. La requête est vectorisée avec le modèle de la base ; seuls les fragments dont les lecteurs correspondent aux identités de l'appelant et dont la classification respecte son habilitation sont recherchés. 3. Les fragments trouvés sont contrôlés contre l'injection de prompt (écartés en mode blocage) et vérifiés par rapport aux sources actives. 4. hybrid recalcule le score des candidats avec le recouvrement de mots-clés ; rerank les ordonne avec un modèle de reranking (un refus est signalé dans warnings, jamais caché). Un appelant hors ACL obtient un résultat vide, audité comme refus. Audité sous knowledge.query ; l'usage est mesuré.
Route : /v1/knowledge-bases/{kb_id}/query (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
query | str | oui | Texte de la requête (au moins 1 caractère). | |
top_k | int | 5 | non | Nombre de résultats (1 à 100, 5 par défaut). |
**params | Any | non | Champs supplémentaires fusionnés dans la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Interroger une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.retry_ingestion
retry_ingestion(kb_id: str, job_id: str, reason: str | None = None) -> Any
Relancer un travail d'ingestion en échec. Remet en file un travail failed : en extracting quand son analyse a déjà libéré le fichier (jamais analysé deux fois), sinon en quarantined ; les tentatives repartent de zéro. Tout autre état est refusé en 409 ingestion_job_not_failed (un fichier rejected n'est jamais relancé). Répond le travail avec son historique. Audité knowledge.ingestion.retry. Demande la relation ReBAC editor.
Route : /v1/knowledge-bases/{kb_id}/ingestion-jobs/{job_id}/retry (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
job_id | str | oui | Identifiant (UUID) du travail d'ingestion en échec. | |
reason | str | None | None | non | Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure. |
Retour : Any. Réponse JSON décodée de l'opération « Relancer un travail d'ingestion en échec ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.review
review(kb_id: str, doc_id: str, decision: str, reason: str | None = None) -> Any
Examiner un document en quarantaine. Libère (fragments de nouveau recherchables, status: active) ou rejette (status: rejected) un document en quarantaine. Demande tenant_admin, security_officer ou data_steward ; la politique knowledge.document.review est évaluée. 409 document_not_quarantined ; 404 not_found. La décision est enregistrée et auditée sous knowledge.document.release ou knowledge.document.reject.
Route : /v1/knowledge-bases/{kb_id}/documents/{doc_id}/review (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
doc_id | str | oui | Identifiant (UUID) du document. | |
decision | str | oui | release (de nouveau recherchable) ou reject. | |
reason | str | None | None | non | Raison (2000 caractères au plus). Vide par défaut. |
Retour : Any. Réponse JSON décodée de l'opération « Examiner un document en quarantaine ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.search
search(kb_id: str, query: str, top_k: int = 5, **params: Any) -> Any
Interroger une base de connaissances. Recherche dans la base et renvoie results (fragment, score, risque d'injection, classification, provenance), citations et un lineage_run_id. Demande la relation ReBAC can_invoke. Étapes : 1. La politique knowledge.query est évaluée et une réservation de quota est prise. 2. La requête est vectorisée avec le modèle de la base ; seuls les fragments dont les lecteurs correspondent aux identités de l'appelant et dont la classification respecte son habilitation sont recherchés. 3. Les fragments trouvés sont contrôlés contre l'injection de prompt (écartés en mode blocage) et vérifiés par rapport aux sources actives. 4. hybrid recalcule le score des candidats avec le recouvrement de mots-clés ; rerank les ordonne avec un modèle de reranking (un refus est signalé dans warnings, jamais caché). Un appelant hors ACL obtient un résultat vide, audité comme refus. Audité sous knowledge.query ; l'usage est mesuré.
Route : /v1/knowledge-bases/{kb_id}/query (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
query | str | oui | Texte de la requête (au moins 1 caractère). | |
top_k | int | 5 | non | Nombre de résultats (1 à 100, 5 par défaut). |
**params | Any | non | Champs supplémentaires fusionnés dans la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Interroger une base de connaissances ».
Erreurs levées : les erreurs typées du transport (Erreurs).
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
Remplacer l'ACL d'une base. Remplace les lecteurs et rédacteurs de la base. Avec apply_to_documents, les documents qui héritent de l'ACL de la base (sans lecteurs propres) et leurs fragments reçoivent les nouveaux lecteurs ; documents_updated en donne le nombre. Demande la relation ReBAC owner, et l'appelant doit être tenant_admin, security_officer ou le créateur. Audité sous knowledge_base.acl.update ; le cache de recherche est invalidé.
Route : /v1/knowledge-bases/{kb_id}/acl (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
readers | list[str] | None | None | non | Identités autorisées à lire et interroger. Par défaut ["*"]. |
writers | list[str] | None | None | non | Identités autorisées à écrire. Vide : tenant_admin, developer et agent. |
apply_to_documents | bool | None | None | non | Si vrai (par défaut), les documents qui héritent de l'ACL de la base reçoivent les nouveaux lecteurs. |
Retour : Any. Réponse JSON décodée de l'opération « Remplacer l'ACL d'une base ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.set_retrieval
set_retrieval(kb_id: str, **strategy: Any) -> Any
Définir la stratégie de recherche. Remplace la stratégie de recherche de la base : mode par défaut, fusion et son rrf_k, candidats par résultat, reranking et son modèle, déduplication, fenêtre de contexte et budget de jetons, signal de conflit. Un champ omis prend sa valeur par défaut ; les options d'une requête remplacent la stratégie pour cette requête. Demande la relation ReBAC owner et le droit d'écriture par l'ACL (403 not_permitted_acl) ; 404 not_found pour un appelant hors ACL. Audité sous knowledge_base.retrieval.update ; le cache de recherche est invalidé. Renvoie la base avec sa retrieval.
Route : /v1/knowledge-bases/{kb_id}/retrieval (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
**strategy | Any | non | Champs de la stratégie de recherche (mode, fusion, rerank, token_budget...) ; un champ omis prend sa valeur par défaut. |
Retour : Any. Réponse JSON décodée de l'opération « Définir la stratégie de recherche ».
Erreurs levées : les erreurs typées du transport (Erreurs).
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
Envoyer un document pour une ingestion asynchrone. Contrôle la taille (413 payload_too_large, limite EAI_RAG_UPLOAD_MAX_BYTES), le mime_type déclaré face à la signature réelle des octets (PDF, DOCX, XLSX et PPTX comme paquets ZIP aux bons types de contenu, PNG, JPEG, TIFF ; les formats texte doivent être de l'UTF-8 valide sans NUL) et l'extension de filename : 422 unsupported_format, format_mismatch, extension_mismatch ou archive_refused (bombe d'archive, archive imbriquée, trop volumineuse une fois décompressée). Les octets sont rangés sous le préfixe de quarantaine du profil de stockage des documents (409 ingestion_storage_required sans profil, 503 ingestion_storage_unavailable), la version du document est enregistrée avec document_status uploaded et un travail durable est créé. Répond 202 avec job_id, kb_id, document_id, document_key, version, state (uploaded), detected_format, size_bytes et sha256, et un en-tête Location. La tâche du worker knowledge_ingestion analyse ensuite le fichier par le domaine de sécurité des fichiers (fermé en cas d'échec), l'extrait, le découpe, calcule ses vecteurs et l'indexe. La même Idempotency-Key rejoue la même réponse (en-tête Idempotency-Replayed) ; avec un autre corps, elle est refusée en 409 idempotency_conflict. Demande la relation ReBAC editor.
Route : /v1/knowledge-bases/{kb_id}/documents/uploads (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
content | bytes | oui | Octets bruts du document, encodés en base64 par le SDK et vérifiés par le serveur par rapport à mime_type. | |
mime_type | str | oui | Type de média déclaré, contrôlé face à la signature réelle des octets. | |
filename | str | '' | non | Nom de fichier d'origine (500 caractères au plus) ; son extension doit correspondre au format déclaré. Par défaut : le titre. |
title | str | '' | non | Titre du document (500 caractères au plus). Vide par défaut. |
uri | str | None | None | non | URI source. Un document portant l'URI d'un document existant devient sa version suivante. |
classification | str | None | None | non | public, internal, confidential, restricted ou secret. Par défaut : la classification de la base. |
readers | list[str] | None | None | non | Lecteurs de ce document. Omis : les lecteurs de la base. |
metadata | dict[str, Any] | None | None | non | Métadonnées libres conservées avec le document. |
collection | str | None | None | non | Collection du document dans la base (1 à 200 caractères). Aucune par défaut. |
language | str | None | None | non | Langue du document (code ISO 639-1). Par défaut : détectée dans le texte extrait. |
idempotency_key | str | None | None | non | En-tête Idempotency-Key : une reprise avec la même clé rejoue la première réponse. |
Retour : Any. Réponse JSON décodée de l'opération « Envoyer un document pour une ingestion asynchrone ».
Erreurs levées : les erreurs typées du transport (Erreurs).
RagClient.versions
versions(kb_id: str, doc_id: str) -> Any
Lister les versions d'un document. Historique des versions d'un document, de la plus récente à la plus ancienne : document_key (stable d'une version à l'autre) et items avec document_id, version, state (current, superseded ou deleted), searchable (seule la version courante active est recherchée), titre, URI, type de média, classification, content_hash, taille, nombre de fragments, extracteur, langue, collection, document_status, création, superseded_by et superseded_at, deleted_at, et les artifacts Docling (nature, profil de stockage, clé d'objet, taille, SHA-256). doc_id peut être le document courant ou n'importe quelle version passée. Une version n'est listée que si l'appelant fait partie de ses lecteurs et si sa classification respecte son habilitation. Demande la relation ReBAC viewer ; 404 not_found sinon.
Route : /v1/knowledge-bases/{kb_id}/documents/{doc_id}/versions (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kb_id | str | oui | Identifiant (UUID) de la base de connaissances. | |
doc_id | str | oui | Identifiant (UUID) du document ou de l'une de ses versions passées. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les versions d'un document ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Fonctions
to_segments
to_segments(builder: Any, kb_id: str, result: Any, priority: int = 60) -> list[Any]
Ajoute les résultats d'une requête à un ContextBuilder comme segments rag_document avec leur provenance.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
builder | Any | oui | ContextBuilder qui reçoit les segments par sa méthode add. | |
kb_id | str | oui | Base de connaissances des résultats, utilisée dans la provenance kb:<kb_id>/<document>#<chunk>. | |
result | Any | oui | Réponse de la requête (items ou hits) ou liste de résultats. | |
priority | int | 60 | non | Priorité du premier résultat (60 par défaut), diminuée de 1 par rang, jamais sous 0. |
Retour : list[Any]. Les segments ajoutés, dans l'ordre des rangs ; chacun garde la classification de son résultat (internal par défaut).