retrieve - Locus

POST /v2/retrieve est le chemin principal. Il enchaîne, en un appel :

query maker — qualifie ce que le dernier message apporte (nouvelle question, précision, fait patient) et le reformule ;
retrieving deux voies — sémantique ‖ concepts + graphe, en parallèle ;
contexte — les unités de connaissance retenues, leurs tables de décision, leurs documents ;
rédaction — une réponse en Markdown, citée sur ces unités et rien d’autre.

Pas de juge, pas de passe de sécurité : ces deux-là se demandent explicitement (voir deliberate ci-dessous).

Requête minimale

{ "query": "antibioprophylaxie chirurgie colorectale" }

Les champs qui comptent

Champ	Défaut	Ce qu’il change
`query`	—	La question. Seul champ requis.
`patient_ehr`	`null`	Le dossier patient, en texte libre. C’est lui qui est confronté aux critères des règles.
`history`	`[]`	Les tours précédents. Sert uniquement au query maker. Les réponses antérieures ne sont jamais redonnées au rédacteur : elles n’ont pas de règle derrière elles et ne peuvent pas faire source.
`deliberate`	`false`	Seconde lecture : confronte les critères au dossier, va chercher une définition manquante, et ne pose une question qu’en dernier recours. Hors du point de fonctionnement de référence — l’activer change le coût.
`app_version` · `app_build` · `app_platform`	`null`	Portés sur la trace. `app_build` est ce qui distingue deux binaires d’une même version publiée : sans lui, un bug n’est pas rejouable.

Les réglages de retrieving (concept_k, chunk_k, mku_k, mku_weight, table_k, use_cross_refs) sont exposés, mais leurs défauts sont le point de fonctionnement mesuré. Les changer, c’est sortir de ce que les évaluations couvrent. Le détail de chacun est dans l’onglet API Reference.

Ce que rend la réponse

Champ	Ce que c’est
`answer`	La réponse rédigée, en Markdown.
`answer_short`	La conduite à tenir en une phrase, dérivée du titre de `answer`.
`trace_id`	L’identifiant de CETTE réponse — la clé à renvoyer à `/v2/feedback`. Vide si la journalisation est coupée : ne proposez alors pas le retour.
`core_version`	La version qui a produit la réponse : `0.2.0+a1b2c3d (r:4f9e2b71)`. À afficher dans un rapport de bug.
`mkus` · `tables` · `chunks` · `docs`	Ce sur quoi la réponse est fondée : unités de connaissance, tables de décision, extraits, documents avec lien profond.
`drugs`	Les cartes médicament des règles citées. Voie séparée des unités citables : une rubrique de RCP n’entre jamais dans le contexte de rédaction. Ses rubriques sont tronquées — le texte entier s’obtient par `/v2/drugs`.
`deliberation`	Présent uniquement si `deliberate` était demandé.

Trois formats pour une même réponse

La négociation se fait sur Accept, plutôt que par un ?format= : le client déclare ce qu’il sait lire.

`Accept`	Réponse
`application/json` (défaut)	La payload complète.
`text/markdown`	Réponse et provenance en un document Markdown.
`text/html`	Le même document, rendu en page lisible.

En JSON, les sauts de ligne d’answer sont échappés en \n : lire avec jq -r '.answer'.

Erreurs

Statut	Code	Signification
503	`GRAPH_UNAVAILABLE`	Le graphe est injoignable.
503	`RETRIEVAL_UNAVAILABLE`	Les embeddings sont injoignables.
502	`ANSWER_UNAVAILABLE`	La rédaction a échoué.