Skip to content
Novaterra

llm.structured

Schema

Input = {
  prompt: string,
  jsonSchema: Record<string, unknown>,   // the JSON Schema the response must satisfy
  system?: string,
  tier?: 'cheap' | 'standard' | 'strong' | 'image' | 'embed',   // default 'cheap'
  retries?: number,                        // 0-4, default 2
}


Output = {
  data: unknown,               // validated against jsonSchema
  model: string,
  costUsd: number,
}

Unlike most of Novaterra’s own structured calls (which validate against a real Zod schema), llm.structured accepts an arbitrary caller-supplied JSON Schema at runtime, so it’s wrapped against a small hand-written checker (checkJsonSchema()) rather than Zod: it walks type, required, properties, items, and enum recursively and reports every mismatch as a path-tagged message (e.g. $.tags[1]: expected string, got number), which becomes the repair hint the model sees on a retry. It’s intentionally minimal — enough to drive a useful repair loop, not a full JSON Schema validator (no oneOf/anyOf/pattern/format checks).

Example

Terminal window
curl -s -X POST http://localhost:4000/api/studio/skills/invoke \
  -H 'content-type: application/json' -b cookies.txt \
  -d '{
    "name": "llm.structured",
    "input": {
      "prompt": "Extract the person and company from: Jordan Alvarez, VP Ops at Nimbus Freight, wants a demo.",
      "jsonSchema": {"type":"object","required":["name","company"],"properties":{"name":{"type":"string"},"company":{"type":"string"}}}
    }
  }'
{ "ok": true, "output": { "data": { "name": "Jordan Alvarez", "company": "Nimbus Freight" }, "model": "google/gemini-2.5-flash-lite", "costUsd": 0.00003 } }