packages/core/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai
 
+## 3.0.15
+
+### Patch Changes
+
+- 4aed2a5: Add JSDoc comments for ai/core functions.
+- cf8d12f: Export experimental language model specification under `ai/spec`.
+
 ## 3.0.14
 
 ### Patch Changes

packages/core/core/generate-object/generate-object.ts

@@ -6,7 +6,7 @@ import {
   LanguageModelV1FinishReason,
   NoTextGeneratedError,
   safeParseJSON,
-} from '../../ai-model-specification';
+} from '../../spec';
 import { TokenUsage, calculateTokenUsage } from '../generate-text/token-usage';
 import { CallSettings } from '../prompt/call-settings';
 import { convertToLanguageModelPrompt } from '../prompt/convert-to-language-model-prompt';
@@ -17,7 +17,40 @@ import { retryWithExponentialBackoff } from '../util/retry-with-exponential-back
 import { injectJsonSchemaIntoSystem } from './inject-json-schema-into-system';
 
 /**
- * Generate a structured, typed object using a language model.
+Generate a structured, typed object for a given prompt and schema using a language model.
+
+This function does not stream the output. If you want to stream the output, use `experimental_streamObject` instead.
+
+@param model - The language model to use.
+@param schema - The schema of the object that the model should generate.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting. 
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - Presence penalty setting. 
+It affects the likelihood of the model to repeat information that is already in the prompt.
+The presence penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition). 
+0 means no penalty.
+@param frequencyPenalty - Frequency penalty setting.
+It affects the likelihood of the model to repeatedly use the same words or phrases.
+The frequency penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+0 means no penalty.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@returns 
+A result object that contains the generated object, the finish reason, the token usage, and additional information.
  */
 export async function experimental_generateObject<T>({
   model,
@@ -31,8 +64,21 @@ export async function experimental_generateObject<T>({
   ...settings
 }: CallSettings &
   Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+
+    /**
+The schema of the object that the model should generate.
+     */
     schema: z.Schema<T>;
+
+    /**
+The mode to use for object generation. Not all models support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+     */
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
   }): Promise<GenerateObjectResult<T>> {
   const retry = retryWithExponentialBackoff({ maxRetries });
@@ -160,10 +206,28 @@ export async function experimental_generateObject<T>({
   });
 }
 
+/**
+The result of a `generateObject` call.
+ */
 export class GenerateObjectResult<T> {
+  /**
+The generated object (typed according to the schema).
+   */
   readonly object: T;
+
+  /**
+The reason why the generation finished.
+   */
   readonly finishReason: LanguageModelV1FinishReason;
+
+  /**
+The token usage of the generated text.
+   */
   readonly usage: TokenUsage;
+
+  /**
+Warnings from the model provider (e.g. unsupported settings)
+   */
   readonly warnings: LanguageModelV1CallWarning[] | undefined;
 
   constructor(options: {

packages/core/core/generate-object/stream-object.ts

@@ -5,7 +5,7 @@ import {
   LanguageModelV1CallOptions,
   LanguageModelV1CallWarning,
   LanguageModelV1StreamPart,
-} from '../../ai-model-specification';
+} from '../../spec';
 import { CallSettings } from '../prompt/call-settings';
 import { convertToLanguageModelPrompt } from '../prompt/convert-to-language-model-prompt';
 import { getInputFormat } from '../prompt/get-input-format';
@@ -22,7 +22,40 @@ import { retryWithExponentialBackoff } from '../util/retry-with-exponential-back
 import { injectJsonSchemaIntoSystem } from './inject-json-schema-into-system';
 
 /**
- * Stream an object as a partial object stream.
+Generate a structured, typed object for a given prompt and schema using a language model.
+
+This function streams the output. If you do not want to stream the output, use `experimental_generateObject` instead.
+
+@param model - The language model to use.
+@param schema - The schema of the object that the model should generate.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting. 
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - Presence penalty setting. 
+It affects the likelihood of the model to repeat information that is already in the prompt.
+The presence penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition). 
+0 means no penalty.
+@param frequencyPenalty - Frequency penalty setting.
+It affects the likelihood of the model to repeatedly use the same words or phrases.
+The frequency penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+0 means no penalty.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@return
+A result object for accessing the partial object stream and additional information.
  */
 export async function experimental_streamObject<T>({
   model,
@@ -36,8 +69,21 @@ export async function experimental_streamObject<T>({
   ...settings
 }: CallSettings &
   Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+
+    /**
+The schema of the object that the model should generate.
+ */
     schema: z.Schema<T>;
+
+    /**
+The mode to use for object generation. Not all models support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+ */
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
   }): Promise<StreamObjectResult<T>> {
   const retry = retryWithExponentialBackoff({ maxRetries });
@@ -161,9 +207,15 @@ export async function experimental_streamObject<T>({
   });
 }
 
+/**
+The result of a `streamObject` call that contains the partial object stream and additional information.
+ */
 export class StreamObjectResult<T> {
   private readonly originalStream: ReadableStream<string | ErrorStreamPart>;
 
+  /**
+Warnings from the model provider (e.g. unsupported settings)
+   */
   readonly warnings: LanguageModelV1CallWarning[] | undefined;
 
   constructor({

packages/core/core/generate-text/generate-text.ts

@@ -3,7 +3,7 @@ import {
   LanguageModelV1,
   LanguageModelV1CallWarning,
   LanguageModelV1FinishReason,
-} from '../../ai-model-specification';
+} from '../../spec';
 import { CallSettings } from '../prompt/call-settings';
 import { convertToLanguageModelPrompt } from '../prompt/convert-to-language-model-prompt';
 import { getInputFormat } from '../prompt/get-input-format';
@@ -16,7 +16,40 @@ import { ToToolCallArray, parseToolCall } from './tool-call';
 import { ToToolResultArray } from './tool-result';
 
 /**
- * Generate a text and call tools using a language model.
+Generate a text and call tools for a given prompt using a language model.
+
+This function does not stream the output. If you want to stream the output, use `experimental_streamText` instead.
+
+@param model - The language model to use.
+@param tools - The tools that the model can call. The model needs to support calling tools.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting. 
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - Presence penalty setting. 
+It affects the likelihood of the model to repeat information that is already in the prompt.
+The presence penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition). 
+0 means no penalty.
+@param frequencyPenalty - Frequency penalty setting.
+It affects the likelihood of the model to repeatedly use the same words or phrases.
+The frequency penalty is a number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).
+0 means no penalty.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@returns
+A result object that contains the generated text, the results of the tool calls, and additional information.
  */
 export async function experimental_generateText<
   TOOLS extends Record<string, ExperimentalTool>,
@@ -31,7 +64,14 @@ export async function experimental_generateText<
   ...settings
 }: CallSettings &
   Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+
+    /**
+The tools that the model can call. The model needs to support calling tools.
+*/
     tools?: TOOLS;
   }): Promise<GenerateTextResult<TOOLS>> {
   const retry = retryWithExponentialBackoff({ maxRetries });
@@ -114,14 +154,41 @@ async function executeTools<TOOLS extends Record<string, ExperimentalTool>>({
   );
 }
 
+/**
+The result of a `generateText` call.
+It contains the generated text, the tool calls that were made during the generation, and the results of the tool calls.
+ */
 export class GenerateTextResult<
   TOOLS extends Record<string, ExperimentalTool>,
 > {
+  /**
+The generated text.
+   */
   readonly text: string;
+
+  /**
+The tool calls that were made during the generation.
+   */
   readonly toolCalls: ToToolCallArray<TOOLS>;
+
+  /**
+The results of the tool calls.
+   */
   readonly toolResults: ToToolResultArray<TOOLS>;
+
+  /**
+The reason why the generation finished.
+   */
   readonly finishReason: LanguageModelV1FinishReason;
+
+  /**
+The token usage of the generated text.
+   */
   readonly usage: TokenUsage;
+
+  /**
+Warnings from the model provider (e.g. unsupported settings)
+   */
   readonly warnings: LanguageModelV1CallWarning[] | undefined;
 
   constructor(options: {

packages/core/core/generate-text/run-tools-transformation.ts

@@ -1,7 +1,4 @@
-import {
-  LanguageModelV1StreamPart,
-  NoSuchToolError,
-} from '../../ai-model-specification';
+import { LanguageModelV1StreamPart, NoSuchToolError } from '../../spec';
 import { generateId } from '../../shared/generate-id';
 import { ExperimentalTool } from '../tool';
 import { TextStreamPart } from './stream-text';