API i format odgovora

Upiti

Upit se šalje na krajnju točku orkestratora /query. Svaki odgovor — bez obzira na to koji ga je stupanj cjevovoda obradio — slijedi istu Pod shemu:

{
  "query": "30% of 8 miles",
  "stage_used": 1,
  "assumptions_available": false,
  "pods": [
    { "title": "Input Interpretation", "type": "text",           "content": "8 miles × 30%" },
    { "title": "Result",               "type": "primary_result", "content": "2.4 miles" },
    { "title": "Unit Conversions",     "type": "list",           "content": ["3.862 km", "3862 m", "12672 ft"] },
    { "title": "Comparisons",          "type": "list",           "content": ["≈ 16× length of the Hindenburg"] }
  ]
}

Sastavljanje podova uvijek na početak dodaje pod Input Interpretation, a na kraj Comparisons kada se numerički rezultat podudara s poznatom referencom veličine.

Vrste podova

Polje stage_used izvještava koji je stupanj cjevovoda proizveo odgovor (1 = brzi put gramatika, 2/3 = LLM planiranje), a assumptions_available signalizira da su priložene pretpostavke Fermijevog tipa.

Ograničenje broja zahtjeva

Flask-Limiter nameće 30 zahtjeva u minuti po API ključu (zaglavlje X-API-Key) ili IP adresi klijenta. Ograničenja se pohranjuju u Redis kada je dostupan.

Keširanje

• Ključ keša: SHA-256 upita (neosjetljivo na velika/mala slova), s prefiksom jezika i naznake domene kada nisu zadani.
• TTL po domeni: vrijeme 10 min, datumi 1 h, činjenice 24 h, matematika neograničeno.
• Odgovori koji sadrže error podove nikada se ne keširaju.
• Redis kroz compose; pričuvno ograničeni LRU u memoriji kada Redis nije dostupan.

Sigurnosne kontrole i kontrole resursa

Metrike

Brojači u procesu izloženi su na GET /metrics na orkestratoru.