packages feed

claude-hs-0.1.0.0: src/Claude/Batches.hs

-- | Asynchronous Message Batches and scoped JSON Lines result consumption.
module Claude.Batches
  ( BatchId,
    batchId,
    batchIdText,
    CustomId,
    mkCustomId,
    customIdText,
    BatchItem (..),
    Batch (..),
    ProcessingStatus (..),
    RequestCounts (..),
    BatchPage (..),
    BatchCursor (..),
    BatchListOptions (..),
    BatchResult (..),
    BatchOutcome (..),
    createBatch,
    retrieveBatch,
    listBatches,
    cancelBatch,
    consumeBatchResults,
  )
where

import Claude.Client
import Claude.Internal.Http (decodeResponse, jsonRequest, redactApiError, runRequest)
import Claude.Internal.Request qualified as Request
import Claude.Messages (MessageRequest, MessageResponse)
import Control.Lens ((^.))
import Control.Monad.IO.Class (liftIO)
import Control.Monad.Trans.Except (throwE)
import Data.Aeson (FromJSON (..), ToJSON (..), object, withObject, withText, (.:), (.:?), (.=))
import Data.ByteString (ByteString)
import Data.ByteString qualified as BS
import Data.ByteString.Char8 qualified as BSC
import Data.ByteString.Lazy qualified as LBS
import Data.Char (isAlphaNum, isAscii)
import Data.Generics.Labels ()
import Data.List.NonEmpty (NonEmpty)
import Data.List.NonEmpty qualified as NonEmpty
import Data.Set qualified as Set
import Data.Text (Text)
import Data.Text qualified as Text
import Data.Text.Encoding (encodeUtf8)
import Data.Time (UTCTime)
import GHC.Generics (Generic)
import Network.HTTP.Types (Query)
import Numeric.Natural (Natural)

newtype BatchId = BatchId Text
  deriving stock (Eq, Ord, Show)

batchId :: Text -> Maybe BatchId
batchId text
  | validId text = Just (BatchId text)
  | otherwise = Nothing

batchIdText :: BatchId -> Text
batchIdText (BatchId text) = text

instance FromJSON BatchId where
  parseJSON = withText "batch ID" $ maybe (fail "invalid batch ID") pure . batchId

newtype CustomId = CustomId Text
  deriving stock (Eq, Ord, Show)
  deriving newtype (ToJSON)

mkCustomId :: Text -> Maybe CustomId
mkCustomId text
  | validId text && Text.length text <= 64 = Just (CustomId text)
  | otherwise = Nothing

customIdText :: CustomId -> Text
customIdText (CustomId text) = text

instance FromJSON CustomId where
  parseJSON = withText "custom ID" $ maybe (fail "invalid custom ID") pure . mkCustomId

validId :: Text -> Bool
validId text =
  not (Text.null text) && Text.all (\c -> isAscii c && (isAlphaNum c || c == '-' || c == '_')) text

data BatchItem = BatchItem
  { customId :: !CustomId,
    params :: !MessageRequest
  }
  deriving stock (Eq, Show, Generic)

