readanydoc 0.1.0__py3-none-any.whl

readanydoc/__init__.py

@@ -0,0 +1,12 @@
+"""readanydoc: an open-source document parser around vision models, with Reducto's HTTP API.
+
+Use it as a library (``readanydoc.parse``, ``readanydoc.extract``) or run the server (``readanydoc serve``).
+"""
+
+__version__ = "0.1.0"
+
+from .library import (Block, BoundingBox, Citation, ExtractResult, ParseResult, Usage,  # noqa: E402
+                      extract, parse)
+
+__all__ = ["parse", "extract", "ParseResult", "ExtractResult", "Block", "BoundingBox", "Citation", "Usage",
+           "__version__"]

readanydoc/api/__init__.py

@@ -0,0 +1,6 @@
+"""HTTP API: a drop-in for Reducto's v3 routes. ``create_app()`` builds the FastAPI app."""
+
+from .app import create_app
+from .config import ServerSettings
+
+__all__ = ["ServerSettings", "create_app"]

readanydoc/api/__main__.py

@@ -0,0 +1,26 @@
+"""``python -m readanydoc.api [--host H] [--port P]`` (same as ``readanydoc serve``)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def serve(host: str = "127.0.0.1", port: int = 8000, log_level: str = "info") -> int:
+    import uvicorn
+
+    from .app import create_app
+    uvicorn.run(create_app(), host=host, port=port, log_level=log_level)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="readanydoc.api")
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=8000)
+    args = ap.parse_args(argv)
+    return serve(args.host, args.port)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

readanydoc/api/app.py

@@ -0,0 +1,300 @@
+"""FastAPI app: Reducto's v3 routes on top of the readanydoc pipeline.
+
+    uv run readanydoc serve --port 8000        (or: python -m readanydoc.api)
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+import os
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from fastapi import Depends, FastAPI, Query, Request
+from fastapi.concurrency import run_in_threadpool
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import FileResponse, JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from .. import __version__
+from ..store import ACTIVE, Database, FileStore, Job, JobStore
+from . import errors, schemas, webhooks
+from .config import API_KEY_ENV, ServerSettings
+from .inputs import ApiGone
+from .service import PIPELINE_GONE, Service
+from .worker import Worker
+
+# GET /job only knows these four in Reducto's schema; the rest are folded unless READANYDOC_JOB_STATUS_DETAIL=1
+PUBLIC_STATUS = {"Pending": "Pending", "InProgress": "Pending", "Completing": "Pending",
+                 "Completed": "Completed", "Failed": "Failed", "Cancelled": "Failed"}
+
+
+def require_auth(request: Request) -> None:
+    key = os.environ.get(API_KEY_ENV)
+    if not key:
+        return  # open server (local use)
+    scheme, _, token = request.headers.get("authorization", "").partition(" ")
+    if scheme.lower() != "bearer" or not hmac.compare_digest(token.strip().encode(), key.encode()):
+        raise errors.unauthorized()
+
+
+def _iso(ts: Optional[float]) -> Optional[str]:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat() if ts else None
+
+
+def create_app(settings: Optional[ServerSettings] = None) -> FastAPI:
+    settings = settings or ServerSettings()
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    db = Database(settings.data_dir / "readanydoc.sqlite3")
+    files = FileStore(db, settings.data_dir / "files")
+    jobs = JobStore(db, settings.data_dir / "jobs")
+    service = Service(settings, files, jobs)
+    worker = Worker(settings, db, files, jobs, service)
+    jobs.recover()
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        worker.ensure_started()
+        yield
+        worker.stop()
+
+    app = FastAPI(title="readanydoc (Reducto-compatible API)", version=__version__, lifespan=lifespan)
+    app.state.settings, app.state.db, app.state.files = settings, db, files
+    app.state.jobs, app.state.service, app.state.worker = jobs, service, worker
+    auth = [Depends(require_auth)]
+
+    # ---- errors ----
+    @app.exception_handler(errors.ApiError)
+    async def _api_error(_: Request, exc: errors.ApiError):
+        return JSONResponse(exc.body(), status_code=exc.status, headers=exc.headers)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http_error(_: Request, exc: StarletteHTTPException):
+        name = {401: "AUTH_ERROR", 404: "NOT_FOUND", 429: "RATE_LIMIT"}.get(exc.status_code, "INVALID_CONFIG")
+        err = errors.ApiError(exc.status_code, name, str(exc.detail), headers=getattr(exc, "headers", None))
+        return JSONResponse(err.body(), status_code=exc.status_code, headers=err.headers)
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_error(_: Request, exc: RequestValidationError):
+        detail = [{k: v for k, v in e.items() if k in ("loc", "msg", "type")} | {"loc": list(e.get("loc", ()))}
+                  for e in exc.errors()]
+        return JSONResponse({"detail": detail}, status_code=422)
+
+    @app.exception_handler(Exception)
+    async def _unhandled(_: Request, exc: Exception):
+        err = errors.from_exception(exc)
+        return JSONResponse(err.body(), status_code=err.status)
+
+    # ---- helpers ----
+    def base_url(request: Request) -> str:
+        return settings.public_url or str(request.base_url).rstrip("/")
+
+    def submit(request: Request, type_: str, body: schemas._M, *, sync: bool) -> Any:
+        req = body.dump()
+        if type_ == "Edit":
+            wh = req.get("webhook") or {}
+            priority, metadata = bool(req.get("priority")), wh.get("metadata")
+            webhook = wh if wh.get("mode", "disabled") != "disabled" else None
+            source = req.get("document_url")
+        else:
+            a = req.get("async") or {}
+            priority, metadata, webhook = bool(a.get("priority")), a.get("metadata"), a.get("webhook")
+            source = req.get("input")
+        job = jobs.create(type_, req, sync=sync, priority=priority, queue_priority=req.get("queue_priority", "auto"),
+                          metadata=metadata, webhook=None if sync else webhook, base_url=base_url(request),
+                          source=source, raw_config=json.dumps(body.model_dump(by_alias=True, mode="json",
+                                                                               exclude_unset=True)))
+        if not sync:
+            worker.notify()
+            return JSONResponse({"job_id": job.id})
+        _, response, err = service.process(job)
+        if err is not None:
+            raise err
+        return JSONResponse(response)
+
+    def get_job(job_id: str) -> Job:
+        job = jobs.get(job_id)
+        if job is None:
+            raise errors.not_found(f"Job not found: {job_id}", "job_not_found")
+        if job.deleted_at is not None:
+            raise ApiGone(job_id)
+        return job
+
+    # ---- upload + file store ----
+    @app.post("/upload", dependencies=auth)
+    async def upload(request: Request, extension: Optional[str] = None):
+        upload_file = None
+        if request.headers.get("content-type", "").lower().startswith("multipart/form-data"):
+            form = await request.form()
+            candidate = form.get("file")
+            if hasattr(candidate, "file") and hasattr(candidate, "filename"):
+                upload_file = candidate
+        if upload_file is None:
+            rec = files.create("upload", None, extension=extension or "", ttl=settings.upload_ttl, pending=True)
+            url = f"{base_url(request)}/upload/presigned/{rec.id}?token={rec.token}"
+            return {"file_id": rec.file_id, "presigned_url": url}
+        try:
+            rec = await run_in_threadpool(
+                files.put, "upload", upload_file.file, upload_file.filename, extension=extension or "",
+                ttl=settings.upload_ttl, content_type=upload_file.content_type, max_bytes=settings.max_upload_bytes)
+        except OverflowError:
+            raise errors.ApiError(413, "DOCUMENT_TOO_LARGE", "File exceeds the direct upload limit "
+                                  f"({settings.max_upload_bytes // (1024 * 1024)} MB)", "file_too_large") from None
+        return {"file_id": rec.file_id, "presigned_url": None}
+
+    @app.put("/upload/presigned/{file_id}", include_in_schema=False)
+    async def presigned_put(file_id: str, request: Request, token: str = ""):
+        rec = files.get(file_id, include_pending=True)
+        if rec is None:
+            raise errors.not_found("Upload URL not found or expired", "file_not_found")
+        if not hmac.compare_digest(token.encode(), rec.token.encode()):
+            raise errors.ApiError(403, "AUTH_ERROR", "Invalid upload token", "permission_error")
+        size = 0
+        with open(rec.path, "wb") as fh:
+            async for chunk in request.stream():
+                size += len(chunk)
+                if size > 50 * settings.max_upload_bytes:  # presigned route is the large-file path
+                    raise errors.ApiError(413, "DOCUMENT_TOO_LARGE", "File is too large", "file_too_large")
+                fh.write(chunk)
+        files.finish(rec, size)
+        return JSONResponse({"file_id": rec.file_id})
+
+    @app.delete("/upload/{file_id:path}", dependencies=auth)
+    def delete_upload(file_id: str):
+        rec = files.get(file_id, include_pending=True)
+        if rec is None or rec.kind != "upload":
+            raise errors.not_found(f"File not found: {file_id}", "file_not_found")
+        files.delete(rec.id)
+        return {"file_id": rec.file_id}
+
+    @app.get("/files/{file_id}", include_in_schema=False)
+    def get_file(file_id: str, token: str = ""):
+        rec = files.get(file_id)
+        if rec is None or not rec.path.exists():
+            raise errors.not_found("File not found or expired", "file_not_found")
+        if not hmac.compare_digest(token.encode(), rec.token.encode()):
+            raise errors.ApiError(403, "AUTH_ERROR", "Invalid file token", "permission_error")
+        return FileResponse(rec.path, media_type=rec.content_type or "application/octet-stream",
+                            filename=rec.filename)
+
+    # ---- parse / extract / split / classify / edit ----
+    @app.post("/parse", dependencies=auth)
+    def parse(request: Request, body: schemas.AsyncParseConfig):
+        # Reducto's /parse takes SyncParseConfig or AsyncParseConfig: an explicit `async` block queues the job
+        return submit(request, "Parse", body, sync="async_" not in body.model_fields_set)
+
+    @app.post("/parse_async", dependencies=auth)
+    def parse_async(request: Request, body: schemas.AsyncParseConfig):
+        return submit(request, "Parse", body, sync=False)
+
+    @app.post("/extract", dependencies=auth)
+    def extract(request: Request, body: schemas.AsyncExtractConfig):
+        return submit(request, "Extract", body, sync="async_" not in body.model_fields_set)
+
+    @app.post("/extract_async", dependencies=auth)
+    def extract_async(request: Request, body: schemas.AsyncExtractConfig):
+        return submit(request, "Extract", body, sync=False)
+
+    @app.post("/split", dependencies=auth)
+    def split(request: Request, body: schemas.SyncSplitConfig):
+        return submit(request, "Split", body, sync=True)
+
+    @app.post("/split_async", dependencies=auth)
+    def split_async(request: Request, body: schemas.AsyncSplitConfig):
+        return submit(request, "Split", body, sync=False)
+
+    @app.post("/classify", dependencies=auth)
+    def classify(request: Request, body: schemas.ClassifyConfig):
+        return submit(request, "Classify", body, sync=True)
+
+    @app.post("/classify_async", dependencies=auth)
+    def classify_async(request: Request, body: schemas.ClassifyConfig):
+        return submit(request, "Classify", body, sync=False)
+
+    @app.post("/edit", dependencies=auth)
+    def edit(request: Request, body: schemas.EditConfig):
+        return submit(request, "Edit", body, sync=True)
+
+    @app.post("/edit_async", dependencies=auth)
+    def edit_async(request: Request, body: schemas.AsyncEditConfig):
+        return submit(request, "Edit", body, sync=False)
+
+    @app.post("/pipeline", dependencies=auth, deprecated=True)
+    def pipeline(body: schemas.V3PipelineConfig):
+        raise errors.not_implemented(PIPELINE_GONE)
+
+    @app.post("/pipeline_async", dependencies=auth, deprecated=True)
+    def pipeline_async(body: schemas.V3AsyncPipelineConfig):
+        raise errors.not_implemented(PIPELINE_GONE)
+
+    # ---- jobs ----
+    @app.get("/job/{job_id}", dependencies=auth)
+    def retrieve_job(job_id: str):
+        job = get_job(job_id)
+        status = job.status if settings.job_status_detail else PUBLIC_STATUS[job.status]
+        result = jobs.read_result(job.id) if job.status == "Completed" else None
+        return {"status": status, "result": result, "progress": job.progress, "reason": job.reason,
+                "error": job.error, "type": job.type, "num_pages": job.num_pages, "total_pages": job.total_pages,
+                "source": job.source, "duration": job.duration, "created_at": _iso(job.created_at),
+                "raw_config": job.raw_config, "bucket": None}
+
+    @app.delete("/job/{job_id}", dependencies=auth, status_code=202)
+    def delete_job(job_id: str, include_persisted: bool = False):
+        job = get_job(job_id)  # 404 unknown, 410 already deleted
+        if job.status in ACTIVE:
+            raise errors.ApiError(409, "JOB_NOT_COMPLETE", f"Job {job_id} is still {job.status}; cancel it or wait "
+                                  "for it to finish before deleting", "job_not_complete", job_id)
+        jobs.mark_deleted(job_id)
+        files.delete_for_job(job_id)
+        return {"job_id": job_id}
+
+    @app.post("/cancel/{job_id}", dependencies=auth)
+    def cancel_job(job_id: str):
+        get_job(job_id)
+        status = jobs.cancel(job_id)
+        if status in ("Completed", "Failed"):
+            raise errors.ApiError(409, "JOB_STATE_ERROR", f"Job {job_id} already finished ({status})",
+                                  "job_state_error", job_id)
+        return {}
+
+    @app.get("/jobs", dependencies=auth)
+    def list_jobs(exclude_configs: bool = False, cursor: Optional[str] = None,
+                  limit: int = Query(default=100, ge=1, le=500)):
+        try:
+            page, nxt = jobs.list(limit=limit, cursor=cursor)
+        except Exception:
+            raise errors.bad_request("Invalid cursor", type="invalid_cursor") from None
+        return {"jobs": [{"job_id": j.id, "status": j.status, "type": j.type,
+                          "raw_config": "" if exclude_configs else j.raw_config, "created_at": _iso(j.created_at),
+                          "source": j.source, "num_pages": j.num_pages, "total_pages": j.total_pages,
+                          "duration": j.duration, "bucket": None} for j in page],
+                "next_cursor": nxt}
+
+    # ---- misc ----
+    @app.post("/configure_webhook", dependencies=auth)
+    async def configure_webhook(request: Request, url: Optional[str] = None):
+        """Reducto returns its Svix portal URL. We have no portal: this stores (``?url=`` or ``{"url": ...}``)
+        and returns the default URL used for svix-mode webhooks."""
+        if url is None and request.headers.get("content-type", "").startswith("application/json"):
+            try:
+                data = await request.json()
+                url = data.get("url") if isinstance(data, dict) else None
+            except Exception:
+                url = None
+        if url is not None:
+            if url and not url.startswith(("http://", "https://")):
+                raise errors.bad_request("url must be http(s)", type="invalid_url")
+            db.set_setting(webhooks.DEFAULT_URL_KEY, url or None)
+        return JSONResponse(db.get_setting(webhooks.DEFAULT_URL_KEY) or settings.webhook_url or "")
+
+    @app.get("/version")
+    def version():
+        return JSONResponse(f"readanydoc-{__version__}")
+
+    @app.get("/health", include_in_schema=False)
+    def health():
+        return {"status": "ok", "version": __version__, "auth": bool(os.environ.get(API_KEY_ENV))}
+
+    return app

