refactor(ocr): separate formats backends and integrations

This commit is contained in:
Yujong Lee 2026-09-09 17:26:54 -07:00
parent fa4b13f6eb
commit 4b03767ec2
33 changed files with 1328 additions and 983 deletions

View file

@ -46,9 +46,11 @@ Route-level Rust structure mirrors LiteLLM's Python responsibilities:
provider-specific transform. For Anthropic Messages, this means
`core/src/providers/anthropic/messages/transformation.rs`.
- OCR separates API shape from hosting. `core/src/ocr/formats/` owns wire types
and transforms, `core/src/ocr/backends/` owns OCR transport behavior, and
`core/src/ocr/registry.rs` lists supported format/backend pairings. Shared
provider authentication remains in `core/src/providers/<provider>/auth.rs`.
and transforms, `core/src/ocr/backends/` owns reusable hosting behavior, and
each file in `core/src/ocr/integrations/` owns one format/backend pairing,
while `core/src/ocr/registry.rs` resolves providers and models through the shared
integration declaration. Shared provider authentication remains in
`core/src/providers/<provider>/auth.rs`.
- Handlers live in `core`, never in a host. `ai-gateway` must not contain a
route handler that talks to a provider; its axum route reads the HTTP request,
picks a deployment, and calls the `core` entrypoint. `python-bridge` marshals

View file

