@@ -161,14 +161,24 @@ export interface LanguageModel {
161161 ObjectEncoded extends Record < string , any > ,
162162 StructuredOutputSchema extends Schema . Encoder < ObjectEncoded , unknown > ,
163163 Options extends NoExcessProperties <
164- GenerateObjectOptions < any , StructuredOutputSchema > ,
164+ GenerateObjectOptions < any , StructuredOutputSchema , boolean > ,
165165 Options
166166 > ,
167167 Tools extends Record < string , Tool . Any > = { }
168168 > (
169- options : Options & GenerateObjectOptions < Tools , StructuredOutputSchema >
169+ options :
170+ & Options
171+ & GenerateObjectOptions <
172+ Tools ,
173+ StructuredOutputSchema ,
174+ false | Extract < Options [ "allowEmpty" & keyof Options ] , boolean >
175+ >
170176 ) => Effect . Effect <
171- GenerateObjectResponse < Tools , StructuredOutputSchema [ "Type" ] , ExtractToolParametersMode < Options > > ,
177+ GenerateObjectResponse <
178+ Tools ,
179+ ExtractObjectValue < Options , StructuredOutputSchema [ "Type" ] > ,
180+ ExtractToolParametersMode < Options >
181+ > ,
172182 ExtractError < Options > ,
173183 ExtractServices < Options > | StructuredOutputSchema [ "DecodingServices" ]
174184 >
@@ -343,14 +353,23 @@ type GenerateTextOptionsWithoutToolkit = Omit<GenerateTextOptions<{}>, "toolkit"
343353 */
344354export interface GenerateObjectOptions <
345355 Tools extends Record < string , Tool . Any > ,
346- StructuredOutputSchema extends Schema . Top
356+ StructuredOutputSchema extends Schema . Top ,
357+ AllowEmpty extends boolean = false
347358> extends GenerateTextOptions < Tools > {
348359 /**
349360 * The name of the structured output that should be generated. Used by some
350361 * large language model providers to provide additional guidance to the model.
351362 */
352363 readonly objectName ?: string | undefined
353364
365+ /**
366+ * Whether to return `None` for empty or whitespace-only text and `Some` for
367+ * valid output. Defaults to `false`; invalid nonempty output still fails.
368+ * Use literal `true` for an `Option<A>` value; a widened boolean yields
369+ * `A | Option<A>`.
370+ */
371+ readonly allowEmpty ?: AllowEmpty | undefined
372+
354373 /**
355374 * The schema to be used to specify the structure of the object to generate.
356375 */
@@ -523,7 +542,7 @@ export class GenerateObjectResponse<
523542 ParametersMode extends Response . ToolParametersMode = "decoded"
524543> extends GenerateTextResponse < Tools , ParametersMode > {
525544 /**
526- * The parsed structured object that conforms to the provided schema .
545+ * The decoded schema value, wrapped in an `Option` when `allowEmpty` is enabled .
527546 */
528547 readonly value : A
529548
@@ -604,6 +623,18 @@ export type ExtractTools<Options> = Options extends {
604623} ? ExtractToolsFromToolkitOption < Exclude < ToolkitValue , undefined > >
605624 : { }
606625
626+ /**
627+ * Resolves to `Option<A>` when `allowEmpty` is true, `A` when false or absent,
628+ * or their union when the flag may be enabled.
629+ *
630+ * @stability unstable
631+ * @category utility types
632+ * @since 4.1.4
633+ */
634+ export type ExtractObjectValue < Options , A > = Options extends { readonly allowEmpty : true } ? Option . Option < A >
635+ : true extends Options [ "allowEmpty" & keyof Options ] ? A | Option . Option < A >
636+ : A
637+
607638/**
608639 * Resolves to `"deferred"` when tool call resolution may be disabled with
609640 * deferred tool call validation. Otherwise resolves to `"encoded"` when tool
@@ -953,14 +984,24 @@ export const make: (params: {
953984 ObjectEncoded extends Record < string , any > ,
954985 StructuredOutputSchema extends Schema . Encoder < ObjectEncoded , unknown > ,
955986 Options extends NoExcessProperties <
956- GenerateObjectOptions < any , StructuredOutputSchema > ,
987+ GenerateObjectOptions < any , StructuredOutputSchema , boolean > ,
957988 Options
958989 > ,
959990 Tools extends Record < string , Tool . Any > = { }
960991 > (
961- options : Options & GenerateObjectOptions < Tools , StructuredOutputSchema >
992+ options :
993+ & Options
994+ & GenerateObjectOptions <
995+ Tools ,
996+ StructuredOutputSchema ,
997+ false | Extract < Options [ "allowEmpty" & keyof Options ] , boolean >
998+ >
962999 ) : Effect . Effect <
963- GenerateObjectResponse < Tools , StructuredOutputSchema [ "Type" ] , ExtractToolParametersMode < Options > > ,
1000+ GenerateObjectResponse <
1001+ Tools ,
1002+ ExtractObjectValue < Options , StructuredOutputSchema [ "Type" ] > ,
1003+ ExtractToolParametersMode < Options >
1004+ > ,
9641005 ExtractError < Options > ,
9651006 ExtractServices < Options > | StructuredOutputSchema [ "DecodingServices" ]
9661007 > => {
@@ -1009,7 +1050,7 @@ export const make: (params: {
10091050 } )
10101051 } )
10111052
1012- const value = yield * resolveStructuredOutput ( content as any , codec )
1053+ const value = yield * resolveStructuredOutput ( content as any , codec , options . allowEmpty ?? false )
10131054
10141055 return new GenerateObjectResponse ( value , content )
10151056 } ,
@@ -1948,15 +1989,21 @@ export const generateObject = <
19481989 ObjectEncoded extends Record < string , any > ,
19491990 StructuredOutputSchema extends Schema . Encoder < ObjectEncoded , unknown > ,
19501991 Options extends NoExcessProperties <
1951- GenerateObjectOptions < any , StructuredOutputSchema > ,
1992+ GenerateObjectOptions < any , StructuredOutputSchema , boolean > ,
19521993 Options
19531994 >
19541995> (
1955- options : Options & GenerateObjectOptions < ExtractTools < Options > , StructuredOutputSchema >
1996+ options :
1997+ & Options
1998+ & GenerateObjectOptions <
1999+ ExtractTools < Options > ,
2000+ StructuredOutputSchema ,
2001+ false | Extract < Options [ "allowEmpty" & keyof Options ] , boolean >
2002+ >
19562003) : Effect . Effect <
19572004 GenerateObjectResponse <
19582005 ExtractTools < Options > ,
1959- StructuredOutputSchema [ "Type" ] ,
2006+ ExtractObjectValue < Options , StructuredOutputSchema [ "Type" ] > ,
19602007 ExtractToolParametersMode < Options >
19612008 > ,
19622009 ExtractError < Options > ,
@@ -2609,7 +2656,11 @@ export const getObjectName = <StructuredOutputSchema extends Schema.Constraint>(
26092656
26102657const resolveStructuredOutput = Effect . fnUntraced ( function * <
26112658 StructuredOutputSchema extends Schema . Constraint
2612- > ( response : ReadonlyArray < Response . AllParts < any > > , schema : StructuredOutputSchema ) {
2659+ > (
2660+ response : ReadonlyArray < Response . AllParts < any > > ,
2661+ schema : StructuredOutputSchema ,
2662+ allowEmpty : boolean
2663+ ) {
26132664 const texts : Array < string > = [ ]
26142665 for ( const part of response ) {
26152666 if ( part . type === "text" ) {
@@ -2619,6 +2670,10 @@ const resolveStructuredOutput = Effect.fnUntraced(function*<
26192670
26202671 const text = texts . join ( "" )
26212672
2673+ if ( allowEmpty && text . trim ( ) . length === 0 ) {
2674+ return Option . none ( )
2675+ }
2676+
26222677 if ( text . length === 0 ) {
26232678 return yield * AiError . make ( {
26242679 module : "LanguageModel" ,
@@ -2631,12 +2686,13 @@ const resolveStructuredOutput = Effect.fnUntraced(function*<
26312686 }
26322687
26332688 const decode = Schema . decodeEffect ( Schema . fromJsonString ( schema ) )
2634- return yield * Effect . mapError ( decode ( text ) , ( error ) =>
2689+ const value = yield * Effect . mapError ( decode ( text ) , ( error ) =>
26352690 AiError . make ( {
26362691 module : "LanguageModel" ,
26372692 method : "generateObject" ,
26382693 reason : AiError . StructuredOutputError . fromSchemaError ( error , text )
26392694 } ) )
2695+ return allowEmpty ? Option . some ( value ) : value
26402696} )
26412697
26422698const applySpanTransformer = (
0 commit comments