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 {
  /**
   * Generate text completions using the specified model and prompt. This endpoint is
   * useful for text generation tasks that don't require conversational context.
   *
   * @example
   * ```ts
   * const completion = await client.completions.create({
   *   model: 'palmyra-x-003-instruct',
   *   prompt: 'Write me an SEO article about...',
   * });
   * ```
   */
  create(body: CompletionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<Completion>;
  create(
    body: CompletionCreateParamsStreaming,
    options?: RequestOptions,
  ): APIPromise<Stream<CompletionChunk>>;
  create(
    body: CompletionCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<CompletionChunk> | Completion>;
  create(
    body: CompletionCreateParams,
    options?: RequestOptions,
  ): APIPromise<Completion> | APIPromise<Stream<CompletionChunk>> {
    return this._client.post('/v1/completions', { body, ...options, stream: body.stream ?? false }) as
      | APIPromise<Completion>
      | APIPromise<Stream<CompletionChunk>>;
  }
}

export interface Completion {
  /**
   * A list of choices generated by the model, each containing the text of the
   * completion and associated metadata such as log probabilities.
   */
  choices: Array<Completion.Choice>;

  /**
   * The identifier of the model that was used to generate the responses in the
   * 'choices' array.
   */
  model?: string;
}

export namespace Completion {
  export interface Choice {
    /**
     * The generated text output from the model, which forms the main content of the
     * response.
     */
    text: string;

    log_probs?: Shared.Logprobs | null;
  }
}

export interface CompletionChunk {
  value: string;
}

export interface CompletionParams {
  /**
   * The [ID of the model](https://dev.writer.com/home/models) to use for generating
   * text. Supports `palmyra-x5`, `palmyra-x4`, `palmyra-fin`, `palmyra-med`,
   * `palmyra-creative`, and `palmyra-x-003-instruct`.
   */
  model: string;

  /**
   * The input text that the model will process to generate a response.
   */
  prompt: string;

  /**
   * Specifies the number of completions to generate and return the best one. Useful
   * for generating multiple outputs and choosing the best based on some criteria.
   */
  best_of?: number;

  /**
   * The maximum number of tokens that the model can generate in the response.
   */
  max_tokens?: number;

  /**
   * A seed used to initialize the random number generator for the model, ensuring
   * reproducibility of the output when the same inputs are provided.
   */
  random_seed?: number;

  /**
   * Specifies stopping conditions for the model's output generation. This can be an
   * array of strings or a single string that the model will look for as a signal to
   * stop generating further tokens.
   */
  stop?: Array<string> | string;

  /**
   * Determines whether the model's output should be streamed. If true, the output is
   * generated and sent incrementally, which can be useful for real-time
   * applications.
   */
  stream?: boolean;

  /**
   * Controls the randomness of the model's outputs. Higher values lead to more
   * random outputs, while lower values make the model more deterministic.
   */
  temperature?: number;

  /**
   * Used to control the nucleus sampling, where only the most probable tokens with a
   * cumulative probability of top_p are considered for sampling, providing a way to
   * fine-tune the randomness of predictions.
   */
  top_p?: number;
}

export type CompletionCreateParams = CompletionCreateParamsNonStreaming | CompletionCreateParamsStreaming;

export interface CompletionCreateParamsBase {
  /**
   * The [ID of the model](https://dev.writer.com/home/models) to use for generating
   * text. Supports `palmyra-x5`, `palmyra-x4`, `palmyra-fin`, `palmyra-med`,
   * `palmyra-creative`, and `palmyra-x-003-instruct`.
   */
  model: string;

  /**
   * The input text that the model will process to generate a response.
   */
  prompt: string;

  /**
   * Specifies the number of completions to generate and return the best one. Useful
   * for generating multiple outputs and choosing the best based on some criteria.
   */
  best_of?: number;

  /**
   * The maximum number of tokens that the model can generate in the response.
   */
  max_tokens?: number;

  /**
   * A seed used to initialize the random number generator for the model, ensuring
   * reproducibility of the output when the same inputs are provided.
   */
  random_seed?: number;

  /**
   * Specifies stopping conditions for the model's output generation. This can be an
   * array of strings or a single string that the model will look for as a signal to
   * stop generating further tokens.
   */
  stop?: Array<string> | string;

  /**
   * Determines whether the model's output should be streamed. If true, the output is
   * generated and sent incrementally, which can be useful for real-time
   * applications.
   */
  stream?: boolean;

  /**
   * Controls the randomness of the model's outputs. Higher values lead to more
   * random outputs, while lower values make the model more deterministic.
   */
  temperature?: number;

  /**
   * Used to control the nucleus sampling, where only the most probable tokens with a
   * cumulative probability of top_p are considered for sampling, providing a way to
   * fine-tune the randomness of predictions.
   */
  top_p?: number;
}

export namespace CompletionCreateParams {
  export type CompletionCreateParamsNonStreaming = CompletionsAPI.CompletionCreateParamsNonStreaming;
  export type CompletionCreateParamsStreaming = CompletionsAPI.CompletionCreateParamsStreaming;
}

export interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
  /**
   * Determines whether the model's output should be streamed. If true, the output is
   * generated and sent incrementally, which can be useful for real-time
   * applications.
   */
  stream?: false;
}

export interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
  /**
   * Determines whether the model's output should be streamed. If true, the output is
   * generated and sent incrementally, which can be useful for real-time
   * applications.
   */
  stream: true;
}

export declare namespace Completions {
  export {
    type Completion as Completion,
    type CompletionChunk as CompletionChunk,
    type CompletionParams as CompletionParams,
    type CompletionCreateParams as CompletionCreateParams,
    type CompletionCreateParamsNonStreaming as CompletionCreateParamsNonStreaming,
    type CompletionCreateParamsStreaming as CompletionCreateParamsStreaming,
  };
}