LLM intelligence over your scores
Three Pro+ endpoints that turn deterministic scoring output into natural-language explanations, multi-slot briefings, and analyses of borderline conditions. Backed by Claude with strict hallucination guards.
/explain + /briefing are Pro+; /edge-case is Scale-only (its analysis depth runs a heavier model). Free + Starter return 402 PAYMENT_REQUIRED on all three. Per-tenant monthly LLM token budget caps spend; the exact numbers per plan are in the plans reference.
What's covered
All three intelligence endpoints share the same input contract: a score (passed inline as scoreResult, or referenced by session_id if you scored within the last 48h). The LLM only sees the deterministic score + breakdown — it cannot fabricate physics, only narrate it.
POST /v1/intelligence/explain
One-paragraph natural-language explanation of a score. Use for the "why is today's verdict marginal?" UI in a booking flow.
{
"session_id": "a3f2...",
"location": { lat: 36.013, lng: -5.604 },
"locale": "en",
"model": "claude-haiku-4-5-20251001"
}POST /v1/intelligence/briefing
Multi-slot briefing across an activity day. Takes an array of scored slots (morning / midday / afternoon / evening, or any custom window cuts) and returns a narrative paragraph summarising which slot is best and why the rest don't beat it. Slot cap: up to 24 on Pro, 96 on Scale.
POST /v1/intelligence/edge-case
Targeted analysis of borderline scores — verdict near a band boundary, contradictory drivers, surprising downgrade. Returns a narrative + a structured limiting_class taxonomy entry identifying which dimension is the constraint. Scale-only: runs the heavier model + extra reasoning passes Pro keeps closed.
Hallucination guard
Every LLM response is run through a programmatic guard before it returns. The guard checks that every numeric claim in the narrative appears in the deterministic score breakdown (±3% tolerance) and that no dimension is mentioned that isn't actually scored. On guard failure the orchestrator does a one-shot retry with a tightened prompt; on second failure it falls back to a deterministic template.
Costs + budget
Each call counts against the tenant's monthly LLM-token budget — 500,000 tokens / month on Pro, 5,000,000 on Scale. The budget resets on the first of each month UTC.
When the budget is exhausted, the endpoint returns 429 LLM_BUDGET_EXCEEDED until the next reset. Track spend from the tenant portal at the usage dashboard — it surfaces tokens consumed this month alongside the API call count.