readanydoc/api/config.py

@@ -0,0 +1,72 @@
+"""Server settings. Everything comes from environment variables; nothing here is a secret.
+
+The API key (``READANYDOC_API_KEY``) and the webhook signing secret (``READANYDOC_WEBHOOK_SECRET``) are read
+from the environment at the moment they are needed and are never stored, logged or returned.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .. import paths
+
+API_KEY_ENV = "READANYDOC_API_KEY"
+WEBHOOK_SECRET_ENV = "READANYDOC_WEBHOOK_SECRET"
+
+
+def _f(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, default))
+    except ValueError:
+        return default
+
+
+def _b(name: str, default: bool = False) -> bool:
+    v = os.environ.get(name)
+    return default if v is None else v.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _default_data_dir() -> Path:
+    return Path(os.environ.get("READANYDOC_DATA_DIR") or (paths.cache_dir() / "server"))
+
+
+@dataclass
+class ServerSettings:
+    data_dir: Path = field(default_factory=_default_data_dir)
+    # Base URL used in links we hand out (file URLs, presigned uploads). Empty = taken from each request.
+    public_url: str = field(default_factory=lambda: os.environ.get("READANYDOC_PUBLIC_URL", "").rstrip("/"))
+    upload_ttl: float = field(default_factory=lambda: _f("READANYDOC_UPLOAD_TTL_HOURS", 24) * 3600)
+    result_ttl: float = field(default_factory=lambda: _f("READANYDOC_RESULT_TTL_HOURS", 12) * 3600)
+    max_inline_bytes: int = field(default_factory=lambda: int(_f("READANYDOC_MAX_INLINE_BYTES", 6_000_000)))
+    max_upload_bytes: int = field(default_factory=lambda: int(_f("READANYDOC_MAX_UPLOAD_MB", 100) * 1024 * 1024))
+    # async jobs processed at once; pages of one document are read in parallel within each job
+    workers: int = field(default_factory=lambda: max(1, int(_f("READANYDOC_WORKERS", 4))))
+    # longest time one document may take (0 = no limit); a request that runs over fails with a timeout error
+    document_timeout: float = field(default_factory=lambda: _f("READANYDOC_DOCUMENT_TIMEOUT_SECONDS", 1800.0))
+    webhook_retries: int = field(default_factory=lambda: int(_f("READANYDOC_WEBHOOK_RETRIES", 3)))
+    webhook_backoff: float = field(default_factory=lambda: _f("READANYDOC_WEBHOOK_BACKOFF_SECONDS", 1.0))
+    webhook_timeout: float = field(default_factory=lambda: _f("READANYDOC_WEBHOOK_TIMEOUT_SECONDS", 10.0))
+    webhook_url: str = field(default_factory=lambda: os.environ.get("READANYDOC_WEBHOOK_URL", ""))
+    download_timeout: float = field(default_factory=lambda: _f("READANYDOC_DOWNLOAD_TIMEOUT_SECONDS", 60.0))
+    # Local file paths as `input` let a caller read any file the server can: off unless asked for.
+    allow_local_paths: bool = field(default_factory=lambda: _b("READANYDOC_ALLOW_LOCAL_PATHS"))
+    # document URLs that point at private or loopback addresses are refused (set to 0 to fetch from internal hosts)
+    block_private_urls: bool = field(default_factory=lambda: _b("READANYDOC_BLOCK_PRIVATE_URLS", True))
+    # GET /job reports only the statuses in Reducto's schema unless this is on (see docs/decisions.md).
+    job_status_detail: bool = field(default_factory=lambda: _b("READANYDOC_JOB_STATUS_DETAIL"))
+    janitor_interval: float = field(default_factory=lambda: _f("READANYDOC_JANITOR_SECONDS", 300.0))
+    poll_interval: float = 0.25
+    # ---- disk hygiene (store/cleanup.py); every limit is checked by the janitor, never against running jobs ----
+    # working caches (page renders, decrypted copies, figure crops, word caches); None = leave them alone
+    cache_dir: Path | None = field(default_factory=lambda: paths.cache_dir() if _b("READANYDOC_CLEAN_CACHE", True) else None)
+    cache_ttl: float = field(default_factory=lambda: _f("READANYDOC_CACHE_TTL_HOURS", 6) * 3600)
+    reused_cache_ttl: float = field(default_factory=lambda: _f("READANYDOC_REUSED_CACHE_TTL_DAYS", 14) * 86400)
+    max_cache_bytes: int = field(default_factory=lambda: int(_f("READANYDOC_MAX_CACHE_GB", 5) * 1024 ** 3))
+    max_data_bytes: int = field(default_factory=lambda: int(_f("READANYDOC_MAX_DATA_GB", 0) * 1024 ** 3))
+    clean_min_age: float = field(default_factory=lambda: _f("READANYDOC_CLEAN_MIN_AGE_SECONDS", 900.0))
+
+
+def api_key_configured() -> bool:
+    return bool(os.environ.get(API_KEY_ENV))

readanydoc/api/contracts.py

@@ -0,0 +1,139 @@
+"""The call contract between the API layer and ``readanydoc.tasks``.
+
+The API resolves inputs, runs the parse pipeline and hands each task a ``Document``; the task returns
+a plain dict that the API wraps into Reducto's response (job id, duration, usage defaults, URL result).
+
+Minimal form (what a replacement task or a test double needs):
+
+    readanydoc.tasks.extract.run(document, config)  -> dict
+    readanydoc.tasks.split.run(document, config)    -> dict
+    readanydoc.tasks.classify.run(document, config) -> dict
+    readanydoc.tasks.edit.run(input_path, config)   -> dict
+
+The tasks' published form adds keyword-only arguments; the adapter here inspects the signature
+and supplies whichever of them ``run`` declares:
+
+    run(document, config, *, llm, options=None)                              extract / split / classify
+    run(document, config, *, llm, source_path, output_path=None, options=None)   edit (document is None)
+
+``llm`` is ``readanydoc.tasks.llm.get_llm(os.environ.get("READANYDOC_TASK_LLM") or DEFAULT_LLM)``;
+``source_path`` is the local file to edit; ``output_path`` a path inside the job's output directory.
+
+``document``
+    ``readanydoc.model.Document`` (already parsed with the request's ``parsing`` options), or a
+    ``list[Document]`` when the request's ``input`` is a list (multi-document).
+``input_path`` (edit, minimal form only)
+    ``str`` path of the local file to edit (PDF or DOCX), already downloaded.
+``config``
+    The validated request body as a dict with every documented default filled in, keys exactly as in
+    Reducto's API (``instructions.schema``, ``settings.citations.enabled``, ``split_description``,
+    ``classification_schema``, ``edit_instructions``, ``form_schema`` ...). It still contains ``input``
+    / ``parsing`` / ``async`` (ignore them) and one extra key, ``"_readanydoc"``:
+    ``{"job_id": str, "profile": str, "output_dir": str}``; ``output_dir`` is a directory the task may
+    write files into.
+
+Return value: a dict (or a pydantic model, which is dumped). Keys the API reads:
+
+    extract   {"result": <object | list>,                      # required; with citations the task puts
+               "usage": {"num_fields": int, ...}?,             #   {"value", "citations"} leaves in result
+               "confidence": "high"|"low"?, "confidence_reason": str?}
+    split     {"result": {"splits": [{"name", "pages", "conf", "partitions"?}], "section_mapping": {...}|None},
+               "usage": {...}?}
+    classify  {"result": {"category": str}, "response_confidence": {"categories": [...]}?,
+               "extra_metadata": {str: str}?, "usage": {...}?}
+    edit      {"document_url": <local output file path, or a ready http(s) URL>
+               (or "document_path": str, or "document_bytes": bytes), "filename": str?,
+               "form_schema": [EditWidget...]?, "usage": {...}?}
+
+``job_id``, ``duration`` and ``response_type`` are set by the API; missing ``usage`` fields get
+defaults (``num_pages`` from the Document, ``num_fields`` by counting result leaves, ``credits`` null).
+Anything else in the dict is passed through into the response untouched.
+
+Errors: ``readanydoc.tasks.TaskError(status_code, detail)`` -> that status; ``NotImplementedError`` -> 501;
+``jsonschema`` SchemaError -> 422 INVALID_SCHEMA; ``ValueError`` -> 400 INVALID_CONFIG;
+``readanydoc.api.errors.ApiError`` -> as given; anything else -> 500. All in Reducto's error shape.
+If ``readanydoc.tasks.<name>`` cannot be imported, or has no ``run``, the route answers 501.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import os
+from pathlib import Path
+from typing import Any, Callable
+
+from . import errors
+
+TASK_LLM_ENV = "READANYDOC_TASK_LLM"
+TASKS = ("extract", "split", "classify", "edit")
+TaskFn = Callable[[Any, dict[str, Any]], Any]
+
+# tests (and embedders) can register a replacement here: OVERRIDES["extract"] = fn
+OVERRIDES: dict[str, TaskFn] = {}
+
+
+def load_task(name: str) -> TaskFn:
+    if name not in TASKS:
+        raise errors.not_implemented(f"unknown task {name!r}")
+    if name in OVERRIDES:
+        return OVERRIDES[name]
+    try:
+        mod = importlib.import_module(f"readanydoc.tasks.{name}")
+    except Exception as e:  # ImportError, or the module failing at import while it is being written
+        raise errors.not_implemented(
+            f"/{name} is not available in this build: readanydoc.tasks.{name} could not be imported "
+            f"({e.__class__.__name__}: {e})") from e
+    fn = getattr(mod, "run", None)
+    if not callable(fn):
+        raise errors.not_implemented(f"/{name} is not available in this build: readanydoc.tasks.{name}.run is missing")
+    return fn
+
+
+_STATUS_NAMES = {400: "INVALID_CONFIG", 401: "AUTH_ERROR", 404: "NOT_FOUND", 413: "DOCUMENT_TOO_LARGE",
+                 415: "DOCUMENT_UNSUPPORTED", 422: "INVALID_SCHEMA", 429: "RATE_LIMIT",
+                 442: "DOCUMENT_PASSWORD_PROTECTED", 501: "NOT_APPLICABLE", 502: "LLM_PROVIDER_ERROR",
+                 503: "SERVICE_UNAVAILABLE", 504: "TIMEOUT"}
+
+
+def _keyword_args(fn: TaskFn, name: str, target: Any, config: dict[str, Any]) -> tuple[Any, dict[str, Any]]:
+    """Supply the keyword-only arguments of the task signature, if ``fn`` declares them."""
+    try:
+        params = inspect.signature(fn).parameters
+    except (TypeError, ValueError):
+        return target, {}
+    kwargs: dict[str, Any] = {}
+    if "llm" in params:
+        from ..tasks.llm import DEFAULT_LLM, get_llm  # only reached when readanydoc.tasks exists
+        kwargs["llm"] = get_llm(os.environ.get(TASK_LLM_ENV) or DEFAULT_LLM)
+    if name == "edit" and "source_path" in params:
+        kwargs["source_path"] = target
+        if "output_path" in params:
+            out_dir = Path((config.get("_readanydoc") or {}).get("output_dir") or ".")
+            kwargs["output_path"] = str(out_dir / f"edited{Path(str(target)).suffix or '.pdf'}")
+        target = None
+    return target, kwargs
+
+
+def call_task(name: str, target: Any, config: dict[str, Any]) -> dict[str, Any]:
+    fn = load_task(name)
+    try:
+        target, kwargs = _keyword_args(fn, name, target, config)
+        out = fn(target, config, **kwargs)
+    except errors.ApiError:
+        raise
+    except NotImplementedError as e:
+        raise errors.not_implemented(str(e) or f"/{name} is not implemented yet") from e
+    except Exception as e:
+        status = getattr(e, "status_code", None)
+        if isinstance(status, int) and hasattr(e, "detail"):  # readanydoc.tasks.TaskError
+            raise errors.ApiError(status, _STATUS_NAMES.get(status, "PROCESSING_FAILED" if status < 500
+                                                            else "INTERNAL_ERROR"), str(e.detail)) from e
+        if isinstance(e, ValueError) and not e.__class__.__module__.startswith("jsonschema"):
+            raise errors.bad_request(str(e)) from e
+        raise errors.from_exception(e) from e
+    if hasattr(out, "model_dump"):
+        out = out.model_dump(mode="json", by_alias=True)
+    if not isinstance(out, dict):
+        raise errors.internal(f"readanydoc.tasks.{name}.run returned {type(out).__name__}, expected a dict")
+    return out

