retrieve

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.
`sources` · `exclude_sources`	`null`	Restreint le corpus lu à certains éditeurs (`["HAS"]`). Les identifiants sont ceux de `GET /v2/sources`, insensibles à la casse. Une source inconnue est refusée en 400 — jamais servie comme une réponse vide.
`source_weights`	`{}`	Multiplicateur de score par éditeur (`{"recomedicales": 1.2}`). Ne retire rien : déplace dans le classement. Un poids ≠ 1 déclenche un sur-tirage des recherches vectorielles, sans quoi la pondération ne pourrait que réordonner ce que le cosinus a déjà laissé passer.
`logic_answers`	`[]`	Ce que le praticien a répondu aux unités logiques du tour précédent (voir ci-dessous). Sans elles, un score est proposé ; avec elles, il est calculé.
`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`.
`elicitations`	Les unités logiques retrouvées — un score, un arbre — et ce qu’elles demandent pour être exécutées. Voir ci-dessous.
`source_scope`	La restriction d’éditeurs réellement appliquée, en identifiants canoniques. `null` = tout le corpus. Une réponse courte sous restriction se lit alors comme telle, et non comme un trou du corpus.
`deliberation`	Présent uniquement si `deliberate` était demandé.

Les unités logiques : score et arbre

Toutes les unités de connaissance ne sont pas des règles plates. Deux formes portent une logique exécutable :

un score — des questions cotées, un total, des paliers d’interprétation ;
un arbre — des nœuds, des branches, des conduites terminales.

Le serveur ne les fait jamais calculer au modèle. Il énumère des choix bornés (elicitations[].steps[]), le client les affiche, le praticien répond, et le tour suivant repasse ses réponses dans logic_answers : le calcul est alors fait par un moteur déterministe, et c’est son résultat (computed) qui entre dans le contexte de rédaction.

{
  "query": "risque embolique chez ce patient en FA",
  "logic_answers": [
    {
      "mku_key": "score:cha2ds2vasc",
      "checked": ["Âge ≥ 75 ans", "Hypertension"]
    }
  ]
}

L’unité se désigne par mku_id (l’identité citable) ou par mku_key (la clé lisible) : la seconde survit à une ré-extraction, ce qui compte quand un formulaire reste ouvert entre deux tours. Selon la forme du score, on répond par answers (question → modalité), checked (les cases retenues) ou level (un palier d’échelle) ; un arbre répond par answers, du nœud vers la branche choisie. Chaque étape porte un kind : question, items, niveau (un palier à choisir) ou branchement (une branche d’arbre). Un client qui ignore elicitations reçoit la même réponse rédigée qu’avant — l’unité est alors citée sans être exécutée.

Une seule unité est dépliée

Une réponse peut retrouver plusieurs unités logiques. Un praticien n’en remplit qu’une : celle qu’il est venu chercher. Une seule porte donc ses steps — expanded: true — et c’est la mieux classée, ou celle que la question nomme si elle en nomme une. Les autres restent dans elicitations avec expanded: false et steps: []. Elles gardent tout le reste : identité, titre, total_max, bands, graph. De quoi les proposer sans les afficher, et les ouvrir soi-même sans un second appel. Une unité pour laquelle la requête portait des logic_answers est toujours dépliée, quel que soit son rang : un formulaire ouvert ne se referme pas parce qu’un autre score est mieux classé.

Un score porte son interprétation — `bands`

bands donne les paliers d’un score : ce que vaut un total, tel que la source le publie à côté du barème. Le client peut donc afficher une conduite dès que le praticien coche, sans aller-retour.

"bands": [
  { "rang": 0, "quand": [{ "op": ">", "valeur": 4 }], "pur_total": true,
    "condition": "score > 4", "libelle": "Risque hémorragique élevé" },
  { "rang": 1, "quand": [{ "op": ">", "valeur": 0 }], "pur_total": true,
    "condition": "score 1-4", "libelle": "Risque hémorragique intermédiaire" },
  { "rang": 2, "quand": [], "pur_total": true,
    "condition": "sinon", "libelle": "Risque hémorragique faible" }
]

L’ordre fait foi. Ces paliers sont une chaîne si / sinon si : chacun est borné par ceux qui le précèdent. Les évaluer par rang croissant, premier satisfait, premier servi, et s’arrêter là. Les lire comme des intervalles indépendants fait apparaître trous et recouvrements — mesuré sur 43 scores sur 85.Et une bande pur_total: false dépend d’autre chose que du total : le moteur refuse d’y conclure. Afficher sa condition, jamais une conclusion.

computed.outcome reste la seule conclusion opposable — elle vient du moteur. bands sert à afficher le barème et à situer un total, pas à trancher.

Un arbre porte son graphe — `graph`

steps ne contient que les nœuds qui demandent une décision. Les nœuds de passage et les conduites terminales n’en sont pas — or le moteur traverse les premiers tout seul et conclut sur les seconds. graph rend l’arbre entier, et lève l’asymétrie : ce que le moteur traverse, le client le voit.

Champ	Ce que c’est
`graph.nodes[]`	Tous les nœuds : `id` (la clé de navigation), `label`, `forme`.
`graph.edges[]`	Toutes les arêtes : `de`, `vers`, `condition`, `optionnel`.
`graph.entries[]`	Les entrées. Plusieurs = le départ est lui-même un choix.
`graph.outcomes[]`	Les nœuds terminaux : les conduites de l’arbre.
`graph.cyclique`	Un fait structurel de la source (une titration repasse par son nœud d’évaluation), pas un défaut.

Côté options, to porte l’identifiant du nœud d’arrivée ; leads_to porte son libellé. Naviguer par to : deux nœuds peuvent porter le même texte, et un nœud de passage n’apparaît dans aucun steps[].key. computed.path_ids donne le chemin parcouru en identifiants, computed.path les mêmes nœuds en libellés — un pour un.

Calculer sans re-chercher

Pour les tours intermédiaires d’un formulaire ouvert — cocher une case, choisir une branche — utilisez /v2/logic/compute plutôt que de rappeler /v2/retrieve. C’est plus rapide, et surtout c’est déterministe : l’unité y est désignée par sa clé, pas re-classée.

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
400	`UNKNOWN_SOURCE`	Une source demandée n’existe pas. Le corps porte `known_sources`.
400	`EMPTY_SOURCE_SCOPE`	La restriction ne peut rien rendre (tout ce qui est inclus est exclu).
503	`GRAPH_UNAVAILABLE`	Le graphe est injoignable.
503	`RETRIEVAL_UNAVAILABLE`	Les embeddings sont injoignables.
502	`ANSWER_UNAVAILABLE`	La rédaction a échoué.

Premiers pas

Capacités

Référence

Requête minimale

Les champs qui comptent

Ce que rend la réponse

Les unités logiques : score et arbre

Une seule unité est dépliée

Un score porte son interprétation — `bands`

Un arbre porte son graphe — `graph`

Calculer sans re-chercher

Trois formats pour une même réponse

Erreurs

​Requête minimale

​Les champs qui comptent

​Ce que rend la réponse

​Les unités logiques : score et arbre

​Une seule unité est dépliée

​Un score porte son interprétation — bands

​Un arbre porte son graphe — graph

​Calculer sans re-chercher

​Trois formats pour une même réponse

​Erreurs

Requête minimale

Les champs qui comptent

Ce que rend la réponse

Les unités logiques : score et arbre

Une seule unité est dépliée

Un score porte son interprétation — `bands`

Un arbre porte son graphe — `graph`

Calculer sans re-chercher

Trois formats pour une même réponse

Erreurs