instance ToJSON BatchItem where
  toJSON item = object ["custom_id" .= (item ^. #customId), "params" .= (item ^. #params)]

data ProcessingStatus = InProgress | Canceling | Ended | UnknownProcessingStatus !Text
  deriving stock (Eq, Show)

instance FromJSON ProcessingStatus where
  parseJSON =
    withText "processing_status" $
      pure . \case
        "in_progress" -> InProgress
        "canceling" -> Canceling
        "ended" -> Ended
        other -> UnknownProcessingStatus other

data RequestCounts = RequestCounts
  { processing :: !Natural,
    succeeded :: !Natural,
    errored :: !Natural,
    canceled :: !Natural,
    expired :: !Natural
  }
  deriving stock (Eq, Show, Generic)

instance FromJSON RequestCounts where
  parseJSON = withObject "batch request counts" $ \o ->
    RequestCounts <$> o .: "processing" <*> o .: "succeeded" <*> o .: "errored" <*> o .: "canceled" <*> o .: "expired"

data Batch = Batch
  { id :: !BatchId,
    processingStatus :: !ProcessingStatus,
    requestCounts :: !RequestCounts,
    createdAt :: !UTCTime,
    expiresAt :: !UTCTime,
    endedAt :: !(Maybe UTCTime),
    cancelInitiatedAt :: !(Maybe UTCTime),
    archivedAt :: !(Maybe UTCTime),
    resultsUrl :: !(Maybe Text)
  }
  deriving stock (Eq, Show, Generic)

instance FromJSON Batch where
  parseJSON = withObject "batch" $ \o ->
    Batch
      <$> o .: "id"
      <*> o .: "processing_status"
      <*> o .: "request_counts"
      <*> o .: "created_at"
      <*> o .: "expires_at"
      <*> o .:? "ended_at"
      <*> o .:? "cancel_initiated_at"
      <*> o .:? "archived_at"
      <*> o .:? "results_url"

data BatchPage = BatchPage
  { batches :: ![Batch],
    firstId :: !(Maybe BatchId),
    lastId :: !(Maybe BatchId),
    hasMore :: !Bool
  }
  deriving stock (Eq, Show, Generic)

instance FromJSON BatchPage where
  parseJSON = withObject "batch page" $ \o ->
    BatchPage <$> o .: "data" <*> o .:? "first_id" <*> o .:? "last_id" <*> o .: "has_more"

data BatchCursor = After !BatchId | Before !BatchId
  deriving stock (Eq, Show)

data BatchListOptions = BatchListOptions
  { cursor :: !(Maybe BatchCursor),
    limit :: !(Maybe Natural)
  }
  deriving stock (Eq, Show, Generic)

data BatchResult = BatchResult
  { customId :: !CustomId,
    outcome :: !BatchOutcome
  }
  deriving stock (Eq, Generic)

data BatchOutcome
  = BatchSucceeded !MessageResponse
  | BatchErrored !ApiError
  | BatchCanceled
  | BatchExpired
  deriving stock (Eq)

instance FromJSON BatchResult where
  parseJSON = withObject "batch result line" $ \o ->
    BatchResult <$> o .: "custom_id" <*> o .: "result"

instance FromJSON BatchOutcome where
  parseJSON = withObject "batch outcome" $ \o ->
    o .: "type" >>= \case
      "succeeded" -> BatchSucceeded <$> o .: "message"
      "errored" -> do
        envelope <- o .: "error"
        BatchErrored <$> withObject "error envelope" (.: "error") envelope
      "canceled" -> pure BatchCanceled
      "expired" -> pure BatchExpired
      (_ :: Text) -> fail "unknown batch outcome"

batchRoot :: ByteString
batchRoot = "/v1/messages/batches"

batchRoute :: BatchId -> ByteString
batchRoute ident = batchRoot <> "/" <> encodeUtf8 (batchIdText ident)

createBatch :: Client -> RequestOptions -> NonEmpty BatchItem -> IO (Either ClientError (Response Batch))
createBatch client options items
  | Set.size ids /= NonEmpty.length items = pure (Left (InvalidRequest "Batch custom IDs must be unique"))
  | otherwise = case traverse (Request.validateMessages client Request.Batch . toJSON . (^. #params)) items of
      Left err -> pure (Left err)
      Right _ -> jsonRequest client "POST" batchRoot [] options (Just (object ["requests" .= items]))
  where
    ids = Set.fromList (map (^. #customId) (NonEmpty.toList items))

retrieveBatch :: Client -> RequestOptions -> BatchId -> IO (Either ClientError (Response Batch))
retrieveBatch client options ident = jsonRequest client "GET" (batchRoute ident) [] options Nothing

listBatches :: Client -> RequestOptions -> BatchListOptions -> IO (Either ClientError (Response BatchPage))
listBatches client options page
  | any (\n -> n < 1 || n > 1000) (page ^. #limit) = pure (Left (InvalidRequest "Batch list limit must be between 1 and 1000"))
  | otherwise = jsonRequest client "GET" batchRoot query options Nothing
  where
    query :: Query
    query = case page ^. #cursor of
      Just (After ident) -> ("after_id", Just (encodeUtf8 (batchIdText ident))) : limits
      Just (Before ident) -> ("before_id", Just (encodeUtf8 (batchIdText ident))) : limits
      Nothing -> limits
    limits = [("limit", Just (BSC.pack (show n))) | Just n <- [page ^. #limit]]

cancelBatch :: Client -> RequestOptions -> BatchId -> IO (Either ClientError (Response Batch))
cancelBatch client options ident = jsonRequest client "POST" (batchRoute ident <> "/cancel") [] options Nothing

-- | Deliver each result before reading the next line. Correlate by custom ID.
-- An HTTP or decoding failure may follow already delivered results.
-- The documented endpoint is constructed from the batch ID on the client origin.
consumeBatchResults ::
  Client ->
  RequestOptions ->
  BatchId ->
  (BatchResult -> IO ()) ->
  IO (Either ClientError (Response ()))
consumeBatchResults client options ident consume =
  runRequest client "GET" (batchRoute ident <> "/results") [] options "application/binary" Nothing $ \meta readBody -> do
    let deliver fragments = do
          result <- either throwE pure (decodeResponse meta (LBS.fromChunks (reverse fragments)))
          liftIO $ consume $ case result of
            BatchResult requestId_ (BatchErrored err) -> BatchResult requestId_ (BatchErrored (redactApiError client err))
            other -> other
        feed fragments chunk
          | BS.null chunk = do
              next <- readBody
              if BS.null next
                then if null fragments then pure () else deliver fragments
                else feed fragments next
          | otherwise = case BS.break (== 10) chunk of
              (prefix, rest)
                | BS.null rest -> feed (prefix : fragments) BS.empty
                | otherwise -> deliver (prefix : fragments) >> feed [] (BS.drop 1 rest)
    feed [] BS.empty