From 934d6851bda76bb54ca8a0b8ce20cf9c326761fa Mon Sep 17 00:00:00 2001 From: Fumito Ito Date: Fri, 25 Oct 2024 02:43:51 +0900 Subject: [PATCH] add docs --- .../Entity/Batch/BatchParameter.swift | 15 +++ .../Entity/Batch/BatchRequestCounts.swift | 14 +++ .../Entity/Batch/BatchResultType.swift | 10 +- .../Entity/Batch/MessageBatch.swift | 6 ++ .../Entity/Batch/ProcessingStatus.swift | 2 +- .../AnthropicSwiftSDK/MessageBatches.swift | 91 +++++++++++++++++++ .../Request/CancelMessageBatchRequest.swift | 5 + .../Request/ListMessageBatchesRequest.swift | 6 ++ .../Request/MessageBatchesRequest.swift | 10 +- .../RetrieveMessageBatchResultsRequest.swift | 7 ++ .../RetrieveMessageBatchesRequest.swift | 3 + .../Response/BatchResultResponse.swift | 5 + 12 files changed, 169 insertions(+), 5 deletions(-) diff --git a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchParameter.swift b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchParameter.swift index 7f0ee38..995f0dc 100644 --- a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchParameter.swift +++ b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchParameter.swift @@ -8,11 +8,21 @@ import FunctionCalling public struct BatchParameter { + /// Input messages. public let messages: [Message] + /// The model that will complete your prompt. + /// + /// See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. public let model: Model + /// System prompt. + /// + /// A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. public let system: [SystemPrompt] + /// The maximum number of tokens to generate before stopping. public let maxTokens: Int + /// An object describing metadata about the request. public let metaData: MetaData? + /// Custom text sequences that will cause the model to stop generating. public let stopSequence: [String]? /// Whether the response should be handles as streaming or not, /// @@ -21,10 +31,15 @@ public struct BatchParameter { /// - Note: Streaming is not supported for batch requests. /// For more details, see https://docs.anthropic.com/en/docs/build-with-claude/message-batches#can-i-use-the-message-batches-api-with-other-api-features public let stream: Bool = false + /// Amount of randomness injected into the response. public let temperature: Double? + /// Use nucleus sampling. public let topP: Double? + /// Only sample from the top K options for each subsequent token. public let topK: Int? + /// Definitions of tools that the model may use. public let toolContainer: ToolContainer? + /// How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself. public let toolChoice: ToolChoice public init( diff --git a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchRequestCounts.swift b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchRequestCounts.swift index 0814875..ef8591c 100644 --- a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchRequestCounts.swift +++ b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchRequestCounts.swift @@ -5,10 +5,24 @@ // Created by 伊藤史 on 2024/10/09. // +/// Tallies requests within the Message Batch, categorized by their status. public struct BatchRequestCounts: Decodable { + /// Number of requests in the Message Batch that are processing. let processing: Int + /// Number of requests in the Message Batch that have completed successfully. + /// + /// This is zero until processing of the entire Message Batch has ended. let succeeeded: Int + /// Number of requests in the Message Batch that encountered an error. + /// + /// This is zero until processing of the entire Message Batch has ended. let errored: Int + /// Number of requests in the Message Batch that have been canceled. + /// + /// This is zero until processing of the entire Message Batch has ended. let canceled: Int + /// Number of requests in the Message Batch that have expired. + /// + /// This is zero until processing of the entire Message Batch has ended. let expired: Int } diff --git a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchResultType.swift b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchResultType.swift index a3f7a63..59ac1c7 100644 --- a/Sources/AnthropicSwiftSDK/Entity/Batch/BatchResultType.swift +++ b/Sources/AnthropicSwiftSDK/Entity/Batch/BatchResultType.swift @@ -5,10 +5,16 @@ // Created by 伊藤史 on 2024/10/09. // -/// https://docs.anthropic.com/en/docs/build-with-claude/message-batches#retrieving-batch-results +/// Once batch processing has ended, each Messages request in the batch will have a result. public enum BatchResultType: String, Decodable { - case succeeded // include the message result as jsonl + /// Request was successful. Includes the message result. + case succeeded + /// Request encountered an error and a message was not created. + /// + /// Possible errors include invalid requests and internal server errors. You will not be billed for these requests. case errored + /// User canceled the batch before this request could be sent to the model. You will not be billed for these requests. case cancelled + /// Batch reached its 24 hour expiration before this request could be sent to the model. You will not be billed for these requests. case expired } diff --git a/Sources/AnthropicSwiftSDK/Entity/Batch/MessageBatch.swift b/Sources/AnthropicSwiftSDK/Entity/Batch/MessageBatch.swift index 328fd25..c5f2bfd 100644 --- a/Sources/AnthropicSwiftSDK/Entity/Batch/MessageBatch.swift +++ b/Sources/AnthropicSwiftSDK/Entity/Batch/MessageBatch.swift @@ -6,7 +6,13 @@ // public struct MessageBatch { + /// Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + /// + /// Must be unique for each request within the Message Batch. public let customId: String + /// Messages API creation parameters for the individual request. + /// + /// See the [Messages API](https://docs.anthropic.com/en/api/messages) reference for full documentation on available parameters. public let parameter: BatchParameter public init(customId: String, parameter: BatchParameter) { diff --git a/Sources/AnthropicSwiftSDK/Entity/Batch/ProcessingStatus.swift b/Sources/AnthropicSwiftSDK/Entity/Batch/ProcessingStatus.swift index 737ffe9..4ac9363 100644 --- a/Sources/AnthropicSwiftSDK/Entity/Batch/ProcessingStatus.swift +++ b/Sources/AnthropicSwiftSDK/Entity/Batch/ProcessingStatus.swift @@ -5,7 +5,7 @@ // Created by 伊藤史 on 2024/10/09. // -/// https://docs.anthropic.com/en/api/retrieving-message-batches +/// Processing status of the Message Batch. public enum ProcessingStatus: String, RawRepresentable, Decodable { case inProgress = "in_progress" case canceling diff --git a/Sources/AnthropicSwiftSDK/MessageBatches.swift b/Sources/AnthropicSwiftSDK/MessageBatches.swift index e16e49f..3e9774c 100644 --- a/Sources/AnthropicSwiftSDK/MessageBatches.swift +++ b/Sources/AnthropicSwiftSDK/MessageBatches.swift @@ -9,15 +9,28 @@ import Foundation import FunctionCalling import SwiftyJSONLines +/// A class responsible for managing message batches in the Anthropic API. public struct MessageBatches { + /// The API key used for authentication with the Anthropic API. private let apiKey: String + /// The URL session used for network requests. private let session: URLSession + /// Initializes a new instance of `MessageBatches`. + /// + /// - Parameters: + /// - apiKey: The API key for authentication. + /// - session: The URL session for network requests. init(apiKey: String, session: URLSession) { self.apiKey = apiKey self.session = session } + /// Creates new message batches. + /// + /// - Parameter batches: An array of `MessageBatch` to be created. + /// - Returns: A `BatchResponse` containing the details of the created batches. + /// - Throws: An error if the request fails. public func createBatches(batches: [MessageBatch]) async throws -> BatchResponse { try await createBatches( batches: batches, @@ -26,6 +39,14 @@ public struct MessageBatches { ) } + /// Creates new message batches with custom header providers. + /// + /// - Parameters: + /// - batches: An array of `MessageBatch` to be created. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: A `BatchResponse` containing the details of the created batches. + /// - Throws: An error if the request fails. public func createBatches( batches: [MessageBatch], anthropicHeaderProvider: AnthropicHeaderProvider, @@ -51,6 +72,11 @@ public struct MessageBatches { return try anthropicJSONDecoder.decode(BatchResponse.self, from: data) } + /// Retrieves a specific message batch by its ID. + /// + /// - Parameter batchId: The ID of the batch to retrieve. + /// - Returns: A `BatchResponse` containing the details of the retrieved batch. + /// - Throws: An error if the request fails. public func retrieve(batchId: String) async throws -> BatchResponse { try await retrieve( batchId: batchId, @@ -59,6 +85,14 @@ public struct MessageBatches { ) } + /// Retrieves a specific message batch by its ID with custom header providers. + /// + /// - Parameters: + /// - batchId: The ID of the batch to retrieve. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: A `BatchResponse` containing the details of the retrieved batch. + /// - Throws: An error if the request fails. public func retrieve( batchId: String, anthropicHeaderProvider: AnthropicHeaderProvider, @@ -84,6 +118,11 @@ public struct MessageBatches { return try anthropicJSONDecoder.decode(BatchResponse.self, from: data) } + /// Retrieves the results of a specific message batch by its ID. + /// + /// - Parameter batchId: The ID of the batch to retrieve results for. + /// - Returns: An array of `BatchResultResponse` containing the results of the batch. + /// - Throws: An error if the request fails. public func results(of batchId: String) async throws -> [BatchResultResponse] { try await results( of: batchId, @@ -92,6 +131,14 @@ public struct MessageBatches { ) } + /// Retrieves the results of a specific message batch by its ID with custom header providers. + /// + /// - Parameters: + /// - batchId: The ID of the batch to retrieve results for. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: An array of `BatchResultResponse` containing the results of the batch. + /// - Throws: An error if the request fails. public func results( of batchId: String, anthropicHeaderProvider: AnthropicHeaderProvider, @@ -117,6 +164,11 @@ public struct MessageBatches { return try JSONLines(data: data).toObjects(with: anthropicJSONDecoder) } + /// Streams the results of a specific message batch by its ID. + /// + /// - Parameter batchId: The ID of the batch to stream results for. + /// - Returns: An `AsyncThrowingStream` of `BatchResultResponse` containing the streamed results of the batch. + /// - Throws: An error if the request fails. public func results(streamOf batchId: String) async throws -> AsyncThrowingStream { try await results( streamOf: batchId, @@ -125,6 +177,14 @@ public struct MessageBatches { ) } + /// Streams the results of a specific message batch by its ID with custom header providers. + /// + /// - Parameters: + /// - batchId: The ID of the batch to stream results for. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: An `AsyncThrowingStream` of `BatchResultResponse` containing the streamed results of the batch. + /// - Throws: An error if the request fails. public func results( streamOf batchId: String, anthropicHeaderProvider: AnthropicHeaderProvider, @@ -164,6 +224,14 @@ public struct MessageBatches { } } + /// Lists message batches with optional pagination. + /// + /// - Parameters: + /// - beforeId: The ID to list batches before. + /// - afterId: The ID to list batches after. + /// - limit: The maximum number of batches to list. + /// - Returns: A `BatchListResponse` containing the list of batches. + /// - Throws: An error if the request fails. public func list(beforeId: String? = nil, afterId: String? = nil, limit: Int = 20) async throws -> BatchListResponse { try await list( beforeId: beforeId, @@ -174,6 +242,16 @@ public struct MessageBatches { ) } + /// Lists message batches with optional pagination and custom header providers. + /// + /// - Parameters: + /// - beforeId: The ID to list batches before. + /// - afterId: The ID to list batches after. + /// - limit: The maximum number of batches to list. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: A `BatchListResponse` containing the list of batches. + /// - Throws: An error if the request fails. public func list( beforeId: String?, afterId: String?, @@ -213,6 +291,11 @@ public struct MessageBatches { return try anthropicJSONDecoder.decode(BatchListResponse.self, from: data) } + /// Cancels a specific message batch by its ID. + /// + /// - Parameter batchId: The ID of the batch to cancel. + /// - Returns: A `BatchResponse` containing the details of the canceled batch. + /// - Throws: An error if the request fails. public func cancel(batchId: String) async throws -> BatchResponse { try await cancel( batchId: batchId, @@ -221,6 +304,14 @@ public struct MessageBatches { ) } + /// Cancels a specific message batch by its ID with custom header providers. + /// + /// - Parameters: + /// - batchId: The ID of the batch to cancel. + /// - anthropicHeaderProvider: The provider for Anthropic-specific headers. + /// - authenticationHeaderProvider: The provider for authentication headers. + /// - Returns: A `BatchResponse` containing the details of the canceled batch. + /// - Throws: An error if the request fails. public func cancel( batchId: String, anthropicHeaderProvider: AnthropicHeaderProvider, diff --git a/Sources/AnthropicSwiftSDK/Network/Request/CancelMessageBatchRequest.swift b/Sources/AnthropicSwiftSDK/Network/Request/CancelMessageBatchRequest.swift index a2770dd..cb418ef 100644 --- a/Sources/AnthropicSwiftSDK/Network/Request/CancelMessageBatchRequest.swift +++ b/Sources/AnthropicSwiftSDK/Network/Request/CancelMessageBatchRequest.swift @@ -5,6 +5,10 @@ // Created by 伊藤史 on 2024/10/16. // +/// Batches may be canceled any time before processing ends. +/// +/// Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. +/// The number of canceled requests is specified in request_counts. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. struct CancelMessageBatchRequest: Request { let method: HttpMethod = .post var path: String { @@ -12,5 +16,6 @@ struct CancelMessageBatchRequest: Request { } let queries: [String: CustomStringConvertible]? = nil let body: Never? = nil + /// ID of the Message Batch. let batchId: String } diff --git a/Sources/AnthropicSwiftSDK/Network/Request/ListMessageBatchesRequest.swift b/Sources/AnthropicSwiftSDK/Network/Request/ListMessageBatchesRequest.swift index 0a85489..59fdcc5 100644 --- a/Sources/AnthropicSwiftSDK/Network/Request/ListMessageBatchesRequest.swift +++ b/Sources/AnthropicSwiftSDK/Network/Request/ListMessageBatchesRequest.swift @@ -5,6 +5,7 @@ // Created by 伊藤史 on 2024/10/16. // +/// List all Message Batches within a Workspace. Most recently created batches are returned first. struct ListMessageBatchesRequest: Request { let method: HttpMethod = .get let path: String = RequestType.batches.basePath @@ -12,8 +13,13 @@ struct ListMessageBatchesRequest: Request { let body: Never? = nil enum Parameter: String { + /// ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. case beforeId = "before_id" + /// ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. case afterId = "after_id" + /// Number of items to return per page. + /// + /// Defaults to 20. Ranges from 1 to 100. case limit } } diff --git a/Sources/AnthropicSwiftSDK/Network/Request/MessageBatchesRequest.swift b/Sources/AnthropicSwiftSDK/Network/Request/MessageBatchesRequest.swift index 87e7be1..5adcb34 100644 --- a/Sources/AnthropicSwiftSDK/Network/Request/MessageBatchesRequest.swift +++ b/Sources/AnthropicSwiftSDK/Network/Request/MessageBatchesRequest.swift @@ -5,6 +5,14 @@ // Created by 伊藤史 on 2024/10/09. // +/// The Message Batches API can be used to process multiple Messages API requests at once. +/// +/// Once a Message Batch is created, it begins processing immediately. +/// Batches can take up to 24 hours to complete. +/// +/// The Message Batches API supports the following models: Claude 3 Haiku, Claude 3 Opus, and Claude 3.5 Sonnet. +/// All features available in the Messages API, including beta features, are available through the Message Batches API. +/// While in beta, batches may contain up to 10,000 requests and be up to 32 MB in total size. struct MessageBatchesRequest: Request { typealias Body = MessageBatchesRequestBody @@ -16,7 +24,6 @@ struct MessageBatchesRequest: Request { // MARK: Request Body -/// https://docs.anthropic.com/en/api/creating-message-batches struct MessageBatchesRequestBody: Encodable { /// List of requests for prompt completion. Each is an individual request to create a Message. let requests: [Batch] @@ -26,7 +33,6 @@ struct MessageBatchesRequestBody: Encodable { } } -/// https://docs.anthropic.com/en/api/creating-message-batches struct Batch: Encodable { /// Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. /// diff --git a/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchResultsRequest.swift b/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchResultsRequest.swift index 2361ac9..a038f80 100644 --- a/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchResultsRequest.swift +++ b/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchResultsRequest.swift @@ -5,6 +5,12 @@ // Created by 伊藤史 on 2024/10/16. // +/// Streams the results of a Message Batch as a .jsonl file. +/// +/// Each line in the file is a JSON object containing the result of a single request in the Message Batch. +/// Results are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests. +/// +/// While in beta, this endpoint requires passing the anthropic-beta header with value message-batches-2024-09-24 struct RetrieveMessageBatchResultsRequest: Request { let method: HttpMethod = .get var path: String { @@ -13,5 +19,6 @@ struct RetrieveMessageBatchResultsRequest: Request { let queries: [String: CustomStringConvertible]? = nil let body: Never? = nil + /// ID of the Message Batch. let batchId: String } diff --git a/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchesRequest.swift b/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchesRequest.swift index ca2896a..c35557a 100644 --- a/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchesRequest.swift +++ b/Sources/AnthropicSwiftSDK/Network/Request/RetrieveMessageBatchesRequest.swift @@ -5,6 +5,8 @@ // Created by 伊藤史 on 2024/10/16. // +/// This endpoint is idempotent and can be used to poll for Message Batch completion. +/// To access the results of a Message Batch, make a request to the results_url field in the response. struct RetrieveMessageBatchesRequest: Request { let method: HttpMethod = .get var path: String { @@ -13,5 +15,6 @@ struct RetrieveMessageBatchesRequest: Request { let queries: [String: CustomStringConvertible]? = nil let body: Never? = nil + /// ID of the Message Batch. let batchId: String } diff --git a/Sources/AnthropicSwiftSDK/Network/Response/BatchResultResponse.swift b/Sources/AnthropicSwiftSDK/Network/Response/BatchResultResponse.swift index ecda647..9a2164f 100644 --- a/Sources/AnthropicSwiftSDK/Network/Response/BatchResultResponse.swift +++ b/Sources/AnthropicSwiftSDK/Network/Response/BatchResultResponse.swift @@ -11,7 +11,12 @@ public struct BatchResult: Decodable { public let error: StreamingError? } +/// The results will be in .jsonl format, where each line is a valid JSON object representing the result of a single request in the Message Batch. +/// +/// For each streamed result, you can do something different depending on its custom_id and result type. public struct BatchResultResponse: Decodable { + /// ID of the request. public let customId: String + /// Result of the request. public let result: BatchResult? }