foundry-local-sdk

Enumerations

DeviceType

Enumeration Members

Enumeration Member	Value
CPU	"CPU"
GPU	"GPU"
Invalid	"Invalid"
NPU	"NPU"

Classes

• AudioClient
• AudioClientSettings
• Catalog
• ChatClient
• ChatClientSettings
• EmbeddingClient
• FoundryLocalManager
• Model
• ModelLoadManager
• ResponsesClient
• ResponsesClientSettings

Interfaces

Annotation

Extended by

• UrlCitationAnnotation

Properties

end_index

end_index: number;

start_index

start_index: number;

type

type: string;

---

ContentPartAddedEvent

Properties

content_index

content_index: number;

item_id

item_id: string;

part

part: ContentPart;

sequence_number

sequence_number: number;

type

type: "response.content_part.added";

---

ContentPartDoneEvent

Properties

content_index

content_index: number;

item_id

item_id: string;

part

part: ContentPart;

sequence_number

sequence_number: number;

type

type: "response.content_part.done";

---

DeleteResponseResult

Properties

deleted

deleted: boolean;

id

id: string;

object

object: string;

---

EpDownloadResult

Result of an explicit EP download and registration operation.

Properties

failedEps

failedEps: string[];

Names of EPs that failed to register.

registeredEps

registeredEps: string[];

Names of EPs that were successfully registered.

status

status: string;

Human-readable status message.

success

success: boolean;

True if all requested EPs were successfully downloaded and registered.

---

EpInfo

Describes a discoverable execution provider.

Properties

isRegistered

isRegistered: boolean;

True if this EP has already been successfully downloaded and registered.

name

name: string;

The identifier of the execution provider (e.g. "CUDAExecutionProvider").

---

FoundryLocalConfig

Configuration options for the Foundry Local SDK. Use a plain object with these properties to configure the SDK.

Properties

additionalSettings?

optional additionalSettings?: {
[key: string]: string;
};

Additional settings to pass to the core. Optional. Internal use only.

Index Signature

[key: string]: string

appDataDir?

optional appDataDir?: string;

The directory where application data should be stored. Optional. Defaults to {user_home}/.{appName}.

appName

appName: string;

REQUIRED The name of the application using the SDK. Used for identifying the application in logs and telemetry.

libraryPath?

optional libraryPath?: string;

The path to the directory containing the native Foundry Local Core libraries. Optional. This directory must contain Microsoft.AI.Foundry.Local.Core, onnxruntime, and onnxruntime-genai binaries. If not provided, the SDK attempts to discover them in standard locations.

logLevel?

optional logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";

The logging level for the SDK. Optional. Valid values: 'trace', 'debug', 'info', 'warn', 'error', 'fatal'. Defaults to 'warn'.

logsDir?

optional logsDir?: string;

The directory where log files are written. Optional. Defaults to {appDataDir}/logs.

modelCacheDir?

optional modelCacheDir?: string;

The directory where models are downloaded and cached. Optional. Defaults to {appDataDir}/cache/models.

serviceEndpoint?

optional serviceEndpoint?: string;

The external URL if the web service is running in a separate process. Optional. This is used to connect to an existing service instance.

webServiceUrls?

optional webServiceUrls?: string;

The URL(s) for the local web service to bind to. Optional. Multiple URLs can be separated by semicolons. Example: "http://127.0.0.1:8080"

---

FunctionCallArgsDeltaEvent

Properties

delta

delta: string;

item_id

item_id: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

type

type: "response.function_call_arguments.delta";

---

FunctionCallArgsDoneEvent

Properties

arguments

arguments: string;

item_id

item_id: string;

name

name: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

type

type: "response.function_call_arguments.done";

---

FunctionCallItem

Properties

arguments

arguments: string;

call_id

call_id: string;

id?

optional id?: string;

name

name: string;

status?

optional status?: ResponseItemStatus;

type

type: "function_call";

---

FunctionCallOutputItem

Properties

call_id

call_id: string;

id?

optional id?: string;

output

