feat(api): add usage metadata when streaming (#829)

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 64
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-97c9a5f089049dc9eb5cee9475558049003e37e42202cab39e59d75e08b4c613.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-edb5af3ade0cd27cf366b0654b90c7a81c43c433e11fc3f6e621e2c779de10d4.yml

api.md

@@ -41,6 +41,7 @@ Types:
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionMessageToolCall</a></code>
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionNamedToolChoice</a></code>
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionRole</a></code>
+- <code><a href="./src/resources/chat/completions.ts">ChatCompletionStreamOptions</a></code>
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionSystemMessageParam</a></code>
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionTokenLogprob</a></code>
 - <code><a href="./src/resources/chat/completions.ts">ChatCompletionTool</a></code>

src/index.ts

@@ -251,6 +251,7 @@ export namespace OpenAI {
   export import ChatCompletionMessageToolCall = API.ChatCompletionMessageToolCall;
   export import ChatCompletionNamedToolChoice = API.ChatCompletionNamedToolChoice;
   export import ChatCompletionRole = API.ChatCompletionRole;
+  export import ChatCompletionStreamOptions = API.ChatCompletionStreamOptions;
   export import ChatCompletionSystemMessageParam = API.ChatCompletionSystemMessageParam;
   export import ChatCompletionTokenLogprob = API.ChatCompletionTokenLogprob;
   export import ChatCompletionTool = API.ChatCompletionTool;

src/resources/chat/chat.ts

@@ -45,6 +45,7 @@ export namespace Chat {
   export import ChatCompletionMessageToolCall = CompletionsAPI.ChatCompletionMessageToolCall;
   export import ChatCompletionNamedToolChoice = CompletionsAPI.ChatCompletionNamedToolChoice;
   export import ChatCompletionRole = CompletionsAPI.ChatCompletionRole;
+  export import ChatCompletionStreamOptions = CompletionsAPI.ChatCompletionStreamOptions;
   export import ChatCompletionSystemMessageParam = CompletionsAPI.ChatCompletionSystemMessageParam;
   export import ChatCompletionTokenLogprob = CompletionsAPI.ChatCompletionTokenLogprob;
   export import ChatCompletionTool = CompletionsAPI.ChatCompletionTool;

src/resources/chat/completions.ts

@@ -183,8 +183,9 @@ export interface ChatCompletionChunk {
   id: string;
 
   /**
-   * A list of chat completion choices. Can be more than one if `n` is greater
-   * than 1.
+   * A list of chat completion choices. Can contain more than one elements if `n` is
+   * greater than 1. Can also be empty for the last chunk if you set
+   * `stream_options: {"include_usage": true}`.
    */
   choices: Array<ChatCompletionChunk.Choice>;
 
@@ -210,6 +211,14 @@ export interface ChatCompletionChunk {
    * backend changes have been made that might impact determinism.
    */
   system_fingerprint?: string;
+
+  /**
+   * An optional field that will only be present when you set
+   * `stream_options: {"include_usage": true}` in your request. When present, it
+   * contains a null value except for the last chunk which contains the token usage
+   * statistics for the entire request.
+   */
+  usage?: CompletionsAPI.CompletionUsage;
 }
 
 export namespace ChatCompletionChunk {
@@ -517,6 +526,19 @@ export namespace ChatCompletionNamedToolChoice {
  */
 export type ChatCompletionRole = 'system' | 'user' | 'assistant' | 'tool' | 'function';
 
+/**
+ * Options for streaming response. Only set this when you set `stream: true`.
+ */
+export interface ChatCompletionStreamOptions {
+  /**
+   * If set, an additional chunk will be streamed before the `data: [DONE]` message.
+   * The `usage` field on this chunk shows the token usage statistics for the entire
+   * request, and the `choices` field will always be an empty array. All other chunks
+   * will also include a `usage` field, but with a null value.
+   */
+  include_usage?: boolean;
+}
+
 export interface ChatCompletionSystemMessageParam {
   /**
    * The contents of the system message.
@@ -786,6 +808,11 @@ export interface ChatCompletionCreateParamsBase {
    */
   stream?: boolean | null;
 
+  /**
+   * Options for streaming response. Only set this when you set `stream: true`.
+   */
+  stream_options?: ChatCompletionStreamOptions | null;
+
   /**
    * What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
    * make the output more random, while lower values like 0.2 will make it more
@@ -949,6 +976,7 @@ export namespace Completions {
   export import ChatCompletionMessageToolCall = ChatCompletionsAPI.ChatCompletionMessageToolCall;
   export import ChatCompletionNamedToolChoice = ChatCompletionsAPI.ChatCompletionNamedToolChoice;
   export import ChatCompletionRole = ChatCompletionsAPI.ChatCompletionRole;
+  export import ChatCompletionStreamOptions = ChatCompletionsAPI.ChatCompletionStreamOptions;
   export import ChatCompletionSystemMessageParam = ChatCompletionsAPI.ChatCompletionSystemMessageParam;
   export import ChatCompletionTokenLogprob = ChatCompletionsAPI.ChatCompletionTokenLogprob;
   export import ChatCompletionTool = ChatCompletionsAPI.ChatCompletionTool;

src/resources/chat/index.ts

@@ -14,6 +14,7 @@ export {
   ChatCompletionMessageToolCall,
   ChatCompletionNamedToolChoice,
   ChatCompletionRole,
+  ChatCompletionStreamOptions,
   ChatCompletionSystemMessageParam,
   ChatCompletionTokenLogprob,
   ChatCompletionTool,

src/resources/completions.ts

@@ -4,6 +4,7 @@ import * as Core from 'openai/core';
 import { APIPromise } from 'openai/core';
 import { APIResource } from 'openai/resource';
 import * as CompletionsAPI from 'openai/resources/completions';
+import * as ChatCompletionsAPI from 'openai/resources/chat/completions';
 import { Stream } from 'openai/streaming';
 
 export class Completions extends APIResource {
@@ -251,6 +252,11 @@ export interface CompletionCreateParamsBase {
    */
   stream?: boolean | null;
 
+  /**
+   * Options for streaming response. Only set this when you set `stream: true`.
+   */
+  stream_options?: ChatCompletionsAPI.ChatCompletionStreamOptions | null;
+
   /**
    * The suffix that comes after a completion of inserted text.
    *

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

@@ -39,6 +39,7 @@ describe('resource completions', () => {
       seed: -9223372036854776000,
       stop: 'string',
       stream: false,
+      stream_options: { include_usage: true },
       temperature: 1,
       tool_choice: 'none',
       tools: [

tests/api-resources/completions.test.ts

@@ -35,6 +35,7 @@ describe('resource completions', () => {
       seed: -9223372036854776000,
       stop: '\n',
       stream: false,
+      stream_options: { include_usage: true },
       suffix: 'test.',
       temperature: 1,
       top_p: 1,