diff --git a/sdk/js/README.md b/sdk/js/README.md index cac564dc..3308c9d8 100644 --- a/sdk/js/README.md +++ b/sdk/js/README.md @@ -129,7 +129,7 @@ You can also select a specific variant manually: ```typescript const variants = model.variants; -model.selectVariant(variants[0].id); +model.selectVariant(variants[0]); ``` ### Chat Completions diff --git a/sdk/js/docs/README.md b/sdk/js/docs/README.md index b15c29a4..e79be84d 100644 --- a/sdk/js/docs/README.md +++ b/sdk/js/docs/README.md @@ -24,9 +24,135 @@ - [Model](classes/Model.md) - [ModelLoadManager](classes/ModelLoadManager.md) - [ModelVariant](classes/ModelVariant.md) +- [ResponsesClient](classes/ResponsesClient.md) +- [ResponsesClientSettings](classes/ResponsesClientSettings.md) ## Interfaces +### Annotation + +#### Extended by + +- [`UrlCitationAnnotation`](#urlcitationannotation) + +#### Properties + +##### end\_index + +```ts +end_index: number; +``` + +##### start\_index + +```ts +start_index: number; +``` + +##### type + +```ts +type: string; +``` + +*** + +### ContentPartAddedEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### part + +```ts +part: ContentPart; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.content_part.added"; +``` + +*** + +### ContentPartDoneEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### part + +```ts +part: ContentPart; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.content_part.done"; +``` + +*** + +### DeleteResponseResult + +#### Properties + +##### deleted + +```ts +deleted: boolean; +``` + +##### id + +```ts +id: string; +``` + +##### object + +```ts +object: string; +``` + +*** + ### FoundryLocalConfig Configuration options for the Foundry Local SDK. @@ -128,6 +254,198 @@ Example: "http://127.0.0.1:8080" *** +### FunctionCallArgsDeltaEvent + +#### Properties + +##### delta + +```ts +delta: string; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.function_call_arguments.delta"; +``` + +*** + +### FunctionCallArgsDoneEvent + +#### Properties + +##### arguments + +```ts +arguments: string; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### name + +```ts +name: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.function_call_arguments.done"; +``` + +*** + +### FunctionCallItem + +#### Properties + +##### arguments + +```ts +arguments: string; +``` + +##### call\_id + +```ts +call_id: string; +``` + +##### id? + +```ts +optional id: string; +``` + +##### name + +```ts +name: string; +``` + +##### status? + +```ts +optional status: ResponseItemStatus; +``` + +##### type + +```ts +type: "function_call"; +``` + +*** + +### FunctionCallOutputItem + +#### Properties + +##### call\_id + +```ts +call_id: string; +``` + +##### id? + +```ts +optional id: string; +``` + +##### output + +```ts +output: string | ContentPart[]; +``` + +##### status? + +```ts +optional status: ResponseItemStatus; +``` + +##### type + +```ts +type: "function_call_output"; +``` + +*** + +### FunctionToolDefinition + +#### Properties + +##### description? + +```ts +optional description: string; +``` + +##### name + +```ts +name: string; +``` + +##### parameters? + +```ts +optional parameters: Record; +``` + +##### strict? + +```ts +optional strict: boolean; +``` + +##### type + +```ts +type: "function"; +``` + +*** + ### IModel #### Accessors @@ -202,6 +520,26 @@ createChatClient(): ChatClient; [`ChatClient`](classes/ChatClient.md) +##### createResponsesClient() + +```ts +createResponsesClient(baseUrl): ResponsesClient; +``` + +Creates a ResponsesClient for interacting with the model via the Responses API. +Unlike createChatClient/createAudioClient (which use FFI), the Responses API +is HTTP-based, so the web service base URL must be provided. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `baseUrl` | `string` | The base URL of the Foundry Local web service. | + +###### Returns + +[`ResponsesClient`](classes/ResponsesClient.md) + ##### download() ```ts @@ -260,37 +598,163 @@ unload(): Promise; *** -### ModelInfo +### IncompleteDetails #### Properties -##### alias +##### reason ```ts -alias: string; +reason: string; ``` -##### cached +*** -```ts -cached: boolean; -``` +### InputItemsListResponse -##### createdAtUnix +#### Properties + +##### data ```ts -createdAtUnix: number; +data: ResponseInputItem[]; ``` -##### displayName? +##### object ```ts -optional displayName: string | null; +object: "list"; ``` -##### fileSizeMb? +*** -```ts +### InputTextContent + +#### Properties + +##### text + +```ts +text: string; +``` + +##### type + +```ts +type: "input_text"; +``` + +*** + +### ItemReference + +#### Properties + +##### id + +```ts +id: string; +``` + +##### type + +```ts +type: "item_reference"; +``` + +*** + +### LogProb + +#### Properties + +##### bytes? + +```ts +optional bytes: number[]; +``` + +##### logprob + +```ts +logprob: number; +``` + +##### token + +```ts +token: string; +``` + +*** + +### MessageItem + +#### Properties + +##### content + +```ts +content: string | ContentPart[]; +``` + +##### id? + +```ts +optional id: string; +``` + +##### role + +```ts +role: MessageRole; +``` + +##### status? + +```ts +optional status: ResponseItemStatus; +``` + +##### type + +```ts +type: "message"; +``` + +*** + +### ModelInfo + +#### Properties + +##### alias + +```ts +alias: string; +``` + +##### cached + +```ts +cached: boolean; +``` + +##### createdAtUnix + +```ts +createdAtUnix: number; +``` + +##### displayName? + +```ts +optional displayName: string | null; +``` + +##### fileSizeMb? + +```ts optional fileSizeMb: number | null; ``` @@ -404,6 +868,192 @@ optional parameters: Parameter[] | null; *** +### OutputItemAddedEvent + +#### Properties + +##### item + +```ts +item: ResponseOutputItem; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.output_item.added"; +``` + +*** + +### OutputItemDoneEvent + +#### Properties + +##### item + +```ts +item: ResponseOutputItem; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.output_item.done"; +``` + +*** + +### OutputTextContent + +#### Properties + +##### annotations? + +```ts +optional annotations: Annotation[]; +``` + +##### logprobs? + +```ts +optional logprobs: LogProb[]; +``` + +##### text + +```ts +text: string; +``` + +##### type + +```ts +type: "output_text"; +``` + +*** + +### OutputTextDeltaEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### delta + +```ts +delta: string; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.output_text.delta"; +``` + +*** + +### OutputTextDoneEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### output\_index + +```ts +output_index: number; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### text + +```ts +text: string; +``` + +##### type + +```ts +type: "response.output_text.done"; +``` + +*** + ### Parameter #### Properties @@ -452,18 +1102,918 @@ optional user: string | null; *** -### Runtime +### ReasoningConfig #### Properties -##### deviceType +##### effort? ```ts -deviceType: DeviceType; +optional effort: string; ``` -##### executionProvider +##### summary? ```ts -executionProvider: string; +optional summary: string; +``` + +*** + +### ReasoningItem + +#### Properties + +##### content? + +```ts +optional content: ContentPart[]; +``` + +##### encrypted\_content? + +```ts +optional encrypted_content: string; +``` + +##### id? + +```ts +optional id: string; +``` + +##### status? + +```ts +optional status: ResponseItemStatus; ``` + +##### summary? + +```ts +optional summary: string; +``` + +##### type + +```ts +type: "reasoning"; +``` + +*** + +### RefusalContent + +#### Properties + +##### refusal + +```ts +refusal: string; +``` + +##### type + +```ts +type: "refusal"; +``` + +*** + +### RefusalDeltaEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### delta + +```ts +delta: string; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.refusal.delta"; +``` + +*** + +### RefusalDoneEvent + +#### Properties + +##### content\_index + +```ts +content_index: number; +``` + +##### item\_id + +```ts +item_id: string; +``` + +##### refusal + +```ts +refusal: string; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "response.refusal.done"; +``` + +*** + +### ResponseCreateParams + +#### Properties + +##### frequency\_penalty? + +```ts +optional frequency_penalty: number; +``` + +##### input? + +```ts +optional input: string | ResponseInputItem[]; +``` + +##### instructions? + +```ts +optional instructions: string; +``` + +##### max\_output\_tokens? + +```ts +optional max_output_tokens: number; +``` + +##### metadata? + +```ts +optional metadata: Record; +``` + +##### model? + +```ts +optional model: string; +``` + +##### parallel\_tool\_calls? + +```ts +optional parallel_tool_calls: boolean; +``` + +##### presence\_penalty? + +```ts +optional presence_penalty: number; +``` + +##### previous\_response\_id? + +```ts +optional previous_response_id: string; +``` + +##### reasoning? + +```ts +optional reasoning: ReasoningConfig; +``` + +##### seed? + +```ts +optional seed: number; +``` + +##### store? + +```ts +optional store: boolean; +``` + +##### stream? + +```ts +optional stream: boolean; +``` + +##### temperature? + +```ts +optional temperature: number; +``` + +##### text? + +```ts +optional text: TextConfig; +``` + +##### tool\_choice? + +```ts +optional tool_choice: ResponseToolChoice; +``` + +##### tools? + +```ts +optional tools: FunctionToolDefinition[]; +``` + +##### top\_p? + +```ts +optional top_p: number; +``` + +##### truncation? + +```ts +optional truncation: TruncationStrategy; +``` + +##### user? + +```ts +optional user: string; +``` + +*** + +### ResponseError + +#### Properties + +##### code + +```ts +code: string; +``` + +##### message + +```ts +message: string; +``` + +*** + +### ResponseFormat + +#### Properties + +##### jsonSchema? + +```ts +optional jsonSchema: string; +``` + +##### larkGrammar? + +```ts +optional larkGrammar: string; +``` + +##### type + +```ts +type: string; +``` + +*** + +### ResponseLifecycleEvent + +#### Properties + +##### response + +```ts +response: ResponseObject; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: + | "response.created" + | "response.queued" + | "response.in_progress" + | "response.completed" + | "response.failed" + | "response.incomplete"; +``` + +*** + +### ResponseObject + +#### Properties + +##### cancelled\_at? + +```ts +optional cancelled_at: number | null; +``` + +##### completed\_at? + +```ts +optional completed_at: number | null; +``` + +##### created\_at + +```ts +created_at: number; +``` + +##### error? + +```ts +optional error: ResponseError | null; +``` + +##### failed\_at? + +```ts +optional failed_at: number | null; +``` + +##### frequency\_penalty + +```ts +frequency_penalty: number; +``` + +##### id + +```ts +id: string; +``` + +##### incomplete\_details? + +```ts +optional incomplete_details: IncompleteDetails | null; +``` + +##### instructions? + +```ts +optional instructions: string | null; +``` + +##### max\_output\_tokens? + +```ts +optional max_output_tokens: number | null; +``` + +##### metadata? + +```ts +optional metadata: Record | null; +``` + +##### model + +```ts +model: string; +``` + +##### object + +```ts +object: "response"; +``` + +##### output + +```ts +output: ResponseOutputItem[]; +``` + +##### parallel\_tool\_calls + +```ts +parallel_tool_calls: boolean; +``` + +##### presence\_penalty + +```ts +presence_penalty: number; +``` + +##### previous\_response\_id? + +```ts +optional previous_response_id: string | null; +``` + +##### reasoning? + +```ts +optional reasoning: ReasoningConfig | null; +``` + +##### status + +```ts +status: ResponseStatus; +``` + +##### store + +```ts +store: boolean; +``` + +##### temperature + +```ts +temperature: number; +``` + +##### text + +```ts +text: TextConfig; +``` + +##### tool\_choice + +```ts +tool_choice: ResponseToolChoice; +``` + +##### tools + +```ts +tools: FunctionToolDefinition[]; +``` + +##### top\_p + +```ts +top_p: number; +``` + +##### truncation + +```ts +truncation: TruncationStrategy; +``` + +##### usage? + +```ts +optional usage: ResponseUsage | null; +``` + +##### user? + +```ts +optional user: string | null; +``` + +*** + +### ResponseToolChoiceFunction + +#### Properties + +##### name + +```ts +name: string; +``` + +##### type + +```ts +type: "function"; +``` + +*** + +### ResponseUsage + +#### Properties + +##### input\_tokens + +```ts +input_tokens: number; +``` + +##### input\_tokens\_details? + +```ts +optional input_tokens_details: { + cached_tokens: number; +}; +``` + +###### cached\_tokens + +```ts +cached_tokens: number; +``` + +##### output\_tokens + +```ts +output_tokens: number; +``` + +##### output\_tokens\_details? + +```ts +optional output_tokens_details: { + reasoning_tokens: number; +}; +``` + +###### reasoning\_tokens + +```ts +reasoning_tokens: number; +``` + +##### total\_tokens + +```ts +total_tokens: number; +``` + +*** + +### Runtime + +#### Properties + +##### deviceType + +```ts +deviceType: DeviceType; +``` + +##### executionProvider + +```ts +executionProvider: string; +``` + +*** + +### StreamingErrorEvent + +#### Properties + +##### code? + +```ts +optional code: string; +``` + +##### message? + +```ts +optional message: string; +``` + +##### param? + +```ts +optional param: string; +``` + +##### sequence\_number + +```ts +sequence_number: number; +``` + +##### type + +```ts +type: "error"; +``` + +*** + +### TextConfig + +#### Properties + +##### format? + +```ts +optional format: TextFormat; +``` + +##### verbosity? + +```ts +optional verbosity: string; +``` + +*** + +### TextFormat + +#### Properties + +##### description? + +```ts +optional description: string; +``` + +##### name? + +```ts +optional name: string; +``` + +##### schema? + +```ts +optional schema: unknown; +``` + +##### strict? + +```ts +optional strict: boolean; +``` + +##### type + +```ts +type: string; +``` + +*** + +### ToolChoice + +#### Properties + +##### name? + +```ts +optional name: string; +``` + +##### type + +```ts +type: string; +``` + +*** + +### UrlCitationAnnotation + +#### Extends + +- [`Annotation`](#annotation) + +#### Properties + +##### end\_index + +```ts +end_index: number; +``` + +###### Inherited from + +[`Annotation`](#annotation).[`end_index`](#end_index) + +##### start\_index + +```ts +start_index: number; +``` + +###### Inherited from + +[`Annotation`](#annotation).[`start_index`](#start_index) + +##### title + +```ts +title: string; +``` + +##### type + +```ts +type: "url_citation"; +``` + +###### Overrides + +[`Annotation`](#annotation).[`type`](#type) + +##### url + +```ts +url: string; +``` + +## Type Aliases + +### ContentPart + +```ts +type ContentPart = + | InputTextContent + | OutputTextContent + | RefusalContent; +``` + +*** + +### MessageRole + +```ts +type MessageRole = "system" | "user" | "assistant" | "developer"; +``` + +Role of a message in the Responses API. + +*** + +### ResponseInputItem + +```ts +type ResponseInputItem = + | MessageItem + | FunctionCallItem + | FunctionCallOutputItem + | ItemReference + | ReasoningItem; +``` + +*** + +### ResponseItemStatus + +```ts +type ResponseItemStatus = "in_progress" | "completed" | "incomplete"; +``` + +Status of an individual response item. + +*** + +### ResponseOutputItem + +```ts +type ResponseOutputItem = + | MessageItem + | FunctionCallItem + | ReasoningItem; +``` + +*** + +### ResponseStatus + +```ts +type ResponseStatus = + | "queued" + | "in_progress" + | "completed" + | "failed" + | "incomplete" + | "cancelled"; +``` + +Status of a Response object. + +*** + +### ResponseToolChoice + +```ts +type ResponseToolChoice = + | "none" + | "auto" + | "required" + | ResponseToolChoiceFunction; +``` + +Controls which tool the model should use. + +*** + +### ServiceTier + +```ts +type ServiceTier = "default" | "auto" | "flex" | "priority"; +``` + +Service tier. + +*** + +### StreamingEvent + +```ts +type StreamingEvent = + | ResponseLifecycleEvent + | OutputItemAddedEvent + | OutputItemDoneEvent + | ContentPartAddedEvent + | ContentPartDoneEvent + | OutputTextDeltaEvent + | OutputTextDoneEvent + | RefusalDeltaEvent + | RefusalDoneEvent + | FunctionCallArgsDeltaEvent + | FunctionCallArgsDoneEvent + | StreamingErrorEvent; +``` + +*** + +### TruncationStrategy + +```ts +type TruncationStrategy = "auto" | "disabled"; +``` + +Truncation strategy. + +## Functions + +### getOutputText() + +```ts +function getOutputText(response): string; +``` + +Extracts the text content from an assistant message in a Response. +Equivalent to OpenAI Python SDK's `response.output_text`. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `response` | [`ResponseObject`](#responseobject) | The Response object. | + +#### Returns + +`string` + +The concatenated text from the first assistant message, or an empty string. diff --git a/sdk/js/docs/classes/ChatClient.md b/sdk/js/docs/classes/ChatClient.md index 70ce80c4..91e877aa 100644 --- a/sdk/js/docs/classes/ChatClient.md +++ b/sdk/js/docs/classes/ChatClient.md @@ -19,51 +19,109 @@ Configuration settings for chat completions. ### completeChat() +#### Call Signature + ```ts completeChat(messages): Promise; ``` Performs a synchronous chat completion. -#### Parameters +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `messages` | `any`[] | An array of message objects (e.g., { role: 'user', content: 'Hello' }). | + +##### Returns + +`Promise`\<`any`\> + +The chat completion response object. + +##### Throws + +Error - If messages or tools are invalid or completion fails. + +#### Call Signature + +```ts +completeChat(messages, tools): Promise; +``` + +Performs a synchronous chat completion. + +##### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | | `messages` | `any`[] | An array of message objects (e.g., { role: 'user', content: 'Hello' }). | +| `tools` | `any`[] | An array of tool objects (e.g. { type: 'function', function: { name: 'get_apps', description: 'Returns a list of apps available on the system' } }). | -#### Returns +##### Returns `Promise`\<`any`\> The chat completion response object. -#### Throws +##### Throws -Error - If messages are invalid or completion fails. +Error - If messages or tools are invalid or completion fails. *** ### completeStreamingChat() +#### Call Signature + ```ts completeStreamingChat(messages, callback): Promise; ``` Performs a streaming chat completion. -#### Parameters +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `messages` | `any`[] | An array of message objects. | +| `callback` | (`chunk`) => `void` | A callback function that receives each chunk of the streaming response. | + +##### Returns + +`Promise`\<`void`\> + +A promise that resolves when the stream is complete. + +##### Throws + +Error - If messages, tools, or callback are invalid, or streaming fails. + +#### Call Signature + +```ts +completeStreamingChat( + messages, + tools, +callback): Promise; +``` + +Performs a streaming chat completion. + +##### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | | `messages` | `any`[] | An array of message objects. | +| `tools` | `any`[] | An array of tool objects. | | `callback` | (`chunk`) => `void` | A callback function that receives each chunk of the streaming response. | -#### Returns +##### Returns `Promise`\<`void`\> A promise that resolves when the stream is complete. -#### Throws +##### Throws -Error - If messages or callback are invalid, or streaming fails. +Error - If messages, tools, or callback are invalid, or streaming fails. diff --git a/sdk/js/docs/classes/ChatClientSettings.md b/sdk/js/docs/classes/ChatClientSettings.md index 0136bcb9..7fed8a46 100644 --- a/sdk/js/docs/classes/ChatClientSettings.md +++ b/sdk/js/docs/classes/ChatClientSettings.md @@ -56,6 +56,14 @@ optional randomSeed: number; *** +### responseFormat? + +```ts +optional responseFormat: ResponseFormat; +``` + +*** + ### temperature? ```ts @@ -64,6 +72,14 @@ optional temperature: number; *** +### toolChoice? + +```ts +optional toolChoice: ToolChoice; +``` + +*** + ### topK? ```ts diff --git a/sdk/js/docs/classes/FoundryLocalManager.md b/sdk/js/docs/classes/FoundryLocalManager.md index c0f1aa30..fb9a4783 100644 --- a/sdk/js/docs/classes/FoundryLocalManager.md +++ b/sdk/js/docs/classes/FoundryLocalManager.md @@ -25,6 +25,22 @@ The Catalog instance. *** +### isWebServiceRunning + +#### Get Signature + +```ts +get isWebServiceRunning(): boolean; +``` + +Whether the web service is currently running. + +##### Returns + +`boolean` + +*** + ### urls #### Get Signature @@ -44,6 +60,33 @@ An array of URLs. ## Methods +### createResponsesClient() + +```ts +createResponsesClient(modelId?): ResponsesClient; +``` + +Creates a ResponsesClient for interacting with the Responses API. +The web service must be started first via `startWebService()`. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `modelId?` | `string` | Optional default model ID for requests. | + +#### Returns + +[`ResponsesClient`](ResponsesClient.md) + +A ResponsesClient instance. + +#### Throws + +Error - If the web service is not running. + +*** + ### startWebService() ```ts diff --git a/sdk/js/docs/classes/Model.md b/sdk/js/docs/classes/Model.md index c09c4f6c..48340dae 100644 --- a/sdk/js/docs/classes/Model.md +++ b/sdk/js/docs/classes/Model.md @@ -69,7 +69,7 @@ The ID of the selected variant. #### Implementation of -[`IModel`](../README.md#imodel).[`id`](../README.md#id) +[`IModel`](../README.md#imodel).[`id`](../README.md#id-3) *** @@ -200,6 +200,32 @@ A ChatClient instance. *** +### createResponsesClient() + +```ts +createResponsesClient(baseUrl): ResponsesClient; +``` + +Creates a ResponsesClient for interacting with the model via the Responses API. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `baseUrl` | `string` | The base URL of the Foundry Local web service. | + +#### Returns + +[`ResponsesClient`](ResponsesClient.md) + +A ResponsesClient instance. + +#### Implementation of + +[`IModel`](../README.md#imodel).[`createResponsesClient`](../README.md#createresponsesclient) + +*** + ### download() ```ts @@ -285,16 +311,16 @@ Removes the currently selected variant from the local cache. ### selectVariant() ```ts -selectVariant(modelId): void; +selectVariant(variant): void; ``` -Selects a specific variant by its ID. +Selects a specific variant. #### Parameters | Parameter | Type | Description | | ------ | ------ | ------ | -| `modelId` | `string` | The ID of the variant to select. | +| `variant` | [`ModelVariant`](ModelVariant.md) | The model variant to select. | #### Returns @@ -302,7 +328,7 @@ Selects a specific variant by its ID. #### Throws -Error - If the variant with the specified ID is not found. +Error - If the argument is not a ModelVariant object, or if the variant does not belong to this model. *** diff --git a/sdk/js/docs/classes/ModelVariant.md b/sdk/js/docs/classes/ModelVariant.md index d320dd3f..837ead70 100644 --- a/sdk/js/docs/classes/ModelVariant.md +++ b/sdk/js/docs/classes/ModelVariant.md @@ -74,7 +74,7 @@ The model ID. #### Implementation of -[`IModel`](../README.md#imodel).[`id`](../README.md#id) +[`IModel`](../README.md#imodel).[`id`](../README.md#id-3) *** @@ -180,6 +180,32 @@ A ChatClient instance. *** +### createResponsesClient() + +```ts +createResponsesClient(baseUrl): ResponsesClient; +``` + +Creates a ResponsesClient for interacting with the model via the Responses API. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `baseUrl` | `string` | The base URL of the Foundry Local web service. | + +#### Returns + +[`ResponsesClient`](ResponsesClient.md) + +A ResponsesClient instance. + +#### Implementation of + +[`IModel`](../README.md#imodel).[`createResponsesClient`](../README.md#createresponsesclient) + +*** + ### download() ```ts diff --git a/sdk/js/docs/classes/ResponsesClient.md b/sdk/js/docs/classes/ResponsesClient.md new file mode 100644 index 00000000..5ee70c81 --- /dev/null +++ b/sdk/js/docs/classes/ResponsesClient.md @@ -0,0 +1,197 @@ +[@prathikrao/foundry-local-sdk](../README.md) / ResponsesClient + +# Class: ResponsesClient + +Client for the OpenAI Responses API served by Foundry Local's embedded web service. + +Unlike ChatClient/AudioClient (which use FFI via CoreInterop), the Responses API +is HTTP-only. This client uses fetch() for all operations and parses Server-Sent Events +for streaming. + +Create via `FoundryLocalManager.createResponsesClient()` or +`model.createResponsesClient(baseUrl)`. + +## Example + +```typescript +const manager = FoundryLocalManager.create({ appName: 'MyApp' }); +manager.startWebService(); +const client = manager.createResponsesClient('my-model-id'); + +// Non-streaming +const response = await client.create('Hello, world!'); +console.log(response.output); + +// Streaming +await client.createStreaming('Tell me a story', (event) => { + if (event.type === 'response.output_text.delta') { + process.stdout.write(event.delta); + } +}); +``` + +## Constructors + +### Constructor + +```ts +new ResponsesClient(baseUrl, modelId?): ResponsesClient; +``` + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `baseUrl` | `string` | The base URL of the Foundry Local web service (e.g. "http://127.0.0.1:5273"). | +| `modelId?` | `string` | Optional default model ID. Can be overridden per-request via options. | + +#### Returns + +`ResponsesClient` + +## Properties + +### settings + +```ts +settings: ResponsesClientSettings; +``` + +Configuration settings for responses. + +## Methods + +### cancel() + +```ts +cancel(responseId): Promise; +``` + +Cancels an in-progress response. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `responseId` | `string` | The ID of the response to cancel. | + +#### Returns + +`Promise`\<[`ResponseObject`](../README.md#responseobject)\> + +The cancelled Response object. + +*** + +### create() + +```ts +create(input, options?): Promise; +``` + +Creates a model response (non-streaming). + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `input` | `string` \| [`ResponseInputItem`](../README.md#responseinputitem)[] | A string prompt or array of input items. | +| `options?` | `Partial`\<[`ResponseCreateParams`](../README.md#responsecreateparams)\> | Additional request parameters that override client settings. The `model` field is optional here if a default model was set in the constructor. | + +#### Returns + +`Promise`\<[`ResponseObject`](../README.md#responseobject)\> + +The completed Response object. Check `response.status` and `response.error` + even on success — the server returns HTTP 200 for model-level failures too. + +*** + +### createStreaming() + +```ts +createStreaming( + input, + callback, +options?): Promise; +``` + +Creates a model response with streaming via Server-Sent Events. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `input` | `string` \| [`ResponseInputItem`](../README.md#responseinputitem)[] | A string prompt or array of input items. | +| `callback` | (`event`) => `void` | Called for each streaming event received. | +| `options?` | `Partial`\<[`ResponseCreateParams`](../README.md#responsecreateparams)\> | Additional request parameters that override client settings. | + +#### Returns + +`Promise`\<`void`\> + +*** + +### delete() + +```ts +delete(responseId): Promise; +``` + +Deletes a stored response by ID. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `responseId` | `string` | The ID of the response to delete. | + +#### Returns + +`Promise`\<[`DeleteResponseResult`](../README.md#deleteresponseresult)\> + +The deletion result. + +*** + +### get() + +```ts +get(responseId): Promise; +``` + +Retrieves a stored response by ID. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `responseId` | `string` | The ID of the response to retrieve. | + +#### Returns + +`Promise`\<[`ResponseObject`](../README.md#responseobject)\> + +The Response object, or throws if not found. + +*** + +### getInputItems() + +```ts +getInputItems(responseId): Promise; +``` + +Retrieves input items for a stored response. + +#### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `responseId` | `string` | The ID of the response. | + +#### Returns + +`Promise`\<[`InputItemsListResponse`](../README.md#inputitemslistresponse)\> + +The list of input items. diff --git a/sdk/js/docs/classes/ResponsesClientSettings.md b/sdk/js/docs/classes/ResponsesClientSettings.md new file mode 100644 index 00000000..08b9ea94 --- /dev/null +++ b/sdk/js/docs/classes/ResponsesClientSettings.md @@ -0,0 +1,132 @@ +[@prathikrao/foundry-local-sdk](../README.md) / ResponsesClientSettings + +# Class: ResponsesClientSettings + +Configuration settings for the Responses API client. +Properties use camelCase in JS and are serialized to snake_case for the API. + +## Constructors + +### Constructor + +```ts +new ResponsesClientSettings(): ResponsesClientSettings; +``` + +#### Returns + +`ResponsesClientSettings` + +## Properties + +### frequencyPenalty? + +```ts +optional frequencyPenalty: number; +``` + +*** + +### instructions? + +```ts +optional instructions: string; +``` + +System-level instructions to guide the model. + +*** + +### maxOutputTokens? + +```ts +optional maxOutputTokens: number; +``` + +*** + +### metadata? + +```ts +optional metadata: Record; +``` + +*** + +### parallelToolCalls? + +```ts +optional parallelToolCalls: boolean; +``` + +*** + +### presencePenalty? + +```ts +optional presencePenalty: number; +``` + +*** + +### reasoning? + +```ts +optional reasoning: ReasoningConfig; +``` + +*** + +### seed? + +```ts +optional seed: number; +``` + +*** + +### store? + +```ts +optional store: boolean; +``` + +*** + +### temperature? + +```ts +optional temperature: number; +``` + +*** + +### text? + +```ts +optional text: TextConfig; +``` + +*** + +### toolChoice? + +```ts +optional toolChoice: ResponseToolChoice; +``` + +*** + +### topP? + +```ts +optional topP: number; +``` + +*** + +### truncation? + +```ts +optional truncation: TruncationStrategy; +``` diff --git a/sdk/js/src/model.ts b/sdk/js/src/model.ts index daac6558..e2b37119 100644 --- a/sdk/js/src/model.ts +++ b/sdk/js/src/model.ts @@ -20,15 +20,27 @@ export class Model implements IModel { this.selectedVariant = variant; } + private validateVariantInput(variant: ModelVariant, caller: string): void { + if (variant === null || variant === undefined) { + throw new Error(`${caller}() requires a ModelVariant object but received ${variant}.`); + } + if (typeof variant !== 'object') { + throw new Error( + `${caller}() requires a ModelVariant object but received ${typeof variant}.` + ); + } + } + /** * Adds a new variant to this model. * Automatically selects the new variant if it is cached and the current one is not. * @param variant - The model variant to add. - * @throws Error - If the variant's alias does not match the model's alias. + * @throws Error - If the argument is not a ModelVariant object, or if the variant's alias does not match the model's alias. */ public addVariant(variant: ModelVariant): void { - if (variant.alias !== this._alias) { - throw new Error("Variant alias does not match model alias."); + this.validateVariantInput(variant, 'addVariant'); + if (!variant || variant.alias !== this._alias) { + throw new Error(`Variant alias "${variant?.alias}" does not match model alias "${this._alias}".`); } this._variants.push(variant); @@ -39,18 +51,17 @@ export class Model implements IModel { } /** - * Selects a specific variant by its ID. - * @param modelId - The ID of the variant to select. - * @throws Error - If the variant with the specified ID is not found. + * Selects a specific variant. + * @param variant - The model variant to select. + * @throws Error - If the argument is not a ModelVariant object, or if the variant does not belong to this model. */ - public selectVariant(modelId: string): void { - for (const variant of this._variants) { - if (variant.id === modelId) { - this.selectedVariant = variant; - return; - } + public selectVariant(variant: ModelVariant): void { + this.validateVariantInput(variant, 'selectVariant'); + const matchingVariant = this._variants.find(v => v.id === variant.id); + if (!variant.id || !matchingVariant) { + throw new Error(`Model variant with ID ${variant.id} does not belong to model "${this._alias}".`); } - throw new Error(`Model variant with id ${modelId} not found.`); + this.selectedVariant = matchingVariant; } /** @@ -156,4 +167,4 @@ export class Model implements IModel { public createResponsesClient(baseUrl: string): ResponsesClient { return this.selectedVariant.createResponsesClient(baseUrl); } -} +} \ No newline at end of file diff --git a/sdk/js/test/model.test.ts b/sdk/js/test/model.test.ts index 72526e09..acc4d6e2 100644 --- a/sdk/js/test/model.test.ts +++ b/sdk/js/test/model.test.ts @@ -39,7 +39,7 @@ describe('Model Tests', () => { expect(model).to.not.be.undefined; if (!model || !cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); // Ensure it's not loaded initially (or unload if it is) if (await model.isLoaded()) { @@ -53,4 +53,4 @@ describe('Model Tests', () => { await model.unload(); expect(await model.isLoaded()).to.be.false; }); -}); +}); \ No newline at end of file diff --git a/sdk/js/test/openai/audioClient.test.ts b/sdk/js/test/openai/audioClient.test.ts index 8a93eacb..a57c02e5 100644 --- a/sdk/js/test/openai/audioClient.test.ts +++ b/sdk/js/test/openai/audioClient.test.ts @@ -23,7 +23,7 @@ describe('Audio Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -61,7 +61,7 @@ describe('Audio Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -99,7 +99,7 @@ describe('Audio Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -140,7 +140,7 @@ describe('Audio Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -213,4 +213,4 @@ describe('Audio Client Tests', () => { } } }); -}); +}); \ No newline at end of file diff --git a/sdk/js/test/openai/chatClient.test.ts b/sdk/js/test/openai/chatClient.test.ts index 6c0b1c4b..5f612845 100644 --- a/sdk/js/test/openai/chatClient.test.ts +++ b/sdk/js/test/openai/chatClient.test.ts @@ -20,7 +20,7 @@ describe('Chat Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); @@ -63,7 +63,7 @@ describe('Chat Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); @@ -213,7 +213,7 @@ describe('Chat Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -284,7 +284,7 @@ describe('Chat Client Tests', () => { expect(model).to.not.be.undefined; if (!cachedVariant) return; - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); try { @@ -355,4 +355,4 @@ describe('Chat Client Tests', () => { await model.unload(); } }); -}); +}); \ No newline at end of file diff --git a/sdk/js/test/openai/responsesClient.test.ts b/sdk/js/test/openai/responsesClient.test.ts index 6e45f465..925a2360 100644 --- a/sdk/js/test/openai/responsesClient.test.ts +++ b/sdk/js/test/openai/responsesClient.test.ts @@ -395,7 +395,7 @@ describe('ResponsesClient Tests', () => { } model = await catalog.getModel(TEST_MODEL_ALIAS); - model.selectVariant(cachedVariant.id); + model.selectVariant(cachedVariant); await model.load(); manager.startWebService(); client = manager.createResponsesClient(cachedVariant.id); @@ -568,4 +568,4 @@ describe('ResponsesClient Tests', () => { } }); }); -}); +}); \ No newline at end of file