Skip to main content

Module author

Module author 

Source
Expand description

Language-agnostic authoring: YAML/JSON question-spec documents → IR.

The document format is the jev-1 questions map with an optional shared state, in our own prose (clean-room, S6a §3):

state: "The refund arrived two weeks late and the box was crushed."
questions:
  is_refund:                    # caller-chosen id — never sent to the model
    type: noul
    instructions: "The customer is asking for a refund."
    criteria:                   # optional; keys are literally "true" / "false"
      "true": "Explicitly requests money back"
      "false": ~                # null = undescribed
  tone:
    type: choice
    instructions: "Classify the tone of the review."
    criteria:                   # option name -> rubric (null = undescribed option)
      positive: "The review expresses approval."
      negative: "The review expresses disapproval."
      neutral: ~
  severity:
    type: score
    criteria:                   # ordered levels, 0-indexed; null = undescribed level
      - "Cosmetic issue only"
      - "Usable but damaged"
      - "Completely unusable"

Validation produces structured, positioned SpecErrors — the first violation is returned with a document path (and line/column for syntax errors). The enforced rules:

  • top level: a mapping with optional state and required questions; unknown keys rejected (D-parity with the upstream SDKs’ extra=forbid).
  • questions: ≥ 1 entry; ids non-empty and unique.
  • every question: type required; instructions optional and nullable (D4); unknown fields rejected.
  • noul: criteria optional; only keys "true"/"false" allowed.
  • choice: criteria required; 2–255 options (D2); option names non-empty, unique.
  • score: criteria required; ≥ 2 levels (D1); null levels allowed (D3).
  • span / derived are recognized and rejected as reserved v2 types.

There is intentionally no limit on questions per document (S6a A12 footnote: the upstream profile publishes only token budgets). The serialized-size contract is the 2k token budget documented on crate::serialize.

Constants§

MAX_CHOICE_OPTIONS
The profile-pinned maximum number of options on a choice question (S6a A4: the 255 limit is prose-documented upstream; this profile pins it as a hard validation).

Functions§

parse_json
Parse a JSON question-spec document into the IR.
parse_yaml
Parse a YAML question-spec document into the IR.