@ -56,6 +56,15 @@ handler.rs the provider call
client.rs the shared reqwest client
```
OCR keeps each concern independently changeable:
```
ocr/formats/<format>/ typed wire shape and transforms
ocr/backends/<backend>.rs shared auth, upload, polling, and hosting behavior
ocr/integrations/<name>.rs one typed format/backend pairing
ocr/registry.rs provider/model resolution and generated dispatch
```
## Parity Rules
- Every shared type used by a provider transform needs unit tests for

View file

@ -5,6 +5,33 @@ use serde_json::{Map, Value};
use crate::constants::UPSTREAM_ERROR_BODY_MAX_CHARS;
use crate::error::{Error, json_type_name};
pub(crate) enum HeaderPolicy<'a> {
All,
Only(&'a [&'a str]),
Except(&'a [&'a str]),
}
pub(crate) fn with_headers(
builder: reqwest::RequestBuilder,
headers: &[(String, String)],
policy: HeaderPolicy<'_>,
) -> reqwest::RequestBuilder {
headers
.iter()
.filter(|(name, _)| match policy {
HeaderPolicy::All => true,
HeaderPolicy::Only(names) => names
.iter()
.any(|allowed| name.eq_ignore_ascii_case(allowed)),
HeaderPolicy::Except(names) => !names
.iter()
.any(|excluded| name.eq_ignore_ascii_case(excluded)),
})
.fold(builder, |builder, (name, value)| {
builder.header(name, value)
})
}
#[tracing::instrument(target = "litellm::function_trace", level = "trace", skip_all)]
pub async fn http_request(
request: reqwest::RequestBuilder,
@ -76,6 +103,58 @@ mod tests {
use super::*;
use serde_json::json;
#[rstest::rstest]
#[case(HeaderPolicy::All, true, true)]
#[case(HeaderPolicy::Only(&["authorization"]), true, false)]
#[case(HeaderPolicy::Except(&["authorization"]), false, true)]
fn forwarding_policy_preserves_matching_headers_and_duplicates(
#[case] policy: HeaderPolicy<'_>,
#[case] auth: bool,
#[case] trace: bool,
) {
let request = with_headers(
reqwest::Client::new().get("https://example.com"),
&[
("AuThOrIzAtIoN".into(), "Bearer token".into()),
("X-Trace".into(), "first".into()),
("x-trace".into(), "second".into()),
],
policy,
)
.build()
.unwrap();
assert_eq!(request.headers().contains_key("authorization"), auth);
let traces: Vec<_> = request.headers().get_all("x-trace").iter().collect();
if trace {
assert_eq!(traces, ["first", "second"]);
} else {
assert!(traces.is_empty());
}
}
#[test]
fn multipart_policy_leaves_content_headers_to_reqwest() {
let request = with_headers(
reqwest::Client::new()
.post("https://example.com")
.multipart(reqwest::multipart::Form::new().text("file", "abc")),
&[
("Content-Type".into(), "application/json".into()),
("CONTENT-LENGTH".into(), "0".into()),
],
HeaderPolicy::Except(&["content-type", "content-length"]),
)
.build()
.unwrap();
assert!(
request.headers()["content-type"]
.to_str()
.unwrap()
.starts_with("multipart/form-data; boundary=")
);
assert_ne!(request.headers()["content-length"], "0");
}
#[test]
fn truncate_leaves_short_bodies_untouched() {
assert_eq!(truncate_error_body("short"), "short");

View file

@ -1,176 +1,11 @@
use serde_json::{Map, Value};
use crate::Error;
use crate::auth::azure::AzureAuthInputs;
use crate::constants::{AZURE_AI_OCR_PATH, AZURE_DI_API_VERSION};
use crate::ocr::backends::{BackendConfig, OcrBackend, OcrIntegration, PreparedOcrBackend};
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::document_intelligence::{
AzureDocumentIntelligenceOcrFormat,
types::{AzureDocumentIntelligenceOperation, DocumentIntelligenceParams},
};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument, OcrRequestFormat};
use crate::ocr::wire::DecodedOcrResponse;
use crate::ocr::backends::OcrBackend;
use crate::ocr::error::OcrError;
use crate::ocr::types::OcrConnection;
use crate::providers::azure_ai::auth;
use crate::url_utils::ApiUrl;
fn model_id(model: &str) -> Result<&str, OcrRequestError> {
let model = model.rsplit('/').next().unwrap_or(model);
if matches!(model, "." | "..") {
return Err(OcrRequestError::DotModel);
}
Ok(model)
}
#[derive(Clone, Debug)]
pub struct AzureMistral;
impl OcrIntegration for AzureMistral {
type Backend = AzureBackend;
type Format = MistralOcrFormat;
type PreparedDocument = crate::ocr::document::InlineOcrDocument;
const FORMAT: Self::Format = MistralOcrFormat;
#[tracing::instrument(target = "litellm::function_trace", level = "trace", skip_all)]
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
_model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let base = auth::resolve_api_base(connection.api_base.as_deref(), env_lookup)?;
let headers = auth::authenticate(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
Some(config),
env_lookup,
)
.await?;
let path: Vec<&str> = AZURE_AI_OCR_PATH.trim_matches('/').split('/').collect();
Ok(PreparedOcrBackend {
url: ApiUrl::parse(&base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers,
})
}
fn validate_request_body(
&self,
body: &crate::ocr::formats::mistral::types::MistralOcrRequest,
) -> Result<(), crate::ocr::error::OcrRequestError> {
crate::ocr::document::InlineOcrDocument::try_from(body.document.clone())?;
Ok(())
}
async fn prepare_document(
&self,
client: &crate::ocr::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::PreparedDocument, OcrError> {
crate::ocr::document::inline_remote_document(
client.document_fetcher(),
document,
connection,
)
.await
}
}
#[derive(Clone, Debug)]
pub struct AzureDocumentIntelligence;
impl OcrIntegration for AzureDocumentIntelligence {
type Backend = AzureBackend;
type Format = AzureDocumentIntelligenceOcrFormat;
type PreparedDocument = OcrDocument;
const FORMAT: Self::Format = AzureDocumentIntelligenceOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
params: &DocumentIntelligenceParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let endpoint = auth::resolve_document_intelligence_endpoint(
connection.api_base.as_deref(),
env_lookup,
)?;
let model = format!("{}:analyze", model_id(model)?);
let url = ApiUrl::parse(&endpoint)
.and_then(|url| url.complete_path(&["documentintelligence", "documentModels", &model]))
.map(|url| {
url.append_query_pairs(
[("api-version", AZURE_DI_API_VERSION)]
.into_iter()
.chain(params.pages.iter().map(|pages| ("pages", pages.0.as_str())))
.chain(
params
.features
.iter()
.map(|features| ("features", features.0.as_str())),
),
)
.into_string()
})
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
let headers = auth::authenticate_document_intelligence(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
Some(config),
env_lookup,
)
.await?;
Ok(PreparedOcrBackend { url, headers })
}
async fn prepare_document(
&self,
_client: &crate::ocr::OcrClient,
document: OcrDocument,
_connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::PreparedDocument, OcrError> {
Ok(document)
}
fn preserve_native_response(&self, params: &DocumentIntelligenceParams) -> bool {
params.request_format == OcrRequestFormat::Native
}
fn supports_native_request_format(&self) -> bool {
true
}
async fn read_response(
&self,
client: &crate::ocr::OcrClient,
response: reqwest::Response,
url: &str,
headers: &[(String, String)],
connection: &OcrConnection,
params: &DocumentIntelligenceParams,
) -> Result<DecodedOcrResponse<AzureDocumentIntelligenceOperation>, OcrError> {
super::azure_document_intelligence::polling::read_operation_response(
client.provider_http(),
response,
url,
headers,
connection,
params.request_format == OcrRequestFormat::Native,
)
.await
}
}
#[derive(Clone, Debug)]
pub struct AzureBackend;
@ -178,4 +13,60 @@ pub struct AzureBackend;
impl OcrBackend for AzureBackend {
type Config = AzureAuthInputs;
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::AzureAi;
fn decode_config(params: &Map<String, Value>) -> Result<Self::Config, Error> {
Ok(AzureAuthInputs::from_optional_params(params)?)
}
}
pub(crate) fn resolve_integration(
model: &crate::ocr::registry::OcrModel,
) -> crate::ocr::registry::OcrIntegrationKind {
let model = model.as_str().to_ascii_lowercase();
if model.contains("doc-intelligence") || model.contains("documentintelligence") {
crate::ocr::registry::OcrIntegrationKind::AzureDocumentIntelligence
} else {
crate::ocr::registry::OcrIntegrationKind::AzureMistral
}
}
pub(crate) async fn authenticate_mistral(
connection: &OcrConnection,
config: &AzureAuthInputs,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<Vec<(String, String)>, OcrError> {
Ok(auth::authenticate(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
Some(config),
env_lookup,
)
.await?)
}
pub(crate) async fn prepare_document_intelligence_auth(
connection: &OcrConnection,
config: &AzureAuthInputs,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<(String, Vec<(String, String)>), OcrError> {
let endpoint =
auth::resolve_document_intelligence_endpoint(connection.api_base.as_deref(), env_lookup)?;
let headers = auth::authenticate_document_intelligence(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
Some(config),
env_lookup,
)
.await?;
Ok((endpoint, headers))
}
pub(crate) fn resolve_mistral_api_base(
connection: &OcrConnection,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<String, OcrError> {
Ok(auth::resolve_api_base(
connection.api_base.as_deref(),
env_lookup,
)?)
}

View file

@ -56,16 +56,14 @@ async fn poll_document_intelligence(
.checked_duration_since(Instant::now())
.filter(|remaining| !remaining.is_zero())
.ok_or(OcrPollingError::PollTimeout)?;
let mut builder = http_client
let builder = http_client
.get(url.clone())
.timeout(remaining.min(connection.timeout));
for (name, value) in headers {
if name.eq_ignore_ascii_case(AZURE_DI_SUBSCRIPTION_HEADER)
|| name.eq_ignore_ascii_case("authorization")
{
builder = builder.header(name, value);
}
}
let builder = crate::http_utils::with_headers(
builder,
headers,
crate::http_utils::HeaderPolicy::Only(&[AZURE_DI_SUBSCRIPTION_HEADER, "authorization"]),
);
let response = tokio::time::timeout_at(deadline, crate::http_utils::http_request(builder))
.await
.map_err(|_| OcrPollingError::PollTimeout)?

View file

@ -1,12 +1,26 @@
use serde_json::{Map, Value};
use crate::Error;
use crate::constants::MISTRAL_OCR_API_BASE;
use crate::ocr::backends::{BackendConfig, OcrBackend, OcrIntegration, PreparedOcrBackend};
use crate::ocr::backends::OcrBackend;
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::ocr::types::OcrConnection;
use crate::providers::mistral::auth;
use crate::url_utils::ApiUrl;
pub fn complete_url(api_base: Option<&str>) -> Result<String, OcrError> {
#[derive(Clone, Debug)]
pub struct MistralBackend;
impl OcrBackend for MistralBackend {
type Config = ();
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::Mistral;
fn decode_config(_params: &Map<String, Value>) -> Result<Self::Config, Error> {
Ok(())
}
}
pub(crate) fn complete_url(api_base: Option<&str>) -> Result<String, OcrError> {
let base = api_base
.map(str::trim)
.filter(|base| !base.is_empty())
@ -22,49 +36,13 @@ pub fn complete_url(api_base: Option<&str>) -> Result<String, OcrError> {
})
}
#[derive(Clone, Debug)]
pub struct MistralDirect;
impl OcrIntegration for MistralDirect {
type Backend = MistralBackend;
type Format = MistralOcrFormat;
type PreparedDocument = OcrDocument;
const FORMAT: Self::Format = MistralOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
_config: &BackendConfig<Self>,
_model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let headers = auth::validate_environment(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
env_lookup,
)?;
Ok(PreparedOcrBackend {
url: complete_url(connection.api_base.as_deref())?,
headers,
})
}
async fn prepare_document(
&self,
_client: &crate::ocr::OcrClient,
document: OcrDocument,
_connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::PreparedDocument, OcrError> {
Ok(document)
}
}
#[derive(Clone, Debug)]
pub struct MistralBackend;
impl OcrBackend for MistralBackend {
type Config = ();
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::Mistral;
pub(crate) fn authenticate(
connection: &OcrConnection,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<Vec<(String, String)>, OcrError> {
Ok(auth::validate_environment(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
env_lookup,
)?)
}

View file

@ -1,98 +1,21 @@
use std::future::Future;
use super::OcrClient;
use super::error::OcrError;
use super::formats::OcrFormat;
use super::types::{OcrConnection, OcrDocument};
use super::wire::DecodedOcrResponse;
pub(crate) mod azure_ai;
mod azure_document_intelligence;
pub(crate) mod azure_document_intelligence;
pub(crate) mod mistral;
pub(crate) mod reducto;
pub(crate) mod vertex_ai;
use serde_json::{Map, Value};
use crate::Error;
pub struct PreparedOcrBackend {
pub url: String,
pub headers: Vec<(String, String)>,
}
pub trait OcrIntegration: Send + Sync + Sized + 'static {
type Backend: OcrBackend;
type Format: OcrFormat;
type PreparedDocument: Into<<Self::Format as OcrFormat>::PreparedDocument> + Send;
const FORMAT: Self::Format;
fn supports_native_request_format(&self) -> bool {
false
}
fn guard_document_before_preparation(&self) -> bool {
false
}
fn decode_input_params(
&self,
params: serde_json::Map<String, serde_json::Value>,
prefix: &str,
) -> Result<InputParams<Self>, super::error::OcrRequestError> {
super::registry::validate_request_format(
&params,
self.supports_native_request_format(),
Self::Backend::PROVIDER.as_str(),
)?;
Self::Format::validate_input_params(&params)?;
super::wire::decode_request_value(serde_json::Value::Object(params), prefix)
}
fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
params: &MappedParams<Self>,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> impl Future<Output = Result<PreparedOcrBackend, OcrError>> + Send;
fn prepare_document(
&self,
client: &OcrClient,
document: OcrDocument,
connection: &OcrConnection,
headers: &[(String, String)],
) -> impl Future<Output = Result<Self::PreparedDocument, OcrError>> + Send;
fn validate_request_body(
&self,
_body: &<Self::Format as OcrFormat>::RequestBody,
) -> Result<(), super::error::OcrRequestError> {
Ok(())
}
fn preserve_native_response(&self, _params: &MappedParams<Self>) -> bool {
false
}
fn read_response(
&self,
_client: &OcrClient,
response: reqwest::Response,
_url: &str,
_headers: &[(String, String)],
_connection: &OcrConnection,
params: &MappedParams<Self>,
) -> impl Future<
Output = Result<DecodedOcrResponse<<Self::Format as OcrFormat>::ResponseBody>, OcrError>,
> + Send {
super::client::read_json_response(response, self.preserve_native_response(params))
}
}
pub trait OcrBackend: Send + Sync + 'static {
type Config: Clone + std::fmt::Debug + Send + Sync + 'static;
const PROVIDER: super::registry::OcrProvider;
}
pub type InputParams<I> = <<I as OcrIntegration>::Format as OcrFormat>::InputParams;
pub type MappedParams<I> = <<I as OcrIntegration>::Format as OcrFormat>::MappedParams;
pub type BackendConfig<I> = <<I as OcrIntegration>::Backend as OcrBackend>::Config;
fn decode_config(params: &Map<String, Value>) -> Result<Self::Config, Error>;
}

View file

@ -1,14 +1,13 @@
use crate::Error;
use crate::constants::{REDUCTO_ID_PREFIX, REDUCTO_OCR_API_BASE};
use crate::ocr::backends::{BackendConfig, OcrBackend, OcrIntegration, PreparedOcrBackend};
use crate::ocr::document::InlineDocument;
use crate::ocr::error::{OcrError, OcrRequestError, OcrResponseError};
use crate::ocr::formats::reducto::{
ReductoParseLegacyFormat, ReductoParseV3Format,
types::{ReductoFileId, ReductoLegacyParams, ReductoUploadResponse, ReductoV3Params},
};
use crate::ocr::backends::OcrBackend;
use crate::ocr::document::{DocumentPreparation, InlineDocument};
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::reducto::types::{ReductoFileId, ReductoUploadResponse};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::providers::reducto::auth;
use crate::url_utils::ApiUrl;
use serde_json::{Map, Value};
#[derive(Clone, Debug)]
pub struct ReductoBackend;
@ -16,9 +15,24 @@ pub struct ReductoBackend;
impl OcrBackend for ReductoBackend {
type Config = ();
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::Reducto;
fn decode_config(_params: &Map<String, Value>) -> Result<Self::Config, Error> {
Ok(())
}
}
pub fn complete_url(api_base: Option<&str>, path: &str) -> Result<String, OcrError> {
pub(crate) fn resolve_integration(
model: &crate::ocr::registry::OcrModel,
) -> crate::ocr::registry::OcrIntegrationKind {
match model {
crate::ocr::registry::OcrModel::ReductoLegacy => {
crate::ocr::registry::OcrIntegrationKind::ReductoLegacy
}
_ => crate::ocr::registry::OcrIntegrationKind::ReductoV3,
}
}
pub(crate) fn complete_url(api_base: Option<&str>, path: &str) -> Result<String, OcrError> {
let base = api_base
.map(str::trim)
.filter(|base| !base.is_empty())
@ -34,100 +48,64 @@ pub fn complete_url(api_base: Option<&str>, path: &str) -> Result<String, OcrErr
})
}
async fn prepare_reducto_document(
pub struct ReductoUpload;
impl DocumentPreparation for ReductoUpload {
type Output = ReductoFileId;
async fn prepare(
client: &crate::ocr::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
headers: &[(String, String)],
) -> Result<Self::Output, OcrError> {
let source = document.source();
if source.starts_with(REDUCTO_ID_PREFIX) {
return Ok(ReductoFileId(source.to_string()));
}
let document = InlineDocument::parse(source)?.ok_or(OcrRequestError::ReductoSource)?;
upload_document(client, document, connection, headers).await
}
}
async fn upload_document(
client: &crate::ocr::OcrClient,
document: OcrDocument,
document: InlineDocument<'_>,
connection: &OcrConnection,
headers: &[(String, String)],
) -> Result<ReductoFileId, OcrError> {
let source = document.source();
if source.starts_with(REDUCTO_ID_PREFIX) {
return Ok(ReductoFileId(source.to_string()));
}
let document = InlineDocument::parse(source)?.ok_or(OcrRequestError::ReductoSource)?;
let mime = document.mime_type().to_string();
let bytes = document.decode(crate::constants::OCR_INLINE_MAX_BYTES)?;
let part = reqwest::multipart::Part::bytes(bytes)
.file_name("document")
.mime_str(&mime)
.map_err(|_| OcrRequestError::InvalidDataUri)?;
let mut builder = client
let builder = client
.provider_http()
.post(complete_url(connection.api_base.as_deref(), "upload")?)
.multipart(reqwest::multipart::Form::new().part("file", part))
.timeout(connection.timeout);
for (name, value) in headers {
if !name.eq_ignore_ascii_case("content-type")
&& !name.eq_ignore_ascii_case("content-length")
{
builder = builder.header(name, value);
}
}
let builder = crate::http_utils::with_headers(
builder,
headers,
crate::http_utils::HeaderPolicy::Except(&["content-type", "content-length"]),
);
let response = crate::http_utils::http_request(builder)
.await
.map_err(crate::error::TransportError::from)?;
let response = crate::ocr::client::read_json_response::<ReductoUploadResponse>(response, false)
.await?
.data;
if response.file_id.is_empty() {
return Err(OcrResponseError::ResponseField {
path: "file_id".into(),
}
.into());
}
Ok(ReductoFileId(response.file_id))
response.try_into()
}
macro_rules! impl_reducto_backend {
($integration:ident, $format:ident, $params:ty) => {
#[derive(Clone, Debug)]
pub struct $integration;
impl OcrIntegration for $integration {
type Backend = ReductoBackend;
type Format = $format;
type PreparedDocument = ReductoFileId;
const FORMAT: Self::Format = $format;
async fn prepare(
&self,
connection: &OcrConnection,
_config: &BackendConfig<Self>,
_model: &str,
_params: &$params,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let headers = auth::validate_environment(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
env_lookup,
)?;
Ok(PreparedOcrBackend {
url: complete_url(connection.api_base.as_deref(), "parse")?,
headers,
})
}
async fn prepare_document(
&self,
client: &crate::ocr::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
headers: &[(String, String)],
) -> Result<ReductoFileId, OcrError> {
prepare_reducto_document(client, document, connection, headers).await
}
fn guard_document_before_preparation(&self) -> bool {
true
}
fn preserve_native_response(&self, _params: &$params) -> bool {
true
}
}
};
pub(crate) fn authenticate(
connection: &OcrConnection,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<Vec<(String, String)>, OcrError> {
Ok(auth::validate_environment(
connection.extra_headers.clone(),
connection.api_key.as_deref(),
env_lookup,
)?)
}
impl_reducto_backend!(ReductoV3, ReductoParseV3Format, ReductoV3Params);
impl_reducto_backend!(ReductoLegacy, ReductoParseLegacyFormat, ReductoLegacyParams);

View file

@ -1,13 +1,35 @@
use crate::constants::{VERTEX_DEEPSEEK_API_BASE, VERTEX_OCR_DEFAULT_LOCATION};
use crate::ocr::backends::{BackendConfig, OcrBackend, OcrIntegration, PreparedOcrBackend};
use crate::ocr::error::OcrError;
use crate::ocr::formats::deepseek::{DeepSeekOcrFormat, types::DeepSeekOcrParams};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::{OcrConnection, OcrDocument};
use crate::providers::vertex_ai::auth::{self, VertexAuthInputs};
use crate::url_utils::ApiUrl;
use serde_json::{Map, Value};
async fn authenticate(
use crate::Error;
use crate::constants::VERTEX_OCR_DEFAULT_LOCATION;
use crate::ocr::backends::OcrBackend;
use crate::ocr::error::OcrError;
use crate::ocr::types::OcrConnection;
use crate::providers::vertex_ai::auth::{self, VertexAuthInputs};
#[derive(Clone, Debug)]
pub struct VertexBackend;
impl OcrBackend for VertexBackend {
type Config = VertexAuthInputs;
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::VertexAi;
fn decode_config(params: &Map<String, Value>) -> Result<Self::Config, Error> {
Ok(VertexAuthInputs::from_optional_params(params)?)
}
}
pub(crate) fn resolve_integration(
model: &crate::ocr::registry::OcrModel,
) -> crate::ocr::registry::OcrIntegrationKind {
if model.as_str().to_ascii_lowercase().contains("deepseek") {
crate::ocr::registry::OcrIntegrationKind::VertexDeepSeek
} else {
crate::ocr::registry::OcrIntegrationKind::VertexMistral
}
}
pub(crate) async fn authenticate(
connection: &OcrConnection,
config: &VertexAuthInputs,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
@ -22,141 +44,10 @@ async fn authenticate(
.await?)
}
fn location(config: &VertexAuthInputs, env_lookup: &dyn Fn(&str) -> Option<String>) -> String {
pub(crate) fn location(
config: &VertexAuthInputs,
env_lookup: &dyn Fn(&str) -> Option<String>,
) -> String {
auth::resolve_location(config, env_lookup)
.unwrap_or_else(|| VERTEX_OCR_DEFAULT_LOCATION.to_string())
}
#[derive(Clone, Debug)]
pub struct VertexMistral;
impl OcrIntegration for VertexMistral {
type Backend = VertexBackend;
type Format = MistralOcrFormat;
type PreparedDocument = crate::ocr::document::InlineOcrDocument;
const FORMAT: Self::Format = MistralOcrFormat;
#[tracing::instrument(target = "litellm::function_trace", level = "trace", skip_all)]
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let authentication = authenticate(connection, config, env_lookup).await?;
let location = location(config, env_lookup);
let default_base = format!("https://{location}-aiplatform.googleapis.com");
let base = connection.api_base.as_deref().unwrap_or(&default_base);
let prediction = format!("{model}:rawPredict");
let path = [
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"publishers",
"mistralai",
"models",
prediction.as_str(),
];
Ok(PreparedOcrBackend {
url: ApiUrl::parse(base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| crate::ocr::error::OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers: authentication.headers,
})
}
fn validate_request_body(
&self,
body: &crate::ocr::formats::mistral::types::MistralOcrRequest,
) -> Result<(), crate::ocr::error::OcrRequestError> {
crate::ocr::document::InlineOcrDocument::try_from(body.document.clone())?;
Ok(())
}
async fn prepare_document(
&self,
client: &crate::ocr::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::PreparedDocument, OcrError> {
crate::ocr::document::inline_remote_document(
client.document_fetcher(),
document,
connection,
)
.await
}
}
#[derive(Clone, Debug)]
pub struct VertexDeepSeek;
impl OcrIntegration for VertexDeepSeek {
type Backend = VertexBackend;
type Format = DeepSeekOcrFormat;
type PreparedDocument = OcrDocument;
const FORMAT: Self::Format = DeepSeekOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
_model: &str,
_params: &DeepSeekOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let authentication = authenticate(connection, config, env_lookup).await?;
let location = location(config, env_lookup);
let base = connection
.api_base
.as_deref()
.unwrap_or(VERTEX_DEEPSEEK_API_BASE);
Ok(PreparedOcrBackend {
url: ApiUrl::parse(base)
.and_then(|url| {
url.complete_path(&[
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"endpoints",
"openapi",
"chat",
"completions",
])
})
.map(|url| url.into_string())
.map_err(|_| crate::ocr::error::OcrRequestError::RequestField {
path: "api_base".into(),
})?,
headers: authentication.headers,
})
}
async fn prepare_document(
&self,
_client: &crate::ocr::OcrClient,
document: OcrDocument,
_connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::PreparedDocument, OcrError> {
Ok(document)
}
}
#[derive(Clone, Debug)]
pub struct VertexBackend;
impl OcrBackend for VertexBackend {
type Config = VertexAuthInputs;
const PROVIDER: crate::ocr::registry::OcrProvider = crate::ocr::registry::OcrProvider::VertexAi;
}

View file

@ -8,6 +8,47 @@ use crate::constants::OCR_MAX_FETCH_REDIRECTS;
use crate::error::{MediaError, TransportError};
use crate::media::{DownloadPolicy, MediaFetcher};
pub trait DocumentPreparation: Send + Sync + 'static {
type Output: Send;
fn prepare(
client: &super::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
headers: &[(String, String)],
) -> impl std::future::Future<Output = Result<Self::Output, OcrError>> + Send;
}
pub struct PassThrough;
impl DocumentPreparation for PassThrough {
type Output = OcrDocument;
async fn prepare(
_client: &super::OcrClient,
document: OcrDocument,
_connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::Output, OcrError> {
Ok(document)
}
}
pub struct RequireInline;
impl DocumentPreparation for RequireInline {
type Output = InlineOcrDocument;
async fn prepare(
client: &super::OcrClient,
document: OcrDocument,
connection: &OcrConnection,
_headers: &[(String, String)],
) -> Result<Self::Output, OcrError> {
inline_remote_document(client.document_fetcher(), document, connection).await
}
}
pub(crate) struct InlineDocument<'a>(DataUrl<'a>);
impl<'a> InlineDocument<'a> {

View file

@ -28,6 +28,21 @@ pub struct ReductoLegacyRequest {
pub options: Option<ReductoLegacyParams>,
}
pub struct ReductoFileId(pub(crate) String);
impl TryFrom<ReductoUploadResponse> for ReductoFileId {
type Error = crate::ocr::error::OcrError;
fn try_from(response: ReductoUploadResponse) -> Result<Self, Self::Error> {
if response.file_id.is_empty() {
return Err(crate::ocr::error::OcrResponseError::ResponseField {
path: "file_id".into(),
}
.into());
}
Ok(Self(response.file_id))
}
}
#[derive(Deserialize)]
pub struct ReductoUploadResponse {
pub file_id: String,

View file

@ -1,14 +1,11 @@
use std::sync::Arc;
use super::OcrClient;
use super::backends::{MappedParams, OcrIntegration};
use super::formats::{OcrFormat, request_error};
use super::hooks::{OcrDuringCallRequest, OcrHooks, OcrLifecycleHooks};
use super::integrations::{GuardrailStage, MappedParams, OcrIntegration};
use super::prepare::{MappedOcrRequest, prepare_ocr_call};
use super::registry::{
AZURE_DOCUMENT_INTELLIGENCE, AZURE_MISTRAL, MISTRAL, OcrIntegrationInput,
OcrIntegrationRequest, REDUCTO_LEGACY, REDUCTO_V3, VERTEX_DEEPSEEK, VERTEX_MISTRAL,
};
use super::registry::{OcrIntegrationInput, OcrIntegrationRequest};
use super::types::{OcrConnection, OcrDocument, OcrRequest, OcrResponseData};
use crate::Error;
use crate::call_lifecycle::{CallLifecycle, CallLifecycleContext};
@ -42,17 +39,15 @@ pub(crate) async fn perform_ocr_request(
lifecycle_context: context,
hooks: request.hooks,
};
match request.integration {
OcrIntegrationRequest::Mistral(input) => execution.run(MISTRAL, input).await,
OcrIntegrationRequest::AzureMistral(input) => execution.run(AZURE_MISTRAL, input).await,
OcrIntegrationRequest::AzureDocumentIntelligence(input) => {
execution.run(AZURE_DOCUMENT_INTELLIGENCE, input).await
}
OcrIntegrationRequest::VertexMistral(input) => execution.run(VERTEX_MISTRAL, input).await,
OcrIntegrationRequest::VertexDeepSeek(input) => execution.run(VERTEX_DEEPSEEK, input).await,
OcrIntegrationRequest::ReductoV3(input) => execution.run(REDUCTO_V3, input).await,
OcrIntegrationRequest::ReductoLegacy(input) => execution.run(REDUCTO_LEGACY, input).await,
macro_rules! execute_selected_integration {
($( $variant:ident, $integration:ty, $instance:expr, $provider:ident; )+) => {
match request.integration {
$( OcrIntegrationRequest::$variant(input) => execution.run($instance, input).await, )+
}
};
}
super::integrations::for_each_ocr_integration!(execute_selected_integration)
}
impl OcrExecution<'_> {
@ -121,7 +116,7 @@ where
.await?;
let url = prepared_backend.url;
let headers = prepared_backend.headers;
let document = if backend.guard_document_before_preparation() && hooks.has_guardrails() {
let document = if I::GUARDRAIL_STAGE == GuardrailStage::Document && hooks.has_guardrails() {
let guarded = hooks
.during_call(OcrDuringCallRequest {
model: request.model.clone(),
@ -139,7 +134,7 @@ where
.prepare_document(client, document, &request.connection, &headers)
.await?;
let body = format.transform_request(&request.model, document.into(), &request.params)?;
let body = if !backend.guard_document_before_preparation() && hooks.has_guardrails() {
let body = if I::GUARDRAIL_STAGE == GuardrailStage::RequestBody && hooks.has_guardrails() {
let guarded = hooks
.during_call(OcrDuringCallRequest {
model: request.model.clone(),
@ -221,14 +216,13 @@ async fn send_ocr_call<I: OcrIntegration>(
} = request;
let backend = &integration;
let format = I::FORMAT;
let mut builder = client
let builder = client
.provider_http()
.post(&url)
.json(&body)
.timeout(connection.timeout);
for (name, value) in &headers {
builder = builder.header(name, value);
}
let builder =
crate::http_utils::with_headers(builder, &headers, crate::http_utils::HeaderPolicy::All);
let response = crate::http_utils::http_request(builder)
.await
.map_err(crate::error::TransportError::from)?;

View file

@ -2,8 +2,8 @@ use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use super::backends::OcrIntegration;
use super::formats::OcrFormat;
use super::integrations::OcrIntegration;
use super::prepare::MappedOcrRequest;
use super::types::{OcrDocument, OcrResponseData};
use crate::Error;

View file

@ -0,0 +1,92 @@
use crate::constants::AZURE_DI_API_VERSION;
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::azure_ai::{self, AzureBackend};
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::document_intelligence::{
AzureDocumentIntelligenceOcrFormat,
types::{AzureDocumentIntelligenceOperation, DocumentIntelligenceParams},
};
use crate::ocr::types::{OcrConnection, OcrRequestFormat};
use crate::ocr::wire::DecodedOcrResponse;
use crate::url_utils::ApiUrl;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct AzureDocumentIntelligence;
impl OcrIntegration for AzureDocumentIntelligence {
type Backend = AzureBackend;
type Format = AzureDocumentIntelligenceOcrFormat;
type DocumentPreparation = super::PassThrough;
const FORMAT: Self::Format = AzureDocumentIntelligenceOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
params: &DocumentIntelligenceParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let (endpoint, headers) =
azure_ai::prepare_document_intelligence_auth(connection, config, env_lookup).await?;
let model = format!("{}:analyze", model_id(model)?);
let url = ApiUrl::parse(&endpoint)
.and_then(|url| url.complete_path(&["documentintelligence", "documentModels", &model]))
.map(|url| {
url.append_query_pairs(
[("api-version", AZURE_DI_API_VERSION)]
.into_iter()
.chain(params.pages.iter().map(|pages| ("pages", pages.0.as_str())))
.chain(
params
.features
.iter()
.map(|features| ("features", features.0.as_str())),
),
)
.into_string()
})
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
Ok(PreparedOcrBackend { url, headers })
}
fn preserve_native_response(&self, params: &DocumentIntelligenceParams) -> bool {
params.request_format == OcrRequestFormat::Native
}
fn supports_native_request_format(&self) -> bool {
true
}
async fn read_response(
&self,
client: &crate::ocr::OcrClient,
response: reqwest::Response,
url: &str,
headers: &[(String, String)],
connection: &OcrConnection,
params: &DocumentIntelligenceParams,
) -> Result<DecodedOcrResponse<AzureDocumentIntelligenceOperation>, OcrError> {
crate::ocr::backends::azure_document_intelligence::polling::read_operation_response(
client.provider_http(),
response,
url,
headers,
connection,
params.request_format == OcrRequestFormat::Native,
)
.await
}
}
fn model_id(model: &str) -> Result<&str, OcrRequestError> {
let model = model.rsplit('/').next().unwrap_or(model);
if matches!(model, "." | "..") {
return Err(OcrRequestError::DotModel);
}
Ok(model)
}

View file

@ -0,0 +1,48 @@
use crate::constants::AZURE_AI_OCR_PATH;
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::azure_ai::{self, AzureBackend};
use crate::ocr::document::InlineOcrDocument;
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::OcrConnection;
use crate::url_utils::ApiUrl;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct AzureMistral;
impl OcrIntegration for AzureMistral {
type Backend = AzureBackend;
type Format = MistralOcrFormat;
type DocumentPreparation = super::RequireInline;
const FORMAT: Self::Format = MistralOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
_model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let base = azure_ai::resolve_mistral_api_base(connection, env_lookup)?;
let path: Vec<&str> = AZURE_AI_OCR_PATH.trim_matches('/').split('/').collect();
let url = ApiUrl::parse(&base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
let headers = azure_ai::authenticate_mistral(connection, config, env_lookup).await?;
Ok(PreparedOcrBackend { url, headers })
}
fn validate_request_body(
&self,
body: &crate::ocr::formats::mistral::types::MistralOcrRequest,
) -> Result<(), OcrRequestError> {
InlineOcrDocument::try_from(body.document.clone())?;
Ok(())
}
}

View file

@ -0,0 +1,31 @@
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::mistral::{self, MistralBackend};
use crate::ocr::error::OcrError;
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::OcrConnection;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct MistralDirect;
impl OcrIntegration for MistralDirect {
type Backend = MistralBackend;
type Format = MistralOcrFormat;
type DocumentPreparation = super::PassThrough;
const FORMAT: Self::Format = MistralOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
_config: &BackendConfig<Self>,
_model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
Ok(PreparedOcrBackend {
url: mistral::complete_url(connection.api_base.as_deref())?,
headers: mistral::authenticate(connection, env_lookup)?,
})
}
}

View file

@ -0,0 +1,144 @@
use std::future::Future;
use serde_json::{Map, Value};
use super::OcrClient;
use super::backends::{OcrBackend, PreparedOcrBackend};
use super::error::{OcrError, OcrRequestError};
use super::formats::OcrFormat;
use super::types::{OcrConnection, OcrDocument, OcrRequestFormat};
use super::wire::DecodedOcrResponse;
mod azure_document_intelligence;
mod azure_mistral;
mod mistral_direct;
mod reducto_legacy;
mod reducto_v3;
mod vertex_deepseek;
mod vertex_mistral;
pub use super::backends::reducto::ReductoUpload;
pub use super::document::{DocumentPreparation, PassThrough, RequireInline};
pub use azure_document_intelligence::AzureDocumentIntelligence;
pub use azure_mistral::AzureMistral;
pub use mistral_direct::MistralDirect;
pub use reducto_legacy::ReductoLegacy;
pub use reducto_v3::ReductoV3;
pub use vertex_deepseek::VertexDeepSeek;
pub use vertex_mistral::VertexMistral;
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum GuardrailStage {
Document,
RequestBody,
}
pub trait OcrIntegration: Send + Sync + Sized + 'static {
type Backend: OcrBackend;
type Format: OcrFormat;
type DocumentPreparation: DocumentPreparation<
Output: Into<<Self::Format as OcrFormat>::PreparedDocument>,
>;
const FORMAT: Self::Format;
const GUARDRAIL_STAGE: GuardrailStage = GuardrailStage::RequestBody;
fn supports_native_request_format(&self) -> bool {
false
}
fn decode_input_params(
&self,
params: Map<String, Value>,
prefix: &str,
) -> Result<InputParams<Self>, OcrRequestError> {
validate_request_format(
&params,
self.supports_native_request_format(),
Self::Backend::PROVIDER.as_str(),
)?;
Self::Format::validate_input_params(&params)?;
super::wire::decode_request_value(Value::Object(params), prefix)
}
fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
params: &MappedParams<Self>,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> impl Future<Output = Result<PreparedOcrBackend, OcrError>> + Send;
fn prepare_document(
&self,
client: &OcrClient,
document: OcrDocument,
connection: &OcrConnection,
headers: &[(String, String)],
) -> impl Future<
Output = Result<<Self::DocumentPreparation as DocumentPreparation>::Output, OcrError>,
> + Send {
Self::DocumentPreparation::prepare(client, document, connection, headers)
}
fn validate_request_body(
&self,
_body: &<Self::Format as OcrFormat>::RequestBody,
) -> Result<(), OcrRequestError> {
Ok(())
}
fn preserve_native_response(&self, _params: &MappedParams<Self>) -> bool {
false
}
fn read_response(
&self,
_client: &OcrClient,
response: reqwest::Response,
_url: &str,
_headers: &[(String, String)],
_connection: &OcrConnection,
params: &MappedParams<Self>,
) -> impl Future<
Output = Result<DecodedOcrResponse<<Self::Format as OcrFormat>::ResponseBody>, OcrError>,
> + Send {
super::client::read_json_response(response, self.preserve_native_response(params))
}
}
fn validate_request_format(
params: &Map<String, Value>,
supports_native: bool,
provider: &'static str,
) -> Result<(), OcrRequestError> {
let Some(format) = params.get("req_format") else {
return Ok(());
};
let format: OcrRequestFormat =
serde_json::from_value(format.clone()).map_err(|_| OcrRequestError::RequestFormat)?;
if format == OcrRequestFormat::Native && !supports_native {
return Err(OcrRequestError::NativeUnsupported(provider));
}
Ok(())
}
pub type InputParams<I> = <<I as OcrIntegration>::Format as OcrFormat>::InputParams;
pub type MappedParams<I> = <<I as OcrIntegration>::Format as OcrFormat>::MappedParams;
pub type BackendConfig<I> = <<I as OcrIntegration>::Backend as OcrBackend>::Config;
macro_rules! for_each_ocr_integration {
($callback:ident) => {
$callback! {
Mistral, $crate::ocr::integrations::MistralDirect, $crate::ocr::integrations::MistralDirect, Mistral;
AzureMistral, $crate::ocr::integrations::AzureMistral, $crate::ocr::integrations::AzureMistral, AzureAi;
AzureDocumentIntelligence, $crate::ocr::integrations::AzureDocumentIntelligence, $crate::ocr::integrations::AzureDocumentIntelligence, AzureAi;
VertexMistral, $crate::ocr::integrations::VertexMistral, $crate::ocr::integrations::VertexMistral, VertexAi;
VertexDeepSeek, $crate::ocr::integrations::VertexDeepSeek, $crate::ocr::integrations::VertexDeepSeek, VertexAi;
ReductoV3, $crate::ocr::integrations::ReductoV3, $crate::ocr::integrations::ReductoV3, Reducto;
ReductoLegacy, $crate::ocr::integrations::ReductoLegacy, $crate::ocr::integrations::ReductoLegacy, Reducto;
}
};
}
pub(crate) use for_each_ocr_integration;

View file

@ -0,0 +1,37 @@
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::reducto::{self, ReductoBackend};
use crate::ocr::error::OcrError;
use crate::ocr::formats::reducto::{ReductoParseLegacyFormat, types::ReductoLegacyParams};
use crate::ocr::types::OcrConnection;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct ReductoLegacy;
impl OcrIntegration for ReductoLegacy {
type Backend = ReductoBackend;
type Format = ReductoParseLegacyFormat;
type DocumentPreparation = super::ReductoUpload;
const FORMAT: Self::Format = ReductoParseLegacyFormat;
async fn prepare(
&self,
connection: &OcrConnection,
_config: &BackendConfig<Self>,
_model: &str,
_params: &ReductoLegacyParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
Ok(PreparedOcrBackend {
url: reducto::complete_url(connection.api_base.as_deref(), "parse")?,
headers: reducto::authenticate(connection, env_lookup)?,
})
}
const GUARDRAIL_STAGE: super::GuardrailStage = super::GuardrailStage::Document;
fn preserve_native_response(&self, _params: &ReductoLegacyParams) -> bool {
true
}
}

View file

@ -0,0 +1,37 @@
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::reducto::{self, ReductoBackend};
use crate::ocr::error::OcrError;
use crate::ocr::formats::reducto::{ReductoParseV3Format, types::ReductoV3Params};
use crate::ocr::types::OcrConnection;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct ReductoV3;
impl OcrIntegration for ReductoV3 {
type Backend = ReductoBackend;
type Format = ReductoParseV3Format;
type DocumentPreparation = super::ReductoUpload;
const FORMAT: Self::Format = ReductoParseV3Format;
async fn prepare(
&self,
connection: &OcrConnection,
_config: &BackendConfig<Self>,
_model: &str,
_params: &ReductoV3Params,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
Ok(PreparedOcrBackend {
url: reducto::complete_url(connection.api_base.as_deref(), "parse")?,
headers: reducto::authenticate(connection, env_lookup)?,
})
}
const GUARDRAIL_STAGE: super::GuardrailStage = super::GuardrailStage::Document;
fn preserve_native_response(&self, _params: &ReductoV3Params) -> bool {
true
}
}

View file

@ -0,0 +1,57 @@
use crate::constants::VERTEX_DEEPSEEK_API_BASE;
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::vertex_ai::{self, VertexBackend};
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::deepseek::{DeepSeekOcrFormat, types::DeepSeekOcrParams};
use crate::ocr::types::OcrConnection;
use crate::url_utils::ApiUrl;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct VertexDeepSeek;
impl OcrIntegration for VertexDeepSeek {
type Backend = VertexBackend;
type Format = DeepSeekOcrFormat;
type DocumentPreparation = super::PassThrough;
const FORMAT: Self::Format = DeepSeekOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
_model: &str,
_params: &DeepSeekOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let authentication = vertex_ai::authenticate(connection, config, env_lookup).await?;
let location = vertex_ai::location(config, env_lookup);
let base = connection
.api_base
.as_deref()
.unwrap_or(VERTEX_DEEPSEEK_API_BASE);
let url = ApiUrl::parse(base)
.and_then(|url| {
url.complete_path(&[
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"endpoints",
"openapi",
"chat",
"completions",
])
})
.map(|url| url.into_string())
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
Ok(PreparedOcrBackend {
url,
headers: authentication.headers,
})
}
}

View file

@ -0,0 +1,63 @@
use crate::ocr::backends::PreparedOcrBackend;
use crate::ocr::backends::vertex_ai::{self, VertexBackend};
use crate::ocr::document::InlineOcrDocument;
use crate::ocr::error::{OcrError, OcrRequestError};
use crate::ocr::formats::mistral::{MistralOcrFormat, types::MistralOcrParams};
use crate::ocr::types::OcrConnection;
use crate::url_utils::ApiUrl;
use super::{BackendConfig, OcrIntegration};
#[derive(Clone, Debug)]
pub struct VertexMistral;
impl OcrIntegration for VertexMistral {
type Backend = VertexBackend;
type Format = MistralOcrFormat;
type DocumentPreparation = super::RequireInline;
const FORMAT: Self::Format = MistralOcrFormat;
async fn prepare(
&self,
connection: &OcrConnection,
config: &BackendConfig<Self>,
model: &str,
_params: &MistralOcrParams,
env_lookup: &(dyn Fn(&str) -> Option<String> + Sync),
) -> Result<PreparedOcrBackend, OcrError> {
let authentication = vertex_ai::authenticate(connection, config, env_lookup).await?;
let location = vertex_ai::location(config, env_lookup);
let default_base = format!("https://{location}-aiplatform.googleapis.com");
let base = connection.api_base.as_deref().unwrap_or(&default_base);
let prediction = format!("{model}:rawPredict");
let path = [
"v1",
"projects",
authentication.project_id.as_str(),
"locations",
location.as_str(),
"publishers",
"mistralai",
"models",
prediction.as_str(),
];
let url = ApiUrl::parse(base)
.and_then(|url| url.complete_path(&path))
.map(|url| url.into_string())
.map_err(|_| OcrRequestError::RequestField {
path: "api_base".into(),
})?;
Ok(PreparedOcrBackend {
url,
headers: authentication.headers,
})
}
fn validate_request_body(
&self,
body: &crate::ocr::formats::mistral::types::MistralOcrRequest,
) -> Result<(), OcrRequestError> {
InlineOcrDocument::try_from(body.document.clone())?;
Ok(())
}
}

View file

@ -5,6 +5,7 @@ pub mod error;
pub mod formats;
mod handler;
pub mod hooks;
pub mod integrations;
pub mod prepare;
pub mod registry;
pub mod types;
@ -26,6 +27,9 @@ mod mistral_tests;
#[path = "../../tests/reducto_ocr.rs"]
mod reducto_tests;
#[cfg(test)]
#[path = "../../tests/ocr/support.rs"]
pub(crate) mod test_support;
#[cfg(test)]
#[path = "../../tests/ocr.rs"]
pub(crate) mod tests;
#[cfg(test)]

View file

@ -1,5 +1,5 @@
use super::backends::{BackendConfig, InputParams, MappedParams, OcrIntegration};
use super::formats::OcrFormat;
use super::integrations::{BackendConfig, InputParams, MappedParams, OcrIntegration};
use super::types::{OcrConnection, OcrDocument};
use crate::Error;

View file

@ -2,41 +2,14 @@ use serde_json::{Map, Value};
use strum::EnumString;
use crate::Error;
use crate::auth::azure::AzureAuthInputs;
use crate::providers::vertex_ai::auth::VertexAuthInputs;
use crate::routing_utils::provider::{CustomLlmProvider, get_custom_llm_provider};
pub use super::backends::azure_ai::{AzureDocumentIntelligence, AzureMistral};
pub use super::backends::mistral::MistralDirect;
pub use super::backends::reducto::{ReductoLegacy, ReductoV3};
pub use super::backends::vertex_ai::{VertexDeepSeek, VertexMistral};
use super::backends::{BackendConfig, InputParams};
pub use super::backends::{OcrBackend, OcrIntegration};
use super::types::OcrRequestFormat;
pub(crate) fn validate_request_format(
params: &Map<String, Value>,
supports_native: bool,
provider: &'static str,
) -> Result<(), super::error::OcrRequestError> {
let Some(format) = params.get("req_format") else {
return Ok(());
};
let format: OcrRequestFormat = serde_json::from_value(format.clone())
.map_err(|_| super::error::OcrRequestError::RequestFormat)?;
if format == OcrRequestFormat::Native && !supports_native {
return Err(super::error::OcrRequestError::NativeUnsupported(provider));
}
Ok(())
}
pub(crate) const MISTRAL: MistralDirect = MistralDirect;
pub(crate) const AZURE_MISTRAL: AzureMistral = AzureMistral;
pub(crate) const AZURE_DOCUMENT_INTELLIGENCE: AzureDocumentIntelligence = AzureDocumentIntelligence;
pub(crate) const VERTEX_MISTRAL: VertexMistral = VertexMistral;
pub(crate) const VERTEX_DEEPSEEK: VertexDeepSeek = VertexDeepSeek;
pub(crate) const REDUCTO_V3: ReductoV3 = ReductoV3;
pub(crate) const REDUCTO_LEGACY: ReductoLegacy = ReductoLegacy;
pub use super::backends::OcrBackend;
pub use super::integrations::{
AzureDocumentIntelligence, AzureMistral, MistralDirect, ReductoLegacy, ReductoV3,
VertexDeepSeek, VertexMistral,
};
use super::integrations::{BackendConfig, InputParams, OcrIntegration};
/// ```
/// use litellm_core::ocr::registry::{MistralDirect, OcrIntegrationInput};
@ -70,27 +43,37 @@ pub struct OcrIntegrationInput<I: OcrIntegration> {
pub backend_config: BackendConfig<I>,
}
#[derive(Clone, Debug)]
pub enum OcrIntegrationRequest {
Mistral(OcrIntegrationInput<MistralDirect>),
AzureMistral(OcrIntegrationInput<AzureMistral>),
AzureDocumentIntelligence(OcrIntegrationInput<AzureDocumentIntelligence>),
VertexMistral(OcrIntegrationInput<VertexMistral>),
VertexDeepSeek(OcrIntegrationInput<VertexDeepSeek>),
ReductoV3(OcrIntegrationInput<ReductoV3>),
ReductoLegacy(OcrIntegrationInput<ReductoLegacy>),
macro_rules! define_integration_types {
($( $variant:ident, $integration:ty, $instance:expr, $provider:ident; )+) => {
#[derive(Clone, Debug)]
pub enum OcrIntegrationRequest {
$( $variant(OcrIntegrationInput<$integration>), )+
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OcrIntegrationKind {
$( $variant, )+
}
impl OcrIntegrationKind {
pub const fn provider(self) -> OcrProvider {
match self {
$( Self::$variant => OcrProvider::$provider, )+
}
}
}
impl OcrIntegrationRequest {
pub fn kind(&self) -> OcrIntegrationKind {
match self {
$( Self::$variant(_) => OcrIntegrationKind::$variant, )+
}
}
}
};
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OcrIntegrationKind {
Mistral,
AzureMistral,
AzureDocumentIntelligence,
VertexMistral,
VertexDeepSeek,
ReductoV3,
ReductoLegacy,
}
super::integrations::for_each_ocr_integration!(define_integration_types);
#[derive(Clone, Copy, Debug, EnumString, PartialEq, Eq)]
#[strum(serialize_all = "snake_case")]
@ -112,17 +95,6 @@ impl OcrProvider {
}
}
impl OcrIntegrationKind {
pub const fn provider(self) -> OcrProvider {
match self {
Self::Mistral => OcrProvider::Mistral,
Self::AzureMistral | Self::AzureDocumentIntelligence => OcrProvider::AzureAi,
Self::VertexMistral | Self::VertexDeepSeek => OcrProvider::VertexAi,
Self::ReductoV3 | Self::ReductoLegacy => OcrProvider::Reducto,
}
}
}
#[derive(Clone, Debug, EnumString, PartialEq, Eq)]
pub enum OcrModel {
#[strum(serialize = "parse-v3")]
@ -143,37 +115,13 @@ impl OcrModel {
}
}
impl OcrIntegrationRequest {
pub fn kind(&self) -> OcrIntegrationKind {
match self {
Self::Mistral(_) => OcrIntegrationKind::Mistral,
Self::AzureMistral(_) => OcrIntegrationKind::AzureMistral,
Self::AzureDocumentIntelligence(_) => OcrIntegrationKind::AzureDocumentIntelligence,
Self::VertexMistral(_) => OcrIntegrationKind::VertexMistral,
Self::VertexDeepSeek(_) => OcrIntegrationKind::VertexDeepSeek,
Self::ReductoV3(_) => OcrIntegrationKind::ReductoV3,
Self::ReductoLegacy(_) => OcrIntegrationKind::ReductoLegacy,
}
}
}
#[tracing::instrument(target = "litellm::function_trace", level = "trace", skip_all)]
pub fn resolve_ocr_integration(provider: OcrProvider, model: &OcrModel) -> OcrIntegrationKind {
let lower = model.as_str().to_ascii_lowercase();
match (provider, model) {
(OcrProvider::Mistral, _) => OcrIntegrationKind::Mistral,
(OcrProvider::AzureAi, _)
if lower.contains("doc-intelligence") || lower.contains("documentintelligence") =>
{
OcrIntegrationKind::AzureDocumentIntelligence
}
(OcrProvider::AzureAi, _) => OcrIntegrationKind::AzureMistral,
(OcrProvider::VertexAi, _) if lower.contains("deepseek") => {
OcrIntegrationKind::VertexDeepSeek
}
(OcrProvider::VertexAi, _) => OcrIntegrationKind::VertexMistral,
(OcrProvider::Reducto, OcrModel::ReductoLegacy) => OcrIntegrationKind::ReductoLegacy,
(OcrProvider::Reducto, _) => OcrIntegrationKind::ReductoV3,
match provider {
OcrProvider::Mistral => OcrIntegrationKind::Mistral,
OcrProvider::AzureAi => super::backends::azure_ai::resolve_integration(model),
OcrProvider::VertexAi => super::backends::vertex_ai::resolve_integration(model),
OcrProvider::Reducto => super::backends::reducto::resolve_integration(model),
}
}
@ -199,50 +147,34 @@ pub fn decode_integration_request(
kind: OcrIntegrationKind,
params: Map<String, Value>,
) -> Result<OcrIntegrationRequest, Error> {
let request = match kind {
OcrIntegrationKind::Mistral => OcrIntegrationRequest::Mistral(OcrIntegrationInput {
params: MISTRAL.decode_input_params(params, "optional_params")?,
backend_config: (),
}),
OcrIntegrationKind::AzureMistral => {
let backend = AzureAuthInputs::from_optional_params(&params)?;
OcrIntegrationRequest::AzureMistral(OcrIntegrationInput {
params: AZURE_MISTRAL.decode_input_params(params, "optional_params")?,
backend_config: backend,
})
}
OcrIntegrationKind::AzureDocumentIntelligence => {
let backend = AzureAuthInputs::from_optional_params(&params)?;
OcrIntegrationRequest::AzureDocumentIntelligence(OcrIntegrationInput {
params: AZURE_DOCUMENT_INTELLIGENCE
.decode_input_params(params, "optional_params")?,
backend_config: backend,
})
}
OcrIntegrationKind::VertexMistral => {
let backend = VertexAuthInputs::from_optional_params(&params)?;
OcrIntegrationRequest::VertexMistral(OcrIntegrationInput {
params: VERTEX_MISTRAL.decode_input_params(params, "optional_params")?,
backend_config: backend,
})
}
OcrIntegrationKind::VertexDeepSeek => {
let backend = VertexAuthInputs::from_optional_params(&params)?;
OcrIntegrationRequest::VertexDeepSeek(OcrIntegrationInput {
params: VERTEX_DEEPSEEK.decode_input_params(params, "optional_params")?,
backend_config: backend,
})
}
OcrIntegrationKind::ReductoV3 => OcrIntegrationRequest::ReductoV3(OcrIntegrationInput {
params: REDUCTO_V3.decode_input_params(params, "optional_params")?,
backend_config: (),
}),
OcrIntegrationKind::ReductoLegacy => {
OcrIntegrationRequest::ReductoLegacy(OcrIntegrationInput {
params: REDUCTO_LEGACY.decode_input_params(params, "optional_params")?,
backend_config: (),
})
}
};
Ok(request)
macro_rules! decode_selected_integration {
($( $variant:ident, $integration:ty, $instance:expr, $provider:ident; )+) => {
match kind {
$(
OcrIntegrationKind::$variant => OcrIntegrationRequest::$variant(
decode_input::<$integration>($instance, params)?,
),
)+
}
};
}
Ok(super::integrations::for_each_ocr_integration!(
decode_selected_integration
))
}
fn decode_input<I>(
integration: I,
params: Map<String, Value>,
) -> Result<OcrIntegrationInput<I>, Error>
where
I: OcrIntegration,
{
let backend_config = I::Backend::decode_config(&params)?;
let params = integration.decode_input_params(params, "optional_params")?;
Ok(OcrIntegrationInput {
params,
backend_config,
})
}

View file

@ -1,6 +1,6 @@
use crate::ocr::backends::OcrIntegration;
use crate::ocr::registry::{AZURE_MISTRAL, MISTRAL};
use crate::ocr::tests::body;
use crate::ocr::integrations::OcrIntegration;
use crate::ocr::integrations::{AzureMistral as AZURE_MISTRAL, MistralDirect as MISTRAL};
use crate::ocr::test_support::body;
use crate::ocr::types::OcrConnection;
use serde_json::json;

View file

@ -1,11 +1,12 @@
use crate::ocr::backends::OcrIntegration;
use crate::ocr::formats::OcrFormat;
use crate::ocr::integrations::AzureDocumentIntelligence as AZURE_DOCUMENT_INTELLIGENCE;
use crate::ocr::integrations::OcrIntegration;
use crate::ocr::prepare::OcrIntegrationKind;
use crate::ocr::registry::{AZURE_DOCUMENT_INTELLIGENCE, decode_integration_request};
use crate::ocr::tests::perform_ocr;
use crate::ocr::tests::{MockResponse, body, mock_server, params, transform, wire_request};
use crate::ocr::registry::decode_integration_request;
use crate::ocr::test_support::perform_ocr;
use crate::ocr::test_support::{MockResponse, body, mock_server, params, transform, wire_request};
use crate::ocr::types::OcrConnection;
use rstest::rstest;
use rstest::{fixture, rstest};
use serde_json::{Value, json};
fn connection() -> OcrConnection {
@ -15,6 +16,7 @@ fn connection() -> OcrConnection {
..Default::default()
}
}
#[fixture]
fn operation() -> Value {
json!({"status":"succeeded","operationExtension":42,"analyzeResult":{
"content":"A\n\nB","tables":[{"cells":[]}],"keyValuePairs":[{"key":{"content":"A"}}],
@ -164,12 +166,12 @@ async fn azure_document_intelligence_dot_segment_model_id_is_rejected() {
assert!(prepared_url(model, &mapped).await.is_err());
}
}
#[test]
fn document_intelligence_response_normalizes_pages() {
#[rstest]
fn document_intelligence_response_normalizes_pages(operation: Value) {
let result = transform(
&AZURE_DOCUMENT_INTELLIGENCE,
"model",
operation(),
operation.clone(),
json!({}),
)
.unwrap();
@ -179,7 +181,7 @@ fn document_intelligence_response_normalizes_pages() {
json!({"width":816,"height":1056,"dpi":96})
);
assert_eq!(result["usage_info"]["pages_processed"], 1);
assert_eq!(result["tables"], operation()["analyzeResult"]["tables"]);
assert_eq!(result["tables"], operation["analyzeResult"]["tables"]);
}
#[test]
fn document_intelligence_response_tolerates_missing_native_fields() {
@ -255,21 +257,21 @@ fn document_intelligence_non_succeeded_status_is_rejected() {
);
}
}
#[test]
fn document_intelligence_native_format_carries_raw_operation() {
#[rstest]
fn document_intelligence_native_format_carries_raw_operation(operation: Value) {
let response = transform(
&AZURE_DOCUMENT_INTELLIGENCE,
"model",
operation(),
operation.clone(),
json!({"req_format":"native"}),
)
.unwrap();
assert_eq!(response["provider_native_response"], operation());
assert_eq!(response["provider_native_response"], operation);
assert!(
transform(
&AZURE_DOCUMENT_INTELLIGENCE,
"model",
operation(),
operation.clone(),
json!({"req_format":"litellm"})
)
.unwrap()
@ -301,7 +303,10 @@ fn document_intelligence_rejects_unknown_req_format() {
#[case(false)]
#[case(true)]
#[tokio::test]
async fn polling_forwards_subscription_or_bearer_and_preserves_native(#[case] bearer: bool) {
async fn polling_forwards_subscription_or_bearer_and_preserves_native(
operation: Value,
#[case] bearer: bool,
) {
let (base, requests, server) = mock_server(vec![
MockResponse {
status: 202,
@ -313,7 +318,7 @@ async fn polling_forwards_subscription_or_bearer_and_preserves_native(#[case] be
headers: vec![("Retry-After", "0".into())],
body: json!({"status":"running"}),
},
MockResponse::json(operation()),
MockResponse::json(operation.clone()),
])
.await;
let mut request = wire_request(
@ -325,15 +330,21 @@ async fn polling_forwards_subscription_or_bearer_and_preserves_native(#[case] be
request.connection.api_key = None;
request.connection.extra_headers = vec![("Authorization".into(), "Bearer token".into())];
}
request
.connection
.extra_headers
.push(("X-Trace".into(), "initial-request-only".into()));
let result = perform_ocr(request).await.unwrap();
server.await.unwrap();
assert_eq!(
result.provider_native_response,
Some(operation().as_object().unwrap().clone())
Some(operation.as_object().unwrap().clone())
);
let seen = requests.lock().unwrap();
assert!(seen[0].contains("&pages=1%2C3"));
assert!(seen[0].contains("x-trace: initial-request-only"));
for poll in &seen[1..] {
assert!(!poll.to_ascii_lowercase().contains("x-trace:"));
assert!(poll.to_ascii_lowercase().contains(if bearer {
"authorization: bearer token"
} else {

View file

@ -1,6 +1,7 @@
use crate::ocr::backends::mistral::complete_url;
use crate::ocr::registry::MISTRAL;
use crate::ocr::tests::{body, transform};
use crate::ocr::formats::mistral::MistralOcrFormat;
use crate::ocr::test_support::{format_body, transform_format};
use crate::ocr::types::OcrDocument;
use rstest::rstest;
use serde_json::json;
@ -10,12 +11,15 @@ use serde_json::json;
#[case(json!({"pages":[0,2],"include_image_base64":true,"image_limit":2,"image_min_size":100}))]
#[case(json!({"table_format":"html","confidence_scores_granularity":"word","include_blocks":true,"id":"req-123"}))]
#[case(json!({"bbox_annotation_format":{"type":"json_schema","schema":{"type":"object"}},"document_annotation_format":{"type":"json_schema"},"document_annotation_prompt":"extract"}))]
#[tokio::test]
async fn transform_ocr_request_includes_each_optional_param(#[case] options: serde_json::Value) {
fn transform_ocr_request_includes_each_optional_param(#[case] options: serde_json::Value) {
let document = json!({"type":"document_url","document_url":"https://example.com/a.pdf"});
let result = body(&MISTRAL, "model", document.clone(), options.clone())
.await
.unwrap();
let result = format_body(
&MistralOcrFormat,
"model",
serde_json::from_value::<OcrDocument>(document.clone()).unwrap(),
options.clone(),
)
.unwrap();
assert_eq!(result["model"], "model");
assert_eq!(result["document"], document);
for (name, value) in options.as_object().unwrap() {
@ -23,15 +27,17 @@ async fn transform_ocr_request_includes_each_optional_param(#[case] options: ser
}
}
#[tokio::test]
async fn map_ocr_params_drops_unknown_params() {
let result = body(
&MISTRAL,
#[test]
fn map_ocr_params_drops_unknown_params() {
let result = format_body(
&MistralOcrFormat,
"model",
json!({"type":"image_url","image_url":"data:image/png;base64,YWJj"}),
serde_json::from_value::<OcrDocument>(
json!({"type":"image_url","image_url":"data:image/png;base64,YWJj"}),
)
.unwrap(),
json!({"unknown":{},"extract_header":true}),
)
.await
.unwrap();
assert!(result.get("unknown").is_none());
assert_eq!(result["extract_header"], true);
@ -40,7 +46,7 @@ async fn map_ocr_params_drops_unknown_params() {
#[test]
fn transform_ocr_response_preserves_ocr4_page_fields() {
let page = json!({"index":0,"markdown":"hello","header":"head","footer":"foot","confidence_scores":{"mean":0.99},"blocks":[{"type":"text","content":"hello"}],"images":[{"id":"img-1","image_base64":"YWJj","top_left_x":12}],"dimensions":{"width":100,"height":200,"dpi":96}});
let response = transform(&MISTRAL, "model", json!({"pages":[page.clone()],"model":"returned-model","usage_info":{"pages_processed":1,"future_counter":5}}), json!({})).unwrap();
let response = transform_format(&MistralOcrFormat, "model", json!({"pages":[page.clone()],"model":"returned-model","usage_info":{"pages_processed":1,"future_counter":5}}), json!({}), false).unwrap();
for (name, value) in page.as_object().unwrap() {
if name != "images" {
assert_eq!(&response["pages"][0][name], value);
@ -53,18 +59,28 @@ fn transform_ocr_response_preserves_ocr4_page_fields() {
#[test]
fn transform_ocr_response_normalizes_mistral_json() {
let result = transform(
&MISTRAL,
let result = transform_format(
&MistralOcrFormat,
"model",
json!({"pages":[{"index":"0","markdown":"hello"}],"usage_info":{"pages_processed":"1"}}),
json!({}),
false,
)
.unwrap();
assert_eq!(result["pages"][0]["index"], 0);
assert_eq!(result["usage_info"]["pages_processed"], 1);
assert_eq!(result["pages"][0]["images"], serde_json::Value::Null);
assert!(result.get("provider_native_response").is_none());
assert!(transform(&MISTRAL, "model", json!({"pages":null}), json!({})).is_err());
assert!(
transform_format(
&MistralOcrFormat,
"model",
json!({"pages":null}),
json!({}),
false
)
.is_err()
);
}
#[test]

View file

@ -1,93 +1,10 @@
use serde_json::{Value, json};
use std::sync::{Arc, Mutex};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
use super::backends::{MappedParams, OcrIntegration};
use super::formats::OcrFormat;
use serde_json::{Value, json};
use super::types::OcrConnection;
use super::OcrClient;
use super::test_support::{MockResponse, mock_server, perform_ocr, wire_request};
use super::wire::{OcrWireRequest, decode_request, decode_response};
use super::{OcrClient, OcrRequest};
use crate::ocr::error::OcrError;
pub(crate) fn ocr_client() -> OcrClient {
let document_http = reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.build()
.expect("test document client builds");
OcrClient::for_test(reqwest::Client::new(), document_http)
}
pub(crate) async fn perform_ocr(
request: OcrRequest,
) -> Result<super::OcrResponseData, crate::Error> {
ocr_client().perform(request).await
}
pub(crate) fn params<I>(_integration: &I, value: Value) -> MappedParams<I>
where
I: OcrIntegration,
{
I::FORMAT
.map_params(serde_json::from_value(value).unwrap())
.unwrap()
}
pub(crate) fn transform<I>(
integration: &I,
model: &str,
value: Value,
options: Value,
) -> Result<Value, OcrError>
where
I: OcrIntegration,
{
let params = I::FORMAT.map_params(serde_json::from_value(options).unwrap())?;
let decoded = decode_response(
&serde_json::to_vec(&value).unwrap(),
integration.preserve_native_response(&params),
)?;
let mut response = I::FORMAT.transform_response(model, decoded.data, &params)?;
response.provider_native_response = decoded.native;
Ok(response.into_json())
}
pub(crate) async fn body<I>(
integration: &I,
model: &str,
document: Value,
options: Value,
) -> Result<Value, OcrError>
where
I: OcrIntegration,
{
let params = I::FORMAT.map_params(serde_json::from_value(options).unwrap())?;
let client = ocr_client();
let document = integration
.prepare_document(
&client,
serde_json::from_value(document).unwrap(),
&OcrConnection::default(),
&[],
)
.await?;
Ok(
serde_json::to_value(I::FORMAT.transform_request(model, document.into(), &params)?)
.unwrap(),
)
}
pub(crate) fn wire_request(model: &str, base: &str, options: Value) -> OcrRequest {
decode_request(OcrWireRequest {
model: model.into(),
document: json!({"type":"document_url","document_url":"data:application/pdf;base64,YWJj"}),
api_key: Some("test-key".into()),
api_base: Some(base.into()),
custom_llm_provider: None,
extra_headers: None,
optional_params: options.as_object().unwrap().clone(),
timeout_seconds: Some(2.0),
})
.unwrap()
}
#[test]
fn provider_options_are_decoded_only_for_the_selected_backend() {
@ -116,78 +33,6 @@ fn provider_options_are_decoded_only_for_the_selected_backend() {
assert!(vertex.is_err());
}
pub(crate) struct MockResponse {
pub status: u16,
pub headers: Vec<(&'static str, String)>,
pub body: Value,
}
impl MockResponse {
pub fn json(body: Value) -> Self {
Self {
status: 200,
headers: vec![],
body,
}
}
}
pub(crate) async fn mock_server(
responses: Vec<MockResponse>,
) -> (String, Arc<Mutex<Vec<String>>>, tokio::task::JoinHandle<()>) {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let base = format!("http://{}", listener.local_addr().unwrap());
let requests = Arc::new(Mutex::new(Vec::new()));
let seen = requests.clone();
let server_base = base.clone();
let task = tokio::spawn(async move {
for response in responses {
let (mut socket, _) = listener.accept().await.unwrap();
let mut bytes = Vec::new();
let mut buffer = [0u8; 4096];
let header_end = loop {
let n = socket.read(&mut buffer).await.unwrap();
assert!(n > 0);
bytes.extend_from_slice(&buffer[..n]);
if let Some(index) = bytes.windows(4).position(|s| s == b"\r\n\r\n") {
break index + 4;
}
};
let length = String::from_utf8_lossy(&bytes[..header_end])
.lines()
.find_map(|line| {
let (name, value) = line.split_once(':')?;
name.eq_ignore_ascii_case("content-length")
.then(|| value.trim().parse::<usize>().unwrap())
})
.unwrap_or(0);
while bytes.len() < header_end + length {
let n = socket.read(&mut buffer).await.unwrap();
assert!(n > 0);
bytes.extend_from_slice(&buffer[..n]);
}
seen.lock()
.unwrap()
.push(String::from_utf8_lossy(&bytes).into_owned());
let body = serde_json::to_vec(&response.body).unwrap();
let headers = response
.headers
.into_iter()
.map(|(name, value)| {
format!("{name}: {}\r\n", value.replace("{base}", &server_base))
})
.collect::<String>();
let head = format!(
"HTTP/1.1 {} OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{}\r\n",
response.status,
body.len(),
headers
);
socket.write_all(head.as_bytes()).await.unwrap();
socket.write_all(&body).await.unwrap();
}
});
(base, requests, task)
}
#[rstest::rstest]
#[case("mistral/model", "/v1/ocr")]
#[case(

View file

@ -0,0 +1,189 @@
use std::sync::{Arc, Mutex};
use serde_json::{Value, json};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
use crate::ocr::error::OcrError;
use crate::ocr::formats::OcrFormat;
use crate::ocr::integrations::{MappedParams, OcrIntegration};
use crate::ocr::types::OcrConnection;
use crate::ocr::wire::{OcrWireRequest, decode_request, decode_response};
use crate::ocr::{OcrClient, OcrRequest, OcrResponseData};
pub(crate) fn ocr_client() -> OcrClient {
let document_http = reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.build()
.expect("test document client builds");
OcrClient::for_test(reqwest::Client::new(), document_http)
}
pub(crate) async fn perform_ocr(request: OcrRequest) -> Result<OcrResponseData, crate::Error> {
ocr_client().perform(request).await
}
pub(crate) fn params<I>(_integration: &I, value: Value) -> MappedParams<I>
where
I: OcrIntegration,
{
I::FORMAT
.map_params(serde_json::from_value(value).unwrap())
.unwrap()
}
pub(crate) fn transform<I>(
integration: &I,
model: &str,
value: Value,
options: Value,
) -> Result<Value, OcrError>
where
I: OcrIntegration,
{
let params = I::FORMAT.map_params(serde_json::from_value(options.clone()).unwrap())?;
let preserve_native_response = integration.preserve_native_response(&params);
transform_format(&I::FORMAT, model, value, options, preserve_native_response)
}
pub(crate) fn transform_format<F>(
format: &F,
model: &str,
value: Value,
options: Value,
preserve_native_response: bool,
) -> Result<Value, OcrError>
where
F: OcrFormat,
{
let params = format.map_params(serde_json::from_value(options).unwrap())?;
let decoded = decode_response(
&serde_json::to_vec(&value).unwrap(),
preserve_native_response,
)?;
let mut response = format.transform_response(model, decoded.data, &params)?;
response.provider_native_response = decoded.native;
Ok(response.into_json())
}
pub(crate) async fn body<I>(
integration: &I,
model: &str,
document: Value,
options: Value,
) -> Result<Value, OcrError>
where
I: OcrIntegration,
{
let client = ocr_client();
let document = integration
.prepare_document(
&client,
serde_json::from_value(document).unwrap(),
&OcrConnection::default(),
&[],
)
.await?;
format_body(&I::FORMAT, model, document.into(), options)
}
pub(crate) fn format_body<F>(
format: &F,
model: &str,
document: F::PreparedDocument,
options: Value,
) -> Result<Value, OcrError>
where
F: OcrFormat,
{
let params = format.map_params(serde_json::from_value(options).unwrap())?;
Ok(serde_json::to_value(format.transform_request(model, document, &params)?).unwrap())
}
pub(crate) fn wire_request(model: &str, base: &str, options: Value) -> OcrRequest {
decode_request(OcrWireRequest {
model: model.into(),
document: json!({"type":"document_url","document_url":"data:application/pdf;base64,YWJj"}),
api_key: Some("test-key".into()),
api_base: Some(base.into()),
custom_llm_provider: None,
extra_headers: None,
optional_params: options.as_object().unwrap().clone(),
timeout_seconds: Some(2.0),
})
.unwrap()
}
pub(crate) struct MockResponse {
pub status: u16,
pub headers: Vec<(&'static str, String)>,
pub body: Value,
}
impl MockResponse {
pub fn json(body: Value) -> Self {
Self {
status: 200,
headers: vec![],
body,
}
}
}
pub(crate) async fn mock_server(
responses: Vec<MockResponse>,
) -> (String, Arc<Mutex<Vec<String>>>, tokio::task::JoinHandle<()>) {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let base = format!("http://{}", listener.local_addr().unwrap());
let requests = Arc::new(Mutex::new(Vec::new()));
let seen = requests.clone();
let server_base = base.clone();
let task = tokio::spawn(async move {
for response in responses {
let (mut socket, _) = listener.accept().await.unwrap();
let mut bytes = Vec::new();
let mut buffer = [0u8; 4096];
let header_end = loop {
let n = socket.read(&mut buffer).await.unwrap();
assert!(n > 0);
bytes.extend_from_slice(&buffer[..n]);
if let Some(index) = bytes.windows(4).position(|s| s == b"\r\n\r\n") {
break index + 4;
}
};
let length = String::from_utf8_lossy(&bytes[..header_end])
.lines()
.find_map(|line| {
let (name, value) = line.split_once(':')?;
name.eq_ignore_ascii_case("content-length")
.then(|| value.trim().parse::<usize>().unwrap())
})
.unwrap_or(0);
while bytes.len() < header_end + length {
let n = socket.read(&mut buffer).await.unwrap();
assert!(n > 0);
bytes.extend_from_slice(&buffer[..n]);
}
seen.lock()
.unwrap()
.push(String::from_utf8_lossy(&bytes).into_owned());
let body = serde_json::to_vec(&response.body).unwrap();
let headers = response
.headers
.into_iter()
.map(|(name, value)| {
format!("{name}: {}\r\n", value.replace("{base}", &server_base))
})
.collect::<String>();
let head = format!(
"HTTP/1.1 {} OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n{}\r\n",
response.status,
body.len(),
headers
);
socket.write_all(head.as_bytes()).await.unwrap();
socket.write_all(&body).await.unwrap();
}
});
(base, requests, task)
}

View file

@ -1,77 +1,48 @@
use super::*;
use rstest::rstest;
#[test]
fn typed_provider_and_model_select_the_request_contract() {
let cases = [
("mistral", "future-model", OcrIntegrationKind::Mistral),
(
"azure_ai",
"doc-intelligence/prebuilt-read",
OcrIntegrationKind::AzureDocumentIntelligence,
),
("azure_ai", "future-model", OcrIntegrationKind::AzureMistral),
(
"vertex_ai",
"deepseek-ocr",
OcrIntegrationKind::VertexDeepSeek,
),
(
"vertex_ai",
"future-model",
OcrIntegrationKind::VertexMistral,
),
("reducto", "parse-legacy", OcrIntegrationKind::ReductoLegacy),
("reducto", "parse-v3", OcrIntegrationKind::ReductoV3),
("reducto", "future-model", OcrIntegrationKind::ReductoV3),
];
for (provider, model, expected) in cases {
let provider = provider.parse().expect("known provider");
let model = OcrModel::from(model);
assert_eq!(resolve_ocr_integration(provider, &model), expected);
}
#[rstest]
#[case::mistral_default("mistral", "future-model", OcrIntegrationKind::Mistral)]
#[case::azure_document_intelligence(
"azure_ai",
"doc-intelligence/prebuilt-read",
OcrIntegrationKind::AzureDocumentIntelligence
)]
#[case::azure_mistral("azure_ai", "future-model", OcrIntegrationKind::AzureMistral)]
#[case::vertex_deepseek("vertex_ai", "deepseek-ocr", OcrIntegrationKind::VertexDeepSeek)]
#[case::vertex_mistral("vertex_ai", "future-model", OcrIntegrationKind::VertexMistral)]
#[case::reducto_legacy("reducto", "parse-legacy", OcrIntegrationKind::ReductoLegacy)]
#[case::reducto_v3("reducto", "parse-v3", OcrIntegrationKind::ReductoV3)]
#[case::reducto_default("reducto", "future-model", OcrIntegrationKind::ReductoV3)]
fn typed_provider_and_model_select_the_request_contract(
#[case] provider: &str,
#[case] model: &str,
#[case] expected: OcrIntegrationKind,
) {
let provider = provider.parse().expect("known provider");
let model = OcrModel::from(model);
assert_eq!(resolve_ocr_integration(provider, &model), expected);
}
#[test]
fn integration_kind_exposes_its_routing_provider() {
let cases = [
(OcrIntegrationKind::Mistral, OcrProvider::Mistral, "mistral"),
(
OcrIntegrationKind::AzureMistral,
OcrProvider::AzureAi,
"azure_ai",
),
(
OcrIntegrationKind::AzureDocumentIntelligence,
OcrProvider::AzureAi,
"azure_ai",
),
(
OcrIntegrationKind::VertexMistral,
OcrProvider::VertexAi,
"vertex_ai",
),
(
OcrIntegrationKind::VertexDeepSeek,
OcrProvider::VertexAi,
"vertex_ai",
),
(
OcrIntegrationKind::ReductoV3,
OcrProvider::Reducto,
"reducto",
),
(
OcrIntegrationKind::ReductoLegacy,
OcrProvider::Reducto,
"reducto",
),
];
for (integration, expected_provider, expected_name) in cases {
assert_eq!(integration.provider(), expected_provider);
assert_eq!(integration.provider().as_str(), expected_name);
}
#[rstest]
#[case::mistral(OcrIntegrationKind::Mistral, OcrProvider::Mistral, "mistral")]
#[case::azure_mistral(OcrIntegrationKind::AzureMistral, OcrProvider::AzureAi, "azure_ai")]
#[case::azure_document_intelligence(
OcrIntegrationKind::AzureDocumentIntelligence,
OcrProvider::AzureAi,
"azure_ai"
)]
#[case::vertex_mistral(OcrIntegrationKind::VertexMistral, OcrProvider::VertexAi, "vertex_ai")]
#[case::vertex_deepseek(OcrIntegrationKind::VertexDeepSeek, OcrProvider::VertexAi, "vertex_ai")]
#[case::reducto_v3(OcrIntegrationKind::ReductoV3, OcrProvider::Reducto, "reducto")]
#[case::reducto_legacy(OcrIntegrationKind::ReductoLegacy, OcrProvider::Reducto, "reducto")]
fn integration_kind_exposes_its_routing_provider(
#[case] integration: OcrIntegrationKind,
#[case] expected_provider: OcrProvider,
#[case] expected_name: &str,
) {
assert_eq!(integration.provider(), expected_provider);
assert_eq!(integration.provider().as_str(), expected_name);
}
#[test]

View file

@ -1,5 +1,7 @@
use crate::ocr::registry::{REDUCTO_LEGACY, REDUCTO_V3};
use crate::ocr::tests::{MockResponse, body, mock_server, perform_ocr, transform, wire_request};
use crate::ocr::integrations::{ReductoLegacy as REDUCTO_LEGACY, ReductoV3 as REDUCTO_V3};
use crate::ocr::test_support::{
MockResponse, body, mock_server, perform_ocr, transform, wire_request,
};
use rstest::rstest;
use serde_json::json;
@ -103,14 +105,78 @@ async fn test_parse_v3_file_upload_and_response_mapping(
.await;
let mut request = wire_request(&format!("reducto/{model}"), &base, json!({}));
request.document = request.document.with_source(source.to_string());
request.connection.extra_headers = vec![
("Content-Type".into(), "application/json".into()),
("X-Trace".into(), "upload-test".into()),
];
let response = perform_ocr(request).await.unwrap();
server.await.unwrap();
assert_eq!(response.pages[0].markdown, "hello");
let seen = seen.lock().unwrap();
assert_eq!(seen.len(), 2);
assert!(seen[0].starts_with("POST /upload "));
assert!(seen[0].contains("content-type: multipart/form-data; boundary="));
assert!(seen[0].contains("x-trace: upload-test"));
assert!(seen[0].contains("application/pdf"));
assert!(seen[0].contains("abc"));
assert!(seen[1].starts_with("POST /parse "));
assert!(seen[1].contains("reducto://uploaded.pdf"));
}
#[rstest]
#[case("parse-v3")]
#[case("parse-legacy")]
#[tokio::test]
async fn upload_rejects_empty_file_id_before_parsing(#[case] model: &str) {
let (base, seen, server) = mock_server(vec![MockResponse::json(json!({"file_id":""}))]).await;
let error = perform_ocr(wire_request(&format!("reducto/{model}"), &base, json!({})))
.await
.unwrap_err();
server.await.unwrap();
assert!(
matches!(error, crate::Error::OcrResponse(crate::ocr::error::OcrResponseError::ResponseField { path }) if path == "file_id")
);
assert_eq!(seen.lock().unwrap().len(), 1);
}
#[rstest]
#[case("parse-v3")]
#[case("parse-legacy")]
#[tokio::test]
async fn guardrail_rewrites_document_before_upload(#[case] model: &str) {
use crate::ocr::hooks::{OcrDuringCallRequest, OcrHookFuture, OcrHooks};
struct RewriteDocument;
impl OcrHooks for RewriteDocument {
fn has_guardrails(&self) -> bool {
true
}
fn during_call(
&self,
request: OcrDuringCallRequest,
) -> OcrHookFuture<'_, OcrDuringCallRequest> {
Box::pin(async move {
assert_eq!(
request.body["document_url"],
"data:application/pdf;base64,YWJj"
);
Ok(OcrDuringCallRequest {
body: json!({"type":"document_url","document_url":"reducto://guarded.pdf"}),
..request
})
})
}
}
let (base, seen, server) =
mock_server(vec![MockResponse::json(json!({"result":{"chunks":[]}}))]).await;
let mut request = wire_request(&format!("reducto/{model}"), &base, json!({}));
request.hooks = std::sync::Arc::new(RewriteDocument);
perform_ocr(request).await.unwrap();
server.await.unwrap();
let seen = seen.lock().unwrap();
assert_eq!(seen.len(), 1);
assert!(seen[0].starts_with("POST /parse "));
assert!(seen[0].contains("reducto://guarded.pdf"));
}

View file

@ -1,20 +1,22 @@
use crate::ocr::registry::VERTEX_DEEPSEEK;
use crate::ocr::tests::{body, transform};
use crate::ocr::formats::deepseek::DeepSeekOcrFormat;
use crate::ocr::test_support::{format_body, transform_format};
use crate::ocr::types::OcrDocument;
use rstest::rstest;
use serde_json::json;
#[rstest]
#[case("deepseek-ocr-maas")]
#[case("deepseek-ai/deepseek-ocr-maas")]
#[tokio::test]
async fn vertex_deepseek_request_uses_single_provider_namespace(#[case] model: &str) {
let result = body(
&VERTEX_DEEPSEEK,
fn deepseek_request_uses_single_provider_namespace(#[case] model: &str) {
let result = format_body(
&DeepSeekOcrFormat,
model,
json!({"type":"image_url","image_url":"gs://bucket/a.png"}),
serde_json::from_value::<OcrDocument>(
json!({"type":"image_url","image_url":"gs://bucket/a.png"}),
)
.unwrap(),
json!({"temperature":0.1,"max_tokens":1024,"ignored":true}),
)
.await
.unwrap();
assert_eq!(result["model"], "deepseek-ai/deepseek-ocr-maas");
assert_eq!(
@ -33,11 +35,12 @@ fn vertex_deepseek_response_wraps_markdown_content(
#[case] content: serde_json::Value,
#[case] expected: &str,
) {
let result = transform(
&VERTEX_DEEPSEEK,
let result = transform_format(
&DeepSeekOcrFormat,
"model",
json!({"choices":[{"message":{"content":content}}],"usage":{"prompt_tokens":1}}),
json!({}),
false,
)
.unwrap();
assert_eq!(result["pages"][0]["markdown"], expected);
@ -51,6 +54,6 @@ fn deepseek_rejects_missing_content_and_invalid_structured_pages() {
json!({"choices":[{"message":{"content":""}}]}),
json!({"choices":[{"message":{"content":{"pages":[{"markdown":42}]}}}]}),
] {
assert!(transform(&VERTEX_DEEPSEEK, "model", response, json!({})).is_err());
assert!(transform_format(&DeepSeekOcrFormat, "model", response, json!({}), false).is_err());
}
}

View file

@ -1,6 +1,6 @@
use crate::ocr::backends::OcrIntegration;
use crate::ocr::registry::{MISTRAL, VERTEX_MISTRAL};
use crate::ocr::tests::body;
use crate::ocr::integrations::OcrIntegration;
use crate::ocr::integrations::{MistralDirect as MISTRAL, VertexMistral as VERTEX_MISTRAL};
use crate::ocr::test_support::body;
use crate::ocr::types::OcrConnection;
use crate::providers::vertex_ai::auth::VertexAuthInputs;
use serde_json::json;