completions.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as CompletionsAPI from './completions';
import * as Shared from '../shared';
import { APIPromise } from '../../core/api-promise';
import { Stream } from '../../core/streaming';
import { RequestOptions } from '../../internal/request-options';

export class Completions extends APIResource {
  /**
   * Creates a model response for the given chat conversation.
   *
   * @example
   * ```ts
   * const completion = await client.chat.completions.create({
   *   messages: [{ content: 'string', role: 'system' }],
   *   model: 'llama3-8b-instruct',
   * });
   * ```
   */
  create(
    body: CompletionCreateParamsNonStreaming,
    options?: RequestOptions,
  ): APIPromise<CompletionCreateResponse>;
  create(
    body: CompletionCreateParamsStreaming,
    options?: RequestOptions,
  ): APIPromise<Stream<Shared.ChatCompletionChunk>>;
  create(
    body: CompletionCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<Shared.ChatCompletionChunk> | CompletionCreateResponse>;
  create(
    body: CompletionCreateParams,
    options?: RequestOptions,
  ): APIPromise<CompletionCreateResponse> | APIPromise<Stream<Shared.ChatCompletionChunk>> {
    return this._client.post('/chat/completions', {
      body,
      defaultBaseURL: '{inferenceEndpoint}/v1',
      ...options,
      stream: body.stream ?? false,
    }) as APIPromise<CompletionCreateResponse> | APIPromise<Stream<Shared.ChatCompletionChunk>>;
  }
}

/**
 * Represents a chat completion response returned by model, based on the provided
 * input.
 */
export interface CompletionCreateResponse {
  /**
   * A unique identifier for the chat completion.
   */
  id: string;

  /**
   * A list of chat completion choices. Can be more than one if `n` is greater
   * than 1.
   */
  choices: Array<CompletionCreateResponse.Choice>;

  /**
   * The Unix timestamp (in seconds) of when the chat completion was created.
   */
  created: number;

  /**
   * The model used for the chat completion.
   */
  model: string;

  /**
   * The object type, which is always `chat.completion`.
   */
  object: 'chat.completion';

  /**
   * Usage statistics for the completion request.
   */
  usage?: Shared.CompletionUsage;
}

export namespace CompletionCreateResponse {
  export interface Choice {
    /**
     * The reason the model stopped generating tokens. This will be `stop` if the model
     * hit a natural stop point or a provided stop sequence, or `length` if the maximum
     * number of tokens specified in the request was reached, `tool_calls` if the model
     * called a tool.
     */
    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter';

    /**
     * The index of the choice in the list of choices.
     */
    index: number;

    /**
     * Log probability information for the choice.
     */
    logprobs: Choice.Logprobs | null;

    /**
     * A chat completion message generated by the model.
     */
    message: Choice.Message;
  }

  export namespace Choice {
    /**
     * Log probability information for the choice.
     */
    export interface Logprobs {
      /**
       * A list of message content tokens with log probability information.
       */
      content: Array<Shared.ChatCompletionTokenLogprob> | null;

      /**
       * A list of message refusal tokens with log probability information.
       */
      refusal: Array<Shared.ChatCompletionTokenLogprob> | null;
    }

    /**
     * A chat completion message generated by the model.
     */
    export interface Message {
      /**
       * The contents of the message.
       */
      content: string | null;

      /**
       * The reasoning content generated by the model.
       */
      reasoning_content: string | null;

      /**
       * The refusal message generated by the model.
       */
      refusal: string | null;

      /**
       * The role of the author of this message.
       */
      role: 'assistant';

      /**
       * The tool calls generated by the model, such as function calls.
       */
      tool_calls?: Array<Message.ToolCall>;
    }

    export namespace Message {
      export interface ToolCall {
        /**
         * The ID of the tool call.
         */
        id: string;

        /**
         * The function that the model called.
         */
        function: ToolCall.Function;

        /**
         * The type of the tool. Currently, only `function` is supported.
         */
        type: 'function';
      }

      export namespace ToolCall {
        /**
         * The function that the model called.
         */
        export interface Function {
          /**
           * The arguments to call the function with, as generated by the model in JSON
           * format. Note that the model does not always generate valid JSON, and may
           * hallucinate parameters not defined by your function schema. Validate the
           * arguments in your code before calling your function.
           */
          arguments: string;

          /**
           * The name of the function to call.
           */
          name: string;
        }
      }
    }
  }
}

export type CompletionCreateParams = CompletionCreateParamsNonStreaming | CompletionCreateParamsStreaming;

export interface CompletionCreateParamsBase {
  /**
   * A list of messages comprising the conversation so far.
   */
  messages: Array<
    | CompletionCreateParams.ChatCompletionRequestSystemMessage
    | CompletionCreateParams.ChatCompletionRequestDeveloperMessage
    | CompletionCreateParams.ChatCompletionRequestUserMessage
    | CompletionCreateParams.ChatCompletionRequestAssistantMessage
    | CompletionCreateParams.ChatCompletionRequestToolMessage
  >;

  /**
   * Model ID used to generate the response.
   */
  model: string;

