retrieve/stream

POST /v2/retrieve/stream prend le même corps de requête que /v2/retrieve et rend la même payload — mais au fil de l’eau, une ligne JSON par étape réellement terminée. C’est ce qui permet à une interface de montrer l’avancée réelle du retrieving au lieu d’une barre qui invente sa progression. Une réponse enchaîne plusieurs appels lourds ; une étape muette pendant ce temps-là est indistinguable d’une étape bloquée.

Content-Type: application/x-ndjson

Chaque ligne est un objet JSON complet, séparé par \n. Il n’y a pas de reconnexion à gérer : fetch et un lecteur de flux suffisent.

Les lignes

`step`	Émise quand
`query_maker`	La question est qualifiée et reformulée.
`retrieval`	Les deux voies ont rendu leurs unités.
`deliberation`	La seconde lecture est terminée (trace complète).
`answer`	La réponse est rédigée.
`drugs`	Les cartes médicament sont rattachées.
`done`	Ligne terminale. `payload` porte le corps complet, identique à celui de `/v2/retrieve`.
`error`	Ligne terminale. `detail` dit ce qui a lâché.

Avec deliberate: true, la boucle réflexive diffuse en plus chacun de ses tours sans attendre son verdict :

`step`	Ce qu’il porte
`deliberation_judge`	`index`, `saw` (ce que le juge avait sous les yeux), `sufficient`, `checks`, `gaps`, la `probe` décidée, `asked`.
`deliberation_probe`	`index`, `modality`, `query`, `seeds`, `rationale`, `gained`, `gained_ids`.

Sans eux, l’étape reste muette pendant trois appels lourds et deux retrievings.

Une panne de dépendance ne peut plus lever une erreur HTTP ici : le flux a déjà commencé, donc elle arrive comme ligne terminale error. Le statut est 200 dès la première ligne — c’est le contenu du flux qu’il faut lire, pas le code.

Lire le flux

const resp = await fetch("https://core.locusmedical.fr/v2/retrieve/stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "antibioprophylaxie chirurgie colorectale" }),
});

const reader = resp.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // Une ligne complète = un objet. La dernière peut être partielle : on la garde.
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? "";

  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);
    if (event.step === "done") console.log(event.payload.answer);
    else if (event.step === "error") throw new Error(event.detail);
    else showProgress(event.step);
  }
}

import httpx, json

with httpx.stream(
    "POST",
    "https://core.locusmedical.fr/v2/retrieve/stream",
    headers={"Authorization": f"Bearer {LOCUS_API_KEY}"},
    json={"query": "antibioprophylaxie chirurgie colorectale"},
    timeout=180,
) as r:
    r.raise_for_status()
    for line in r.iter_lines():
        if not line:
            continue
        event = json.loads(line)
        if event["step"] == "done":
            print(event["payload"]["answer"])
        elif event["step"] == "error":
            raise RuntimeError(event["detail"])
        else:
            print("…", event["step"])

curl -N -X POST https://core.locusmedical.fr/v2/retrieve/stream \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "antibioprophylaxie chirurgie colorectale"}'

Bufferisez la fin de tampon. Un morceau réseau ne tombe pas sur une frontière de ligne : découper naïvement sur \n sans conserver le reliquat coupe un objet JSON en deux et fait échouer le parse au hasard de la charge.

Premiers pas

Capacités

Référence

retrieve/stream

Les lignes

Lire le flux

​Les lignes

​Lire le flux

Les lignes

Lire le flux