Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
"""Tasks 共享协议模型,仅定义字段与校验,不依赖 HTTP 或本地执行服务。"""
from __future__ import annotations
from typing import Literal
from docvortex.document.page_range import PAGE_RANGE_DESCRIPTION
from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, field_validator, model_validator
from ..filetypes import validate_parse_filename
from ..task_types import TaskFileState, TaskOutputFormat, TaskStatus
from ..types import Tier
MAX_TASK_FILES = 100
_PYDANTIC_CONFIG = ConfigDict(extra="forbid")
class ErrorDetail(BaseModel):
"""公共错误只使用稳定错误码和说明,可选参数路径用于精确定位输入。"""
model_config = _PYDANTIC_CONFIG
code: str = Field(min_length=1)
message: str
param: str | None = None
class ErrorResponse(BaseModel):
model_config = _PYDANTIC_CONFIG
error: ErrorDetail
class TaskProgress(BaseModel):
model_config = _PYDANTIC_CONFIG
completed: int = 0
failed: int = 0
total: int = 0
class FileParseInfo(BaseModel):
model_config = _PYDANTIC_CONFIG
tier: Tier
duration_ms: int | None = None
parser_version: str | None = None
class TaskFileIdentity(BaseModel):
"""共享文件身份和状态,部署响应及客户端可分别扩展各自上下文。"""
file_id: str = Field(min_length=1)
file_name: str
status: TaskFileState
class TaskFileInput(BaseModel):
"""仅声明输入,文件标识由服务端分配,不接受任何客户端 ID。"""
model_config = ConfigDict(extra="forbid")
file_name: str = Field(
min_length=1,
max_length=1024,
description=(
"Logical basename, not a path. No '/', backslash, ':', Unicode Cc control characters, or names '.' / '..'. "
"Hidden names and spaces are allowed; accepted names are preserved without trimming or URL decoding."
),
)
bytes: int | None = Field(default=None, gt=0, strict=True)
url: str | None = None
sha256sum: str | None = Field(default=None, pattern=r"^[a-f0-9]{64}$")
page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
@field_validator("file_name")
@classmethod
def validate_file_name(cls, value: str) -> str:
"""在接单前统一拒绝路径名称,保留逐文件字段的错误位置。"""
return validate_parse_filename(value)
@model_validator(mode="after")
def validate_source(self) -> TaskFileInput:
"""上传项必须声明大小;URL 只校验合法性,保留签名地址的原始字符串。"""
if self.url is None:
if self.bytes is None:
raise ValueError("bytes is required when url is not supplied")
else:
AnyHttpUrl(self.url)
return self
class TaskFileItem(TaskFileInput):
"""接单前补全文件标识,内部执行和状态响应只消费完整文件条目。"""
file_id: str
class UploadTaskOptions(BaseModel):
"""解析选项仅来自 JSON 主体,文件元数据独立保存在 files 中。"""
model_config = ConfigDict(extra="forbid")
tier: Tier | None = Field(
default=None,
description=(
"PDF/image tier only. Omitted or null selects the first supported tier in the order "
"standard, basic, flash, advanced; advanced is automatic only when it is the sole available tier. "
"Explicit unsupported tiers are rejected. "
"All servers support native document formats with flash, independently of /v1/tiers "
"and ignoring any valid tier value."
),
)
ocr_mode: Literal["auto", "txt", "ocr"] = "auto"
page_range: str = ""
output_formats: list[TaskOutputFormat] = Field(default_factory=lambda: ["default"], min_length=1)
class CreateTaskRequest(UploadTaskOptions):
"""严格 JSON 创建请求,清单是数组而不是编码后的字符串。"""
files: list[TaskFileInput] = Field(min_length=1, max_length=MAX_TASK_FILES)
class TaskUploadLink(BaseModel):
"""描述一个文件的上传目标,客户端原样使用服务端给出的地址和请求头。"""
url: str
headers: dict[str, str]
expires_at: int
class CreatedTaskFile(TaskFileIdentity):
"""创建回执只提供输入映射、当前状态和可执行的上传动作。"""
upload: TaskUploadLink | None = None
@model_validator(mode="after")
def validate_upload_action(self) -> CreatedTaskFile:
"""创建回执的上传动作只能属于仍在等待文件的条目。"""
if self.upload is not None and self.status != "waiting-file":
raise ValueError("Only waiting-file accepts uploads")
return self
class CreateTaskResponse(BaseModel):
"""创建回执独立于查询详情,后续详情扩展不会进入创建响应。"""
task_id: str
status: TaskStatus
files: list[CreatedTaskFile]
class TaskFileDetail(TaskFileIdentity):
"""用统一状态描述文件准备和解析,上传对象仅表示客户端当前可执行的动作。"""
bytes: int | None = None
url: str | None = None
upload: TaskUploadLink | None = None
parse: FileParseInfo | None = None
result_url: str | None = None
error: ErrorDetail | None = None
@model_validator(mode="after")
def validate_upload_action(self) -> TaskFileDetail:
"""只有等待客户端文件的条目才能提供上传目标,服务端准备阶段可以为空。"""
if self.upload is not None and (self.status != "waiting-file" or self.url is not None):
raise ValueError("Only waiting-file without a URL source accepts uploads")
return self
class TaskDetailResponse(BaseModel):
"""任务状态只携带元数据;每个成功文件提供自己的下载链接。"""
task_id: str
status: TaskStatus
created_at: str
started_at: str | None = None
finished_at: str | None = None
output_formats: list[TaskOutputFormat]
progress: TaskProgress
files: list[TaskFileDetail]
error: ErrorDetail | None = None
class CanceledTaskFile(TaskFileIdentity):
"""取消回执保留每个文件的终态、可下载产物和失败原因。"""
status: Literal["completed", "failed", "canceled"]
parse: FileParseInfo | None = None
result_url: str | None = None
error: ErrorDetail | None = None
class CancelTaskResponse(BaseModel):
"""取消回执只描述本次取消后的确定终态,不携带上传或查询扩展字段。"""
task_id: str
status: Literal["canceled"]
finished_at: str
files: list[CanceledTaskFile]
class UploadFileResponse(BaseModel):
"""确认一次文件上传,仅返回对应文件的身份和当前状态。"""
task_id: str
file_id: str = Field(min_length=1)
status: TaskFileState
__all__ = [
"MAX_TASK_FILES",
"ErrorDetail",
"ErrorResponse",
"TaskProgress",
"FileParseInfo",
"TaskFileIdentity",
"TaskFileInput",
"TaskFileItem",
"UploadTaskOptions",
"CreateTaskRequest",
"TaskUploadLink",
"CreatedTaskFile",
"CreateTaskResponse",
"TaskFileDetail",
"TaskDetailResponse",
"CanceledTaskFile",
"CancelTaskResponse",
"UploadFileResponse",
]