ExAthena.Structured (ExAthena v0.7.1)

Copy Markdown View Source

One-shot structured extraction backed by a JSON schema.

Two implementation paths depending on provider capability:

  • JSON mode (provider declares json_mode: true) — we set response_format: :json on the request. The provider asks the model to emit JSON only.

  • Fenced-block fallback — for providers without JSON mode we append instructions to the system prompt telling the model to emit exactly one ~~~json ... ~~~ block, then extract and parse it.

Regardless of path, the returned JSON is validated against the supplied schema. Validation is best-effort (we check types + required keys — no fancy $ref chasing); for stricter validation, pass your own validator via :validator opt.

Summary

Functions

extract(prompt, opts)

Extract structured JSON from a single inference call.

validate_basic(json, schema)

Best-effort JSON Schema validation. Enough to catch shape errors without pulling in a full schema validator.

Functions

extract(prompt, opts)

@spec extract(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Extract structured JSON from a single inference call.

Options:

  • All of ExAthena.query/2's options.
  • :schema (required) — a JSON Schema map. Describes the output shape.

  • :validator (optional) — (map, schema -> :ok | {:error, reason}). Defaults to validate_basic/2.

  • :instructions (optional) — extra natural-language hint prepended to the prompt before the schema block.

validate_basic(json, schema)

@spec validate_basic(map(), map()) :: :ok | {:error, term()}

Best-effort JSON Schema validation. Enough to catch shape errors without pulling in a full schema validator.

Checks:

  • Top-level type
  • required keys are present
  • Property types match (for string / integer / number / boolean / array / object)

Does NOT check $ref, oneOf, anyOf, allOf, patternProperties, etc. Pass your own validator via the :validator opt for strict checking.