output: string | ContentPart[];

status?

optional status?: ResponseItemStatus;

type

type: "function_call_output";

---

FunctionToolDefinition

Properties

description?

optional description?: string;

name

name: string;

parameters?

optional parameters?: Record<string, unknown>;

strict?

optional strict?: boolean;

type

type: "function";

---

IModel

Accessors

alias

Get Signature

get alias(): string;

Returns

string

capabilities

Get Signature

get capabilities(): string | null;

Returns

string | null

contextLength

Get Signature

get contextLength(): number | null;

Returns

number | null

id

Get Signature

get id(): string;

Returns

string

info

Get Signature

get info(): ModelInfo;

Returns

ModelInfo

inputModalities

Get Signature

get inputModalities(): string | null;

Returns

string | null

isCached

Get Signature

get isCached(): boolean;

Returns

boolean

outputModalities

Get Signature

get outputModalities(): string | null;

Returns

string | null

path

Get Signature

get path(): string;

Returns

string

supportsToolCalling

Get Signature

get supportsToolCalling(): boolean | null;

Returns

boolean | null

variants

Get Signature

get variants(): IModel[];

Variants of the model that are available. Variants of the model are optimized for different devices.

Returns

IModel[]

Methods

createAudioClient()

createAudioClient(): AudioClient;

Returns

AudioClient

createChatClient()

createChatClient(): ChatClient;

Returns

ChatClient

createResponsesClient()

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

download()

download(progressCallback?): Promise<void>;

Parameters

Parameter	Type
progressCallback?	(progress) => void

Returns

Promise<void>

isLoaded()

isLoaded(): Promise<boolean>;

Returns

Promise<boolean>

load()

load(): Promise<void>;

Returns

Promise<void>

removeFromCache()

removeFromCache(): void;

Returns

void

selectVariant()

selectVariant(variant): void;

Select a model variant from variants to use for IModel operations. An IModel from variants can also be used directly.

Parameters

Parameter	Type	Description
variant	IModel	Model variant to select. Must be one of the variants in variants.

Returns

void

Throws

Error if variant is not valid for this model.

unload()

unload(): Promise<void>;

Returns

Promise<void>

---

IncompleteDetails

Properties

reason

reason: string;

---

InputItemsListResponse

Properties

data

data: ResponseInputItem[];

object

object: "list";

---

InputTextContent

Properties

text

text: string;

type

type: "input_text";

---

ItemReference

Properties

id

id: string;

type

type: "item_reference";

---

LogProb

Properties

bytes?

optional bytes?: number[];

logprob

logprob: number;

token

token: string;

---

MessageItem

Properties

content

content: string | ContentPart[];

id?

optional id?: string;

role

role: MessageRole;

status?

optional status?: ResponseItemStatus;

type

type: "message";

---

ModelInfo

Properties

alias

alias: string;

cached

cached: boolean;

capabilities?

optional capabilities?: string | null;

contextLength?

optional contextLength?: number | null;

createdAtUnix

createdAtUnix: number;

displayName?

optional displayName?: string | null;

fileSizeMb?

optional fileSizeMb?: number | null;

id

id: string;

inputModalities?

optional inputModalities?: string | null;

license?

optional license?: string | null;

licenseDescription?

optional licenseDescription?: string | null;

maxOutputTokens?

optional maxOutputTokens?: number | null;

minFLVersion?

optional minFLVersion?: string | null;

modelSettings?

optional modelSettings?: ModelSettings | null;

modelType

modelType: string;

name

name: string;

outputModalities?

optional outputModalities?: string | null;

promptTemplate?

optional promptTemplate?: PromptTemplate | null;

providerType

providerType: string;

publisher?

optional publisher?: string | null;

runtime?

optional runtime?: Runtime | null;

supportsToolCalling?

optional supportsToolCalling?: boolean | null;

task?

optional task?: string | null;

uri

uri: string;

version

version: number;

---

ModelSettings

Properties

parameters?

optional parameters?: Parameter[] | null;

---

OutputItemAddedEvent

