Skip to content

Commit ce13a48

Browse files
authored
feat(ai): decode response parts without a toolkit (#9674)
1 parent 6250d31 commit ce13a48

3 files changed

Lines changed: 121 additions & 65 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"effect": patch
3+
---
4+
5+
Allow `Response.AllParts`, `Response.Part` and `Response.StreamPart` to be called without a toolkit, decoding tool call and tool result parts for any tool name with `unknown` parameters and results.

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

Lines changed: 77 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,21 @@ const toolPartSchemas = (tool: Tool.Any) => {
170170
return parts
171171
}
172172

173+
type AnyToolParts = ToolCallPart<string, unknown> | ToolResultPart<string, unknown, unknown>
174+
175+
const toolPartSchemasFor = (
176+
toolkit: Toolkit.Any | Toolkit.WithHandler<any> | undefined
177+
): ReadonlyArray<Schema.Top> => {
178+
if (toolkit === undefined) {
179+
return [
180+
makeToolCallPart(Schema.String, Schema.Unknown),
181+
makeToolResultPart(Schema.String, Schema.Unknown, Schema.Unknown)
182+
]
183+
}
184+
const parts = Object.values(toolkit.tools as Record<string, Tool.Any>).map(toolPartSchemas)
185+
return [...parts.map((part) => part.toolCall), ...parts.map((part) => part.toolResult)]
186+
}
187+
173188
/**
174189
* Creates a Schema for all response parts based on a toolkit.
175190
*
@@ -178,6 +193,9 @@ const toolPartSchemas = (tool: Tool.Any) => {
178193
* Generates a schema that includes all possible response parts, with tool call
179194
* and tool result parts dynamically created based on the provided toolkit.
180195
*
196+
* When no toolkit is provided, tool call and tool result parts accept any tool
197+
* name, with parameters and results decoded as `unknown`.
198+
*
181199
* **Example** (Building a response parts schema)
182200
*
183201
* ```ts import.meta.vitest
@@ -193,28 +211,25 @@ const toolPartSchemas = (tool: Tool.Any) => {
193211
*
194212
* const allPartsSchema = Response.AllParts(myToolkit)
195213
* Schema.isSchema(allPartsSchema) // => true
214+
*
215+
* const anyToolPartsSchema = Response.AllParts()
216+
* Schema.isSchema(anyToolPartsSchema) // => true
196217
* ```
197218
*
198219
* @stability unstable
199220
* @category schemas
200221
* @since 4.0.0
201222
*/
202-
export const AllParts = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
203-
toolkit: T
204-
): Schema.Codec<
205-
AllParts<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
206-
AllPartsEncoded,
207-
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
208-
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
209-
> => {
210-
const toolCalls: Array<Schema.Top> = []
211-
const toolResults: Array<Schema.Top> = []
212-
for (const tool of Object.values(toolkit.tools as Record<string, Tool.Any>)) {
213-
const parts = toolPartSchemas(tool)
214-
toolCalls.push(parts.toolCall)
215-
toolResults.push(parts.toolResult)
216-
}
217-
return Schema.Union([
223+
export const AllParts: {
224+
<T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
225+
AllParts<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
226+
AllPartsEncoded,
227+
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
228+
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
229+
>
230+
(): Schema.Codec<AllParts<{}> | AnyToolParts, AllPartsEncoded>
231+
} = (toolkit?: Toolkit.Any | Toolkit.WithHandler<any>) =>
232+
Schema.Union([
218233
TextPart,
219234
TextStartPart,
220235
TextDeltaPart,
@@ -233,10 +248,8 @@ export const AllParts = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
233248
ResponseMetadataPart,
234249
FinishPart,
235250
ErrorPart,
236-
...toolCalls,
237-
...toolResults
251+
...toolPartSchemasFor(toolkit)
238252
]) as any
239-
}
240253

241254
// =============================================================================
242255
// Parts
@@ -289,26 +302,25 @@ export type PartEncoded =
289302
/**
290303
* Creates a Schema for non-streaming response parts based on a toolkit.
291304
*
305+
* **Details**
306+
*
307+
* When no toolkit is provided, tool call and tool result parts accept any tool
308+
* name, with parameters and results decoded as `unknown`.
309+
*
292310
* @stability unstable
293311
* @category schemas
294312
* @since 4.0.0
295313
*/
296-
export const Part = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
297-
toolkit: T
298-
): Schema.Codec<
299-
Part<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
300-
PartEncoded,
301-
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
302-
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
303-
> => {
304-
const toolCalls: Array<Schema.Top> = []
305-
const toolResults: Array<Schema.Top> = []
306-
for (const tool of Object.values(toolkit.tools as Record<string, Tool.Any>)) {
307-
const parts = toolPartSchemas(tool)
308-
toolCalls.push(parts.toolCall)
309-
toolResults.push(parts.toolResult)
310-
}
311-
return Schema.Union([
314+
export const Part: {
315+
<T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
316+
Part<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
317+
PartEncoded,
318+
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
319+
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
320+
>
321+
(): Schema.Codec<Part<{}> | AnyToolParts, PartEncoded>
322+
} = (toolkit?: Toolkit.Any | Toolkit.WithHandler<any>) =>
323+
Schema.Union([
312324
TextPart,
313325
ReasoningPart,
314326
ToolApprovalRequestPart,
@@ -317,10 +329,8 @@ export const Part = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
317329
UrlSourcePart,
318330
ResponseMetadataPart,
319331
FinishPart,
320-
...toolCalls,
321-
...toolResults
332+
...toolPartSchemasFor(toolkit)
322333
]) as any
323-
}
324334

325335
// =============================================================================
326336
// Stream Parts
@@ -386,26 +396,25 @@ export type StreamPartEncoded =
386396
/**
387397
* Creates a Schema for streaming response parts based on a toolkit.
388398
*
399+
* **Details**
400+
*
401+
* When no toolkit is provided, tool call and tool result parts accept any tool
402+
* name, with parameters and results decoded as `unknown`.
403+
*
389404
* @stability unstable
390405
* @category schemas
391406
* @since 4.0.0
392407
*/
393-
export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
394-
toolkit: T
395-
): Schema.Codec<
396-
StreamPart<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
397-
StreamPartEncoded,
398-
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
399-
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
400-
> => {
401-
const toolCalls: Array<Schema.Top> = []
402-
const toolResults: Array<Schema.Top> = []
403-
for (const tool of Object.values(toolkit.tools as Record<string, Tool.Any>)) {
404-
const parts = toolPartSchemas(tool)
405-
toolCalls.push(parts.toolCall)
406-
toolResults.push(parts.toolResult)
407-
}
408-
return Schema.Union([
408+
export const StreamPart: {
409+
<T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T): Schema.Codec<
410+
StreamPart<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>,
411+
StreamPartEncoded,
412+
Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>,
413+
Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>
414+
>
415+
(): Schema.Codec<StreamPart<{}> | AnyToolParts, StreamPartEncoded>
416+
} = (toolkit?: Toolkit.Any | Toolkit.WithHandler<any>) =>
417+
Schema.Union([
409418
TextStartPart,
410419
TextDeltaPart,
411420
TextEndPart,
@@ -422,10 +431,8 @@ export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
422431
ResponseMetadataPart,
423432
FinishPart,
424433
ErrorPart,
425-
...toolCalls,
426-
...toolResults
434+
...toolPartSchemasFor(toolkit)
427435
]) as any
428-
}
429436

430437
// =============================================================================
431438
// utility types
@@ -1522,15 +1529,17 @@ export const ToolCallPart: <const Name extends string, Params extends Schema.Con
15221529
> = <const Name extends string, Params extends Schema.Constraint>(
15231530
name: Name,
15241531
params: Params
1525-
) =>
1532+
) => makeToolCallPart(Schema.Literal(name), params) as any
1533+
1534+
const makeToolCallPart = (name: Schema.Top, params: Schema.Constraint) =>
15261535
Schema.Struct({
15271536
...BasePart.fields,
15281537
type: Schema.Literal("tool-call"),
15291538
id: Schema.String,
1530-
name: Schema.Literal(name),
1539+
name,
15311540
params,
15321541
providerExecuted: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)))
1533-
}).annotate({ identifier: "ToolCallPart" }) as any
1542+
}).annotate({ identifier: "ToolCallPart" })
15341543

