Skip to content

Commit 8176cdb

Browse files
Add allowEmpty to generateObject to accept response with no text content (#10527)
Co-authored-by: Effect Bot <[email protected]>
1 parent 5ec3989 commit 8176cdb

9 files changed

Lines changed: 182 additions & 28 deletions

File tree

‎.changeset/loud-walls-listen.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"effect": patch
3+
"@effect/ai-anthropic": patch
4+
---
5+
6+
Add `allowEmpty` to `LanguageModel.generateObject` and `Chat.generateObject`, and preserve Anthropic tool-call finish reasons with native structured output.

‎packages/ai/anthropic/src/AnthropicLanguageModel.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2045,7 +2045,7 @@ const makeResponse = Effect.fnUntraced(
20452045
// Anthropic always returns a non-null `stop_reason` for non-streaming responses
20462046
const finishReason = InternalUtilities.resolveFinishReason(
20472047
rawResponse.stop_reason!,
2048-
options.responseFormat.type === "json"
2048+
hasStructuredOutputTool
20492049
)
20502050

20512051
const inputTokens = rawResponse.usage.input_tokens

‎packages/ai/anthropic/src/internal/utilities.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ const finishReasonMap: Record<string, Response.FinishReason> = {
1414
/** @internal */
1515
export const resolveFinishReason = (
1616
finishReason: string,
17-
isJsonResponse: boolean = false
17+
hasStructuredOutputTool: boolean = false
1818
): Response.FinishReason => {
1919
const reason = Object.hasOwn(finishReasonMap, finishReason) ? finishReasonMap[finishReason] : undefined
2020
if (Predicate.isUndefined(reason)) {
2121
return "unknown"
2222
}
23-
if (isJsonResponse && reason === "tool-calls") {
23+
if (hasStructuredOutputTool && reason === "tool-calls") {
2424
return "stop"
2525
}
2626
return reason

‎packages/ai/anthropic/test/AnthropicLanguageModel.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2196,6 +2196,7 @@ describe("AnthropicLanguageModel", () => {
21962196
)
21972197

21982198
assert.deepStrictEqual(response.value, { title: "Rain" })
2199+
assert.strictEqual(response.finishReason, "stop")
21992200
}))
22002201

22012202
it.effect("decodes native JSON alongside an ordinary tool call", () =>
@@ -2229,6 +2230,7 @@ describe("AnthropicLanguageModel", () => {
22292230

22302231
assert.deepStrictEqual(response.value, { title: "Rain" })
22312232
assert.strictEqual(response.toolCalls[0]?.name, "Weather")
2233+
assert.strictEqual(response.finishReason, "tool-calls")
22322234
}))
22332235
})
22342236

‎packages/effect/src/ai/Chat.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -423,13 +423,19 @@ export interface Chat {
423423
readonly generateObject: <
424424
ObjectEncoded extends Record<string, any>,
425425
ObjectSchema extends Schema.Encoder<ObjectEncoded, unknown>,
426-
Options extends NoExcessProperties<LanguageModel.GenerateObjectOptions<any, ObjectSchema>, Options>
426+
Options extends NoExcessProperties<LanguageModel.GenerateObjectOptions<any, ObjectSchema, boolean>, Options>
427427
>(
428-
options: Options & LanguageModel.GenerateObjectOptions<LanguageModel.ExtractTools<Options>, ObjectSchema>
428+
options:
429+
& Options
430+
& LanguageModel.GenerateObjectOptions<
431+
LanguageModel.ExtractTools<Options>,
432+
ObjectSchema,
433+
false | Extract<Options["allowEmpty" & keyof Options], boolean>
434+
>
429435
) => Effect.Effect<
430436
LanguageModel.GenerateObjectResponse<
431437
LanguageModel.ExtractTools<Options>,
432-
ObjectSchema["Type"],
438+
LanguageModel.ExtractObjectValue<Options, ObjectSchema["Type"]>,
433439
LanguageModel.ExtractToolParametersMode<Options>
434440
>,
435441
LanguageModel.ExtractError<Options>,

‎packages/effect/src/ai/LanguageModel.ts‎

Lines changed: 70 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -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
*/
344354
export 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

26102657
const 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

26422698
const applySpanTransformer = (

‎packages/effect/test/ai/Chat.test.ts‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { assert, describe, it } from "@effect/vitest"
2-
import { Effect, Layer, Predicate, Ref, Schema, Stream } from "effect"
2+
import { Effect, Layer, Option, Predicate, Ref, Schema, Stream } from "effect"
33
import { Chat, IdGenerator, type LanguageModel, Prompt, type Response, Tool, Toolkit } from "effect/ai"
44
import { KeyValueStore, Persistence } from "effect/persistence"
55
import { TestClock } from "effect/testing"
@@ -54,6 +54,40 @@ const PersistenceLayer = Layer.provideMerge(
5454
)
5555

5656
describe("Chat", () => {
57+
it.effect("generateObject with allowEmpty preserves tool calls and results in history", () =>
58+
Effect.gen(function*() {
59+
const chat = yield* Chat.empty
60+
const response = yield* chat.generateObject({
61+
prompt: "Look it up",
62+
schema: Schema.Struct({ answer: Schema.String }),
63+
toolkit: LoopToolkit,
64+
allowEmpty: true
65+
}).pipe(
66+
TestUtils.withLanguageModel({
67+
generateText: [
68+
{ type: "tool-call", id: "call-1", name: "Lookup", params: { key: "a" } },
69+
{ type: "finish", reason: "tool-calls", usage: { inputTokens: {}, outputTokens: {} } }
70+
]
71+
})
72+
)
73+
74+
assert.deepStrictEqual(response.value, Option.none())
75+
assert.deepStrictEqual(
76+
yield* Ref.get(chat.history),
77+
Prompt.make([
78+
{ role: "user", content: "Look it up" },
79+
{
80+
role: "assistant",
81+
content: [{ type: "tool-call", id: "call-1", name: "Lookup", params: { key: "a" } }]
82+
},
83+
{
84+
role: "tool",
85+
content: [{ type: "tool-result", id: "call-1", name: "Lookup", result: "value of a", isFailure: false }]
86+
}
87+
])
88+
)
89+
}).pipe(Effect.provide(LoopToolkitLayer)))
90+
5791
for (
5892
const [name, data] of [
5993
["bytes", new Uint8Array([0, 137, 255, 65])],

‎packages/effect/test/ai/LanguageModel.test.ts‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, it } from "@effect/vitest"
2-
import { assertDefined, assertTrue, deepStrictEqual, strictEqual } from "@effect/vitest/utils"
2+
import { assertDefined, assertNone, assertSome, assertTrue, deepStrictEqual, strictEqual } from "@effect/vitest/utils"
33
import { type Cause, Effect, Fiber, Latch, Option, Queue, Ref, Schema, Stream } from "effect"
44
import { AiError, LanguageModel, Prompt, Response, ResponseIdTracker, Tool, Toolkit } from "effect/ai"
55
import { TestClock } from "effect/testing"
@@ -1523,13 +1523,11 @@ describe("LanguageModel", () => {
15231523
Effect.gen(function*() {
15241524
const error = yield* LanguageModel.generateObject({
15251525
prompt: [],
1526-
schema: Schema.Struct({ count: Schema.Number })
1526+
schema: Schema.Struct({ count: Schema.Number }),
1527+
allowEmpty: true
15271528
}).pipe(
15281529
TestUtils.withLanguageModel({
1529-
generateText: [{
1530-
type: "text",
1531-
text: "{\"count\":\"oops\"}"
1532-
}]
1530+
generateText: [{ type: "text", text: "{\"count\":\"oops\"}" }]
15331531
}),
15341532
Effect.flip
15351533
)
@@ -1540,6 +1538,30 @@ describe("LanguageModel", () => {
15401538
}
15411539
}))
15421540

1541+
it.effect("allowEmpty treats whitespace-only text as empty", () =>
1542+
Effect.gen(function*() {
1543+
const response = yield* LanguageModel.generateObject({
1544+
prompt: "hi",
1545+
schema: Schema.Struct({ count: Schema.Number }),
1546+
allowEmpty: true
1547+
}).pipe(TestUtils.withLanguageModel({ generateText: [{ type: "text", text: " \n\t" }] }))
1548+
1549+
assertNone(response.value)
1550+
}))
1551+
1552+
it.effect("wraps generated values in some when empty output is allowed", () =>
1553+
Effect.gen(function*() {
1554+
const response = yield* LanguageModel.generateObject({
1555+
prompt: "hi",
1556+
schema: Schema.Struct({ count: Schema.Number }),
1557+
allowEmpty: true
1558+
}).pipe(
1559+
TestUtils.withLanguageModel({ generateText: [{ type: "text", text: "{\"count\":1}" }] })
1560+
)
1561+
1562+
assertSome(response.value, { count: 1 })
1563+
}))
1564+
15431565
it("resolves the canonical top-level $ref for class schemas in defaultCodecTransformer", () => {
15441566
class Person extends Schema.Class<Person>("Person")({
15451567
name: Schema.String

‎packages/effect/typetest/ai/LanguageModel.tst.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { Context, Effect, Schema, SchemaGetter, type Stream } from "effect"
1+
import { Context, Effect, type Option, Schema, SchemaGetter, type Stream } from "effect"
22
import { type AiError, type Chat, LanguageModel, Tool, Toolkit } from "effect/ai"
33
import type * as Response from "effect/ai/Response"
44
import { describe, expect, it } from "tstyche"
@@ -405,6 +405,34 @@ describe("LanguageModel", () => {
405405
})
406406

407407
describe("generateObject", () => {
408+
it("infers the object value from allowEmpty", () => {
409+
const schema = Schema.Struct({ answer: Schema.Number })
410+
type Value = typeof schema.Type
411+
const options = { prompt: "hello", schema }
412+
const flag = null as unknown as boolean
413+
414+
Effect.gen(function*() {
415+
const strictOptions: LanguageModel.GenerateObjectOptions<{}, typeof schema> = options
416+
const strict = yield* LanguageModel.generateObject(strictOptions)
417+
expect<typeof strict.value>().type.toBe<Value>()
418+
419+
expect(LanguageModel.generateObject<Record<string, any>, typeof schema, typeof options>)
420+
.type.not.toBeCallableWith({ ...options, allowEmpty: true })
421+
422+
const absent = yield* LanguageModel.generateObject(options)
423+
const enabled = yield* LanguageModel.generateObject({ ...options, allowEmpty: true })
424+
const widened = yield* LanguageModel.generateObject({ ...options, allowEmpty: flag })
425+
426+
expect<typeof absent.value>().type.toBe<Value>()
427+
expect<typeof enabled.value>().type.toBe<Option.Option<Value>>()
428+
expect<typeof widened.value>().type.toBe<Value | Option.Option<Value>>()
429+
430+
const chat = null as unknown as Chat.Chat
431+
const chatResponse = yield* chat.generateObject({ ...options, allowEmpty: true })
432+
expect<typeof chatResponse.value>().type.toBe<Option.Option<Value>>()
433+
})
434+
})
435+
408436
it("uses encoded tool parameters when tool call resolution is disabled", () => {
409437
const toolkit = Toolkit.make(TransformTool)
410438
const program = LanguageModel.generateObject({

0 commit comments

Comments
 (0)