From c2c5841cbc538e2db6d77dd81a44bb44ab87acf9 Mon Sep 17 00:00:00 2001
From: Stainless Bot <107565488+stainless-bot@users.noreply.github.com>
Date: Fri, 2 Feb 2024 20:07:22 +0000
Subject: [PATCH] feat(api): add new usage response fields (#332)

---
 api.md                                        |   2 +
 src/anthropic/resources/beta/messages.py      | 114 +++++++++++++++---
 src/anthropic/resources/completions.py        |  42 ++++---
 src/anthropic/types/beta/__init__.py          |   2 +
 src/anthropic/types/beta/message.py           |   4 +
 .../types/beta/message_create_params.py       |  17 ++-
 .../types/beta/message_delta_event.py         |   4 +
 .../types/beta/message_delta_usage.py         |  10 ++
 src/anthropic/types/beta/usage.py             |  13 ++
 src/anthropic/types/completion.py             |   3 +-
 .../types/completion_create_params.py         |  14 ++-
 tests/lib/streaming/test_messages.py          |   4 +-
 12 files changed, 178 insertions(+), 51 deletions(-)
 create mode 100644 src/anthropic/types/beta/message_delta_usage.py
 create mode 100644 src/anthropic/types/beta/usage.py

diff --git a/api.md b/api.md
index e29a3b71..da916389 100644
--- a/api.md
+++ b/api.md
@@ -30,12 +30,14 @@ from anthropic.types.beta import (
     ContentBlockStopEvent,
     Message,
     MessageDeltaEvent,
+    MessageDeltaUsage,
     MessageParam,
     MessageStartEvent,
     MessageStopEvent,
     MessageStreamEvent,
     TextBlock,
     TextDelta,
+    Usage,
 )
 ```
 
diff --git a/src/anthropic/resources/beta/messages.py b/src/anthropic/resources/beta/messages.py
index 3c83e697..d549bf22 100644
--- a/src/anthropic/resources/beta/messages.py
+++ b/src/anthropic/resources/beta/messages.py
@@ -64,7 +64,15 @@ def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -136,6 +144,11 @@ def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -161,8 +174,8 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           system: System prompt.
 
@@ -221,7 +234,15 @@ def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -293,6 +314,11 @@ def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -306,8 +332,8 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -378,7 +404,15 @@ def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -450,6 +484,11 @@ def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -463,8 +502,8 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -693,7 +732,15 @@ async def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -765,6 +812,11 @@ async def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -790,8 +842,8 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           system: System prompt.
 
@@ -850,7 +902,15 @@ async def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -922,6 +982,11 @@ async def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -935,8 +1000,8 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -1007,7 +1072,15 @@ async def create(
         """
         Create a Message.
 
-        The Messages API is currently in beta.
+        Send a structured list of input messages, and the model will generate the next
+        message in the conversation.
+
+        Messages can be used for either single queries to the model or for multi-turn
+        conversations.
+
+        The Messages API is currently in beta. During beta, you must send the
+        `anthropic-beta: messages-2023-12-15` header in your requests. If you are using
+        our client SDKs, this is handled for you automatically.
 
         Args:
           max_tokens: The maximum number of tokens to generate before stopping.
@@ -1079,6 +1152,11 @@ async def create(
               [guide to prompt design](https://docs.anthropic.com/claude/docs/introduction-to-prompt-design)
               for more details on how to best construct prompts.
 
+              Note that if you want to include a
+              [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+              you can use the top-level `system` parameter — there is no `"system"` role for
+              input messages in the Messages API.
+
           model: The model that will complete your prompt.
 
               As we improve Claude, we develop new versions of it that you can query. The
@@ -1092,8 +1170,8 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
diff --git a/src/anthropic/resources/completions.py b/src/anthropic/resources/completions.py
index c95b0b1e..d672336f 100644
--- a/src/anthropic/resources/completions.py
+++ b/src/anthropic/resources/completions.py
@@ -52,7 +52,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> Completion:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -96,8 +96,9 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           temperature: Amount of randomness injected into the response.
 
@@ -147,7 +148,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> Stream[Completion]:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -183,8 +184,9 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -242,7 +244,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> Completion | Stream[Completion]:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -278,8 +280,9 @@ def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -391,7 +394,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> Completion:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -435,8 +438,9 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           temperature: Amount of randomness injected into the response.
 
@@ -486,7 +490,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> AsyncStream[Completion]:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -522,8 +526,9 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
@@ -581,7 +586,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = 600,
     ) -> Completion | AsyncStream[Completion]:
         """
-        Create a Completion
+        Create a Text Completion
 
         Args:
           max_tokens_to_sample: The maximum number of tokens to generate before stopping.
@@ -617,8 +622,9 @@ async def create(
 
           stream: Whether to incrementally stream the response using server-sent events.
 
-              See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-              details.
+              See
+              [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+              for details.
 
           metadata: An object describing metadata about the request.
 
diff --git a/src/anthropic/types/beta/__init__.py b/src/anthropic/types/beta/__init__.py
index a076d1a0..aef9fea1 100644
--- a/src/anthropic/types/beta/__init__.py
+++ b/src/anthropic/types/beta/__init__.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from .usage import Usage as Usage
 from .message import Message as Message
 from .text_delta import TextDelta as TextDelta
 from .content_block import ContentBlock as ContentBlock
@@ -9,6 +10,7 @@
 from .text_block_param import TextBlockParam as TextBlockParam
 from .message_stop_event import MessageStopEvent as MessageStopEvent
 from .message_delta_event import MessageDeltaEvent as MessageDeltaEvent
+from .message_delta_usage import MessageDeltaUsage as MessageDeltaUsage
 from .message_start_event import MessageStartEvent as MessageStartEvent
 from .message_stream_event import MessageStreamEvent as MessageStreamEvent
 from .message_create_params import MessageCreateParams as MessageCreateParams
diff --git a/src/anthropic/types/beta/message.py b/src/anthropic/types/beta/message.py
index 0b3bd3bd..23dbe1d2 100644
--- a/src/anthropic/types/beta/message.py
+++ b/src/anthropic/types/beta/message.py
@@ -3,6 +3,7 @@
 from typing import List, Optional
 from typing_extensions import Literal
 
+from .usage import Usage
 from ..._models import BaseModel
 from .content_block import ContentBlock
 
@@ -86,3 +87,6 @@ class Message(BaseModel):
     """
 
     type: Literal["message"]
+
+    usage: Usage
+    """Container for the number of tokens used."""
diff --git a/src/anthropic/types/beta/message_create_params.py b/src/anthropic/types/beta/message_create_params.py
index 4cc4d75f..ec7667c5 100644
--- a/src/anthropic/types/beta/message_create_params.py
+++ b/src/anthropic/types/beta/message_create_params.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Union, Optional
 from typing_extensions import Literal, Required, TypedDict
 
 from .message_param import MessageParam
@@ -82,6 +82,11 @@ class MessageCreateParamsBase(TypedDict, total=False):
     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.
+
+    Note that if you want to include a
+    [system prompt](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts),
+    you can use the top-level `system` parameter — there is no `"system"` role for
+    input messages in the Messages API.
     """
 
     model: Required[str]
@@ -145,7 +150,7 @@ class MessageCreateParamsBase(TypedDict, total=False):
 
 
 class Metadata(TypedDict, total=False):
-    user_id: str
+    user_id: Optional[str]
     """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
@@ -158,8 +163,8 @@ class MessageCreateParamsNonStreaming(MessageCreateParamsBase):
     stream: Literal[False]
     """Whether to incrementally stream the response using server-sent events.
 
-    See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-    details.
+    See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+    for details.
     """
 
 
@@ -167,8 +172,8 @@ class MessageCreateParamsStreaming(MessageCreateParamsBase):
     stream: Required[Literal[True]]
     """Whether to incrementally stream the response using server-sent events.
 
-    See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-    details.
+    See [streaming](https://docs.anthropic.com/claude/reference/messages-streaming)
+    for details.
     """
 
 
diff --git a/src/anthropic/types/beta/message_delta_event.py b/src/anthropic/types/beta/message_delta_event.py
index fc291cf4..5639e3bf 100644
--- a/src/anthropic/types/beta/message_delta_event.py
+++ b/src/anthropic/types/beta/message_delta_event.py
@@ -4,6 +4,7 @@
 from typing_extensions import Literal
 
 from ..._models import BaseModel
+from .message_delta_usage import MessageDeltaUsage
 
 __all__ = ["MessageDeltaEvent", "Delta"]
 
@@ -18,3 +19,6 @@ class MessageDeltaEvent(BaseModel):
     delta: Delta
 
     type: Literal["message_delta"]
+
+    usage: MessageDeltaUsage
+    """Container for the number of tokens used."""
diff --git a/src/anthropic/types/beta/message_delta_usage.py b/src/anthropic/types/beta/message_delta_usage.py
new file mode 100644
index 00000000..d5415573
--- /dev/null
+++ b/src/anthropic/types/beta/message_delta_usage.py
@@ -0,0 +1,10 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from ..._models import BaseModel
+
+__all__ = ["MessageDeltaUsage"]
+
+
+class MessageDeltaUsage(BaseModel):
+    output_tokens: int
+    """The cumulative number of output tokens which were used."""
diff --git a/src/anthropic/types/beta/usage.py b/src/anthropic/types/beta/usage.py
new file mode 100644
index 00000000..5ba569ee
--- /dev/null
+++ b/src/anthropic/types/beta/usage.py
@@ -0,0 +1,13 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from ..._models import BaseModel
+
+__all__ = ["Usage"]
+
+
+class Usage(BaseModel):
+    input_tokens: int
+    """The number of input tokens which were used."""
+
+    output_tokens: int
+    """The number of output tokens which were used."""
diff --git a/src/anthropic/types/completion.py b/src/anthropic/types/completion.py
index 27a063b9..d4bacc2f 100644
--- a/src/anthropic/types/completion.py
+++ b/src/anthropic/types/completion.py
@@ -1,5 +1,6 @@
 # File generated from our OpenAPI spec by Stainless.
 
+from typing import Optional
 from typing_extensions import Literal
 
 from .._models import BaseModel
@@ -20,7 +21,7 @@ class Completion(BaseModel):
     model: str
     """The model that handled the request."""
 
-    stop_reason: str
+    stop_reason: Optional[str] = None
     """The reason that we stopped.
 
     This may be one the following values:
diff --git a/src/anthropic/types/completion_create_params.py b/src/anthropic/types/completion_create_params.py
index 0e210b23..ff367899 100644
--- a/src/anthropic/types/completion_create_params.py
+++ b/src/anthropic/types/completion_create_params.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Union, Optional
 from typing_extensions import Literal, Required, TypedDict
 
 __all__ = [
@@ -91,7 +91,7 @@ class CompletionCreateParamsBase(TypedDict, total=False):
 
 
 class Metadata(TypedDict, total=False):
-    user_id: str
+    user_id: Optional[str]
     """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
@@ -104,8 +104,9 @@ class CompletionCreateParamsNonStreaming(CompletionCreateParamsBase):
     stream: Literal[False]
     """Whether to incrementally stream the response using server-sent events.
 
-    See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-    details.
+    See
+    [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+    for details.
     """
 
 
@@ -113,8 +114,9 @@ class CompletionCreateParamsStreaming(CompletionCreateParamsBase):
     stream: Required[Literal[True]]
     """Whether to incrementally stream the response using server-sent events.
 
-    See [streaming](https://docs.anthropic.com/claude/reference/streaming) for
-    details.
+    See
+    [streaming](https://docs.anthropic.com/claude/reference/text-completions-streaming)
+    for details.
     """
 
 
diff --git a/tests/lib/streaming/test_messages.py b/tests/lib/streaming/test_messages.py
index 05679f0b..561a6617 100644
--- a/tests/lib/streaming/test_messages.py
+++ b/tests/lib/streaming/test_messages.py
@@ -24,7 +24,7 @@
 # copied from the real API
 stream_example = """
 event: message_start
-data: {"type":"message_start","message":{"id":"msg_4QpJur2dWWDjF6C758FbBw5vm12BaVipnK","type":"message","role":"assistant","content":[],"model":"claude-2.1","stop_reason":null,"stop_sequence":null}}
+data: {"type":"message_start","message":{"id":"msg_4QpJur2dWWDjF6C758FbBw5vm12BaVipnK","type":"message","role":"assistant","content":[],"model":"claude-2.1","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":1}}}
 
 event: content_block_start
 data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
@@ -45,7 +45,7 @@
 data: {"type":"content_block_stop","index":0}
 
 event: message_delta
-data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null}}
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":6}}
 
 event: message_stop
 data: {"type":"message_stop"}