diff --git a/src/core.ts b/src/core.ts index 0ef1863..4012190 100644 --- a/src/core.ts +++ b/src/core.ts @@ -294,6 +294,7 @@ export abstract class APIClient { options: FinalRequestOptions, { retryCount = 0 }: { retryCount?: number } = {}, ): { req: RequestInit; url: string; timeout: number } { + options = { ...options }; const { method, path, query, headers: headers = {} } = options; const body = @@ -306,9 +307,9 @@ export abstract class APIClient { const url = this.buildURL(path!, query); if ('timeout' in options) validatePositiveInteger('timeout', options.timeout); - const timeout = options.timeout ?? this.timeout; + options.timeout = options.timeout ?? this.timeout; const httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url); - const minAgentTimeout = timeout + 1000; + const minAgentTimeout = options.timeout + 1000; if ( typeof (httpAgent as any)?.options?.timeout === 'number' && minAgentTimeout > ((httpAgent as any).options.timeout ?? 0) @@ -337,7 +338,7 @@ export abstract class APIClient { signal: options.signal ?? null, }; - return { req, url, timeout }; + return { req, url, timeout: options.timeout }; } private buildHeaders({ @@ -365,15 +366,22 @@ export abstract class APIClient { delete reqHeaders['content-type']; } - // Don't set the retry count header if it was already set or removed through default headers or by the - // caller. We check `defaultHeaders` and `headers`, which can contain nulls, instead of `reqHeaders` to - // account for the removal case. + // Don't set theses headers if they were already set or removed through default headers or by the caller. + // We check `defaultHeaders` and `headers`, which can contain nulls, instead of `reqHeaders` to account + // for the removal case. if ( getHeader(defaultHeaders, 'x-stainless-retry-count') === undefined && getHeader(headers, 'x-stainless-retry-count') === undefined ) { reqHeaders['x-stainless-retry-count'] = String(retryCount); } + if ( + getHeader(defaultHeaders, 'x-stainless-timeout') === undefined && + getHeader(headers, 'x-stainless-timeout') === undefined && + options.timeout + ) { + reqHeaders['x-stainless-timeout'] = String(options.timeout); + } this.validateHeaders(reqHeaders, headers); diff --git a/src/index.ts b/src/index.ts index 8a8a7ee..0dc1041 100644 --- a/src/index.ts +++ b/src/index.ts @@ -159,6 +159,11 @@ import { } from './resources/tool-runtime/tool-runtime'; export interface ClientOptions { + /** + * Defaults to process.env['LLAMA_STACK_CLIENT_API_KEY']. + */ + apiKey?: string | null | undefined; + /** * Override the default base URL for the API, e.g., "https://api.example.com/v2/" * @@ -220,11 +225,14 @@ export interface ClientOptions { * API Client for interfacing with the Llama Stack Client API. */ export class LlamaStackClient extends Core.APIClient { + apiKey: string | null; + private _options: ClientOptions; /** * API Client for interfacing with the Llama Stack Client API. * + * @param {string | null | undefined} [opts.apiKey=process.env['LLAMA_STACK_CLIENT_API_KEY'] ?? null] * @param {string} [opts.baseURL=process.env['LLAMA_STACK_CLIENT_BASE_URL'] ?? http://any-hosted-llama-stack.com] - Override the default base URL for the API. * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out. * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections. @@ -233,8 +241,13 @@ export class LlamaStackClient extends Core.APIClient { * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API. * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API. */ - constructor({ baseURL = Core.readEnv('LLAMA_STACK_CLIENT_BASE_URL'), ...opts }: ClientOptions = {}) { + constructor({ + baseURL = Core.readEnv('LLAMA_STACK_CLIENT_BASE_URL'), + apiKey = Core.readEnv('LLAMA_STACK_CLIENT_API_KEY') ?? null, + ...opts + }: ClientOptions = {}) { const options: ClientOptions = { + apiKey, ...opts, baseURL: baseURL || `http://any-hosted-llama-stack.com`, }; @@ -248,6 +261,8 @@ export class LlamaStackClient extends Core.APIClient { }); this._options = options; + + this.apiKey = apiKey; } toolgroups: API.Toolgroups = new API.Toolgroups(this); @@ -285,6 +300,13 @@ export class LlamaStackClient extends Core.APIClient { }; } + protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers { + if (this.apiKey == null) { + return {}; + } + return { Authorization: `Bearer ${this.apiKey}` }; + } + protected override stringifyQuery(query: Record): string { return qs.stringify(query, { arrayFormat: 'comma' }); } diff --git a/src/resources/agents/agents.ts b/src/resources/agents/agents.ts index 633f3c9..63d8e91 100644 --- a/src/resources/agents/agents.ts +++ b/src/resources/agents/agents.ts @@ -43,6 +43,9 @@ export class Agents extends APIResource { } export interface InferenceStep { + /** + * A message containing the model's (assistant) response in a chat conversation. + */ model_response: Shared.CompletionMessage; step_id: string; @@ -57,6 +60,9 @@ export interface InferenceStep { } export interface MemoryRetrievalStep { + /** + * A image content item + */ inserted_context: Shared.InterleavedContent; step_id: string; @@ -105,6 +111,9 @@ export interface ToolExecutionStep { export interface ToolResponse { call_id: string; + /** + * A image content item + */ content: Shared.InterleavedContent; tool_name: 'brave_search' | 'wolfram_alpha' | 'photogen' | 'code_interpreter' | (string & {}); diff --git a/src/resources/agents/session.ts b/src/resources/agents/session.ts index 5e222a1..716b9b7 100644 --- a/src/resources/agents/session.ts +++ b/src/resources/agents/session.ts @@ -41,6 +41,9 @@ export class SessionResource extends APIResource { } } +/** + * A single session of an interaction with an Agentic System. + */ export interface Session { session_id: string; diff --git a/src/resources/agents/turn.ts b/src/resources/agents/turn.ts index 6b13388..2e1e9d2 100644 --- a/src/resources/agents/turn.ts +++ b/src/resources/agents/turn.ts @@ -50,15 +50,24 @@ export class TurnResource extends APIResource { } } +/** + * streamed agent turn completion response. + */ export interface AgentTurnResponseStreamChunk { event: TurnResponseEvent; } +/** + * A single turn in an interaction with an Agentic System. + */ export interface Turn { input_messages: Array; output_attachments: Array; + /** + * A message containing the model's (assistant) response in a chat conversation. + */ output_message: Shared.CompletionMessage; session_id: string; @@ -79,6 +88,9 @@ export interface Turn { export namespace Turn { export interface OutputAttachment { + /** + * A image content item + */ content: | string | OutputAttachment.ImageContentItem @@ -90,6 +102,9 @@ export namespace Turn { } export namespace OutputAttachment { + /** + * A image content item + */ export interface ImageContentItem { /** * Image as a base64 encoded string or an URL @@ -120,6 +135,9 @@ export namespace Turn { } } + /** + * A text content item + */ export interface TextContentItem { /** * Text content @@ -189,6 +207,9 @@ export namespace TurnResponseEventPayload { export interface AgentTurnResponseTurnCompletePayload { event_type: 'turn_complete'; + /** + * A single turn in an interaction with an Agentic System. + */ turn: TurnAPI.Turn; } } @@ -207,6 +228,9 @@ export interface TurnCreateParamsBase { export namespace TurnCreateParams { export interface Document { + /** + * A image content item + */ content: | string | Document.ImageContentItem @@ -218,6 +242,9 @@ export namespace TurnCreateParams { } export namespace Document { + /** + * A image content item + */ export interface ImageContentItem { /** * Image as a base64 encoded string or an URL @@ -248,6 +275,9 @@ export namespace TurnCreateParams { } } + /** + * A text content item + */ export interface TextContentItem { /** * Text content diff --git a/src/resources/batch-inference.ts b/src/resources/batch-inference.ts index 9f99274..dce9bd2 100644 --- a/src/resources/batch-inference.ts +++ b/src/resources/batch-inference.ts @@ -31,12 +31,23 @@ export interface BatchInferenceChatCompletionParams { logprobs?: BatchInferenceChatCompletionParams.Logprobs; + /** + * Configuration for JSON schema-guided response generation. + */ response_format?: Shared.ResponseFormat; sampling_params?: Shared.SamplingParams; + /** + * Whether tool use is required or automatic. This is a hint to the model which may + * not be followed. It depends on the Instruction Following capabilities of the + * model. + */ tool_choice?: 'auto' | 'required'; + /** + * Prompt format for calling custom / zero shot tools. + */ tool_prompt_format?: 'json' | 'function_tag' | 'python_list'; tools?: Array; @@ -66,6 +77,9 @@ export interface BatchInferenceCompletionParams { logprobs?: BatchInferenceCompletionParams.Logprobs; + /** + * Configuration for JSON schema-guided response generation. + */ response_format?: Shared.ResponseFormat; sampling_params?: Shared.SamplingParams; diff --git a/src/resources/eval/eval.ts b/src/resources/eval/eval.ts index 42ddea3..3953951 100644 --- a/src/resources/eval/eval.ts +++ b/src/resources/eval/eval.ts @@ -34,6 +34,9 @@ export namespace EvalCandidate { type: 'model'; + /** + * A system message providing instructions or context to the model. + */ system_message?: Shared.SystemMessage; } diff --git a/src/resources/inference.ts b/src/resources/inference.ts index 7dc59c7..3425446 100644 --- a/src/resources/inference.ts +++ b/src/resources/inference.ts @@ -71,6 +71,9 @@ export class Inference extends APIResource { } } +/** + * A chunk of a streamed chat completion response. + */ export interface ChatCompletionResponseStreamChunk { /** * The event containing the new content @@ -106,6 +109,9 @@ export namespace ChatCompletionResponseStreamChunk { } } +/** + * Response from a completion request. + */ export interface CompletionResponse { /** * The generated completion text @@ -123,6 +129,9 @@ export interface CompletionResponse { logprobs?: Array; } +/** + * Response containing generated embeddings. + */ export interface EmbeddingsResponse { /** * List of embedding vectors, one per input content. Each embedding is a list of @@ -132,6 +141,9 @@ export interface EmbeddingsResponse { embeddings: Array>; } +/** + * Log probabilities for generated tokens. + */ export interface TokenLogProbs { /** * Dictionary mapping tokens to their log probabilities @@ -182,17 +194,23 @@ export interface InferenceChatCompletionParamsBase { /** * (Optional) Whether tool use is required or automatic. Defaults to - * ToolChoice.auto. + * ToolChoice.auto. .. deprecated:: Use tool_config instead. */ tool_choice?: 'auto' | 'required'; + /** + * (Optional) Configuration for tool use. + */ + tool_config?: InferenceChatCompletionParams.ToolConfig; + /** * (Optional) Instructs the model how to format tool calls. By default, Llama Stack * will attempt to use a format that is best adapted to the model. - * `ToolPromptFormat.json`: The tool calls are formatted as a JSON object. - * `ToolPromptFormat.function_tag`: The tool calls are enclosed in a * tag. - `ToolPromptFormat.python_list`: The tool calls - * are output as Python syntax -- a list of function calls. + * are output as Python syntax -- a list of function calls. .. deprecated:: Use + * tool_config instead. */ tool_prompt_format?: 'json' | 'function_tag' | 'python_list'; @@ -214,6 +232,37 @@ export namespace InferenceChatCompletionParams { top_k?: number; } + /** + * (Optional) Configuration for tool use. + */ + export interface ToolConfig { + /** + * (Optional) Config for how to override the default system prompt. - + * `SystemMessageBehavior.append`: Appends the provided system message to the + * default system prompt. - `SystemMessageBehavior.replace`: Replaces the default + * system prompt with the provided system message. The system message can include + * the string '{{function_definitions}}' to indicate where the function definitions + * should be inserted. + */ + system_message_behavior: 'append' | 'replace'; + + /** + * (Optional) Whether tool use is required or automatic. Defaults to + * ToolChoice.auto. + */ + tool_choice?: 'auto' | 'required'; + + /** + * (Optional) Instructs the model how to format tool calls. By default, Llama Stack + * will attempt to use a format that is best adapted to the model. - + * `ToolPromptFormat.json`: The tool calls are formatted as a JSON object. - + * `ToolPromptFormat.function_tag`: The tool calls are enclosed in a + * tag. - `ToolPromptFormat.python_list`: The tool calls + * are output as Python syntax -- a list of function calls. + */ + tool_prompt_format?: 'json' | 'function_tag' | 'python_list'; + } + export interface Tool { tool_name: 'brave_search' | 'wolfram_alpha' | 'photogen' | 'code_interpreter' | (string & {}); diff --git a/src/resources/post-training/job.ts b/src/resources/post-training/job.ts index 97556ee..8469da7 100644 --- a/src/resources/post-training/job.ts +++ b/src/resources/post-training/job.ts @@ -3,12 +3,15 @@ import { APIResource } from '../../resource'; import * as Core from '../../core'; import { ListPostTrainingJobsResponse } from './post-training'; +import * as PostTrainingAPI from './post-training'; export class Job extends APIResource { - list(options?: Core.RequestOptions): Core.APIPromise> { + list( + options?: Core.RequestOptions, + ): Core.APIPromise> { return ( this._client.get('/v1/post-training/jobs', options) as Core.APIPromise<{ - data: Array; + data: Array; }> )._thenUnwrap((obj) => obj.data); } @@ -41,12 +44,18 @@ export namespace JobListResponse { } } +/** + * Artifacts of a finetuning job. + */ export interface JobArtifactsResponse { checkpoints: Array; job_uuid: string; } +/** + * Status of a finetuning job. + */ export interface JobStatusResponse { checkpoints: Array; diff --git a/src/resources/shared.ts b/src/resources/shared.ts index d236d3c..c5d4271 100644 --- a/src/resources/shared.ts +++ b/src/resources/shared.ts @@ -19,12 +19,23 @@ export interface AgentConfig { output_shields?: Array; + /** + * Configuration for JSON schema-guided response generation. + */ response_format?: ResponseFormat; sampling_params?: SamplingParams; + /** + * Whether tool use is required or automatic. This is a hint to the model which may + * not be followed. It depends on the Instruction Following capabilities of the + * model. + */ tool_choice?: 'auto' | 'required'; + /** + * Prompt format for calling custom / zero shot tools. + */ tool_prompt_format?: 'json' | 'function_tag' | 'python_list'; toolgroups?: Array; @@ -42,6 +53,9 @@ export interface BatchCompletion { batch: Array; } +/** + * Response from a chat completion request. + */ export interface ChatCompletionResponse { /** * The complete response message @@ -54,6 +68,9 @@ export interface ChatCompletionResponse { logprobs?: Array; } +/** + * A message containing the model's (assistant) response in a chat conversation. + */ export interface CompletionMessage { /** * The content of the model's response @@ -106,6 +123,9 @@ export namespace ContentDelta { } export interface Document { + /** + * A image content item + */ content: | string | Document.ImageContentItem @@ -121,6 +141,9 @@ export interface Document { } export namespace Document { + /** + * A image content item + */ export interface ImageContentItem { /** * Image as a base64 encoded string or an URL @@ -151,6 +174,9 @@ export namespace Document { } } + /** + * A text content item + */ export interface TextContentItem { /** * Text content @@ -164,6 +190,9 @@ export namespace Document { } } +/** + * A image content item + */ export type InterleavedContent = | string | InterleavedContent.ImageContentItem @@ -171,6 +200,9 @@ export type InterleavedContent = | Array; export namespace InterleavedContent { + /** + * A image content item + */ export interface ImageContentItem { /** * Image as a base64 encoded string or an URL @@ -201,6 +233,9 @@ export namespace InterleavedContent { } } + /** + * A text content item + */ export interface TextContentItem { /** * Text content @@ -214,11 +249,17 @@ export namespace InterleavedContent { } } +/** + * A image content item + */ export type InterleavedContentItem = | InterleavedContentItem.ImageContentItem | InterleavedContentItem.TextContentItem; export namespace InterleavedContentItem { + /** + * A image content item + */ export interface ImageContentItem { /** * Image as a base64 encoded string or an URL @@ -249,6 +290,9 @@ export namespace InterleavedContentItem { } } + /** + * A text content item + */ export interface TextContentItem { /** * Text content @@ -262,6 +306,9 @@ export namespace InterleavedContentItem { } } +/** + * A message from the user in a chat conversation. + */ export type Message = UserMessage | SystemMessage | ToolResponseMessage | CompletionMessage; export type ParamType = @@ -347,12 +394,21 @@ export namespace QueryGeneratorConfig { } export interface QueryResult { + /** + * A image content item + */ content?: InterleavedContent; } +/** + * Configuration for JSON schema-guided response generation. + */ export type ResponseFormat = ResponseFormat.JsonSchemaResponseFormat | ResponseFormat.GrammarResponseFormat; export namespace ResponseFormat { + /** + * Configuration for JSON schema-guided response generation. + */ export interface JsonSchemaResponseFormat { /** * The JSON schema the response should conform to. In a Python SDK, this is often a @@ -366,6 +422,9 @@ export namespace ResponseFormat { type: 'json_schema'; } + /** + * Configuration for grammar-guided response generation. + */ export interface GrammarResponseFormat { /** * The BNF grammar specification the response should conform to @@ -438,6 +497,9 @@ export interface ScoringResult { score_rows: Array | unknown | null>>; } +/** + * A system message providing instructions or context to the model. + */ export interface SystemMessage { /** * The content of the "system prompt". If multiple system messages are provided, @@ -478,6 +540,9 @@ export interface ToolParamDefinition { required?: boolean; } +/** + * A message representing the result of a tool invocation. + */ export interface ToolResponseMessage { /** * Unique identifier for the tool call this response is for @@ -504,6 +569,9 @@ export interface URL { uri: string; } +/** + * A message from the user in a chat conversation. + */ export interface UserMessage { /** * The content of the message, which can include text and other media diff --git a/src/resources/shields.ts b/src/resources/shields.ts index edc98de..4e75b22 100644 --- a/src/resources/shields.ts +++ b/src/resources/shields.ts @@ -23,6 +23,9 @@ export interface ListShieldsResponse { data: ShieldListResponse; } +/** + * A safety shield resource that can be used to check content + */ export interface Shield { identifier: string; diff --git a/src/resources/synthetic-data-generation.ts b/src/resources/synthetic-data-generation.ts index 52d2b95..4c47616 100644 --- a/src/resources/synthetic-data-generation.ts +++ b/src/resources/synthetic-data-generation.ts @@ -13,6 +13,10 @@ export class SyntheticDataGeneration extends APIResource { } } +/** + * Response from the synthetic data generation. Batch of (prompt, response, score) + * tuples that pass the threshold. + */ export interface SyntheticDataGenerationResponse { synthetic_data: Array | unknown | null>>; @@ -22,6 +26,9 @@ export interface SyntheticDataGenerationResponse { export interface SyntheticDataGenerationGenerateParams { dialogs: Array; + /** + * The type of filtering function. + */ filtering_function: 'none' | 'random' | 'top_k' | 'top_p' | 'top_k_top_p' | 'sigmoid'; model?: string; diff --git a/src/resources/tool-runtime/rag-tool.ts b/src/resources/tool-runtime/rag-tool.ts index c940275..133a036 100644 --- a/src/resources/tool-runtime/rag-tool.ts +++ b/src/resources/tool-runtime/rag-tool.ts @@ -33,6 +33,9 @@ export interface RagToolInsertParams { } export interface RagToolQueryParams { + /** + * A image content item + */ content: Shared.InterleavedContent; vector_db_ids: Array; diff --git a/src/resources/tool-runtime/tool-runtime.ts b/src/resources/tool-runtime/tool-runtime.ts index 4f5c5aa..db66d06 100644 --- a/src/resources/tool-runtime/tool-runtime.ts +++ b/src/resources/tool-runtime/tool-runtime.ts @@ -69,6 +69,9 @@ export namespace ToolDef { } export interface ToolInvocationResult { + /** + * A image content item + */ content: Shared.InterleavedContent; error_code?: number; diff --git a/src/resources/vector-io.ts b/src/resources/vector-io.ts index e52abfe..3e89192 100644 --- a/src/resources/vector-io.ts +++ b/src/resources/vector-io.ts @@ -26,6 +26,9 @@ export interface QueryChunksResponse { export namespace QueryChunksResponse { export interface Chunk { + /** + * A image content item + */ content: Shared.InterleavedContent; metadata: Record | unknown | null>; @@ -42,6 +45,9 @@ export interface VectorIoInsertParams { export namespace VectorIoInsertParams { export interface Chunk { + /** + * A image content item + */ content: Shared.InterleavedContent; metadata: Record | unknown | null>; @@ -49,6 +55,9 @@ export namespace VectorIoInsertParams { } export interface VectorIoQueryParams { + /** + * A image content item + */ query: Shared.InterleavedContent; vector_db_id: string; diff --git a/tests/api-resources/inference.test.ts b/tests/api-resources/inference.test.ts index 7842628..0eb0d24 100644 --- a/tests/api-resources/inference.test.ts +++ b/tests/api-resources/inference.test.ts @@ -29,6 +29,7 @@ describe('resource inference', () => { sampling_params: { strategy: { type: 'greedy' }, max_tokens: 0, repetition_penalty: 0 }, stream: false, tool_choice: 'auto', + tool_config: { system_message_behavior: 'append', tool_choice: 'auto', tool_prompt_format: 'json' }, tool_prompt_format: 'json', tools: [ {