SYS_FQ_2 — Enregistrement d'un appel LLM (`telemetrie.appels_llm`)

Formulaire / enregistrement de référence. Table Postgres réelle, en production (créée 2026-06-02). Prototype direct du schéma cible (ADR-033). DDL : 90_Reference_SQL/lot6g0_telemetrie_appels_llm.sql. [CORPUS]

Objet (quoi enregistrer)

Un enregistrement = un appel LLM (réussi ou échoué) émis par un agent via agent_call. Trace les axes coût / vitesse / tokens / attribution pour le pilotage et l'audit. Append-only (1 appel = 1 ligne immuable). [CORPUS]

Champs / structure (prototype de table M2/telemetrie — `colonne: type`)

Colonne	Type	Rôle	Provenance
`id`	`bigint IDENTITY` PK	clé technique (auto, non modifiable)	Postgres [CORPUS]
`ts`	`timestamptz DEFAULT now()`	horodatage de l'appel	Postgres [CORPUS]
`agent_key`	`text`	agent appelant `CODE-NN` (futur FK `config.agents`)	`prepare_agent_call` [CORPUS]
`code_direction`	`text`	Direction (dénormalisé ; futur FK `config.directions`)	`prepare_agent_call` [CORPUS]
`task_type`	`text`	nature analytique (4ᵉ axe ; vocab v0)	workflow appelant [CORPUS]
`dossier_id`	`text`	dossier rattaché (nullable, sans FK)	workflow appelant [CORPUS]
`model`	`text`	modèle effectif (jamais FK stricte)	`prepare_agent_call` [CORPUS]
`provider`	`text`	fournisseur (ex. openrouter)	`prepare_agent_call` [CORPUS]
`resolved_from_mode`	`text`	`model` \| `profil` \| `dynamic`	`prepare_agent_call` [CORPUS]
`prompt_tokens`	`integer`	tokens entrée	`usage.prompt_tokens` [CORPUS]
`completion_tokens`	`integer`	tokens sortie	`usage.completion_tokens` [CORPUS]
`reasoning_tokens`	`integer`	thinking (⊂ completion)	`usage.completion_tokens_details.reasoning_tokens` [CORPUS]
`cache_read_tokens`	`integer`	tokens lus en cache	`usage.prompt_tokens_details.cached_tokens` [CORPUS]
`cache_write_tokens`	`integer`	tokens écrits en cache	best-effort [CORPUS]
`total_tokens`	`integer`	= prompt + completion	`usage.total_tokens` [CORPUS]
`cost_usd`	`numeric(12,6)`	coût natif OpenRouter	`usage.cost` [CORPUS]
`openrouter_generation_id`	`text`	id de génération (réconciliation)	`response.id` [CORPUS]
`latency_ms`	`integer`	latence round-trip HTTP	`Date.now() − t0` [CORPUS]
`success`	`boolean`	issue de l'appel	`agent_call` [CORPUS]
`error`	`text`	message d'erreur si échec	`agent_call` [CORPUS]

Total : 20 colonnes. [CORPUS]

Règles de remplissage

id et ts : ne jamais fournir — posés par Postgres (insertion manuelle de id rejetée). [CORPUS]
cost_usd : copier le coût natif ; interdiction de recalculer via une grille tarifaire. [CORPUS]
reasoning_tokens : depuis le champ dédié uniquement (P-6g0-1). [CORPUS]
dossier_id / task_type : renseigner dès que connus (axes de pilotage) ; null acceptés. [CORPUS]
Échec : success=false, error rempli, tokens/cost_usd à null (cf. SYS_PRO_5). [CORPUS]
Aucune correction a posteriori (append-only) : une erreur de saisie reste, on n'UPDATE pas. [CORPUS]

Rattachement (procédure/instruction)

Procédure : SYS_PQ_2 (mapping + déroulement). [CORPUS]
Workflow producteur : log_llm_call (07 §B2.12). [CORPUS]

Enregistrement résultant

1 ligne en telemetrie.appels_llm. Exemple réel validé (Lot 6g) : prompt=419 / completion=28 / total=447, cost_usd=0.001677, latency_ms=4330, success=t, openrouter_generation_id réel. [CORPUS]

SYS_FQ_2 — Enregistrement d'un appel LLM (telemetrie.appels_llm)