Sync updates from stainless branch: main (#8)

Author: yanxi0830

src/core.ts

@@ -294,6 +294,7 @@ export abstract class APIClient {
     options: FinalRequestOptions<Req>,
     { 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);
 

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, unknown>): string {
     return qs.stringify(query, { arrayFormat: 'comma' });
   }

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 & {});

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;
 

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<Shared.UserMessage | Shared.ToolResponseMessage>;
 
   output_attachments: Array<Turn.OutputAttachment>;
 
+  /**
+   * 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

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<BatchInferenceChatCompletionParams.Tool>;
@@ -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;

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;
   }