generateStructured method

Future<StructuredResult> generateStructured(String prompt, String schema, { StructuredOutputMode mode = StructuredOutputMode.validationOnly, LlmOptions? options, })

Generate a completion constrained to schema.

mode picks how the schema is enforced:

• StructuredOutputMode.validationOnly (default): generate freely, then validate.
• StructuredOutputMode.repair: validate, then retry once with a repair instruction if invalid.
• StructuredOutputMode.constrained: engine-constrained decoding — fails preflight until a constrained-decoding engine is wired in.

Throws SDKException when mode cannot be honored, generation fails, or the output cannot be parsed against the schema.

Implementation

Future<StructuredResult> generateStructured(
  String prompt,
  String schema, {
  StructuredOutputMode mode = StructuredOutputMode.validationOnly,
  LlmOptions? options,
}) async {
  if (mode == StructuredOutputMode.constrained) {
    throw SDKException.featureNotAvailable(
      'llm.generateStructured(mode: constrained) needs engine-level '
      'constrained decoding, which is not wired in yet; use validationOnly or repair',
    );
  }
  await ModelGate.ensureLoaded(
    modelId: options?.model,
    category: ModelCategory.MODEL_CATEGORY_LANGUAGE,
  );
  final effective = options ?? LlmOptions();
  final model =
      await ModelGate.currentId(ModelCategory.MODEL_CATEGORY_LANGUAGE) ?? '';
  var proto = await RunAnywhereStructuredOutput.generateStructured(
    prompt: prompt,
    schema: schema,
    options: effective.toProto(
      registeredTools: RunAnywhereTools.shared.getRegisteredTools(),
    ),
  );
  if (mode == StructuredOutputMode.repair && !proto.validation.isValid) {
    final repairPrompt =
        '$prompt\n\n'
        'Your previous answer did not match the required JSON schema. '
        'Reply again with ONLY JSON that satisfies this schema.\n\n'
        'Previous invalid answer: '
        '${proto.hasRawText() ? proto.rawText : ''}';
    proto = await RunAnywhereStructuredOutput.generateStructured(
      prompt: repairPrompt,
      schema: schema,
      options: effective.toProto(
        registeredTools: RunAnywhereTools.shared.getRegisteredTools(),
      ),
    );
  }
  return StructuredResult.fromProto(
    proto,
    GenerationResult(text: proto.hasRawText() ? proto.rawText : '', model: model),
  );
}