15351544
/**
15361545
* Constructs a new tool call part.
@@ -1739,14 +1748,19 @@ export const ToolResultPart = <
17391748
ToolResultPartEncoded,
17401749
Success["DecodingServices"] | Failure["DecodingServices"],
17411750
Success["EncodingServices"] | Failure["EncodingServices"]
1742-
> => {
1751+
> =>
1752+
makeToolResultPart(Schema.Literal(name), success, failure).annotate({
1753+
identifier: `ToolResultPart(${name})`
1754+
}) as any
1755+
1756+
const makeToolResultPart = (name: Schema.Top, success: Schema.Constraint, failure: Schema.Constraint) => {
17431757
const makeSchema = (result: Schema.Constraint, isFailure: boolean) => {
17441758
const encodedResult = Schema.toEncoded(result)
17451759
const Common = {
17461760
id: Schema.String,
17471761
type: Schema.Literal("tool-result"),
17481762
isFailure: Schema.Literal(isFailure),
1749-
name: Schema.Literal(name)
1763+
name
17501764
}
17511765
const Decoded = Schema.Struct({
17521766
...Common,
@@ -1779,9 +1793,7 @@ export const ToolResultPart = <
17791793
})
17801794
))
17811795
}
1782-
return Schema.Union([makeSchema(success, false), makeSchema(failure, true)]).annotate({
1783-
identifier: `ToolResultPart(${name})`
1784-
})
1796+
return Schema.Union([makeSchema(success, false), makeSchema(failure, true)])
17851797
}
17861798

17871799
/**

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,45 @@ describe("Response", () => {
199199
}
200200
})
201201

202+
describe("schemas without a toolkit", () => {
203+
const parts = [
204+
Response.toolCallPart({
205+
id: "call-1",
206+
name: "UnknownTool",
207+
params: { path: "a.ts", options: [1, null] },
208+
providerExecuted: false
209+
}),
210+
Response.makePart("tool-result", {
211+
id: "call-1",
212+
name: "UnknownTool",
213+
isFailure: false,
214+
result: { content: "hello" },
215+
encodedResult: { content: "hello" },
216+
providerExecuted: false,
217+
preliminary: false
218+
})
219+
]
220+
221+
for (
222+
const [name, makeSchema] of [
223+
["AllParts", () => Response.AllParts()],
224+
["Part", () => Response.Part()],
225+
["StreamPart", () => Response.StreamPart()]
226+
] as const
227+
) {
228+
it.effect(`${name} round trips tool parts with any tool name through JSON`, () =>
229+
Effect.gen(function*() {
230+
const schema = makeSchema()
231+
for (const part of parts) {
232+
const encoded = yield* Schema.encodeUnknownEffect(schema)(part)
233+
const decoded = yield* Schema.decodeUnknownEffect(schema)(JSON.parse(JSON.stringify(encoded)))
234+
235+
deepStrictEqual<unknown>(decoded, part, `decoded ${part.type}`)
236+
}
237+
}))
238+
}
239+
})
240+
202241
it.effect("decodes response metadata with omitted optional fields", () =>
203242
Effect.gen(function*() {
204243
const encoded: Response.ResponseMetadataPartEncoded = {

0 commit comments

Comments
 (0)