Adapters

An adapter sits between a signature and the LM: it formats inputs into the prompt the model sees and parses the LM’s response back into typed outputs. The default adapter is ChatAdapter, and Predict drives it for you (via the IR interpreter), so you touch it directly only to inspect what the model sees.

What adapters do

SignatureDef + Input → Adapter.format() → Prompt for LM
LM Response → Adapter.parse() → Typed Output

ChatAdapter handles both formatting and parsing. It has one lane: every method is parameterized by an owned SignatureDef — the IR’s value-level signature — whether the def came from a derived Signature type (SignatureDef::of::<S>()) or from a loaded .dsrs program. There is no separate “static” formatting path.

ChatAdapter

Prompt structure

The system message has four parts (in this order):

Field descriptions - Lists input/output fields with types and descriptions
Field structure - Shows the marker format + type schemas
Response instructions - “Respond with [[ ## field ## ]]…”
Task description - Your instruction from the signature docstring (at the end)

Example system message (simplified):

Your input fields are:
1. `question` (string): The question to answer

Your output fields are:
1. `answer` (string): A clear, direct answer

All interactions will be structured in the following way...

[[ ## question ## ]]
question

[[ ## answer ## ]]
Output field `answer` should be of type: string

[[ ## completed ## ]]

Respond with the corresponding output fields, starting with `[[ ## answer ## ]]`,
and then ending with the marker for `[[ ## completed ## ]]`.

In adhering to this structure, your objective is:
        Answer questions accurately and concisely.

Marker protocol

Fields are delimited by markers:

[[ ## field_name ## ]]
value here

[[ ## another_field ## ]]
another value

[[ ## completed ## ]]

This protocol (inspired by DSPy) allows mixing natural language with structured output.

Type schemas

For complex types, the adapter renders full schemas with typesys::render: type_name produces the short inline label, and schema_block expands class field layouts and enum value lists:

[[ ## analysis ## ]]
Output field `analysis` should be of type: Analysis

Definitions (used below):

Sentiment
----
- Positive
- Negative
- Neutral

{
  "sentiment": Sentiment,
  "confidence": float,
  "keywords": string[]
}

Type names are simplified for readability:

Module paths stripped: my_crate::Sentiment → Sentiment
class/enum prefixes removed
" | " → " or " (more natural)

Tolerant parsing with typesys::coerce

Response parsing uses typesys::coerce, a tolerant coercer that turns raw LM field text into typed values, guided by the expected field type. It handles:

Markdown fences - Strips ```json fences before parsing
Lists from prose - Parses bulleted or numbered lists into arrays
Type coercion - "42" → 42, "yes" → true (loose bool and number spellings)
Surrounding text - Ignores extra prose around a JSON object or array
Partial recovery - Per-field failures aggregate; you get every error plus what did parse

// Internally, per output field:
typesys::coerce(raw_text, field_type, &output_schema.types)

Each non-fatal fix (a stripped fence, a coerced scalar) is recorded as a Flag on the returned Coerced value.

Constraint evaluation

After parsing, the adapter runs constraints:

#[check] results → stored in metadata
#[assert] failures → returns ParseError::AssertFailed

Error handling

Parse errors aggregate - you get all problems, not just the first:

ParseError::Multiple {
    errors: vec![...],  // all field errors
    partial: Some(serde_json::Value::Object(...)),  // what did parse
}

Using the adapter directly

Usually you do not touch the adapter - Predict handles it. The public surface is five building blocks, all parameterized by &SignatureDef:

Method	Produces
`build_system_def(def, types, instruction_override)`	The system message (field descriptions, structure template, response instructions, task description)
`format_input_def(def, input)`	The user message: input fields with `[[ ## field ## ]]` markers plus response instructions. `input` is a `JsonMap`; absent fields are skipped
`format_output_def(def, output)`	An assistant message for few-shot demos, ending with `[[ ## completed ## ]]`
`parse_output_def(def, types, response)`	`(JsonMap, IndexMap<String, FieldMeta>)` — the parsed output map plus per-field parse metadata
`ChatAdapter::parse_sections(content)`	Ordered map of `field_name → section_content` split by the delimiters

For debugging what the LM sees from a derived signature:

use dspy_rs::{ChatAdapter, ir::SignatureDef};

let adapter = ChatAdapter;
let def = SignatureDef::of::<MySignature>();
let types = SignatureDef::types_of::<MySignature>();

let system = adapter.build_system_def(def, types, None);
println!("System:\n{system}");

Input formatting options

Input fields support two rendering paths:

#[derive(Signature, Clone, Debug)]
struct Search {
    #[input]
    query: String,  // plain text

    #[input]
    #[format("yaml")]
    filters: Vec<Filter>,  // serialized as YAML

    #[input]
    #[render(jinja = "{{ this.text }}\nQuestion: {{ input.query }}")]
    context: Context,  // custom Jinja rendering

    #[output]
    results: Vec<Result>,
}

#[format("json" | "yaml" | "toon")]: serialize a field using that format.
#[render(jinja = "...")]: render a field with a MiniJinja template.
#[format] and #[render] are mutually exclusive on the same field.

#[render] context in ChatAdapter:

this: current field value
input: full input object (plus top-level alias overlays)
field: { name, rust_name, type }
vars: adapter/surface vars (currently {})

ChatAdapter configures MiniJinja with strict undefined behavior. Available filters include:

MiniJinja built-ins
regex_match and sum helpers
truncate for length-limited string rendering

If template rendering fails at runtime (for example, missing variables), ChatAdapter panics. Templates are compiled per call — defs own their template strings, so there is no process-global template cache to leak per loaded program.

Real example: Insurance claim extraction

This is what a prompt looks like for a complex nested type (from examples/16-insurance-claim-prompt.rs):

#[derive(Signature, Clone, Debug)]
/// Extract the insurance claim information from the following text.
/// - If you are unsure about a field, leave it as null.
pub struct InsuranceClaimInfo {
    #[input]
    claim_text: String,

    #[output]
    claim: InsuranceClaim,  // complex nested struct with enums
}

Full type definitions (InsuranceClaim and nested types)

type NaiveDate = String;  // dates as YYYY-MM-DD strings

/// Basic claim information (metadata about the claim intake).
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub struct ClaimHeader {
    /// Claim ID in format `CLM-XXXXXX`, where `X` is a digit.
    pub claim_id: Option<String>,
    /// Date claim was reported in `YYYY-MM-DD` format.
    pub report_date: Option<NaiveDate>,
    /// Date incident occurred in `YYYY-MM-DD` format.
    pub incident_date: Option<NaiveDate>,
    /// Full name of person reporting claim.
    pub reported_by: Option<String>,
    /// Channel used to report claim.
    pub channel: Option<ClaimChannel>,
}

/// Channel used to report a claim.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub enum ClaimChannel {
    Email,
    Phone,
    Portal,
    InPerson,
}

/// Policy information if available.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub struct PolicyDetails {
    /// Policy number in format `POL-XXXXXXXXX`, where `X` is a digit.
    pub policy_number: Option<String>,
    /// Full legal name on policy.
    pub policyholder_name: Option<String>,
    /// Type of insurance coverage.
    pub coverage_type: Option<CoverageType>,
    /// Policy effective start date in `YYYY-MM-DD` format.
    pub effective_date: Option<NaiveDate>,
    /// Policy expiration end date in `YYYY-MM-DD` format.
    pub expiration_date: Option<NaiveDate>,
}

/// Type of insurance coverage.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub enum CoverageType {
    Property,
    Auto,
    Liability,
    Health,
    Travel,
    Other,
}

/// An insured object involved in the claim (vehicle, building, person, etc.).
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub struct InsuredObject {
    /// Unique identifier for insured object.
    ///
    /// For vehicles, use VIN format (e.g., `VIN12345678901234567`).
    /// For buildings, use `PROP-XXXXXX` format.
    /// For liability, use `LIAB-XXXXXX` format.
    /// For other objects, use `OBJ-XXXXXX` format,
    /// where `X` is a digit.
    pub object_id: Option<String>,
    /// Type of insured object.
    pub object_type: InsuredObjectType,
    /// Make and model for vehicles, or building type for property.
    pub make_model: Option<String>,
    /// Year for vehicles or year built for buildings.
    pub year: Option<i32>,
    /// Full street address where object is located or originated from.
    pub location_address: Option<String>,
    /// Estimated monetary value in USD without currency symbol.
    pub estimated_value: Option<i64>,
}

/// Type of insured object.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub enum InsuredObjectType {
    Vehicle,
    Building,
    Person,
    Other,
}

/// Structured incident details.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub struct IncidentDescription {
    /// Specific standardized incident type.
    pub incident_type: IncidentType,
    /// Standardized location type where incident occurred.
    pub location_type: LocationType,
    /// Estimated damage in USD without currency symbol.
    pub estimated_damage_amount: Option<i64>,
    /// Police report number if applicable.
    pub police_report_number: Option<String>,
}

/// Specific standardized incident type.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub enum IncidentType {
    RearEndCollision,
    SideImpactCollision,
    HeadOnCollision,
    ParkingLotCollision,
    HouseFire,
    KitchenFire,
    ElectricalFire,
    BurstPipeFlood,
    StormDamage,
    RoofLeak,
    SlipAndFall,
    PropertyInjury,
    ProductLiability,
    TheftBurglary,
    Vandalism,
}

/// Standardized location type where incident occurred.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub enum LocationType {
    Intersection,
    Highway,
    ParkingLot,
    Driveway,
    ResidentialStreet,
    ResidenceInterior,
    ResidenceExterior,
    CommercialProperty,
    PublicProperty,
}

/// Top-level insurance claim object aggregating all extracted fields.
#[derive(Debug, Clone, PartialEq, Eq)]
#[Schema]
pub struct InsuranceClaim {
    /// Basic claim information.
    pub header: ClaimHeader,
    /// Policy information if available.
    pub policy_details: Option<PolicyDetails>,
    /// List of insured objects involved, if applicable.
    pub insured_objects: Option<Vec<InsuredObject>>,
    /// Structured incident details.
    pub incident_description: Option<IncidentDescription>,
}

Generated system message:

Your input fields are:
1. `claim_text` (string)

Your output fields are:
1. `claim` (InsuranceClaim)

All interactions will be structured in the following way, with the appropriate values filled in.

[[ ## claim_text ## ]]
claim_text

[[ ## claim ## ]]
Output field `claim` should be of type: InsuranceClaim

Definitions (used below):

// Specific standardized incident type.

IncidentType
----
- RearEndCollision
- SideImpactCollision
- HeadOnCollision
- ParkingLotCollision
- HouseFire
- KitchenFire
- ElectricalFire
- BurstPipeFlood
- StormDamage
- RoofLeak
- SlipAndFall
- PropertyInjury
- ProductLiability
- TheftBurglary
- Vandalism

// Standardized location type where incident occurred.

LocationType
----
- Intersection
- Highway
- ParkingLot
- Driveway
- ResidentialStreet
- ResidenceInterior
- ResidenceExterior
- CommercialProperty
- PublicProperty

{
  // Top-level insurance claim object aggregating all extracted fields.

  // Basic claim information.
  header: {
    // Basic claim information (metadata about the claim intake).

    // Claim ID in format `CLM-XXXXXX`, where `X` is a digit.
    claim_id: string or null,
    // Date claim was reported in `YYYY-MM-DD` format.
    report_date: string or null,
    // Date incident occurred in `YYYY-MM-DD` format.
    incident_date: string or null,
    // Full name of person reporting claim.
    reported_by: string or null,
    // Channel used to report claim.
    channel: 'Email' or 'Phone' or 'Portal' or 'InPerson' or null,
  },
  // Policy information if available.
  policy_details: {
    // Policy information if available.

    // Policy number in format `POL-XXXXXXXXX`, where `X` is a digit.
    policy_number: string or null,
    // Full legal name on policy.
    policyholder_name: string or null,
    // Type of insurance coverage.
    coverage_type: 'Property' or 'Auto' or 'Liability' or 'Health' or 'Travel' or 'Other' or null,
    // Policy effective start date in `YYYY-MM-DD` format.
    effective_date: string or null,
    // Policy expiration end date in `YYYY-MM-DD` format.
    expiration_date: string or null,
  } or null,
  // List of insured objects involved, if applicable.
  insured_objects: [
    {
      // An insured object involved in the claim (vehicle, building, person, etc.).

      // Unique identifier for insured object.
      //
      // For vehicles, use VIN format (e.g., `VIN12345678901234567`).
      // For buildings, use `PROP-XXXXXX` format.
      // For liability, use `LIAB-XXXXXX` format.
      // For other objects, use `OBJ-XXXXXX` format,
      // where `X` is a digit.
      object_id: string or null,
      // Type of insured object.
      object_type: 'Vehicle' or 'Building' or 'Person' or 'Other',
      // Make and model for vehicles (use standardized manufacturer names and models),
      // or building type for property.
      make_model: string or null,
      // Year for vehicles or year built for buildings.
      year: int or null,
      // Full street address where object is located or originated from.
      location_address: string or null,
      // Estimated monetary value in USD without currency symbol.
      estimated_value: int or null,
    }
  ] or null,
  // Structured incident details.
  incident_description: {
    // Structured incident details.

    // Specific standardized incident type.
    incident_type: IncidentType,
    // Standardized location type where incident occurred.
    location_type: LocationType,
    // Estimated damage in USD without currency symbol.
    estimated_damage_amount: int or null,
    // Police report number if applicable.
    police_report_number: string or null,
  } or null,
}

[[ ## completed ## ]]

Respond with the corresponding output fields, starting with the field `[[ ## claim ## ]]`, and then ending with the marker for `[[ ## completed ## ]]`.

In adhering to this structure, your objective is:
        Extract the insurance claim information from the following text.
        - If you are unsure about a field, leave it as null.

Generated user message:

[[ ## claim_text ## ]]
A raccoon bumped a parked scooter in a driveway. Reported by Taylor P. via phone.

Notice how:

Enums with many variants become “Definitions” at the top
Doc comments become inline // comments in the schema
Option<T> renders as T or null
Nested objects show their full structure
The instruction comes from the signature docstring

Design notes

DSPy inspiration: Marker protocol from DSPy’s ChatAdapter
BAML heritage: Schema rendering and tolerant parsing were originally built on the vendored BAML stack (jsonish and its schema renderer). The in-house typesys module (typesys::render, typesys::coerce) replaced that stack while keeping the same prompt-facing schema style.
Separation of concerns: Adapter does not know about LMs - just formatting/parsing

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

What adapters do

ChatAdapter

Prompt structure

Marker protocol

Type schemas

Tolerant parsing with typesys::coerce

Constraint evaluation

Error handling

Using the adapter directly

Input formatting options

Real example: Insurance claim extraction

Design notes

See also

​What adapters do

​ChatAdapter

​Prompt structure

​Marker protocol

​Type schemas

​Tolerant parsing with typesys::coerce

​Constraint evaluation

​Error handling

​Using the adapter directly

​Input formatting options

​Real example: Insurance claim extraction

​Design notes

​See also

What adapters do

ChatAdapter

Prompt structure

Marker protocol

Type schemas

Tolerant parsing with typesys::coerce

Constraint evaluation

Error handling

Using the adapter directly

Input formatting options

Real example: Insurance claim extraction

Design notes

See also