Spec de l'enveloppe wire

Les trois SDK (Python, Node, Go) envoient exactement la même enveloppe JSON vers POST /api/v1/ai/ingest avec Authorization: Bearer aiv_.... Vous pouvez aussi poster directement sans SDK ; l’enveloppe est le contrat.

Endpoint

POST /api/v1/ai/ingest
Host: api.monsys.ai
Authorization: Bearer aiv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Enveloppe top-level

{
  "trace_id": "uuid",                     // UUIDv4 client (requis)
  "root_op": "rag.chat",                  // texte libre (requis)
  "status": "ok" | "error" | "partial",   // (requis)
  "started_at": "2026-05-12T09:50:00Z",   // RFC3339 (requis)
  "ended_at":   "2026-05-12T09:50:01Z",   // RFC3339 (optionnel)
  "user_session_hash": "",                // SHA256 de session id, optionnel
  "sampling_decision": "full",            // "full" | "head" | "summary"
  "spans": [ ... ]                        // 1..N spans (requis)
}

Span

{
  "span_id": "uuid",
  "parent_span_id": "uuid",               // "" pour root
  "op": "openai.chat",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "started_at": "...",
  "ended_at":   "...",
  "status": "ok",                         // "ok" | "error" | "refused" | "partial"
  "input_tokens":  42,
  "output_tokens": 17,

  "prompt":     "...",                    // brut — rédigé sur le hub
  "completion": "...",                    // brut — rédigé sur le hub
  "system_msg": "...",
  "tool_io":    "...",

  "attributes": { ... },
  "events":     [ { ... }, ... ]
}

Noms canoniques providers

Provider	Valeur `provider`
OpenAI	`openai`
Anthropic Claude	`anthropic`
Google Gemini	`google`
Mistral AI	`mistral`
Azure OpenAI	`azure`
Local (Ollama)	`ollama`

Les autres providers sont acceptés mais n’ont pas de lookup tarifaire (coût = 0).

Lookup tarifaire

À l’ingestion, le hub cherche ai_model_pricing par (provider, model). Match exact — les nouveaux modèles non présents dans la table donnent total_cost_micro_eur = 0. Demandez une mise à jour via info@be-hosted.be (changelog tarifaire — bientôt).

La ligne tarifaire utilisée est épinglée par span via une FK pricing_snapshot_id — un backfill des prix ne change pas les coûts historiques.

Réponse

{
  "received": true,
  "trace_id": "uuid",
  "spans": 3,
  "pii_hits": 1,
  "total_cost_micro_eur": 603290
}

Statuts HTTP :

200 — traité (voir body)
401 — token invalide ou révoqué
403 — ai_observability_enabled = false
400 — enveloppe invalide
5xx — erreur côté hub ; le SDK ne retry pas

Exemple curl

curl -X POST https://api.monsys.ai/api/v1/ai/ingest \
  -H "Authorization: Bearer aiv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "trace_id": "0e22…", "root_op": "test", "status": "ok", ... }'

Compat OpenTelemetry GenAI

Nous mappons les conventions sémantiques OTel GenAI sur cette enveloppe en interne mais n’acceptons pas encore OTLP directement. Raison : l’overhead binaire OTLP/HTTP est surdimensionné pour un-call-par-trace. Si vous avez une stack OTel-only, écrivez un adaptateur léger OTel span → notre enveloppe (voir envelope-from-otel.md — bientôt).