feat(providers): implement ClaudeBatchProvider for async batch request submission and polling #4929

Open
opened 2026-04-08 23:00:03 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Commit Message: feat(providers): implement ClaudeBatchProvider for async batch request submission and polling
  • Branch: feature/m9-claude-batch-provider
  • Milestone: v3.8.0
  • Parent Epic: #1251

Background and Context

Claude's Batch Processing API requires a different execution flow than synchronous requests: requests are submitted to a batch, and results are polled after a delay (up to 24 hours). This issue implements the ClaudeBatchProvider that handles the full lifecycle of batch request submission, status polling, and result retrieval.

This depends on the batch_processing field being added to ActorConfiguration (#4928).

Expected Behavior

  • A ClaudeBatchProvider class handles batch API interactions with Anthropic
  • Batch requests are submitted via POST /v1/messages/batches
  • The provider polls for batch completion using GET /v1/messages/batches/{batch_id}
  • Results are retrieved and mapped back to the standard ActorResponse format
  • The provider handles the long wait gracefully (configurable polling interval, max wait time)
  • Errors from the batch API are surfaced as standard ActorError exceptions

Acceptance Criteria

  • ClaudeBatchProvider class implements the standard provider interface
  • Batch requests are submitted correctly to Anthropic's batch endpoint
  • Polling loop checks batch status at configurable intervals
  • Results are correctly mapped to ActorResponse format
  • Timeout handling: raises BatchTimeoutError if max wait exceeded
  • Partial failures in batch results are handled gracefully
  • Type annotations are complete and Pyright passes

Dependencies

  • Must be done after: #4928 (BatchProcessingMode in ActorConfiguration)

Supporting Information

Subtasks

  • Implement ClaudeBatchProvider class with batch submission logic
  • Implement polling loop with configurable interval and max wait
  • Implement result retrieval and mapping to ActorResponse
  • Add BatchTimeoutError exception class
  • Register ClaudeBatchProvider in the provider registry
  • Tests (Behave): Add scenarios for batch submission, polling, and result retrieval
  • Tests (Behave): Add scenarios for timeout handling
  • Tests (Robot): Add integration test for full batch lifecycle (mocked Anthropic API)
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

## Metadata - **Commit Message**: `feat(providers): implement ClaudeBatchProvider for async batch request submission and polling` - **Branch**: `feature/m9-claude-batch-provider` - **Milestone**: v3.8.0 - **Parent Epic**: #1251 ## Background and Context Claude's Batch Processing API requires a different execution flow than synchronous requests: requests are submitted to a batch, and results are polled after a delay (up to 24 hours). This issue implements the `ClaudeBatchProvider` that handles the full lifecycle of batch request submission, status polling, and result retrieval. This depends on the `batch_processing` field being added to `ActorConfiguration` (#4928). ## Expected Behavior - A `ClaudeBatchProvider` class handles batch API interactions with Anthropic - Batch requests are submitted via `POST /v1/messages/batches` - The provider polls for batch completion using `GET /v1/messages/batches/{batch_id}` - Results are retrieved and mapped back to the standard `ActorResponse` format - The provider handles the long wait gracefully (configurable polling interval, max wait time) - Errors from the batch API are surfaced as standard `ActorError` exceptions ## Acceptance Criteria - [ ] `ClaudeBatchProvider` class implements the standard provider interface - [ ] Batch requests are submitted correctly to Anthropic's batch endpoint - [ ] Polling loop checks batch status at configurable intervals - [ ] Results are correctly mapped to `ActorResponse` format - [ ] Timeout handling: raises `BatchTimeoutError` if max wait exceeded - [ ] Partial failures in batch results are handled gracefully - [ ] Type annotations are complete and Pyright passes ## Dependencies - [ ] Must be done after: #4928 (BatchProcessingMode in ActorConfiguration) ## Supporting Information - Claude Batch Processing API: https://platform.claude.com/docs/en/build-with-claude/batch-processing - Parent Epic: #1251 ## Subtasks - [ ] Implement `ClaudeBatchProvider` class with batch submission logic - [ ] Implement polling loop with configurable interval and max wait - [ ] Implement result retrieval and mapping to `ActorResponse` - [ ] Add `BatchTimeoutError` exception class - [ ] Register `ClaudeBatchProvider` in the provider registry - [ ] Tests (Behave): Add scenarios for batch submission, polling, and result retrieval - [ ] Tests (Behave): Add scenarios for timeout handling - [ ] Tests (Robot): Add integration test for full batch lifecycle (mocked Anthropic API) - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner
HAL9000 added this to the v3.8.0 milestone 2026-04-08 23:00:45 +00:00
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium — Implements the batch provider layer, depends on #4928
  • Milestone: v3.8.0 (already assigned correctly)
  • Story Points: 5 — L — Implementing a full async batch provider with polling lifecycle is a large task
  • MoSCoW: Should Have — Batch processing is a cost-efficiency feature important for production scale but not blocking core functionality
  • Parent Epic: #1251 (as noted in issue metadata)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — Implements the batch provider layer, depends on #4928 - **Milestone**: v3.8.0 (already assigned correctly) - **Story Points**: 5 — L — Implementing a full async batch provider with polling lifecycle is a large task - **MoSCoW**: Should Have — Batch processing is a cost-efficiency feature important for production scale but not blocking core functionality - **Parent Epic**: #1251 (as noted in issue metadata) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#4929
No description provided.