Properties

item

item: ResponseOutputItem;

item_id

item_id: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

type

type: "response.output_item.added";

---

OutputItemDoneEvent

Properties

item

item: ResponseOutputItem;

item_id

item_id: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

type

type: "response.output_item.done";

---

OutputTextContent

Properties

annotations?

optional annotations?: Annotation[];

logprobs?

optional logprobs?: LogProb[];

text

text: string;

type

type: "output_text";

---

OutputTextDeltaEvent

Properties

content_index

content_index: number;

delta

delta: string;

item_id

item_id: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

type

type: "response.output_text.delta";

---

OutputTextDoneEvent

Properties

content_index

content_index: number;

item_id

item_id: string;

output_index

output_index: number;

sequence_number

sequence_number: number;

text

text: string;

type

type: "response.output_text.done";

---

Parameter

Properties

name

name: string;

value?

optional value?: string | null;

---

PromptTemplate

Properties

assistant

assistant: string;

prompt

prompt: string;

system?

optional system?: string | null;

user?

optional user?: string | null;

---

ReasoningConfig

Properties

effort?

optional effort?: string;

summary?

optional summary?: string;

---

ReasoningItem

Properties

content?

optional content?: ContentPart[];

encrypted_content?

optional encrypted_content?: string;

id?

optional id?: string;

status?

optional status?: ResponseItemStatus;

summary?

optional summary?: string;

type

type: "reasoning";

---

RefusalContent

Properties

refusal

refusal: string;

type

type: "refusal";

---

RefusalDeltaEvent

Properties

content_index

content_index: number;

delta

delta: string;

item_id

item_id: string;

sequence_number

sequence_number: number;

type

type: "response.refusal.delta";

---

RefusalDoneEvent

Properties

content_index

content_index: number;

item_id

item_id: string;

refusal

refusal: string;

sequence_number

sequence_number: number;

type

type: "response.refusal.done";

---

ResponseCreateParams

Properties

frequency_penalty?

optional frequency_penalty?: number;

input?

optional input?: string | ResponseInputItem[];

instructions?

optional instructions?: string;

max_output_tokens?

optional max_output_tokens?: number;

metadata?

optional metadata?: Record<string, string>;

model?

optional model?: string;

parallel_tool_calls?

optional parallel_tool_calls?: boolean;

presence_penalty?

optional presence_penalty?: number;

previous_response_id?

optional previous_response_id?: string;

reasoning?

optional reasoning?: ReasoningConfig;

seed?

optional seed?: number;

store?

optional store?: boolean;

stream?

optional stream?: boolean;

temperature?

optional temperature?: number;

text?

optional text?: TextConfig;

tool_choice?

optional tool_choice?: ResponseToolChoice;

tools?

optional tools?: FunctionToolDefinition[];

top_p?

optional top_p?: number;

truncation?

optional truncation?: TruncationStrategy;

user?

optional user?: string;

---

ResponseError

Properties

code

code: string;

message

message: string;

---

ResponseFormat

Properties

jsonSchema?

optional jsonSchema?: string;

larkGrammar?

optional larkGrammar?: string;

type

type: string;

---

ResponseLifecycleEvent

Properties

response

response: ResponseObject;

sequence_number

sequence_number: number;

type

type: 
  | "response.created"
  | "response.queued"
  | "response.in_progress"
  | "response.completed"
  | "response.failed"
  | "response.incomplete";

---

ResponseObject

Properties

cancelled_at?

optional cancelled_at?: number | null;

completed_at?

optional completed_at?: number | null;

created_at

created_at: number;

error?

optional error?: ResponseError | null;

failed_at?

optional failed_at?: number | null;

frequency_penalty

frequency_penalty: number;

id

id: string;

incomplete_details?

optional incomplete_details?: IncompleteDetails | null;

instructions?

optional instructions?: string | null;

max_output_tokens?

optional max_output_tokens?: number | null;

metadata?

optional metadata?: Record<string, string> | null;

model

model: string;

object

object: "response";

output

