llama-stack-client 0.1.0 → 0.1.2

package/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' });
   }

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

package/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;
 

package/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

package/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;

package/src/resources/datasets.ts

@@ -35,25 +35,7 @@ export class Datasets extends APIResource {
 }
 
 export interface ListDatasetsResponse {
-  data: Array<ListDatasetsResponse.Data>;
-}
-
-export namespace ListDatasetsResponse {
-  export interface Data {
-    dataset_schema: Record<string, Shared.ParamType>;
-
-    identifier: string;
-
-    metadata: Record<string, boolean | number | string | Array<unknown> | unknown | null>;
-
-    provider_id: string;
-
-    provider_resource_id: string;
-
-    type: 'dataset';
-
-    url: Shared.URL;
-  }
+  data: DatasetListResponse;
 }
 
 export interface DatasetRetrieveResponse {

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

package/src/resources/eval-tasks.ts

@@ -40,7 +40,7 @@ export interface EvalTask {
 }
 
 export interface ListEvalTasksResponse {
-  data: Array<EvalTask>;
+  data: EvalTaskListResponse;
 }
 
 export type EvalTaskListResponse = Array<EvalTask>;

package/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<TokenLogProbs>;
 }
 
+/**
+ * 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<Array<number>>;
 }
 
+/**
+ * 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
    * <function=function_name> 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
+     * <function=function_name> 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 & {});
 

package/src/resources/models.ts

@@ -27,7 +27,7 @@ export class Models extends APIResource {
 }
 
 export interface ListModelsResponse {
-  data: Array<Model>;
+  data: ModelListResponse;
 }
 
 export interface Model {

package/src/resources/post-training/job.ts

@@ -2,11 +2,17 @@
 
 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<JobListResponse> {
+  list(
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<Array<PostTrainingAPI.ListPostTrainingJobsResponse.Data>> {
     return (
-      this._client.get('/v1/post-training/jobs', options) as Core.APIPromise<{ data: JobListResponse }>
+      this._client.get('/v1/post-training/jobs', options) as Core.APIPromise<{
+        data: Array<PostTrainingAPI.ListPostTrainingJobsResponse.Data>;
+      }>
     )._thenUnwrap((obj) => obj.data);
   }
 
@@ -38,12 +44,18 @@ export namespace JobListResponse {
   }
 }
 
+/**
+ * Artifacts of a finetuning job.
+ */
 export interface JobArtifactsResponse {
   checkpoints: Array<unknown>;
 
   job_uuid: string;
 }
 
+/**
+ * Status of a finetuning job.
+ */
 export interface JobStatusResponse {
   checkpoints: Array<unknown>;
 

package/src/resources/providers.ts

@@ -13,7 +13,7 @@ export class Providers extends APIResource {
 }
 
 export interface ListProvidersResponse {
-  data: Array<InspectAPI.ProviderInfo>;
+  data: ProviderListResponse;
 }
 
 export type ProviderListResponse = Array<InspectAPI.ProviderInfo>;

package/src/resources/routes.ts

@@ -13,7 +13,7 @@ export class Routes extends APIResource {
 }
 
 export interface ListRoutesResponse {
-  data: Array<InspectAPI.RouteInfo>;
+  data: RouteListResponse;
 }
 
 export type RouteListResponse = Array<InspectAPI.RouteInfo>;

package/src/resources/scoring-functions.ts

@@ -27,7 +27,7 @@ export class ScoringFunctions extends APIResource {
 }
 
 export interface ListScoringFunctionsResponse {
-  data: Array<ScoringFn>;
+  data: ScoringFunctionListResponse;
 }
 
 export interface ScoringFn {

package/src/resources/shared.ts

@@ -19,12 +19,23 @@ export interface AgentConfig {
 
   output_shields?: Array<string>;
 
+  /**
+   * 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<string | AgentConfig.UnionMember1>;
@@ -42,6 +53,9 @@ export interface BatchCompletion {
   batch: Array<InferenceAPI.CompletionResponse>;
 }
 
+/**
+ * Response from a chat completion request.
+ */
 export interface ChatCompletionResponse {
   /**
    * The complete response message
@@ -54,6 +68,9 @@ export interface ChatCompletionResponse {
   logprobs?: Array<InferenceAPI.TokenLogProbs>;
 }
 
+/**
+ * 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<InterleavedContentItem>;
 
 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<Record<string, boolean | number | string | Array<unknown> | 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

package/src/resources/shields.ts

@@ -20,9 +20,12 @@ export class Shields extends APIResource {
 }
 
 export interface ListShieldsResponse {
-  data: Array<Shield>;
+  data: ShieldListResponse;
 }
 
+/**
+ * A safety shield resource that can be used to check content
+ */
 export interface Shield {
   identifier: string;
 

package/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<Record<string, boolean | number | string | Array<unknown> | unknown | null>>;
 
@@ -22,6 +26,9 @@ export interface SyntheticDataGenerationResponse {
 export interface SyntheticDataGenerationGenerateParams {
   dialogs: Array<Shared.Message>;
 
+  /**
+   * The type of filtering function.
+   */
   filtering_function: 'none' | 'random' | 'top_k' | 'top_p' | 'top_k_top_p' | 'sigmoid';
 
   model?: string;