Feature - Add support to batching and files API's for Anthropic and OpenAI

[joao-salomao]

Description

Adds a Files API and Batch Processing API for Anthropic and OpenAI providers, enabling asynchronous processing of large volumes of LLM requests at reduced cost.

---

Files API (src/Files/)

Shared foundation:

• FileData / FileListResult / DeleteFileResult — normalized response DTOs
• UploadFileRequest, DownloadFileRequest, DeleteFileRequest, ListFilesRequest, GetFileMetadataRequest — typed request value objects

Fluent builder (Prism::files()):

• upload(content, filename, mimeType?) — multipart file upload
• list(limit?, afterId?, beforeId?) — cursor-paginated listing
• getMetadata(fileId) — fetch file metadata
• download(fileId) — download raw file content as a string
• delete(fileId) — delete a file

Provider implementations:

• Both OpenAI and Anthropic implement all five operations under Providers/{Provider}/Handlers/Files/
• Shared response parsing in HandlesFileResponse concerns per provider
• Pagination parameter support varies by provider: beforeId is Anthropic-only; purpose filter (via withProviderOptions) is OpenAI-only
• OpenAI requires a purpose field on upload (batch, assistants, fine-tune, etc.)
• Anthropic restricts downloads to files generated by Claude (e.g. code execution outputs)

Provider contract (Provider.php):

• uploadFile(), listFiles(), getFileMetadata(), downloadFile(), deleteFile() — default to throwing unsupportedProviderAction

---

Batch Processing API (src/Batch/)

Shared foundation:

• BatchRequest / BatchRequestItem — input DTOs; BatchRequestItem wraps a TextRequest with a customId
• BatchJob / BatchJobRequestCounts — normalized job representation across providers, including inputFileId, outputFileId, errorFileId, timestamps, and status
• BatchListResult — paginated listing response
• BatchResultItem — individual result with text, usage, and error info
• BatchStatus / BatchResultStatus — enums normalizing provider-specific statuses
• GetBatchResultsRequest, RetrieveBatchRequest, ListBatchesRequest, CancelBatchRequest — typed request value objects

Fluent builder (Prism::batch()):

• create(items?, inputFileId?) — create a batch
• retrieve(batchId) — poll for status
• list(limit?, afterId?, beforeId?) — cursor-paginated listing
• getResults(batchId) — retrieve all results as BatchResultItem[]
• cancel(batchId) — cancel an in-progress batch

Provider contract (Provider.php):

• batch(), retrieveBatch(), listBatches(), getBatchResults(), cancelBatch() — default to throwing unsupportedProviderAction

Anthropic implementation:

• One handler per operation: Create, Retrieve, ListBatches, Results, Cancel
• HandlesBatchResponse and MapsBatchResults concerns for shared mapping
• Pre-create validation enforcing the 100,000 request limit and 256 MB payload size
• JSONL result parsing with full buffering (returns BatchResultItem[])

OpenAI implementation:

• Same handler-per-operation structure
• HandlesBatchResponse and MapsBatchResults concerns
• Items-first creation: pass BatchRequestItem[] directly — Prism serializes them to JSONL using BuildsRequestBody::buildHttpRequestPayload() and auto-uploads via the Files API; no manual file handling required
• File-first creation: pass a pre-uploaded inputFileId directly as an escape hatch
• Providing both items and inputFileId throws a PrismException
• Results handler uses injected retrieveBatch and downloadFile closures for testable coordination
• BuildsRequestBody concern extracted from text/stream/batch handlers, eliminating duplicated request body mapping

---

Fluent Builder — shared traits

Both Prism::files() and Prism::batch() use the same traits as the existing text/structured/embeddings builders:

• ConfiguresProviders — using(), whenProvider()
• ConfiguresClient — withClientOptions(), withClientRetry()
• HasProviderOptions — withProviderOptions()

---

TextRequest ergonomics

All constructor parameters except model now have sensible defaults, making it straightforward to construct a TextRequest directly for batch use without needing the full fluent builder chain:

new TextRequest(
    model: 'claude-sonnet-4-20250514',
    messages: [new UserMessage('Summarise: ...')],
)

---

Documentation

• docs/core-concepts/files.md — full Files API reference including upload, list (with provider support table), metadata, download, delete, pagination, and provider-conditional options
• docs/core-concepts/batch.md — full Batch API reference including create-poll-retrieve workflow, provider-specific notes, status table, result item properties, listing, cancellation, and links to the official Anthropic and OpenAI batch docs

---

Tests

• Per-provider integration tests for all five batch operations: CreateTest, RetrieveTest, ListTest, ResultsTest, CancelTest
• Unit tests for Results handlers on both providers: ResultsUnitTest — mocks HTTP/callbacks, covering succeeded/errored/expired/canceled parsing, blank-line skipping, and null output file ID handling
• Integration tests for all five file operations on both providers

---

Breaking Changes

None. All new methods on Provider default to throwing unsupportedProviderAction, so existing custom providers are unaffected. The only structural change to an existing class is TextRequest, where constructor parameters now have defaults — all existing call sites using named arguments or the fluent builder are unaffected.

[pedro-fernandes-vinta]

Waiting for this feature to be merged to decrease our API usage, thanks for the feature!

[phill-ug]

@joao-salomao great PR! @sixlive - can you please give this priority as it would really help? Many thanks!

[guths]

@joao-salomao nice PR. @sixlive would be good to have this feature.

[dair-ug]

@joao-salomao such a great feature! @sixlive approve this, please!

[alexandre-da-costa]

Nice stuff, lets merge!

[pentacore]

Would love for this feature to be implemented, its sorely missed in my applications atm

[joao-salomao-ug]

@sixlive any chance you can take a look at this PR?

[JacobHonore]

Unfortunately this has been proposed before and rejected.
I hope it can make it into prism this time, as it is really useful!
Tagging you here, @khalidmaquilang in case you didnt notice this new PR :)

[joao-salomao-ug]

Unfortunately this has been proposed before and rejected. I hope it can make it into prism this time, as it is really useful! Tagging you here, @khalidmaquilang in case you didnt notice this new PR :)

I understand @JacobHonore. For companies running large workloads, the Batch API is a must-have; we are talking about 50% of discount from providers like Anthropic, OpenAI, and Gemini. This needs to be reconsidered.

[hamannjames]

I want to add to the voices in here. This should be merged!

@sixlive