output: ResponseOutputItem[];

parallel_tool_calls

parallel_tool_calls: boolean;

presence_penalty

presence_penalty: number;

previous_response_id?

optional previous_response_id?: string | null;

reasoning?

optional reasoning?: ReasoningConfig | null;

status

status: ResponseStatus;

store

store: boolean;

temperature

temperature: number;

text

text: TextConfig;

tool_choice

tool_choice: ResponseToolChoice;

tools

tools: FunctionToolDefinition[];

top_p

top_p: number;

truncation

truncation: TruncationStrategy;

usage?

optional usage?: ResponseUsage | null;

user?

optional user?: string | null;

---

ResponseToolChoiceFunction

Properties

name

name: string;

type

type: "function";

---

ResponseUsage

Properties

input_tokens

input_tokens: number;

input_tokens_details?

optional input_tokens_details?: {
  cached_tokens: number;
};

cached_tokens

cached_tokens: number;

output_tokens

output_tokens: number;

output_tokens_details?

optional output_tokens_details?: {
  reasoning_tokens: number;
};

reasoning_tokens

reasoning_tokens: number;

total_tokens

total_tokens: number;

---

Runtime

Properties

deviceType

deviceType: DeviceType;

executionProvider

executionProvider: string;

---

StreamingErrorEvent

Properties

code?

optional code?: string;

message?

optional message?: string;

param?

optional param?: string;

sequence_number

sequence_number: number;

type

type: "error";

---

TextConfig

Properties

format?

optional format?: TextFormat;

verbosity?

optional verbosity?: string;

---

TextFormat

Properties

description?

optional description?: string;

name?

optional name?: string;

schema?

optional schema?: unknown;

strict?

optional strict?: boolean;

type

type: string;

---

ToolChoice

Properties

name?

optional name?: string;

type

type: string;

---

UrlCitationAnnotation

Extends

• Annotation

Properties

end_index

end_index: number;

Inherited from

Annotation.end_index

start_index

start_index: number;

Inherited from

Annotation.start_index

title

title: string;

type

type: "url_citation";

Overrides

Annotation.type

url

url: string;

Type Aliases

ContentPart

type ContentPart = 
  | InputTextContent
  | OutputTextContent
  | RefusalContent;

---

MessageRole

type MessageRole = "system" | "user" | "assistant" | "developer";

Role of a message in the Responses API.

---

ResponseInputItem

type ResponseInputItem = 
  | MessageItem
  | FunctionCallItem
  | FunctionCallOutputItem
  | ItemReference
  | ReasoningItem;

---

ResponseItemStatus

type ResponseItemStatus = "in_progress" | "completed" | "incomplete";

Status of an individual response item.

---

ResponseOutputItem

type ResponseOutputItem = 
  | MessageItem
  | FunctionCallItem
  | ReasoningItem;

---

ResponseStatus

type ResponseStatus = 
  | "queued"
  | "in_progress"
  | "completed"
  | "failed"
  | "incomplete"
  | "cancelled";

Status of a Response object.

---

ResponseToolChoice

type ResponseToolChoice = 
  | "none"
  | "auto"
  | "required"
  | ResponseToolChoiceFunction;

Controls which tool the model should use.

---

ServiceTier

type ServiceTier = "default" | "auto" | "flex" | "priority";

Service tier.

---

StreamingEvent

type StreamingEvent = 
  | ResponseLifecycleEvent
  | OutputItemAddedEvent
  | OutputItemDoneEvent
  | ContentPartAddedEvent
  | ContentPartDoneEvent
  | OutputTextDeltaEvent
  | OutputTextDoneEvent
  | RefusalDeltaEvent
  | RefusalDoneEvent
  | FunctionCallArgsDeltaEvent
  | FunctionCallArgsDoneEvent
  | StreamingErrorEvent;

---

TruncationStrategy

type TruncationStrategy = "auto" | "disabled";

Truncation strategy.

Functions

getOutputText()

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	The Response object.

Returns

string

The concatenated text from the first assistant message, or an empty string.