  /**
   * Number between -2.0 and 2.0. Positive values penalize new tokens based on their
   * existing frequency in the text so far, decreasing the model's likelihood to
   * repeat the same line verbatim.
   */
  frequency_penalty?: number | null;

  /**
   * Modify the likelihood of specified tokens appearing in the completion.
   *
   * Accepts a JSON object that maps tokens (specified by their token ID in the
   * tokenizer) to an associated bias value from -100 to 100. Mathematically, the
   * bias is added to the logits generated by the model prior to sampling. The exact
   * effect will vary per model, but values between -1 and 1 should decrease or
   * increase likelihood of selection; values like -100 or 100 should result in a ban
   * or exclusive selection of the relevant token.
   */
  logit_bias?: { [key: string]: number } | null;

  /**
   * Whether to return log probabilities of the output tokens or not. If true,
   * returns the log probabilities of each output token returned in the `content` of
   * `message`.
   */
  logprobs?: boolean | null;

  /**
   * The maximum number of completion tokens that may be used over the course of the
   * run. The run will make a best effort to use only the number of completion tokens
   * specified, across multiple turns of the run.
   */
  max_completion_tokens?: number | null;

  /**
   * The maximum number of tokens that can be generated in the completion.
   *
   * The token count of your prompt plus `max_tokens` cannot exceed the model's
   * context length.
   */
  max_tokens?: number | null;

  /**
   * Set of 16 key-value pairs that can be attached to an object. This can be useful
   * for storing additional information about the object in a structured format, and
   * querying for objects via API or the dashboard.
   *
   * Keys are strings with a maximum length of 64 characters. Values are strings with
   * a maximum length of 512 characters.
   */
  metadata?: { [key: string]: string } | null;

  /**
   * How many chat completion choices to generate for each input message. Note that
   * you will be charged based on the number of generated tokens across all of the
   * choices. Keep `n` as `1` to minimize costs.
   */
  n?: number | null;

  /**
   * Number between -2.0 and 2.0. Positive values penalize new tokens based on
   * whether they appear in the text so far, increasing the model's likelihood to
   * talk about new topics.
   */
  presence_penalty?: number | null;

  /**
   * Up to 4 sequences where the API will stop generating further tokens. The
   * returned text will not contain the stop sequence.
   */
  stop?: string | null | Array<string>;

  /**
   * If set to true, the model response data will be streamed to the client as it is
   * generated using server-sent events.
   */
  stream?: boolean | null;

  /**
   * Options for streaming response. Only set this when you set `stream: true`.
   */
  stream_options?: CompletionCreateParams.StreamOptions | 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
   * focused and deterministic. We generally recommend altering this or `top_p` but
   * not both.
   */
  temperature?: number | null;

  /**
   * Controls which (if any) tool is called by the model. `none` means the model will
   * not call any tool and instead generates a message. `auto` means the model can
   * pick between generating a message or calling one or more tools. `required` means
   * the model must call one or more tools. Specifying a particular tool via
   * `{"type": "function", "function": {"name": "my_function"}}` forces the model to
   * call that tool.
   *
   * `none` is the default when no tools are present. `auto` is the default if tools
   * are present.
   */
  tool_choice?: 'none' | 'auto' | 'required' | CompletionCreateParams.ChatCompletionNamedToolChoice;

  /**
   * A list of tools the model may call. Currently, only functions are supported as a
   * tool.
   */
  tools?: Array<CompletionCreateParams.Tool>;

  /**
   * An integer between 0 and 20 specifying the number of most likely tokens to
   * return at each token position, each with an associated log probability.
   * `logprobs` must be set to `true` if this parameter is used.
   */
  top_logprobs?: number | null;

  /**
   * An alternative to sampling with temperature, called nucleus sampling, where the
   * model considers the results of the tokens with top_p probability mass. So 0.1
   * means only the tokens comprising the top 10% probability mass are considered.
   *
   * We generally recommend altering this or `temperature` but not both.
   */
  top_p?: number | null;

  /**
   * A unique identifier representing your end-user, which can help DigitalOcean to
   * monitor and detect abuse.
   */
  user?: string;

  [k: string]: unknown;
}

export namespace CompletionCreateParams {
  /**
   * System-provided instructions that the model should follow, regardless of
   * messages sent by the user.
   */
  export interface ChatCompletionRequestSystemMessage {
    /**
     * The contents of the system message.
     */
    content: string | Array<string | ChatCompletionRequestSystemMessage.UnionMember1>;

    /**
     * The role of the messages author, in this case `system`.
     */
    role: 'system';
  }

  export namespace ChatCompletionRequestSystemMessage {
    /**
     * Content part with type and text
     */
    export interface UnionMember1 {
      /**
       * The text content
       */
      text: string;

      /**
       * The type of content part
       */
      type: 'text';
    }
  }

  /**
   * Developer-provided instructions that the model should follow, regardless of
   * messages sent by the user.
   */
  export interface ChatCompletionRequestDeveloperMessage {
    /**
     * The contents of the developer message.
     */
    content: string | Array<string | ChatCompletionRequestDeveloperMessage.UnionMember1>;

    /**
     * The role of the messages author, in this case `developer`.
     */
    role: 'developer';
  }