readanydoc/api/errors.py

@@ -0,0 +1,86 @@
+"""Errors in Reducto's shape.
+
+Reducto's error-codes page shows ``{"error": {"message", "type", "code"}}``; FastAPI-style clients read
+``detail``. We send both, plus ``name`` (the ``ErrorCode`` enum of the OpenAPI spec) inside ``error``.
+Failed jobs carry an ``ErrorDetail`` object: ``{code, name, message, job_id}``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, name: str, message: str, type: Optional[str] = None,
+                 job_id: Optional[str] = None, headers: Optional[dict[str, str]] = None):
+        super().__init__(message)
+        self.status = status
+        self.name = name  # ErrorCode enum value
+        self.message = message
+        self.type = type or name.lower()
+        self.job_id = job_id
+        self.headers = headers
+
+    def body(self) -> dict[str, Any]:
+        err: dict[str, Any] = {"message": self.message, "type": self.type, "code": self.status, "name": self.name}
+        if self.job_id:
+            err["job_id"] = self.job_id
+        return {"error": err, "detail": self.message}
+
+    def detail(self, job_id: Optional[str] = None) -> dict[str, Any]:
+        """``ErrorDetail`` for GET /job."""
+        return {"code": self.status, "name": self.name, "message": self.message, "job_id": job_id or self.job_id}
+
+
+def bad_request(message: str, name: str = "INVALID_CONFIG", type: str = "bad_request") -> ApiError:
+    return ApiError(400, name, message, type)
+
+
+def download_failed(extra: str = "") -> ApiError:
+    msg = "Failed to download file from url. Please check the document url and try again"
+    return ApiError(400, "PROCESSING_FAILED", msg + (f" ({extra})" if extra else ""), "file_download_failure")
+
+
+def not_found(message: str, type: str = "not_found") -> ApiError:
+    return ApiError(404, "NOT_FOUND", message, type)
+
+
+def unauthorized() -> ApiError:
+    return ApiError(401, "AUTH_ERROR", "Invalid or missing API key. Send 'Authorization: Bearer <key>'.",
+                    "authentication_error", headers={"WWW-Authenticate": "Bearer"})
+
+
+def not_implemented(message: str) -> ApiError:
+    return ApiError(501, "NOT_APPLICABLE", message, "not_implemented")
+
+
+def internal(message: str) -> ApiError:
+    return ApiError(500, "INTERNAL_ERROR", message, "internal_error")
+
+
+def from_exception(exc: BaseException) -> ApiError:
+    """Map pipeline / task exceptions onto Reducto's status codes."""
+    if isinstance(exc, ApiError):
+        return exc
+    text = str(exc) or exc.__class__.__name__
+    cls = exc.__class__.__name__
+    low = text.lower()
+    if cls == "IntakeError":
+        if "password" in low:
+            return ApiError(442, "DOCUMENT_PASSWORD_PROTECTED",
+                            "Document is password protected or the password is wrong. "
+                            "Pass settings.document_password.", "password_protected")
+        if "not supported" in low:
+            return ApiError(415, "DOCUMENT_UNSUPPORTED", text, "file_conversion_error")
+        if "not found" in low:
+            return bad_request(text, "NOT_FOUND", "invalid_input")
+        return ApiError(415, "DOCUMENT_CORRUPT", text, "pdf_handling_error")
+    if isinstance(exc, NotImplementedError):
+        return not_implemented(text if str(exc) else "This operation is not implemented in this build.")
+    if cls in ("ReaderError", "LayoutError"):
+        return ApiError(502, "LLM_PROVIDER_ERROR", text, "llm_provider_error")
+    if cls in ("SchemaError", "ValidationError") and exc.__class__.__module__.startswith("jsonschema"):
+        return ApiError(422, "INVALID_SCHEMA", f"Invalid JSON schema: {getattr(exc, 'message', text)}", "invalid_schema")
+    if isinstance(exc, TimeoutError):
+        return ApiError(504, "TIMEOUT", text, "timeout")
+    return internal(f"{cls}: {text}")