feat(client): add parse method (#226)

* feat(client): add parse method

* chore(internal): add prettier@2 as a dev dep

---------

Co-authored-by: Robert Craigie <robert@craigie.dev>

Author: stainless-app[bot]

jest.config.ts

@@ -17,6 +17,7 @@ const config: JestConfigWithTsJest = {
     '<rootDir>/deno_tests/',
   ],
   testPathIgnorePatterns: ['scripts'],
+  prettierPath: require.resolve('prettier-2'),
 };
 
 export default config;

package.json

@@ -45,6 +45,7 @@
     "tsconfig-paths": "^4.0.0",
     "typescript": "^4.8.2",
     "typescript-eslint": "^8.24.0",
+    "prettier-2": "npm:prettier@^2",
     "zod": "^3.23.8"
   },
   "resolutions": {
@@ -73,5 +74,13 @@
       "import": "./dist/*.mjs",
       "require": "./dist/*.js"
     }
+  },
+  "peerDependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   }
-}
+}

src/helpers/zod.ts

@@ -66,7 +66,8 @@ export function zodResponseFormat<ZodInput extends ZodType>(
       json_schema: {
         ...props,
         name,
-        // strict: true,
+        // @ts-ignore
+        strict: true,
         schema: zodToJsonSchema(zodObject, { name }),
       },
     },
@@ -96,7 +97,8 @@ export function zodFunction<Parameters extends ZodType>(options: {
       function: {
         name: options.name,
         parameters: zodToJsonSchema(options.parameters, { name: options.name }),
-        // strict: true,
+        // @ts-ignore
+        strict: true,
         ...(options.description ? { description: options.description } : undefined),
       },
     },

src/lib/parser.ts

@@ -13,10 +13,8 @@ type AnyChatChatParams =
   | ChatCompletionStreamingToolRunnerParams<any>
   | ChatCompletionStreamParams;
 
-// note: we currently use a placeholder, structured output isn't yet supported by the API
-// export type ExtractParsedContentFromParams<Params extends AnyChatChatParams> =
-// Params['response_format'] extends AutoParseableResponseFormat<infer P> ? P : null;
-export type ExtractParsedContentFromParams<_Params extends AnyChatChatParams> = null;
+export type ExtractParsedContentFromParams<Params extends AnyChatChatParams> =
+  Params['response_format'] extends AutoParseableResponseFormat<infer P> ? P : null;
 
 export type AutoParseableResponseFormat<ParsedT> = ResponseFormatJSONSchema & {
   __output: ParsedT; // type-level only
@@ -151,9 +149,22 @@ export function parseChatCompletion<
 }
 
 function parseResponseFormat<Params extends ChatChatParams, ParsedT = ExtractParsedContentFromParams<Params>>(
-  _params: Params,
-  _content: string,
+  params: Params,
+  content: string,
 ): ParsedT | null {
+  if ('response_format' in params && params.response_format?.type !== 'json_schema') {
+    return null;
+  }
+
+  if ('response_format' in params && params.response_format?.type === 'json_schema') {
+    if (isAutoParsableResponseFormat(params.response_format)) {
+      const response_format = params.response_format as AutoParseableResponseFormat<ParsedT>;
+      return response_format.$parseRaw(content);
+    }
+
+    return JSON.parse(content) as unknown as ParsedT;
+  }
+
   return null;
 }
 
@@ -169,7 +180,10 @@ function parseToolCall<Params extends ChatChatParams>(
     function: {
       ...toolCall.function,
       parsed_arguments:
-        isAutoParsableTool(inputTool) ? inputTool.$parseRaw(toolCall.function.arguments) : null,
+        isAutoParsableTool(inputTool) ? inputTool.$parseRaw(toolCall.function.arguments)
+        : inputTool?.function && 'strict' in inputTool.function && inputTool.function.strict === true ?
+          JSON.parse(toolCall.function.arguments)
+        : null,
     },
   };
 }
@@ -182,7 +196,11 @@ export function shouldParseToolCall(params: ChatChatParams | null | undefined, t
   const inputTool = params.tools?.find(
     (inputTool) => inputTool.type === 'function' && inputTool.function?.name === toolCall.function.name,
   );
-  return isAutoParsableTool(inputTool) || false;
+  return (
+    isAutoParsableTool(inputTool) ||
+    (inputTool?.function && 'strict' in inputTool.function && inputTool.function.strict === true) ||
+    false
+  );
 }
 
 export function hasAutoParseableInput(params: AnyChatChatParams): boolean {
@@ -206,5 +224,11 @@ export function validateInputTools(tools: ToolParam[] | undefined) {
         `Currently only \`function\` tool types support auto-parsing; Received \`${tool.type}\``,
       );
     }
