llama-stack-client 0.6.1 → 0.7.1

package/src/resources/routes.ts

@@ -11,6 +11,9 @@ import { isRequestOptions } from '../core';
 import * as Core from '../core';
 import * as Shared from './shared';
 
+/**
+ * APIs for inspecting the Llama Stack service, including health status, available API routes with methods and implementing providers.
+ */
 export class Routes extends APIResource {
   /**
    * List all available API routes with their methods and implementing providers.

package/src/resources/safety.ts

@@ -10,6 +10,9 @@ import { APIResource } from '../resource';
 import * as Core from '../core';
 import * as Shared from './shared';
 
+/**
+ * OpenAI-compatible Moderations API.
+ */
 export class Safety extends APIResource {
   /**
    * Run a safety shield on messages to check for policy violations.
@@ -122,6 +125,9 @@ export namespace SafetyRunShieldParams {
       }
     }
 
+    /**
+     * File content part for OpenAI-compatible chat completion messages.
+     */
     export interface OpenAIFile {
       /**
        * File specification.
@@ -222,6 +228,8 @@ export namespace SafetyRunShieldParams {
      * List of tool calls. Each tool call is an OpenAIChatCompletionToolCall object.
      */
     tool_calls?: Array<OpenAIAssistantMessageParamInput.ToolCall> | null;
+
+    [k: string]: unknown;
   }
 
   export namespace OpenAIAssistantMessageParamInput {
@@ -247,38 +255,33 @@ export namespace SafetyRunShieldParams {
       /**
        * Unique identifier for the tool call.
        */
-      id?: string | null;
-
-      /**
-       * Function call details for OpenAI-compatible tool calls.
-       */
-      function?: ToolCall.Function | null;
+      id: string;
 
       /**
-       * Index of the tool call in the list.
+       * Function call details.
        */
-      index?: number | null;
+      function: ToolCall.Function;
 
       /**
        * Must be 'function' to identify this as a function call.
        */
-      type?: 'function';
+      type: 'function';
     }
 
     export namespace ToolCall {
       /**
-       * Function call details for OpenAI-compatible tool calls.
+       * Function call details.
        */
       export interface Function {
         /**
          * Arguments to pass to the function as a JSON string.
          */
-        arguments?: string | null;
+        arguments: string;
 
         /**
          * Name of the function to call.
          */
-        name?: string | null;
+        name: string;
       }
     }
   }

package/src/resources/vector-io.ts

@@ -50,7 +50,7 @@ export namespace QueryChunksResponse {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */
@@ -79,7 +79,7 @@ export namespace QueryChunksResponse {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */
@@ -222,7 +222,7 @@ export namespace VectorIoInsertParams {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */
@@ -251,7 +251,7 @@ export namespace VectorIoInsertParams {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */

package/src/resources/vector-stores/file-batches.ts

@@ -141,6 +141,7 @@ export interface FileBatchCreateParams {
   chunking_strategy?:
     | FileBatchCreateParams.VectorStoreChunkingStrategyAuto
     | FileBatchCreateParams.VectorStoreChunkingStrategyStatic
+    | FileBatchCreateParams.VectorStoreChunkingStrategyContextual
     | null;
 
   [k: string]: unknown;
@@ -176,6 +177,62 @@ export namespace FileBatchCreateParams {
       max_chunk_size_tokens?: number;
     }
   }
+
+  /**
+   * Contextual chunking strategy that uses an LLM to situate chunks within the
+   * document.
+   */
+  export interface VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    contextual: VectorStoreChunkingStrategyContextual.Contextual;
+
+    /**
+     * Strategy type identifier.
+     */
+    type?: 'contextual';
+  }
+
+  export namespace VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    export interface Contextual {
+      /**
+       * Tokens to overlap between adjacent chunks. Must be less than
+       * max_chunk_size_tokens.
+       */
+      chunk_overlap_tokens?: number;
+
+      /**
+       * Prompt template for contextual retrieval. Uses WHOLE_DOCUMENT and CHUNK_CONTENT
+       * placeholders wrapped in double curly braces.
+       */
+      context_prompt?: string;
+
+      /**
+       * Maximum tokens per chunk. Suggested ~700 to allow room for prepended context.
+       */
+      max_chunk_size_tokens?: number;
+
+      /**
+       * Maximum concurrent LLM calls. Falls back to config default if not provided.
+       */
+      max_concurrency?: number | null;
+
+      /**
+       * LLM model for generating context. Falls back to
+       * VectorStoresConfig.contextual_retrieval_params.model if not provided.
+       */
+      model_id?: string | null;
+
+      /**
+       * Timeout per LLM call in seconds. Falls back to config default if not provided.
+       */
+      timeout_seconds?: number | null;
+    }
+  }
 }
 
 export interface FileBatchListFilesParams extends OpenAICursorPageParams {

package/src/resources/vector-stores/files.ts

@@ -127,7 +127,8 @@ export interface VectorStoreFile {
    */
   chunking_strategy:
     | VectorStoreFile.VectorStoreChunkingStrategyAuto
-    | VectorStoreFile.VectorStoreChunkingStrategyStatic;
+    | VectorStoreFile.VectorStoreChunkingStrategyStatic
+    | VectorStoreFile.VectorStoreChunkingStrategyContextual;
 
   created_at: number;
 
@@ -185,6 +186,62 @@ export namespace VectorStoreFile {
     }
   }
 
+  /**
+   * Contextual chunking strategy that uses an LLM to situate chunks within the
+   * document.
+   */
+  export interface VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    contextual: VectorStoreChunkingStrategyContextual.Contextual;
+
+    /**
+     * Strategy type identifier.
+     */
+    type?: 'contextual';
+  }
+
+  export namespace VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    export interface Contextual {
+      /**
+       * Tokens to overlap between adjacent chunks. Must be less than
+       * max_chunk_size_tokens.
+       */
+      chunk_overlap_tokens?: number;
+
+      /**
+       * Prompt template for contextual retrieval. Uses WHOLE_DOCUMENT and CHUNK_CONTENT
+       * placeholders wrapped in double curly braces.
+       */
+      context_prompt?: string;
+
+      /**
+       * Maximum tokens per chunk. Suggested ~700 to allow room for prepended context.
+       */
+      max_chunk_size_tokens?: number;
+
+      /**
+       * Maximum concurrent LLM calls. Falls back to config default if not provided.
+       */
+      max_concurrency?: number | null;
+
+      /**
+       * LLM model for generating context. Falls back to
+       * VectorStoresConfig.contextual_retrieval_params.model if not provided.
+       */
+      model_id?: string | null;
+
+      /**
+       * Timeout per LLM call in seconds. Falls back to config default if not provided.
+       */
+      timeout_seconds?: number | null;
+    }
+  }
+
   /**
    * Error information for failed vector store file processing.
    */
@@ -232,7 +289,7 @@ export namespace FileContentResponse {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */
@@ -248,7 +305,7 @@ export namespace FileContentResponse {
      * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
      * additional information about the chunk that will not be used in the context
      * during inference, but is required for backend functionality. The `ChunkMetadata`
-     * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+     * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
      * expected to change after. Use `Chunk.metadata` for metadata that will be used in
      * the context during inference.
      */
@@ -291,6 +348,7 @@ export interface FileCreateParams {
   chunking_strategy?:
     | FileCreateParams.VectorStoreChunkingStrategyAuto
     | FileCreateParams.VectorStoreChunkingStrategyStatic
+    | FileCreateParams.VectorStoreChunkingStrategyContextual
     | null;
 }
 
@@ -324,6 +382,62 @@ export namespace FileCreateParams {
       max_chunk_size_tokens?: number;
     }
   }
+
+  /**
+   * Contextual chunking strategy that uses an LLM to situate chunks within the
+   * document.
+   */
+  export interface VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    contextual: VectorStoreChunkingStrategyContextual.Contextual;
+
+    /**
+     * Strategy type identifier.
+     */
+    type?: 'contextual';
+  }
+
+  export namespace VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    export interface Contextual {
+      /**
+       * Tokens to overlap between adjacent chunks. Must be less than
+       * max_chunk_size_tokens.
+       */
+      chunk_overlap_tokens?: number;
+
+      /**
+       * Prompt template for contextual retrieval. Uses WHOLE_DOCUMENT and CHUNK_CONTENT
+       * placeholders wrapped in double curly braces.
+       */
+      context_prompt?: string;
+
+      /**
+       * Maximum tokens per chunk. Suggested ~700 to allow room for prepended context.
+       */
+      max_chunk_size_tokens?: number;
+
+      /**
+       * Maximum concurrent LLM calls. Falls back to config default if not provided.
+       */
+      max_concurrency?: number | null;
+
+      /**
+       * LLM model for generating context. Falls back to
+       * VectorStoresConfig.contextual_retrieval_params.model if not provided.
+       */
+      model_id?: string | null;
+
+      /**
+       * Timeout per LLM call in seconds. Falls back to config default if not provided.
+       */
+      timeout_seconds?: number | null;
+    }
+  }
 }
 
 export interface FileUpdateParams {

package/src/resources/vector-stores/vector-stores.ts

@@ -216,7 +216,7 @@ export namespace VectorStoreSearchResponse {
        * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
        * additional information about the chunk that will not be used in the context
        * during inference, but is required for backend functionality. The `ChunkMetadata`
-       * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+       * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
        * expected to change after. Use `Chunk.metadata` for metadata that will be used in
        * the context during inference.
        */
@@ -232,7 +232,7 @@ export namespace VectorStoreSearchResponse {
        * `ChunkMetadata` is backend metadata for a `Chunk` that is used to store
        * additional information about the chunk that will not be used in the context
        * during inference, but is required for backend functionality. The `ChunkMetadata`
-       * is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not
+       * is set during chunk creation in `FileSearchToolRuntimeImpl().insert()`and is not
        * expected to change after. Use `Chunk.metadata` for metadata that will be used in
        * the context during inference.
        */
@@ -266,6 +266,7 @@ export interface VectorStoreCreateParams {
   chunking_strategy?:
     | VectorStoreCreateParams.VectorStoreChunkingStrategyAuto
     | VectorStoreCreateParams.VectorStoreChunkingStrategyStatic
+    | VectorStoreCreateParams.VectorStoreChunkingStrategyContextual
     | null;
 
   expires_after?: { [key: string]: unknown } | null;
@@ -309,6 +310,62 @@ export namespace VectorStoreCreateParams {
       max_chunk_size_tokens?: number;
     }
   }
+
+  /**
+   * Contextual chunking strategy that uses an LLM to situate chunks within the
+   * document.
+   */
+  export interface VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    contextual: VectorStoreChunkingStrategyContextual.Contextual;
+
+    /**
+     * Strategy type identifier.
+     */
+    type?: 'contextual';
+  }
+
+  export namespace VectorStoreChunkingStrategyContextual {
+    /**
+     * Configuration for contextual chunking.
+     */
+    export interface Contextual {
+      /**
+       * Tokens to overlap between adjacent chunks. Must be less than
+       * max_chunk_size_tokens.
+       */
+      chunk_overlap_tokens?: number;
+
+      /**
+       * Prompt template for contextual retrieval. Uses WHOLE_DOCUMENT and CHUNK_CONTENT
+       * placeholders wrapped in double curly braces.
+       */
+      context_prompt?: string;
+
+      /**
+       * Maximum tokens per chunk. Suggested ~700 to allow room for prepended context.
+       */
+      max_chunk_size_tokens?: number;
+
+      /**
+       * Maximum concurrent LLM calls. Falls back to config default if not provided.
+       */
+      max_concurrency?: number | null;
+
+      /**
+       * LLM model for generating context. Falls back to
+       * VectorStoresConfig.contextual_retrieval_params.model if not provided.
+       */
+      model_id?: string | null;
+
+      /**
+       * Timeout per LLM call in seconds. Falls back to config default if not provided.
+       */
+      timeout_seconds?: number | null;
+    }
+  }
 }
 
 export interface VectorStoreUpdateParams {

package/src/streaming.ts

@@ -9,6 +9,9 @@ import { LlamaStackClientError } from './error';
 import { findDoubleNewlineIndex, LineDecoder } from './internal/decoders/line';
 import { ReadableStreamToAsyncIterable } from './internal/stream-utils';
 
+import { createResponseHeaders } from './core';
+import { APIError } from './error';
+
 type Bytes = string | ArrayBuffer | Uint8Array | Buffer | null | undefined;
 
 export type ServerSentEvent = {
@@ -38,12 +41,27 @@ export class Stream<Item> implements AsyncIterable<Item> {
       let done = false;
       try {
         for await (const sse of _iterSSEMessages(response, controller)) {
-          try {
-            yield JSON.parse(sse.data);
-          } catch (e) {
-            console.error(`Could not parse message into JSON:`, sse.data);
-            console.error(`From chunk:`, sse.raw);
-            throw e;
+          if (done) continue;
+
+          if (sse.data.startsWith('[DONE]')) {
+            done = true;
+            continue;
+          } else {
+            let data;
+
+            try {
+              data = JSON.parse(sse.data) as any;
+            } catch (e) {
+              console.error(`Could not parse message into JSON:`, sse.data);
+              console.error(`From chunk:`, sse.raw);
+              throw e;
+            }
+
+            if (data && data.error) {
+              throw new APIError(undefined, data.error, undefined, createResponseHeaders(response.headers));
+            }
+
+            yield data;
           }
         }
         done = true;

package/src/version.ts

@@ -4,4 +4,4 @@
 // This source code is licensed under the terms described in the LICENSE file in
 // the root directory of this source tree.
 
-export const VERSION = '0.6.1'; // x-release-please-version
+export const VERSION = '0.7.1'; // x-release-please-version

package/tests/api-resources/beta/datasets.test.ts

@@ -49,10 +49,7 @@ describe('resource datasets', () => {
   });
 
   test('appendrows: only required params', async () => {
-    const responsePromise = client.beta.datasets.appendrows('dataset_id', {
-      body_dataset_id: 'dataset_id',
-      rows: [{ foo: 'bar' }],
-    });
+    const responsePromise = client.beta.datasets.appendrows('dataset_id', { rows: [{ foo: 'bar' }] });
     const rawResponse = await responsePromise.asResponse();
     expect(rawResponse).toBeInstanceOf(Response);
     const response = await responsePromise;
@@ -63,10 +60,7 @@ describe('resource datasets', () => {
   });
 
   test('appendrows: required and optional params', async () => {
-    const response = await client.beta.datasets.appendrows('dataset_id', {
-      body_dataset_id: 'dataset_id',
-      rows: [{ foo: 'bar' }],
-    });
+    const response = await client.beta.datasets.appendrows('dataset_id', { rows: [{ foo: 'bar' }] });
   });
 
   test('iterrows', async () => {
@@ -100,7 +94,7 @@ describe('resource datasets', () => {
 
   test('register: only required params', async () => {
     const responsePromise = client.beta.datasets.register({
-      purpose: 'post-training/messages',
+      purpose: 'eval/question-answer',
       source: { uri: 'uri', type: 'uri' },
     });
     const rawResponse = await responsePromise.asResponse();
@@ -114,7 +108,7 @@ describe('resource datasets', () => {
 
   test('register: required and optional params', async () => {
     const response = await client.beta.datasets.register({
-      purpose: 'post-training/messages',
+      purpose: 'eval/question-answer',
       source: { uri: 'uri', type: 'uri' },
       dataset_id: 'dataset_id',
       metadata: { foo: 'bar' },

package/tests/api-resources/chat/completions.test.ts

@@ -46,10 +46,12 @@ describe('resource completions', () => {
       n: 1,
       parallel_tool_calls: true,
       presence_penalty: -2,
+      prompt_cache_key: 'prompt_cache_key',
       reasoning_effort: 'none',
       response_format: { type: 'text' },
       safety_identifier: 'safety_identifier',
       seed: 0,
+      service_tier: 'auto',
       stop: 'string',
       stream: false,
       stream_options: { foo: 'bar' },

package/tests/api-resources/files.test.ts

@@ -14,7 +14,7 @@ const client = new LlamaStackClient({ baseURL: process.env['TEST_API_BASE_URL']
 describe('resource files', () => {
   test('create: only required params', async () => {
     const responsePromise = client.files.create({
-      file: await toFile(Buffer.from('# my file contents'), 'README.md'),
+      file: await toFile(Buffer.from('Example data'), 'README.md'),
       purpose: 'assistants',
     });
     const rawResponse = await responsePromise.asResponse();
@@ -28,7 +28,7 @@ describe('resource files', () => {
 
   test('create: required and optional params', async () => {
     const response = await client.files.create({
-      file: await toFile(Buffer.from('# my file contents'), 'README.md'),
+      file: await toFile(Buffer.from('Example data'), 'README.md'),
       purpose: 'assistants',
       expires_after: { anchor: 'created_at', seconds: 3600 },
     });

package/tests/api-resources/models/models.test.ts

@@ -47,43 +47,4 @@ describe('resource models', () => {
       LlamaStackClient.NotFoundError,
     );
   });
-
-  test('register: only required params', async () => {
-    const responsePromise = client.models.register({ model_id: 'model_id' });
-    const rawResponse = await responsePromise.asResponse();
-    expect(rawResponse).toBeInstanceOf(Response);
-    const response = await responsePromise;
-    expect(response).not.toBeInstanceOf(Response);
-    const dataAndResponse = await responsePromise.withResponse();
-    expect(dataAndResponse.data).toBe(response);
-    expect(dataAndResponse.response).toBe(rawResponse);
-  });
-
-  test('register: required and optional params', async () => {
-    const response = await client.models.register({
-      model_id: 'model_id',
-      metadata: { foo: 'bar' },
-      model_type: 'llm',
-      provider_id: 'provider_id',
-      provider_model_id: 'provider_model_id',
-    });
-  });
-
-  test('unregister', async () => {
-    const responsePromise = client.models.unregister('model_id');
-    const rawResponse = await responsePromise.asResponse();
-    expect(rawResponse).toBeInstanceOf(Response);
-    const response = await responsePromise;
-    expect(response).not.toBeInstanceOf(Response);
-    const dataAndResponse = await responsePromise.withResponse();
-    expect(dataAndResponse.data).toBe(response);
-    expect(dataAndResponse.response).toBe(rawResponse);
-  });
-
-  test('unregister: request options instead of params are passed correctly', async () => {
-    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
-    await expect(client.models.unregister('model_id', { path: '/_stainless_unknown_path' })).rejects.toThrow(
-      LlamaStackClient.NotFoundError,
-    );
-  });
 });

package/tests/api-resources/responses/responses.test.ts

@@ -27,7 +27,9 @@ describe('resource responses', () => {
     const response = await client.responses.create({
       input: 'string',
       model: 'model',
+      background: true,
       conversation: 'conversation',
+      frequency_penalty: -2,
       guardrails: ['string'],
       include: ['web_search_call.action.sources'],
       instructions: 'instructions',
@@ -36,16 +38,20 @@ describe('resource responses', () => {
       max_tool_calls: 1,
       metadata: { foo: 'string' },
       parallel_tool_calls: true,
+      presence_penalty: -2,
       previous_response_id: 'previous_response_id',
       prompt: {
         id: 'id',
         variables: { foo: { text: 'text', type: 'input_text' } },
         version: 'version',
       },
-      reasoning: { effort: 'none' },
+      prompt_cache_key: 'prompt_cache_key',
+      reasoning: { effort: 'none', summary: 'auto' },
       safety_identifier: 'safety_identifier',
+      service_tier: 'auto',
       store: true,
       stream: false,
+      stream_options: { include_obfuscation: true },
       temperature: 0,
       text: {
         format: {
@@ -58,6 +64,9 @@ describe('resource responses', () => {
       },
       tool_choice: 'auto',
       tools: [{ search_context_size: 'S?oC"high', type: 'web_search' }],
+      top_logprobs: 0,
+      top_p: 0,
+      truncation: 'auto',
     });
   });
 

package/tests/api-resources/vector-stores/file-batches.test.ts

@@ -103,7 +103,7 @@ describe('resource fileBatches', () => {
           after: 'after',
           before: 'before',
           filter: 'filter',
-          limit: 0,
+          limit: 1,
           order: 'order',
         },
         { path: '/_stainless_unknown_path' },

package/tests/api-resources/vector-stores/files.test.ts

@@ -95,7 +95,7 @@ describe('resource files', () => {
           after: 'after',
           before: 'before',
           filter: 'completed',
-          limit: 0,
+          limit: 1,
           order: 'order',
         },
         { path: '/_stainless_unknown_path' },

package/tests/api-resources/vector-stores/vector-stores.test.ts

@@ -77,7 +77,7 @@ describe('resource vectorStores', () => {
         {
           after: 'after',
           before: 'before',
-          limit: 0,
+          limit: 1,
           order: 'order',
         },
         { path: '/_stainless_unknown_path' },