Improve unstable AI structured output handling for empty tool params and add Tool.EmptyParams, closes #1749 (#1750)

Author: gcanti

.changeset/fix-ai-empty-params-structured-output.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+Improve unstable AI structured output handling for empty tool params and add `Tool.EmptyParams`, closes #1749.

packages/effect/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -22,6 +22,7 @@ import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with Anthropic's
@@ -225,6 +226,9 @@ function recur(ast: AST.AST): AST.AST {
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
+        if (Tool.isEmptyParamsRecord(is)) {
+          return ast
+        }
         // records are not supported by Anthropic, so we translate them to arrays of key-value pairs
         if (annotations !== undefined && typeof annotations.description === "string") {
           annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`

packages/effect/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -11,6 +11,7 @@ import * as Rec from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with OpenAI's
@@ -243,6 +244,9 @@ function recurOpenAI(ast: AST.AST): AST.AST {
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
+        if (Tool.isEmptyParamsRecord(is)) {
+          return ast
+        }
         // records are not supported by OpenAI, so we translate them to arrays of key-value pairs
         if (annotations !== undefined && typeof annotations.description === "string") {
           annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`

packages/effect/src/unstable/ai/Tool.ts

@@ -1129,6 +1129,9 @@ const dynamicProto = <
  * can call. The tool definition includes parameter validation, success/failure
  * schemas, and optional service dependencies.
  *
+ * If a tool accepts no parameters but still needs an explicit empty object
+ * schema, use {@link EmptyParams}.
+ *
  * @example
  * ```ts
  * import { Schema } from "effect"
@@ -1830,3 +1833,20 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
     Error.stackTraceLimit = stackTraceLimit
   }
 }
+
+/**
+ * @since 4.0.0
+ */
+export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
+
+/**
+ * A schema for tools that accept no parameters.
+ *
+ * @since 4.0.0
+ */
+export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
+
+/** @internal */
+export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
+  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+}

packages/effect/test/unstable/ai/AnthropicStructuredOutput.test.ts

@@ -2,6 +2,7 @@ import { assert, describe, it } from "@effect/vitest"
 import { type JsonSchema, Schema } from "effect"
 import { TestSchema } from "effect/testing"
 import { toCodecAnthropic } from "effect/unstable/ai/AnthropicStructuredOutput"
+import * as Tool from "effect/unstable/ai/Tool"
 
 function assertJsonSchema(schema: Schema.Top, expected: JsonSchema.JsonSchema) {
   assert.deepStrictEqual(toCodecAnthropic(schema).jsonSchema, expected)
@@ -464,6 +465,17 @@ describe("toCodecAnthropic", () => {
   })
 
   describe("Record", () => {
+    it("EmptyParams", async () => {
+      assertJsonSchema(Tool.EmptyParams, {
+        "type": "object",
+        "additionalProperties": false
+      })
+      assertJsonSchema(Schema.Record(Schema.String, Schema.Never), {
+        "type": "object",
+        "additionalProperties": false
+      })
+    })
+
     it("Record(String, Finite)", async () => {
       const schema = Schema.Record(Schema.String, Schema.Finite)
       assertJsonSchema(schema, {

packages/effect/test/unstable/ai/OpenAiStructuredOutput.test.ts

@@ -2,6 +2,7 @@ import { assert, describe, it } from "@effect/vitest"
 import { type JsonSchema, Schema } from "effect"
 import { TestSchema } from "effect/testing"
 import { toCodecOpenAI } from "effect/unstable/ai/OpenAiStructuredOutput"
+import * as Tool from "effect/unstable/ai/Tool"
 
 function assertJsonSchema(schema: Schema.Top, expected: JsonSchema.JsonSchema) {
   assert.deepStrictEqual(toCodecOpenAI(schema).jsonSchema, expected)
@@ -592,6 +593,17 @@ describe("toCodecOpenAI", () => {
   })
 
   describe("Record", () => {
+    it("EmptyParams", async () => {
+      assertJsonSchema(Tool.EmptyParams, {
+        "type": "object",
+        "additionalProperties": false
+      })
+      assertJsonSchema(Schema.Record(Schema.String, Schema.Never), {
+        "type": "object",
+        "additionalProperties": false
+      })
+    })
+
     it("Record(String, Finite)", async () => {
       const schema = Schema.Record(Schema.String, Schema.Finite)
       assertJsonSchema(schema, {