add docs

Author: fumito-ito

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(

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
 }

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
 }

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) {

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

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<BatchResultResponse, Error> {
         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,

Sources/AnthropicSwiftSDK/Network/Request/CancelMessageBatchRequest.swift

@@ -5,12 +5,17 @@
 //  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 {
         "\(RequestType.batches.basePath)/\(batchId)/cancel"
     }
     let queries: [String: CustomStringConvertible]? = nil
     let body: Never? = nil
+    /// ID of the Message Batch.
     let batchId: String
 }

Sources/AnthropicSwiftSDK/Network/Request/ListMessageBatchesRequest.swift

@@ -5,15 +5,21 @@
 //  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
     let queries: [String: CustomStringConvertible]?
     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
     }
 }

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.
     ///

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
 }