Skip to main content

openrouter_batch/
lib.rs

1//! OpenRouter normalization Batch API and synchronous embedding client.
2//!
3//! `BatchTransport` owns normalization submission and polling.
4//! `EmbeddingTransport` owns synchronous array embedding requests.
5//!
6//! API rules encoded here, verified against the live API on 2026-08-29
7//! (`.agents/skills/openrouter-api/` and the batch quickstart):
8//!
9//! - One batch carries one `endpoint`, one batch-level `model`, and one
10//!   inline `requests` array. The body must serialize `endpoint` and `model`
11//!   before `requests`: the API stream-parses and answers 400 otherwise.
12//!   `SubmitBatch` fixes that order by field declaration; a test pins it.
13//! - Success is any 2xx with a parseable batch body: submit answers
14//!   `202 Accepted` with `status: "validating"` — queued, not complete.
15//! - Terminal statuses are `completed`, `failed`, `expired`, `cancelled`.
16//!   Results arrive inline in the poll response; there is no download
17//!   endpoint. A `completed` batch can still contain per-request failures:
18//!   exactly one of `response` or `error` is populated per result line.
19//! - Result lines decode per line: a line that breaks the documented
20//!   envelope arrives as `BatchResultLine::Undecodable` with the raw JSON
21//!   preserved, so one bad line never fails a completed batch. The
22//!   result-side helpers are `BatchResultLine::chat_content` and
23//!   `embedding_vectors`.
24//! - The batch-level `model` must be a `:batch` variant slug; a base slug is
25//!   rejected synchronously and fails the whole submission.
26//! - Server-side retention is 30 days: callers persist every result into
27//!   Postgres at poll time.
28//!
29//! The API root is configuration, not a constant (context/05): the default
30//! is the public endpoint; e2e points it at the local fake batch server.
31
32mod facade;
33mod http;
34mod transport;
35
36pub use facade::{
37    EmbeddingDecodeError, Message, StructuredParams, embedding_vectors, structured_body,
38    submit_structured,
39};
40pub use http::HttpTransport;
41pub use transport::{
42    BatchEndpoint, BatchItem, BatchLineError, BatchObject, BatchResultLine, BatchStatus,
43    BatchTransport, BatchUsage, EmbeddingRequest, EmbeddingTransport, RawChatResponse,
44    RawEmbeddingResponse, RequestCounts, ResultLine, ResultResponse, SubmitBatch, TransportError,
45    chat_completion_content,
46};