feat(api): add citations (#839)

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 21
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic-75f0573c3d6d79650bcbd8b1b4fcf93ce146d567afeb1061cd4afccf8d1d6799.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic-7270ee0a79d885681ee507414608229f61c27f47c40f355dcd210b38aa7cddf1.yml

api.md

@@ -24,9 +24,19 @@ Types:
 from anthropic.types import (
     Base64PDFSource,
     CacheControlEphemeral,
+    CitationCharLocation,
+    CitationCharLocationParam,
+    CitationContentBlockLocation,
+    CitationContentBlockLocationParam,
+    CitationPageLocation,
+    CitationPageLocationParam,
+    CitationsConfigParam,
+    CitationsDelta,
     ContentBlock,
     ContentBlockDeltaEvent,
     ContentBlockParam,
+    ContentBlockSource,
+    ContentBlockSourceContent,
     ContentBlockStartEvent,
     ContentBlockStopEvent,
     DocumentBlockParam,
@@ -42,6 +52,7 @@ from anthropic.types import (
     MessageTokensCount,
     Metadata,
     Model,
+    PlainTextSource,
     RawContentBlockDeltaEvent,
     RawContentBlockStartEvent,
     RawContentBlockStopEvent,
@@ -51,6 +62,8 @@ from anthropic.types import (
     RawMessageStreamEvent,
     TextBlock,
     TextBlockParam,
+    TextCitation,
+    TextCitationParam,
     TextDelta,
     Tool,
     ToolChoice,
@@ -153,15 +166,26 @@ from anthropic.types.beta import (
     BetaBase64PDFBlock,
     BetaBase64PDFSource,
     BetaCacheControlEphemeral,
+    BetaCitationCharLocation,
+    BetaCitationCharLocationParam,
+    BetaCitationContentBlockLocation,
+    BetaCitationContentBlockLocationParam,
+    BetaCitationPageLocation,
+    BetaCitationPageLocationParam,
+    BetaCitationsConfigParam,
+    BetaCitationsDelta,
     BetaContentBlock,
     BetaContentBlockParam,
+    BetaContentBlockSource,
+    BetaContentBlockSourceContent,
     BetaImageBlockParam,
     BetaInputJSONDelta,
     BetaMessage,
     BetaMessageDeltaUsage,
     BetaMessageParam,
     BetaMessageTokensCount,
     BetaMetadata,
+    BetaPlainTextSource,
     BetaRawContentBlockDeltaEvent,
     BetaRawContentBlockStartEvent,
     BetaRawContentBlockStopEvent,
@@ -171,6 +195,8 @@ from anthropic.types.beta import (
     BetaRawMessageStreamEvent,
     BetaTextBlock,
     BetaTextBlockParam,
+    BetaTextCitation,
+    BetaTextCitationParam,
     BetaTextDelta,
     BetaTool,
     BetaToolBash20241022,

src/anthropic/resources/beta/messages/batches.py

@@ -239,11 +239,11 @@ def delete(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaDeletedMessageBatch:
-        """This endpoint is idempotent and can be used to poll for Message Batch
-        completion.
+        """
+        Delete a Message Batch.
 
-        To access the results of a Message Batch, make a request to the
-        `results_url` field in the response.
+        Message Batches can only be deleted once they've finished processing. If you'd
+        like to delete an in-progress batch, you must first cancel it.
 
         Args:
           message_batch_id: ID of the Message Batch.
@@ -608,11 +608,11 @@ async def delete(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaDeletedMessageBatch:
-        """This endpoint is idempotent and can be used to poll for Message Batch
-        completion.
+        """
+        Delete a Message Batch.
 
-        To access the results of a Message Batch, make a request to the
-        `results_url` field in the response.
+        Message Batches can only be deleted once they've finished processing. If you'd
+        like to delete an in-progress batch, you must first cancel it.
 
         Args:
           message_batch_id: ID of the Message Batch.

src/anthropic/resources/messages/batches.py

@@ -192,11 +192,11 @@ def delete(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> DeletedMessageBatch:
-        """This endpoint is idempotent and can be used to poll for Message Batch
-        completion.
+        """
+        Delete a Message Batch.
 
-        To access the results of a Message Batch, make a request to the
-        `results_url` field in the response.
+        Message Batches can only be deleted once they've finished processing. If you'd
+        like to delete an in-progress batch, you must first cancel it.
 
         Args:
           message_batch_id: ID of the Message Batch.
@@ -477,11 +477,11 @@ async def delete(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> DeletedMessageBatch:
-        """This endpoint is idempotent and can be used to poll for Message Batch
-        completion.
+        """
+        Delete a Message Batch.
 
-        To access the results of a Message Batch, make a request to the
-        `results_url` field in the response.
+        Message Batches can only be deleted once they've finished processing. If you'd
+        like to delete an in-progress batch, you must first cancel it.
 
         Args:
           message_batch_id: ID of the Message Batch.

src/anthropic/types/__init__.py

@@ -27,9 +27,11 @@
 from .model_param import ModelParam as ModelParam
 from .content_block import ContentBlock as ContentBlock
 from .message_param import MessageParam as MessageParam
+from .text_citation import TextCitation as TextCitation
 from .beta_api_error import BetaAPIError as BetaAPIError
 from .metadata_param import MetadataParam as MetadataParam
 from .tool_use_block import ToolUseBlock as ToolUseBlock
+from .citations_delta import CitationsDelta as CitationsDelta
 from .input_json_delta import InputJSONDelta as InputJSONDelta
 from .text_block_param import TextBlockParam as TextBlockParam
 from .image_block_param import ImageBlockParam as ImageBlockParam
@@ -42,6 +44,7 @@
 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 .text_citation_param import TextCitationParam as TextCitationParam
 from .anthropic_beta_param import AnthropicBetaParam as AnthropicBetaParam
 from .beta_not_found_error import BetaNotFoundError as BetaNotFoundError
 from .document_block_param import DocumentBlockParam as DocumentBlockParam
@@ -53,10 +56,14 @@
 from .beta_rate_limit_error import BetaRateLimitError as BetaRateLimitError
 from .message_create_params import MessageCreateParams as MessageCreateParams
 from .tool_choice_any_param import ToolChoiceAnyParam as ToolChoiceAnyParam
+from .citation_char_location import CitationCharLocation as CitationCharLocation
+from .citation_page_location import CitationPageLocation as CitationPageLocation
+from .citations_config_param import CitationsConfigParam as CitationsConfigParam
 from .raw_message_stop_event import RawMessageStopEvent as RawMessageStopEvent
 from .tool_choice_auto_param import ToolChoiceAutoParam as ToolChoiceAutoParam
 from .tool_choice_tool_param import ToolChoiceToolParam as ToolChoiceToolParam
 from .base64_pdf_source_param import Base64PDFSourceParam as Base64PDFSourceParam
+from .plain_text_source_param import PlainTextSourceParam as PlainTextSourceParam
 from .raw_message_delta_event import RawMessageDeltaEvent as RawMessageDeltaEvent
 from .raw_message_start_event import RawMessageStartEvent as RawMessageStartEvent
 from .tool_result_block_param import ToolResultBlockParam as ToolResultBlockParam
@@ -68,8 +75,16 @@
 from .content_block_start_event import ContentBlockStartEvent as ContentBlockStartEvent
 from .beta_gateway_timeout_error import BetaGatewayTimeoutError as BetaGatewayTimeoutError
 from .beta_invalid_request_error import BetaInvalidRequestError as BetaInvalidRequestError
+from .content_block_source_param import ContentBlockSourceParam as ContentBlockSourceParam
 from .message_count_tokens_params import MessageCountTokensParams as MessageCountTokensParams
+from .citation_char_location_param import CitationCharLocationParam as CitationCharLocationParam
+from .citation_page_location_param import CitationPageLocationParam as CitationPageLocationParam
 from .raw_content_block_stop_event import RawContentBlockStopEvent as RawContentBlockStopEvent
 from .cache_control_ephemeral_param import CacheControlEphemeralParam as CacheControlEphemeralParam
 from .raw_content_block_delta_event import RawContentBlockDeltaEvent as RawContentBlockDeltaEvent
 from .raw_content_block_start_event import RawContentBlockStartEvent as RawContentBlockStartEvent
+from .citation_content_block_location import CitationContentBlockLocation as CitationContentBlockLocation
+from .content_block_source_content_param import ContentBlockSourceContentParam as ContentBlockSourceContentParam
+from .citation_content_block_location_param import (
+    CitationContentBlockLocationParam as CitationContentBlockLocationParam,
+)

src/anthropic/types/beta/__init__.py

@@ -11,8 +11,10 @@
 from .model_list_params import ModelListParams as ModelListParams
 from .beta_content_block import BetaContentBlock as BetaContentBlock
 from .beta_message_param import BetaMessageParam as BetaMessageParam
+from .beta_text_citation import BetaTextCitation as BetaTextCitation
 from .beta_metadata_param import BetaMetadataParam as BetaMetadataParam
 from .beta_tool_use_block import BetaToolUseBlock as BetaToolUseBlock
+from .beta_citations_delta import BetaCitationsDelta as BetaCitationsDelta
 from .beta_input_json_delta import BetaInputJSONDelta as BetaInputJSONDelta
 from .beta_text_block_param import BetaTextBlockParam as BetaTextBlockParam
 from .beta_tool_union_param import BetaToolUnionParam as BetaToolUnionParam
@@ -21,23 +23,38 @@
 from .beta_tool_choice_param import BetaToolChoiceParam as BetaToolChoiceParam
 from .beta_content_block_param import BetaContentBlockParam as BetaContentBlockParam
 from .beta_message_delta_usage import BetaMessageDeltaUsage as BetaMessageDeltaUsage
+from .beta_text_citation_param import BetaTextCitationParam as BetaTextCitationParam
 from .beta_message_tokens_count import BetaMessageTokensCount as BetaMessageTokensCount
 from .beta_tool_use_block_param import BetaToolUseBlockParam as BetaToolUseBlockParam
 from .beta_tool_choice_any_param import BetaToolChoiceAnyParam as BetaToolChoiceAnyParam
 from .beta_base64_pdf_block_param import BetaBase64PDFBlockParam as BetaBase64PDFBlockParam
+from .beta_citation_char_location import BetaCitationCharLocation as BetaCitationCharLocation
+from .beta_citation_page_location import BetaCitationPageLocation as BetaCitationPageLocation
+from .beta_citations_config_param import BetaCitationsConfigParam as BetaCitationsConfigParam
 from .beta_raw_message_stop_event import BetaRawMessageStopEvent as BetaRawMessageStopEvent
 from .beta_tool_choice_auto_param import BetaToolChoiceAutoParam as BetaToolChoiceAutoParam
 from .beta_tool_choice_tool_param import BetaToolChoiceToolParam as BetaToolChoiceToolParam
 from .message_count_tokens_params import MessageCountTokensParams as MessageCountTokensParams
 from .beta_base64_pdf_source_param import BetaBase64PDFSourceParam as BetaBase64PDFSourceParam
+from .beta_plain_text_source_param import BetaPlainTextSourceParam as BetaPlainTextSourceParam
 from .beta_raw_message_delta_event import BetaRawMessageDeltaEvent as BetaRawMessageDeltaEvent
 from .beta_raw_message_start_event import BetaRawMessageStartEvent as BetaRawMessageStartEvent
 from .beta_tool_result_block_param import BetaToolResultBlockParam as BetaToolResultBlockParam
 from .beta_raw_message_stream_event import BetaRawMessageStreamEvent as BetaRawMessageStreamEvent
 from .beta_tool_bash_20241022_param import BetaToolBash20241022Param as BetaToolBash20241022Param
+from .beta_content_block_source_param import BetaContentBlockSourceParam as BetaContentBlockSourceParam
+from .beta_citation_char_location_param import BetaCitationCharLocationParam as BetaCitationCharLocationParam
+from .beta_citation_page_location_param import BetaCitationPageLocationParam as BetaCitationPageLocationParam
 from .beta_raw_content_block_stop_event import BetaRawContentBlockStopEvent as BetaRawContentBlockStopEvent
 from .beta_cache_control_ephemeral_param import BetaCacheControlEphemeralParam as BetaCacheControlEphemeralParam
 from .beta_raw_content_block_delta_event import BetaRawContentBlockDeltaEvent as BetaRawContentBlockDeltaEvent
 from .beta_raw_content_block_start_event import BetaRawContentBlockStartEvent as BetaRawContentBlockStartEvent
+from .beta_citation_content_block_location import BetaCitationContentBlockLocation as BetaCitationContentBlockLocation
 from .beta_tool_text_editor_20241022_param import BetaToolTextEditor20241022Param as BetaToolTextEditor20241022Param
 from .beta_tool_computer_use_20241022_param import BetaToolComputerUse20241022Param as BetaToolComputerUse20241022Param
+from .beta_content_block_source_content_param import (
+    BetaContentBlockSourceContentParam as BetaContentBlockSourceContentParam,
+)
+from .beta_citation_content_block_location_param import (
+    BetaCitationContentBlockLocationParam as BetaCitationContentBlockLocationParam,
+)

src/anthropic/types/beta/beta_base64_pdf_block_param.py

@@ -2,18 +2,29 @@
 
 from __future__ import annotations
 
-from typing import Optional
-from typing_extensions import Literal, Required, TypedDict
+from typing import Union, Optional
+from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
+from .beta_citations_config_param import BetaCitationsConfigParam
 from .beta_base64_pdf_source_param import BetaBase64PDFSourceParam
+from .beta_plain_text_source_param import BetaPlainTextSourceParam
+from .beta_content_block_source_param import BetaContentBlockSourceParam
 from .beta_cache_control_ephemeral_param import BetaCacheControlEphemeralParam
 
-__all__ = ["BetaBase64PDFBlockParam"]
+__all__ = ["BetaBase64PDFBlockParam", "Source"]
+
+Source: TypeAlias = Union[BetaBase64PDFSourceParam, BetaPlainTextSourceParam, BetaContentBlockSourceParam]
 
 
 class BetaBase64PDFBlockParam(TypedDict, total=False):
-    source: Required[BetaBase64PDFSourceParam]
+    source: Required[Source]
 
     type: Required[Literal["document"]]
 
     cache_control: Optional[BetaCacheControlEphemeralParam]
+
+    citations: BetaCitationsConfigParam
+
+    context: Optional[str]
+
+    title: Optional[str]

src/anthropic/types/beta/beta_citation_char_location.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["BetaCitationCharLocation"]
+
+
+class BetaCitationCharLocation(BaseModel):
+    cited_text: str
+
+    document_index: int
+
+    document_title: Optional[str] = None
+
+    end_char_index: int
+
+    start_char_index: int
+
+    type: Literal["char_location"]

src/anthropic/types/beta/beta_citation_char_location_param.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["BetaCitationCharLocationParam"]
+
+
+class BetaCitationCharLocationParam(TypedDict, total=False):
+    cited_text: Required[str]
+
+    document_index: Required[int]
+
+    document_title: Required[Optional[str]]
+
+    end_char_index: Required[int]
+
+    start_char_index: Required[int]
+
+    type: Required[Literal["char_location"]]

src/anthropic/types/beta/beta_citation_content_block_location.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["BetaCitationContentBlockLocation"]
+
+
+class BetaCitationContentBlockLocation(BaseModel):
+    cited_text: str
+
+    document_index: int
+
+    document_title: Optional[str] = None
+
+    end_block_index: int
+
+    start_block_index: int
+
+    type: Literal["content_block_location"]

src/anthropic/types/beta/beta_citation_content_block_location_param.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["BetaCitationContentBlockLocationParam"]
+
+
+class BetaCitationContentBlockLocationParam(TypedDict, total=False):
+    cited_text: Required[str]
+
+    document_index: Required[int]
+
+    document_title: Required[Optional[str]]
+
+    end_block_index: Required[int]
+
+    start_block_index: Required[int]
+
+    type: Required[Literal["content_block_location"]]

src/anthropic/types/beta/beta_citation_page_location.py

@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["BetaCitationPageLocation"]
+
+
+class BetaCitationPageLocation(BaseModel):
+    cited_text: str
+
+    document_index: int
+
+    document_title: Optional[str] = None
+
+    end_page_number: int
+
+    start_page_number: int
+
+    type: Literal["page_location"]