  export namespace ChatCompletionRequestDeveloperMessage {
    /**
     * Content part with type and text
     */
    export interface UnionMember1 {
      /**
       * The text content
       */
      text: string;

      /**
       * The type of content part
       */
      type: 'text';
    }
  }

  /**
   * Messages sent by an end user, containing prompts or additional context
   * information.
   */
  export interface ChatCompletionRequestUserMessage {
    /**
     * The contents of the user message.
     */
    content: string | Array<string | ChatCompletionRequestUserMessage.UnionMember1>;

    /**
     * The role of the messages author, in this case `user`.
     */
    role: 'user';
  }

  export namespace ChatCompletionRequestUserMessage {
    /**
     * Content part with type and text
     */
    export interface UnionMember1 {
      /**
       * The text content
       */
      text: string;

      /**
       * The type of content part
       */
      type: 'text';
    }
  }

  /**
   * Messages sent by the model in response to user messages.
   */
  export interface ChatCompletionRequestAssistantMessage {
    /**
     * The role of the messages author, in this case `assistant`.
     */
    role: 'assistant';

    /**
     * The contents of the assistant message.
     */
    content?: string | Array<string | ChatCompletionRequestAssistantMessage.UnionMember1> | null;

    /**
     * The tool calls generated by the model, such as function calls.
     */
    tool_calls?: Array<ChatCompletionRequestAssistantMessage.ToolCall>;
  }

  export namespace ChatCompletionRequestAssistantMessage {
    /**
     * Content part with type and text
     */
    export interface UnionMember1 {
      /**
       * The text content
       */
      text: string;

      /**
       * The type of content part
       */
      type: 'text';
    }

    export interface ToolCall {
      /**
       * The ID of the tool call.
       */
      id: string;

      /**
       * The function that the model called.
       */
      function: ToolCall.Function;

      /**
       * The type of the tool. Currently, only `function` is supported.
       */
      type: 'function';
    }

    export namespace ToolCall {
      /**
       * The function that the model called.
       */
      export interface Function {
        /**
         * The arguments to call the function with, as generated by the model in JSON
         * format. Note that the model does not always generate valid JSON, and may
         * hallucinate parameters not defined by your function schema. Validate the
         * arguments in your code before calling your function.
         */
        arguments: string;

        /**
         * The name of the function to call.
         */
        name: string;
      }
    }
  }

  export interface ChatCompletionRequestToolMessage {
    /**
     * The contents of the tool message.
     */
    content: string;

    /**
     * The role of the messages author, in this case `tool`.
     */
    role: 'tool';

    /**
     * Tool call that this message is responding to.
     */
    tool_call_id: string;
  }

  /**
   * Options for streaming response. Only set this when you set `stream: true`.
   */
  export interface StreamOptions {
    /**
     * 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.
     * **NOTE:** If the stream is interrupted, you may not receive the final usage
     * chunk which contains the total token usage for the request.
     */
    include_usage?: boolean;
  }

  /**
   * Specifies a tool the model should use. Use to force the model to call a specific
   * function.
   */
  export interface ChatCompletionNamedToolChoice {
    function: ChatCompletionNamedToolChoice.Function;

    /**
     * The type of the tool. Currently, only `function` is supported.
     */
    type: 'function';
  }

  export namespace ChatCompletionNamedToolChoice {
    export interface Function {
      /**
       * The name of the function to call.
       */
      name: string;
    }
  }

  export interface Tool {
    function: Tool.Function;

    /**
     * The type of the tool. Currently, only `function` is supported.
     */
    type: 'function';
  }

  export namespace Tool {
    export interface Function {
      /**
       * The name of the function to be called. Must be a-z, A-Z, 0-9, or contain
       * underscores and dashes, with a maximum length of 64.
       */
      name: string;

      /**
       * A description of what the function does, used by the model to choose when and
       * how to call the function.
       */
      description?: string;

      /**
       * The parameters the functions accepts, described as a JSON Schema object. See the
       * [guide](/docs/guides/function-calling) for examples, and the
       * [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
       * documentation about the format.
       *
       * Omitting `parameters` defines a function with an empty parameter list.
       */
      parameters?: { [key: string]: unknown };
    }
  }

  export type CompletionCreateParamsNonStreaming = CompletionsAPI.CompletionCreateParamsNonStreaming;
  export type CompletionCreateParamsStreaming = CompletionsAPI.CompletionCreateParamsStreaming;
}

export interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
  /**
   * If set to true, the model response data will be streamed to the client as it is
   * generated using server-sent events.
   */
  stream?: false | null;

  [k: string]: unknown;
}

export interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
  /**
   * If set to true, the model response data will be streamed to the client as it is
   * generated using server-sent events.
   */
  stream: true;

  [k: string]: unknown;
}

export declare namespace Completions {
  export {
    type CompletionCreateResponse as CompletionCreateResponse,
    type CompletionCreateParams as CompletionCreateParams,
    type CompletionCreateParamsNonStreaming as CompletionCreateParamsNonStreaming,
    type CompletionCreateParamsStreaming as CompletionCreateParamsStreaming,
  };
}