Imp.Adapter.JSON (Imp v0.5.0)

Copy Markdown View Source

JSON-oriented adapter.

This adapter accepts map outputs directly and parses provider JSON with Jason.

Use this adapter when a field is required, typed, constrained, or consumed by application code that should not guess its way through prose.

Example

iex> signature =
...>   Imp.signature(
...>     "text -> sentiment: enum[positive,negative], confidence: number",
...>     "Classify the text."
...>   )
iex> program = Imp.predict(signature, adapter: Imp.Adapter.JSON)
iex> program.adapter
Imp.Adapter.JSON
iex> {:ok, prediction} =
...>   Imp.Adapter.JSON.parse(signature, ~s({"sentiment":"positive","confidence":0.9}), [])
iex> {Imp.get(prediction, :sentiment), Imp.get(prediction, :confidence)}
{"positive", 0.9}

By default the adapter requests provider JSON object mode when the LM client supports response-format options. Pass config: [native_json_schema: true] to request native JSON Schema mode through providers that support it.

Parse failures return structured retry feedback through Imp.AdapterParseError, so callers and retry loops can tell the model what violated the schema.

Summary

Functions

lm_opts(signature, opts)

Provider request options for a JSON-adapter call. Faithful to DSPy's JSONAdapter, which selects response_format by the LM's capability, not by which keys the caller passed (dspy/adapters/json_adapter.py _json_adapter_call_common + __call__)

lm_opts(signature, opts, capability)

Functions

lm_opts(signature, opts)

Provider request options for a JSON-adapter call. Faithful to DSPy's JSONAdapter, which selects response_format by the LM's capability, not by which keys the caller passed (dspy/adapters/json_adapter.py _json_adapter_call_common + __call__):

  • LM does NOT accept response_format ("response_format" not in lm.supported_params) -> send NOTHING.
  • LM accepts response_format but not structured schema (not lm.supports_response_schema, or an open-ended dict output) -> {"type": "json_object"}.
  • LM supports structured JSON schema -> a pydantic-shaped json_schema built from the signature outputs (DSPy's _get_structured_outputs_response_format, in the litellm wire form).

capability is the LM's Imp.LM.Capability (resolved by Imp.LM.response_format_capability/1 at the call site). The arity-2 form is a capability-agnostic convenience that assumes a standard response_format- capable provider (the historical Imp default, json_object); real dispatch through Imp.Predict/Imp.Streaming uses the arity-3 form with the actual per-LM capability.

Two explicit-override escape hatches are honored ahead of capability gating, with no DSPy analog: native_json_schema: true forces Imp's own json_schema envelope, and a caller-supplied response_format map is passed through untouched (returns [] so the caller's value wins).

Signature-level :code outputs deliberately use a flat JSON string schema. That matches the actual JSON prompt and serialized value Imp accepts. Current DSPy exposes its pydantic Code_<language> wrapper as a $ref object in native response schema even though its JSONAdapter prompt and serializer use a string; Imp does not reproduce that internal pydantic mismatch.

lm_opts(signature, opts, capability)