feat(dsp): Separate structured output example input fields with newlines and allow missing required fields during structured output validation in response processing.

Author: dosco

src/ax/dsp/extract.ts

@@ -718,7 +718,8 @@ export function validateAndParseFieldValue(
  */
 export function validateStructuredOutputValues(
   signature: Readonly<AxSignature>,
-  values: Record<string, unknown>
+  values: Record<string, unknown>,
+  options?: { allowMissingRequired?: boolean }
 ): void {
   const outputFields = signature.getOutputFields();
 
@@ -727,7 +728,7 @@ export function validateStructuredOutputValues(
 
     // Check required fields
     if (value === undefined || value === null) {
-      if (!field.isOptional) {
+      if (!field.isOptional && !options?.allowMissingRequired) {
         throw createRequiredFieldMissingError(field);
       }
       continue;
@@ -773,7 +774,11 @@ export function validateStructuredOutputValues(
       typeof value === 'object' &&
       !Array.isArray(value)
     ) {
-      validateNestedObjectFields(field, value as Record<string, unknown>);
+      validateNestedObjectFields(
+        field,
+        value as Record<string, unknown>,
+        options
+      );
     }
 
     // Validate array of objects
@@ -785,7 +790,11 @@ export function validateStructuredOutputValues(
     ) {
       for (const item of value) {
         if (item && typeof item === 'object') {
-          validateNestedObjectFields(field, item as Record<string, unknown>);
+          validateNestedObjectFields(
+            field,
+            item as Record<string, unknown>,
+            options
+          );
         }
       }
     }
@@ -797,7 +806,8 @@ export function validateStructuredOutputValues(
  */
 function validateNestedObjectFields(
   parentField: Readonly<AxField>,
-  obj: Record<string, unknown>
+  obj: Record<string, unknown>,
+  options?: { allowMissingRequired?: boolean }
 ): void {
   const fields = parentField.type?.fields;
   if (!fields || typeof fields !== 'object') return;
@@ -829,7 +839,7 @@ function validateNestedObjectFields(
 
     // Check required fields
     if (value === undefined || value === null) {
-      if (!nestedField.isOptional) {
+      if (!nestedField.isOptional && !options?.allowMissingRequired) {
         throw createRequiredFieldMissingError(nestedField);
       }
       continue;
@@ -875,7 +885,11 @@ function validateNestedObjectFields(
       typeof value === 'object' &&
       !Array.isArray(value)
     ) {
-      validateNestedObjectFields(nestedField, value as Record<string, unknown>);
+      validateNestedObjectFields(
+        nestedField,
+        value as Record<string, unknown>,
+        options
+      );
     }
 
     // Validate array of objects
@@ -889,7 +903,8 @@ function validateNestedObjectFields(
         if (item && typeof item === 'object') {
           validateNestedObjectFields(
             nestedField,
-            item as Record<string, unknown>
+            item as Record<string, unknown>,
+            options
           );
         }
       }

src/ax/dsp/processResponse.ts

@@ -265,7 +265,8 @@ async function* ProcessStreamingResponse<OUT extends AxGenOut>({
         // Validate structured output values against field constraints
         validateStructuredOutputValues(
           signature,
-          delta as Record<string, unknown>
+          delta as Record<string, unknown>,
+          { allowMissingRequired: true }
         );
 
         // Update state values
@@ -441,7 +442,8 @@ export async function* finalizeStreamingResponse<OUT extends AxGenOut>({
         // Validate structured output values against field constraints
         validateStructuredOutputValues(
           signature,
-          delta as Record<string, unknown>
+          delta as Record<string, unknown>,
+          { allowMissingRequired: true }
         );
 
         Object.assign(state.values, delta);

src/ax/dsp/prompt.ts

@@ -502,6 +502,9 @@ export class AxPromptTemplate {
 
         renderedItem.forEach((v) => {
           if (v) {
+            if ('text' in v) {
+              v.text = `${v.text}\n`;
+            }
             list.push(v);
           }
         });

src/ax/dsp/structured_output_features.test.ts

@@ -75,4 +75,34 @@ describe('Structured Output Features', () => {
       'IMPORTANT: Provide the FULL JSON object for this field'
     );
   });
+
+  it('should separate input fields with newlines in examples when structured outputs are enabled', () => {
+    const signature = f()
+      .input('field1', f.string())
+      .input('field2', f.string())
+      .output('responseText', f.string())
+      .useStructured()
+      .build();
+
+    const template = new AxPromptTemplate(signature);
+    const examples = [
+      {
+        field1: 'value1',
+        field2: 'value2',
+        responseText: 'result',
+      },
+    ];
+
+    const rendered = template.render(
+      { field1: 'test', field2: 'test' },
+      { examples }
+    );
+    const systemMessage = rendered.find((m) => m.role === 'system');
+
+    // Check that fields are separated by newline
+    // We expect "Field1: value1\nField2: value2"
+    expect(systemMessage?.content).toContain(
+      'Field 1: value1\nField 2: value2'
+    );
+  });
 });