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

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

export class Completions extends APIResource {
  /**
   * Generates a legacy text completion from a raw `prompt` (a string or list of
   * strings).
   *
   * Use this endpoint for non-chat, prompt-in/text-out inference using the OpenAI
   * text-completion contract; use /v5/chat/completions when you have a structured
   * `messages` array, /v5/responses for the OpenAI Responses API, and /v5/inference
   * for payloads that follow no OpenAI schema. The model is selected from `model`
   * given as `vendor/name` and routed to the matching per-vendor gateway. When
   * `stream` is set the response is delivered as server-sent events; otherwise a
   * single `text_completion` object is returned. Token usage is recorded for the
   * account, read from the final chunk on streaming responses.
   */
  create(body: CompletionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<Completion>;
  create(body: CompletionCreateParamsStreaming, options?: RequestOptions): APIPromise<Stream<Completion>>;
  create(
    body: CompletionCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<Completion> | Completion>;
  create(
    body: CompletionCreateParams,
    options?: RequestOptions,
  ): APIPromise<Completion> | APIPromise<Stream<Completion>> {
    return this._client.post('/v5/completions', { body, ...options, stream: body.stream ?? false }) as
      | APIPromise<Completion>
      | APIPromise<Stream<Completion>>;
  }
}

export interface Completion {
  id: string;

  choices: Array<Completion.Choice>;

  created: number;

  model: string;

  object?: 'text_completion';

  system_fingerprint?: string;

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

  [k: string]: unknown;
}

export namespace Completion {
  export interface Choice {
    finish_reason: 'stop' | 'length' | 'content_filter';

    index: number;

    text: string;

    logprobs?: Choice.Logprobs;

    [k: string]: unknown;
  }

  export namespace Choice {
    export interface Logprobs {
      text_offset?: Array<number>;

      token_logprobs?: Array<number>;

      tokens?: Array<string>;

      top_logprobs?: Array<{ [key: string]: number }>;

      [k: string]: unknown;
    }
  }
}

/**
 * Usage statistics for the completion request.
 */
export interface CompletionUsage {
  completion_tokens: number;

  prompt_tokens: number;

  total_tokens: number;

  /**
   * Breakdown of tokens used in a completion.
   */
  completion_tokens_details?: CompletionUsage.CompletionTokensDetails;

  /**
   * Breakdown of tokens used in the prompt.
   */
  prompt_tokens_details?: CompletionUsage.PromptTokensDetails;

  [k: string]: unknown;
}

export namespace CompletionUsage {
  /**
   * Breakdown of tokens used in a completion.
   */
  export interface CompletionTokensDetails {
    accepted_prediction_tokens?: number;

    audio_tokens?: number;

    reasoning_tokens?: number;

    rejected_prediction_tokens?: number;

    [k: string]: unknown;
  }

  /**
   * Breakdown of tokens used in the prompt.
   */
  export interface PromptTokensDetails {
    audio_tokens?: number;

    cached_tokens?: number;

    [k: string]: unknown;
  }
}

export type CompletionCreateParams = CompletionCreateParamsNonStreaming | CompletionCreateParamsStreaming;

export interface CompletionCreateParamsBase {
  /**
   * model specified as `model_vendor/model`, for example `openai/gpt-4o`
   */
  model: string;

  /**
   * The prompt to generate completions for, encoded as a string
   */
  prompt: string | Array<string>;

  /**
   * Generates best_of completions server-side and returns the best one. Must be
   * greater than n when used together.
   */
  best_of?: number;

  /**
   * Echo back the prompt in addition to the completion
   */
  echo?: boolean;

  /**
   * Number between -2.0 and 2.0. Positive values penalize new tokens based on their
   * existing frequency in the text.
   */
  frequency_penalty?: number;

  /**
   * Modify the likelihood of specified tokens appearing in the completion. Maps
   * tokens to bias values from -100 to 100.
   */
  logit_bias?: { [key: string]: number };

  /**
   * Include log probabilities of the most likely tokens. Maximum value is 5.
   */
  logprobs?: number;

  /**
   * The maximum number of tokens that can be generated in the completion.
   */
  max_tokens?: number;

  /**
   * How many completions to generate for each prompt.
   */
  n?: number;

  /**
   * Number between -2.0 and 2.0. Positive values penalize new tokens based on their
   * presence in the text so far.
   */
  presence_penalty?: number;

  /**
   * If specified, attempts to generate deterministic samples. Determinism is not
   * guaranteed.
   */
  seed?: number;

  /**
   * Up to 4 sequences where the API will stop generating further tokens.
   */
  stop?: string | Array<string>;

  /**
   * Whether to stream back partial progress. If set, tokens will be sent as
   * data-only server-sent events.
   */
  stream?: boolean;

  /**
   * Options for streaming response. Only set this when stream is True.
   */
  stream_options?: { [key: string]: unknown };

  /**
   * The suffix that comes after a completion of inserted text. Only supported for
   * gpt-3.5-turbo-instruct.
   */
  suffix?: string;

  /**
   * Sampling temperature between 0 and 2. Higher values make output more random,
   * lower more focused.
   */
  temperature?: number;

  /**
   * Alternative to temperature. Consider only tokens with top_p probability mass.
   * Range 0-1.
   */
  top_p?: number;

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

  [k: string]: unknown;
}

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

export interface CompletionCreateParamsNonStreaming extends CompletionCreateParamsBase {
  /**
   * Whether to stream back partial progress. If set, tokens will be sent as
   * data-only server-sent events.
   */
  stream?: false;

  [k: string]: unknown;
}

export interface CompletionCreateParamsStreaming extends CompletionCreateParamsBase {
  /**
   * Whether to stream back partial progress. If set, tokens will be sent as
   * data-only server-sent events.
   */
  stream: true;

  [k: string]: unknown;
}

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