@anthropic-ai/sdk 0.10.1 → 0.11.0

package/src/resources/beta/messages.ts

@@ -0,0 +1,605 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../../core";
+import { APIPromise } from "../../core";
+import { APIResource } from "../../resource";
+import { MessageStream } from "../../lib/MessageStream";
+export { MessageStream } from "../../lib/MessageStream";
+import * as MessagesAPI from "./messages";
+import { Stream } from "../../streaming";
+
+export class Messages extends APIResource {
+  /**
+   * Create a Message.
+   *
+   * The Messages API is currently in beta.
+   */
+  create(params: MessageCreateParamsNonStreaming, options?: Core.RequestOptions): APIPromise<Message>;
+  create(
+    params: MessageCreateParamsStreaming,
+    options?: Core.RequestOptions,
+  ): APIPromise<Stream<MessageStreamEvent>>;
+  create(
+    params: MessageCreateParamsBase,
+    options?: Core.RequestOptions,
+  ): APIPromise<Stream<MessageStreamEvent> | Message>;
+  create(
+    params: MessageCreateParams,
+    options?: Core.RequestOptions,
+  ): APIPromise<Message> | APIPromise<Stream<MessageStreamEvent>> {
+    const { 'anthropic-beta': anthropicBeta, 'x-api-key': xAPIKey, ...body } = params;
+    return this._client.post('/v1/messages', {
+      body,
+      timeout: 600000,
+      ...options,
+      headers: {
+        'Anthropic-Beta': 'messages-2023-12-15',
+        'anthropic-beta': anthropicBeta,
+        'x-api-key': xAPIKey || '',
+        ...options?.headers,
+      },
+      stream: params.stream ?? false,
+    }) as APIPromise<Message> | APIPromise<Stream<MessageStreamEvent>>;
+  }
+
+  /**
+   * Create a Message stream
+   */
+  stream(body: MessageStreamParams, options?: Core.RequestOptions): MessageStream {
+    return MessageStream.createMessage(this._client.beta.messages, body, options);
+  }
+}
+
+export interface ContentBlock {
+  text: string;
+
+  type: 'text';
+}
+
+export interface ContentBlockDeltaEvent {
+  delta: TextDelta;
+
+  index: number;
+
+  type: 'content_block_delta';
+}
+
+export interface ContentBlockStartEvent {
+  content_block: ContentBlock;
+
+  index: number;
+
+  type: 'content_block_start';
+}
+
+export interface ContentBlockStopEvent {
+  index: number;
+
+  type: 'content_block_stop';
+}
+
+export interface Message {
+  /**
+   * Unique object identifier.
+   *
+   * The format and length of IDs may change over time.
+   */
+  id: string;
+
+  /**
+   * Content generated by the model.
+   *
+   * This is an array of content blocks, each of which has a `type` that determines
+   * its shape. Currently, the only `type` available is `"text"`.
+   *
+   * Example:
+   *
+   * ```json
+   * [{ "type": "text", "text": "Hi, I'm Claude." }]
+   * ```
+   *
+   * If the request input `messages` ended with an `assistant` turn, then the
+   * response `content` will continue directly from that last turn. You can use this
+   * to constrain the model's output.
+   *
+   * For example, if the input `messages` were:
+   *
+   * ```json
+   * [
+   *   {
+   *     "role": "user",
+   *     "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"
+   *   },
+   *   {
+   *     "role": "assistant",
+   *     "content": "The best answer is ("
+   *   }
+   * ]
+   * ```
+   *
+   * Then the response `content` might be:
+   *
+   * ```json
+   * [{ "type": "text", "text": "B)" }]
+   * ```
+   */
+  content: Array<ContentBlock>;
+
+  /**
+   * The model that handled the request.
+   */
+  model: string;
+
+  /**
+   * Conversational role of the generated message.
+   *
+   * This will always be `"assistant"`.
+   */
+  role: 'assistant';
+
+  /**
+   * The reason that we stopped.
+   *
+   * This may be one the following values:
+   *
+   * - `"end_turn"`: the model reached a natural stopping point
+   * - `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum
+   * - `"stop_sequence"`: one of your provided custom `stop_sequences` was generated
+   *
+   * Note that these values are different than those in `/v1/complete`, where
+   * `end_turn` and `stop_sequence` were not differentiated.
+   *
+   * In non-streaming mode this value is always non-null. In streaming mode, it is
+   * null in the `message_start` event and non-null otherwise.
+   */
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
+
+  /**
+   * Which custom stop sequence was generated.
+   *
+   * This value will be non-null if one of your custom stop sequences was generated.
+   */
+  stop_sequence: string | null;
+
+  type: 'message';
+}
+
+export interface MessageDeltaEvent {
+  delta: MessageDeltaEvent.Delta;
+
+  type: 'message_delta';
+}
+
+export namespace MessageDeltaEvent {
+  export interface Delta {
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
+
+    stop_sequence: string | null;
+  }
+}
+
+export interface MessageParam {
+  content: string | Array<TextBlock>;
+
+  role: 'user' | 'assistant';
+}
+
+export interface MessageStartEvent {
+  message: Message;
+
+  type: 'message_start';
+}
+
+export interface MessageStopEvent {
+  type: 'message_stop';
+}
+
+export type MessageStreamEvent =
+  | MessageStartEvent
+  | MessageDeltaEvent
+  | MessageStopEvent
+  | ContentBlockStartEvent
+  | ContentBlockDeltaEvent
+  | ContentBlockStopEvent;
+
+export interface TextBlock {
+  text: string;
+
+  type?: 'text';
+}
+
+export interface TextDelta {
+  text: string;
+
+  type: 'text_delta';
+}
+
+export type MessageCreateParams = MessageCreateParamsNonStreaming | MessageCreateParamsStreaming;
+
+export interface MessageCreateParamsBase {
+  /**
+   * Body param: The maximum number of tokens to generate before stopping.
+   *
+   * Note that our models may stop _before_ reaching this maximum. This parameter
+   * only specifies the absolute maximum number of tokens to generate.
+   *
+   * Different models have different maximum values for this parameter. See
+   * [input and output sizes](https://docs.anthropic.com/claude/reference/input-and-output-sizes)
+   * for details.
+   */
+  max_tokens: number;
+
+  /**
+   * Body param: Input messages.
+   *
+   * Our models are trained to operate on alternating `user` and `assistant`
+   * conversational turns. When creating a new `Message`, you specify the prior
+   * conversational turns with the `messages` parameter, and the model then generates
+   * the next `Message` in the conversation.
+   *
+   * Each input message must be an object with a `role` and `content`. You can
+   * specify a single `user`-role message, or you can include multiple `user` and
+   * `assistant` messages. The first message must always use the `user` role.
+   *
+   * If the final message uses the `assistant` role, the response content will
+   * continue immediately from the content in that message. This can be used to
+   * constrain part of the model's response.
+   *
+   * Example with a single `user` message:
+   *
+   * ```json
+   * [{ "role": "user", "content": "Hello, Claude" }]
+   * ```
+   *
+   * Example with multiple conversational turns:
+   *
+   * ```json
+   * [
+   *   { "role": "user", "content": "Hello there." },
+   *   { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" },
+   *   { "role": "user", "content": "Can you explain LLMs in plain English?" }
+   * ]
+   * ```
+   *
+   * Example with a partially-filled response from Claude:
+   *
+   * ```json
+   * [
+   *   { "role": "user", "content": "Please describe yourself using only JSON" },
+   *   { "role": "assistant", "content": "Here is my JSON description:\n{" }
+   * ]
+   * ```
+   *
+   * Each input message `content` may be either a single `string` or an array of
+   * content blocks, where each block has a specific `type`. Using a `string` is
+   * shorthand for an array of one content block of type `"text"`. The following
+   * input messages are equivalent:
+   *
+   * ```json
+   * { "role": "user", "content": "Hello, Claude" }
+   * ```
+   *
+   * ```json
+   * { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] }
+   * ```
+   *
+   * During beta, the Messages API only accepts content blocks of type `"text"`, and
+   * at most one block per message.
+   *
+   * See our
+   * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
+   * for more details on how to best construct prompts.
+   */
+  messages: Array<MessageParam>;
+
+  /**
+   * Body param: The model that will complete your prompt.
+   *
+   * As we improve Claude, we develop new versions of it that you can query. The
+   * `model` parameter controls which version of Claude responds to your request.
+   * Right now we offer two model families: Claude, and Claude Instant. You can use
+   * them by setting `model` to `"claude-2.1"` or `"claude-instant-1.2"`,
+   * respectively.
+   *
+   * See [models](https://docs.anthropic.com/claude/reference/selecting-a-model) for
+   * additional details and options.
+   */
+  model: string;
+
+  /**
+   * Header param: Beta version header.
+   *
+   * During the beta, the Messages API requires sending the
+   * `anthropic-beta: messages-2023-12-15` header. This is a beta-specific header
+   * that is required in addition to the normal `anthropic-version` header. If you
+   * are using our SDKs, both of these headers will be sent automatically.
+   */
+  'anthropic-beta': string;
+
+  /**
+   * Body param: An object describing metadata about the request.
+   */
+  metadata?: MessageCreateParams.Metadata;
+
+  /**
+   * Body param: Custom text sequences that will cause the model to stop generating.
+   *
+   * Our models will normally stop when they have naturally completed their turn,
+   * which will result in a response `stop_reason` of `"end_turn"`.
+   *
+   * If you want the model to stop generating when it encounters custom strings of
+   * text, you can use the `stop_sequences` parameter. If the model encounters one of
+   * the custom sequences, the response `stop_reason` value will be `"stop_sequence"`
+   * and the response `stop_sequence` value will contain the matched stop sequence.
+   */
+  stop_sequences?: Array<string>;
+
+  /**
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
+   *
+   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
+   * details.
+   */
+  stream?: boolean;
+
+  /**
+   * Body param: System prompt.
+   *
+   * A system prompt is a way of providing context and instructions to Claude, such
+   * as specifying a particular goal or role. See our
+   * [guide to system prompts](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts).
+   */
+  system?: string;
+
+  /**
+   * Body param: Amount of randomness injected into the response.
+   *
+   * Defaults to 1. Ranges from 0 to 1. Use temp closer to 0 for analytical /
+   * multiple choice, and closer to 1 for creative and generative tasks.
+   */
+  temperature?: number;
+
+  /**
+   * Body param: Only sample from the top K options for each subsequent token.
+   *
+   * Used to remove "long tail" low probability responses.
+   * [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
+   */
+  top_k?: number;
+
+  /**
+   * Body param: Use nucleus sampling.
+   *
+   * In nucleus sampling, we compute the cumulative distribution over all the options
+   * for each subsequent token in decreasing probability order and cut it off once it
+   * reaches a particular probability specified by `top_p`. You should either alter
+   * `temperature` or `top_p`, but not both.
+   */
+  top_p?: number;
+
+  /**
+   * Header param:
+   */
+  'x-api-key'?: string;
+}
+
+export namespace MessageCreateParams {
+  /**
+   * An object describing metadata about the request.
+   */
+  export interface Metadata {
+    /**
+     * An external identifier for the user who is associated with the request.
+     *
+     * This should be a uuid, hash value, or other opaque identifier. Anthropic may use
+     * this id to help detect abuse. Do not include any identifying information such as
+     * name, email address, or phone number.
+     */
+    user_id?: string;
+  }
+
+  export type MessageCreateParamsNonStreaming = MessagesAPI.MessageCreateParamsNonStreaming;
+  export type MessageCreateParamsStreaming = MessagesAPI.MessageCreateParamsStreaming;
+}
+
+export interface MessageCreateParamsNonStreaming extends MessageCreateParamsBase {
+  /**
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
+   *
+   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
+   * details.
+   */
+  stream?: false;
+}
+
+export interface MessageCreateParamsStreaming extends MessageCreateParamsBase {
+  /**
+   * Body param: Whether to incrementally stream the response using server-sent
+   * events.
+   *
+   * See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
+   * details.
+   */
+  stream: true;
+}
+
+export interface MessageStreamParams {
+  /**
+   * The maximum number of tokens to generate before stopping.
+   *
+   * Note that our models may stop _before_ reaching this maximum. This parameter
+   * only specifies the absolute maximum number of tokens to generate.
+   *
+   * Different models have different maximum values for this parameter. See
+   * [input and output sizes](https://docs.anthropic.com/claude/reference/input-and-output-sizes)
+   * for details.
+   */
+  max_tokens: number;
+
+  /**
+   * Input messages.
+   *
+   * Our models are trained to operate on alternating `user` and `assistant`
+   * conversational turns. When creating a new `Message`, you specify the prior
+   * conversational turns with the `messages` parameter, and the model then generates
+   * the next `Message` in the conversation.
+   *
+   * Each input message must be an object with a `role` and `content`. You can
+   * specify a single `user`-role message, or you can include multiple `user` and
+   * `assistant` messages. The first message must always use the `user` role.
+   *
+   * If the final message uses the `assistant` role, the response content will
+   * continue immediately from the content in that message. This can be used to
+   * constrain part of the model's response.
+   *
+   * Example with a single `user` message:
+   *
+   * ```json
+   * [{ "role": "user", "content": "Hello, Claude" }]
+   * ```
+   *
+   * Example with multiple conversational turns:
+   *
+   * ```json
+   * [
+   *   { "role": "user", "content": "Hello there." },
+   *   { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" },
+   *   { "role": "user", "content": "Can you explain LLMs in plain English?" }
+   * ]
+   * ```
+   *
+   * Example with a partially-filled response from Claude:
+   *
+   * ```json
+   * [
+   *   { "role": "user", "content": "Please describe yourself using only JSON" },
+   *   { "role": "assistant", "content": "Here is my JSON description:\n{" }
+   * ]
+   * ```
+   *
+   * Each input message `content` may be either a single `string` or an array of
+   * content blocks, where each block has a specific `type`. Using a `string` is
+   * shorthand for an array of one content block of type `"text"`. The following
+   * input messages are equivalent:
+   *
+   * ```json
+   * { "role": "user", "content": "Hello, Claude" }
+   * ```
+   *
+   * ```json
+   * { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] }
+   * ```
+   *
+   * During beta, the Messages API only accepts content blocks of type `"text"`, and
+   * at most one block per message.
+   *
+   * See our
+   * [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
+   * for more details on how to best construct prompts.
+   */
+  messages: Array<MessageParam>;
+
+  /**
+   * The model that will complete your prompt.
+   *
+   * As we improve Claude, we develop new versions of it that you can query. The
+   * `model` parameter controls which version of Claude responds to your request.
+   * Right now we offer two model families: Claude, and Claude Instant. You can use
+   * them by setting `model` to `"claude-2.1"` or `"claude-instant-1.2"`,
+   * respectively.
+   *
+   * See [models](https://docs.anthropic.com/claude/reference/selecting-a-model) for
+   * additional details and options.
+   */
+  model: string;
+
+  /**
+   * An object describing metadata about the request.
+   */
+  metadata?: MessageStreamParams.Metadata;
+
+  /**
+   * Custom text sequences that will cause the model to stop generating.
+   *
+   * Our models will normally stop when they have naturally completed their turn,
+   * which will result in a response `stop_reason` of `"end_turn"`.
+   *
+   * If you want the model to stop generating when it encounters custom strings of
+   * text, you can use the `stop_sequences` parameter. If the model encounters one of
+   * the custom sequences, the response `stop_reason` value will be `"stop_sequence"`
+   * and the response `stop_sequence` value will contain the matched stop sequence.
+   */
+  stop_sequences?: Array<string>;
+
+  /**
+   * System prompt.
+   *
+   * A system prompt is a way of providing context and instructions to Claude, such
+   * as specifying a particular goal or role. See our
+   * [guide to system prompts](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts).
+   */
+  system?: string;
+
+  /**
+   * Amount of randomness injected into the response.
+   *
+   * Defaults to 1. Ranges from 0 to 1. Use temp closer to 0 for analytical /
+   * multiple choice, and closer to 1 for creative and generative tasks.
+   */
+  temperature?: number;
+
+  /**
+   * Only sample from the top K options for each subsequent token.
+   *
+   * Used to remove "long tail" low probability responses.
+   * [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277).
+   */
+  top_k?: number;
+
+  /**
+   * Use nucleus sampling.
+   *
+   * In nucleus sampling, we compute the cumulative distribution over all the options
+   * for each subsequent token in decreasing probability order and cut it off once it
+   * reaches a particular probability specified by `top_p`. You should either alter
+   * `temperature` or `top_p`, but not both.
+   */
+  top_p?: number;
+}
+
+export namespace MessageStreamParams {
+  /**
+   * An object describing metadata about the request.
+   */
+  export interface Metadata {
+    /**
+     * An external identifier for the user who is associated with the request.
+     *
+     * This should be a uuid, hash value, or other opaque identifier. Anthropic may use
+     * this id to help detect abuse. Do not include any identifying information such as
+     * name, email address, or phone number.
+     */
+    user_id?: string;
+  }
+}
+
+export namespace Messages {
+  export import ContentBlock = MessagesAPI.ContentBlock;
+  export import ContentBlockDeltaEvent = MessagesAPI.ContentBlockDeltaEvent;
+  export import ContentBlockStartEvent = MessagesAPI.ContentBlockStartEvent;
+  export import ContentBlockStopEvent = MessagesAPI.ContentBlockStopEvent;
+  export import Message = MessagesAPI.Message;
+  export import MessageDeltaEvent = MessagesAPI.MessageDeltaEvent;
+  export import MessageParam = MessagesAPI.MessageParam;
+  export import MessageStartEvent = MessagesAPI.MessageStartEvent;
+  export import MessageStopEvent = MessagesAPI.MessageStopEvent;
+  export import MessageStreamEvent = MessagesAPI.MessageStreamEvent;
+  export import TextBlock = MessagesAPI.TextBlock;
+  export import TextDelta = MessagesAPI.TextDelta;
+  export import MessageCreateParams = MessagesAPI.MessageCreateParams;
+  export import MessageCreateParamsNonStreaming = MessagesAPI.MessageCreateParamsNonStreaming;
+  export import MessageCreateParamsStreaming = MessagesAPI.MessageCreateParamsStreaming;
+  export import MessageStreamParams = MessagesAPI.MessageStreamParams;
+}