+
+    if (!tool.function || !('strict' in tool.function) || tool.function.strict !== true) {
+      throw new WriterError(
+        `The \`${tool.function?.name}\` tool is not marked with \`strict: true\`. Only strict function tools can be auto-parsed`,
+      );
+    }
   }
 }

src/resources/chat.ts

@@ -7,8 +7,9 @@ import { APIPromise } from '../core/api-promise';
 import { Stream } from '../core/streaming';
 import { RequestOptions } from '../internal/request-options';
 import { ToolCall } from './shared';
+import { ResponseFormatJSONSchema } from './shared';
 import { ChatCompletionStream, ChatCompletionStreamParams } from '../lib/ChatCompletionStream';
-import { ExtractParsedContentFromParams } from '../lib/parser';
+import { validateInputTools, maybeParseChatCompletion, ExtractParsedContentFromParams } from '../lib/parser';
 
 export class Chat extends APIResource {
   /**
@@ -31,6 +32,57 @@ export class Chat extends APIResource {
       | APIPromise<Stream<ChatCompletionChunk>>;
   }
 
+  /**
+   * Create a completion and also parse the response
+   *
+   * This method automatically parses the response content into a structured format
+   * based on the provided response_format. It uses either:
+   *
+   * 1. A Zod schema provided with zodResponseFormat() to validate and parse the output
+   * 2. The raw JSON schema response if json_schema is specified directly
+   *
+   * For tools, it will parse function arguments into structured objects if the tools
+   * are created using zodFunction().
+   *
+   * ```ts
+   * const completion = await client.chat.parse({
+   *    model: 'palmyra-x-004',
+   *    messages: [
+   *      { role: 'system', content: 'You are a helpful math tutor.' },
+   *      { role: 'user', content: 'solve 8x + 31 = 2' },
+   *    ],
+   *    response_format: zodResponseFormat(
+   *      z.object({
+   *        steps: z.array(z.object({
+   *          explanation: z.string(),
+   *          answer: z.string(),
+   *        })),
+   *        final_answer: z.string(),
+   *      }),
+   *      'math_answer',
+   *    ),
+   *  });
+   *
+   * const message = completion.choices[0]?.message;
+   * if (message?.parsed) {
+   *   console.log(message.parsed);
+   *   console.log(message.parsed.final_answer);
+   * }
+   * ```
+   */
+  parse<Params extends ChatCompletionParseParams, ParsedT = ExtractParsedContentFromParams<Params>>(
+    body: Params,
+    options?: RequestOptions,
+  ): APIPromise<ParsedChatCompletion<ParsedT>> {
+    if (body.tools) {
+      validateInputTools(body.tools);
+    }
+
+    return this.chat(body, options)._thenUnwrap((completion) =>
+      maybeParseChatCompletion(completion, body),
+    ) as APIPromise<ParsedChatCompletion<ParsedT>>;
+  }
+
   /**
    * Creates a chat completion stream
    */
@@ -644,7 +696,9 @@ export interface ParsedChatCompletion<ParsedT> extends ChatCompletion {
   choices: Array<ParsedChoice<ParsedT>>;
 }
 
-export type ChatCompletionParseParams = ChatChatParamsNonStreaming;
+export interface ChatCompletionParseParams extends ChatChatParamsNonStreaming {
+  response_format?: ResponseFormatJSONSchema;
+}
 
 export declare namespace Chat {
   export {

tests/lib/ChatCompletionStream.test.ts

@@ -33,7 +33,10 @@ describe('.stream()', () => {
         "logprobs": null,
         "message": {
           "content": "{"city":"San Francisco","units":"c"}",
-          "parsed": null,
+          "parsed": {
+            "city": "San Francisco",
+            "units": "c",
+          },
           "refusal": null,
           "role": "assistant",
           "tool_calls": [],
@@ -189,7 +192,10 @@ describe('.stream()', () => {
         },
         "message": {
           "content": "{"city":"San Francisco","units":"f"}",
-          "parsed": null,
+          "parsed": {
+            "city": "San Francisco",
+            "units": "f",
+          },
           "refusal": null,
           "role": "assistant",
           "tool_calls": [],

yarn.lock

@@ -2854,6 +2854,11 @@ prelude-ls@^1.2.1:
   resolved "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz"
   integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==
 
+"prettier-2@npm:prettier@^2":
+  version "2.8.8"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.8.8.tgz#e8c5d7e98a4305ffe3de2e1fc4aca1a71c28b1da"
+  integrity sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==
+
 prettier-linter-helpers@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/prettier-linter-helpers/-/prettier-linter-helpers-1.0.0.tgz"