Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(parser): add LlamaParse v2 bridge (#4824)

Hao Zhe84bbf79711f3
diff --git a/examples/llamaparse-understanding-bridge/.dockerignore b/examples/llamaparse-understanding-bridge/.dockerignore
new file mode 100644
index 000000000..05ba96f17
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/.dockerignore
@@ -0,0 +1,10 @@
+.env
+.git
+.pytest_cache
+.ruff_cache
+.venv
+__pycache__
+build
+dist
+tests
+*.egg-info
diff --git a/examples/llamaparse-understanding-bridge/.env.example b/examples/llamaparse-understanding-bridge/.env.example
new file mode 100644
index 000000000..7d2990c09
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/.env.example
@@ -0,0 +1,24 @@
+# Required
+LLAMA_CLOUD_API_KEY=llx-replace-me
+PARSER_BRIDGE_API_KEY=replace-me
+
+# Select the LlamaCloud region that issued the API key: na or eu.
+LLAMAPARSE_REGION=na
+
+# Parsing defaults
+LLAMAPARSE_TIER=agentic
+LLAMAPARSE_VERSION=latest
+LLAMAPARSE_COST_OPTIMIZER=true
+
+# Bridge network settings
+BRIDGE_PUBLIC_URL=http://127.0.0.1:8080
+BRIDGE_BIND_HOST=127.0.0.1
+BRIDGE_PORT=8080
+
+# Advanced settings
+# LLAMAPARSE_PARSE_OPTIONS_JSON={"input_options":{"spreadsheet":{"detect_sub_tables_in_sheets":true}}}
+# LLAMAPARSE_BASE_URL=https://api.cloud.llamaindex.ai
+# LLAMAPARSE_ORGANIZATION_ID=
+# LLAMAPARSE_PROJECT_ID=
+# BRIDGE_HTTP_TIMEOUT_SECONDS=120
+# BRIDGE_ARTIFACT_TTL_SECONDS=300
diff --git a/examples/llamaparse-understanding-bridge/.gitignore b/examples/llamaparse-understanding-bridge/.gitignore
new file mode 100644
index 000000000..5b76d99c3
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/.gitignore
@@ -0,0 +1,10 @@
+.env
+.pytest_cache/
+.ruff_cache/
+.coverage
+.venv/
+uv.lock
+build/
+dist/
+__pycache__/
+*.egg-info/
diff --git a/examples/llamaparse-understanding-bridge/Dockerfile b/examples/llamaparse-understanding-bridge/Dockerfile
new file mode 100644
index 000000000..66fbcbfde
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/Dockerfile
@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY openviking_llamaparse_bridge ./openviking_llamaparse_bridge
+RUN pip install --no-cache-dir .
+RUN useradd --create-home bridge
+
+USER bridge
+
+EXPOSE 8080
+
+CMD ["python", "-m", "openviking_llamaparse_bridge"]
diff --git a/examples/llamaparse-understanding-bridge/README.md b/examples/llamaparse-understanding-bridge/README.md
new file mode 100644
index 000000000..fa4c8c327
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/README.md
@@ -0,0 +1,127 @@
+# LlamaParse v2 Understanding API bridge
+
+This example shows how to connect a hosted parser to OpenViking through the Understanding API.
+It maps OpenViking requests to LlamaParse v2 without changes to OpenViking core. Use the same
+pattern to adapt services such as Azure AI Document Intelligence or Amazon Textract.
+
+## API mapping
+
+| OpenViking Understanding API | LlamaParse v2 | Bridge action |
+|---|---|---|
+| `POST /api/v3/files` | `POST /api/v1/beta/files` | Upload the local file and return the LlamaParse file ID. |
+| `POST /api/v3/responses` | `POST /api/v2/parse` | Convert `file_id` or a public URL to a parse job. |
+| `GET /api/v3/responses/{id}` | `GET /api/v2/parse/{id}` | Map the LlamaParse job state to `in_progress`, `completed`, or `failed`. |
+| `result.zip_url` | Markdown and image URLs | Build the `content.md` and image ZIP that OpenViking expects. |
+
+```text
+OpenViking -> bridge -> LlamaParse v2
+OpenViking <- ZIP <- Markdown and images
+```
+
+The bridge reuses each LlamaParse file ID and job ID. Polling still works after a bridge restart.
+Completed ZIP files stay in a small in-memory cache for five minutes. The bridge builds the ZIP
+before it reports `completed`. Thus, image downloads and ZIP creation do not use OpenViking's fixed
+60-second artifact download window. A bridge restart removes cached ZIP files, but OpenViking can
+poll the job again and rebuild the ZIP.
+
+## Run
+
+Requirements:
+
+- Python 3.10 or later and [`uv`](https://docs.astral.sh/uv/), or Docker
+- A [LlamaCloud API key](https://developers.llamaindex.ai/llamaparse/general/api_key/)
+- An OpenViking server
+
+From the OpenViking repository root:
+
+```bash
+cp examples/llamaparse-understanding-bridge/.env.example \
+ examples/llamaparse-understanding-bridge/.env
+```
+
+Set these values in `.env`:
+
+```text
+LLAMA_CLOUD_API_KEY=llx-...
+PARSER_BRIDGE_API_KEY=<a-random-secret-with-at-least-32-characters>
+```
+
+Run directly:
+
+```bash
+uv run --env-file examples/llamaparse-understanding-bridge/.env \
+ --project examples/llamaparse-understanding-bridge \
+ openviking-llamaparse-bridge
+```
+
+Or run with Docker:
+
+```bash
+docker build -t openviking-llamaparse-bridge \
+ examples/llamaparse-understanding-bridge
+docker run --rm --env-file examples/llamaparse-understanding-bridge/.env \
+ -p 127.0.0.1:8080:8080 \
+ -e BRIDGE_BIND_HOST=0.0.0.0 \
+ openviking-llamaparse-bridge
+```
+
+## Configure OpenViking
+
+Run `openviking-server init` if `~/.openviking/ov.conf` does not exist. Add:
+
+```json
+{
+ "parser_api": {
+ "enable": true,
+ "host": "http://127.0.0.1:8080",
+ "api_key": "${PARSER_BRIDGE_API_KEY}",
+ "extensions": ["pdf", "docx", "pptx", "xlsx"],
+ "http_timeout_seconds": 130
+ }
+}
+```
+
+Set `PARSER_BRIDGE_API_KEY` in the environment that starts OpenViking. Restart OpenViking after a
+configuration change. `parser_api.extensions` selects which file types use this bridge. Other file
+types continue to use the current OpenViking parsers. Keep `parser_api.enable_resumable_upload`
+disabled. Set `parser_api.http_timeout_seconds` above `BRIDGE_HTTP_TIMEOUT_SECONDS`, which defaults
+to 120 seconds.
+
+## Inputs and results
+
+The example supports local file uploads and public document, image, and audio URLs. It does not
+support video or credential-gated URLs. OpenViking identifies Lark and Feishu credentials with a
+`lark_file` field, so the bridge rejects that request with a clear `unsupported_input` error. Other
+private URLs fail through the normal LlamaParse error response.
+
+LlamaParse can complete a job when some pages fail. The bridge keeps the usable Markdown and adds a
+visible failed-page note. It fails the job only when there is no usable Markdown.
+
+## Settings
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `LLAMA_CLOUD_API_KEY` | Required | Authenticate with LlamaCloud. |
+| `PARSER_BRIDGE_API_KEY` | Required | Authenticate OpenViking requests. Use at least 32 characters. |
+| `LLAMAPARSE_REGION` | `na` | Select the `na` or `eu` LlamaCloud endpoint. |
+| `LLAMAPARSE_TIER` | `agentic` | Select `cost_effective`, `agentic`, or `agentic_plus`. |
+| `LLAMAPARSE_COST_OPTIMIZER` | `true` | Route simple pages to the lower-cost tier. |
+| `BRIDGE_PUBLIC_URL` | `http://127.0.0.1:8080` | Set the URL that OpenViking uses to download ZIP files. |
+
+Use `LLAMAPARSE_PARSE_OPTIONS_JSON` for advanced LlamaParse v2 options. The bridge owns `file_id`,
+`source_url`, `tier`, and `version`. It also requests embedded and layout images because OpenViking
+needs the image files referenced by the returned Markdown.
+
+## Test
+
+The mocked contract tests do not use LlamaCloud credits:
+
+```bash
+uv run --project examples/llamaparse-understanding-bridge --extra test \
+ pytest -c examples/llamaparse-understanding-bridge/pyproject.toml \
+ examples/llamaparse-understanding-bridge/tests/test_bridge.py -q
+```
+
+For a live check, start the bridge and OpenViking, add a small PDF, and confirm that OpenViking
+stores `content.md` and any extracted images. `ov add-resource --wait` can stop waiting after 60
+seconds while the server continues the task. Check `ov task list` before you retry.
diff --git a/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__init__.py b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__init__.py
new file mode 100644
index 000000000..d34d39e1f
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__init__.py
@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""LlamaParse v2 adapter for the OpenViking Understanding API."""
+
+from .bridge import create_app
+
+__all__ = ["create_app"]
diff --git a/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__main__.py b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__main__.py
new file mode 100644
index 000000000..2f252cec5
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/__main__.py
@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Command-line entry point for the LlamaParse bridge."""
+
+import uvicorn
+
+from .bridge import create_app, load_settings
+
+
+def main() -> None:
+ settings = load_settings()
+ uvicorn.run(
+ create_app(settings),
+ host=settings.bind_host,
+ port=settings.bind_port,
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/bridge.py b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/bridge.py
new file mode 100644
index 000000000..86429e734
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/openviking_llamaparse_bridge/bridge.py
@@ -0,0 +1,599 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Reference adapter from OpenViking's Understanding API to LlamaParse v2.
+
+Files API -> LlamaParse upload; Responses API -> LlamaParse parse and status;
+LlamaParse Markdown and images -> the ZIP returned through ``result.zip_url``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import io
+import json
+import os
+import time
+import zipfile
+from contextlib import asynccontextmanager
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any, AsyncIterator, BinaryIO, Mapping, Optional
+from urllib.parse import quote, urlencode, urlsplit
+
+import httpx
+from fastapi import Depends, FastAPI, Form, Header, Query, Request, UploadFile
+from fastapi.responses import JSONResponse, Response
+
+REGION_URLS = {
+ "na": "https://api.cloud.llamaindex.ai",
+ "eu": "https://api.cloud.eu.llamaindex.ai",
+}
+SUPPORTED_TIERS = {"cost_effective", "agentic", "agentic_plus"}
+MAX_CACHED_ARTIFACTS = 32
+MAX_CONCURRENT_ARTIFACT_BUILDS = 2
+MAX_CONCURRENT_IMAGE_DOWNLOADS = 8
+
+
+class BridgeError(RuntimeError):
+ def __init__(self, status_code: int, code: str, message: str):
+ self.status_code = status_code
+ self.code = code
+ super().__init__(message)
+
+
+class LlamaParseError(RuntimeError):
+ def __init__(self, status_code: int, message: str):
+ self.status_code = status_code
+ super().__init__(message)
+
+
+def _boolean(env: Mapping[str, str], name: str, default: bool) -> bool:
+ value = env.get(name, "").strip().lower()
+ if not value:
+ return default
+ if value in {"1", "true", "yes", "on"}:
+ return True
+ if value in {"0", "false", "no", "off"}:
+ return False
+ raise ValueError(f"{name} must be true or false")
+
+
+def _positive_int(env: Mapping[str, str], name: str, default: int) -> int:
+ try:
+ value = int(env.get(name, "").strip() or default)
+ except ValueError as exc:
+ raise ValueError(f"{name} must be an integer") from exc
+ if value <= 0:
+ raise ValueError(f"{name} must be greater than zero")
+ return value
+
+
+def _parse_options(raw: str) -> dict[str, Any]:
+ try:
+ options = json.loads(raw) if raw.strip() else {}
+ except json.JSONDecodeError as exc:
+ raise ValueError("LLAMAPARSE_PARSE_OPTIONS_JSON must be valid JSON") from exc
+ if not isinstance(options, dict):
+ raise ValueError("LLAMAPARSE_PARSE_OPTIONS_JSON must contain a JSON object")
+ conflicts = sorted({"file_id", "source_url", "tier", "version"} & options.keys())
+ if conflicts:
+ raise ValueError(
+ "LLAMAPARSE_PARSE_OPTIONS_JSON cannot set bridge-managed fields: "
+ + ", ".join(conflicts)
+ )
+ for name in ("output_options", "processing_options"):
+ if name in options and not isinstance(options[name], dict):
+ raise ValueError(f"LLAMAPARSE_PARSE_OPTIONS_JSON.{name} must be an object")
+ output = options.get("output_options")
+ if isinstance(output, dict) and not isinstance(output.get("images_to_save", []), list):
+ raise ValueError(
+ "LLAMAPARSE_PARSE_OPTIONS_JSON.output_options.images_to_save must be an array"
+ )
+ return options
+
+
+@dataclass(frozen=True)
+class Settings:
+ llama_api_key: str
+ bridge_api_key: str
+ llama_base_url: str = REGION_URLS["na"]
+ tier: str = "agentic"
+ version: str = "latest"
+ cost_optimizer: bool = True
+ public_url: str = "http://127.0.0.1:8080"
+ bind_host: str = "127.0.0.1"
+ bind_port: int = 8080
+ timeout_seconds: int = 120
+ artifact_ttl_seconds: int = 300
+ organization_id: Optional[str] = None
+ project_id: Optional[str] = None
+ parse_options: dict[str, Any] = field(default_factory=dict)
+
+ def __post_init__(self) -> None:
+ if not self.llama_api_key.strip():
+ raise ValueError("LLAMA_CLOUD_API_KEY is required")
+ if len(self.bridge_api_key.strip()) < 32:
+ raise ValueError("PARSER_BRIDGE_API_KEY must contain at least 32 characters")
+ if self.tier not in SUPPORTED_TIERS:
+ raise ValueError(f"unsupported LlamaParse tier: {self.tier}")
+ if self.cost_optimizer and self.tier == "cost_effective":
+ raise ValueError("LLAMAPARSE_COST_OPTIMIZER requires an agentic tier")
+ for value, name in (
+ (self.llama_base_url, "LLAMAPARSE_BASE_URL"),
+ (self.public_url, "BRIDGE_PUBLIC_URL"),
+ ):
+ parsed = urlsplit(value)
+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+ raise ValueError(f"{name} must be an HTTP(S) URL")
+ if parsed.query or parsed.fragment:
+ raise ValueError(f"{name} must not contain a query or fragment")
+ if not 1 <= self.bind_port <= 65535:
+ raise ValueError("BRIDGE_PORT must be between 1 and 65535")
+ if self.timeout_seconds <= 0 or self.artifact_ttl_seconds <= 0:
+ raise ValueError("bridge timeouts must be greater than zero")
+ _parse_options(json.dumps(self.parse_options))
+
+
+def load_settings(env: Optional[Mapping[str, str]] = None) -> Settings:
+ values = env if env is not None else os.environ
+ region = values.get("LLAMAPARSE_REGION", "na").strip().lower() or "na"
+ base_url = values.get("LLAMAPARSE_BASE_URL", "").strip()
+ if not base_url:
+ try:
+ base_url = REGION_URLS[region]
+ except KeyError as exc:
+ raise ValueError("LLAMAPARSE_REGION must be na or eu") from exc
+ return Settings(
+ llama_api_key=values.get("LLAMA_CLOUD_API_KEY", "").strip(),
+ bridge_api_key=values.get("PARSER_BRIDGE_API_KEY", "").strip(),
+ llama_base_url=base_url.rstrip("/"),
+ tier=values.get("LLAMAPARSE_TIER", "agentic").strip().lower(),
+ version=values.get("LLAMAPARSE_VERSION", "latest").strip() or "latest",
+ cost_optimizer=_boolean(values, "LLAMAPARSE_COST_OPTIMIZER", True),
+ public_url=values.get("BRIDGE_PUBLIC_URL", "http://127.0.0.1:8080").strip().rstrip("/"),
+ bind_host=values.get("BRIDGE_BIND_HOST", "127.0.0.1").strip() or "127.0.0.1",
+ bind_port=_positive_int(values, "BRIDGE_PORT", 8080),
+ timeout_seconds=_positive_int(values, "BRIDGE_HTTP_TIMEOUT_SECONDS", 120),
+ artifact_ttl_seconds=_positive_int(values, "BRIDGE_ARTIFACT_TTL_SECONDS", 300),
+ organization_id=values.get("LLAMAPARSE_ORGANIZATION_ID", "").strip() or None,
+ project_id=values.get("LLAMAPARSE_PROJECT_ID", "").strip() or None,
+ parse_options=_parse_options(values.get("LLAMAPARSE_PARSE_OPTIONS_JSON", "")),
+ )
+
+
+class LlamaParseClient:
+ def __init__(
+ self,
+ settings: Settings,
+ *,
+ api_client: Optional[httpx.AsyncClient] = None,
+ download_client: Optional[httpx.AsyncClient] = None,
+ ):
+ self.settings = settings
+ timeout = httpx.Timeout(settings.timeout_seconds)
+ self._owns_api = api_client is None
+ self._owns_downloads = download_client is None
+ self.api = api_client or httpx.AsyncClient(
+ base_url=settings.llama_base_url,
+ headers={"Authorization": f"Bearer {settings.llama_api_key}"},
+ timeout=timeout,
+ )
+ # This client has no LlamaCloud authorization header.
+ self.downloads = download_client or httpx.AsyncClient(
+ timeout=timeout, follow_redirects=True
+ )
+
+ async def aclose(self) -> None:
+ if self._owns_api:
+ await self.api.aclose()
+ if self._owns_downloads:
+ await self.downloads.aclose()
+
+ def _scope(self) -> dict[str, str]:
+ return {
+ key: value
+ for key, value in {
+ "organization_id": self.settings.organization_id,
+ "project_id": self.settings.project_id,
+ }.items()
+ if value
+ }
+
+ @staticmethod
+ async def _request(
+ client: httpx.AsyncClient, method: str, url: str, **kwargs: Any
+ ) -> httpx.Response:
+ try:
+ response = await client.request(method, url, **kwargs)
+ except httpx.TimeoutException as exc:
+ raise LlamaParseError(504, "LlamaParse request timed out") from exc
+ except httpx.RequestError as exc:
+ raise LlamaParseError(502, "LlamaParse request failed") from exc
+ if response.is_error:
+ try:
+ payload = response.json()
+ detail = payload.get("detail") or payload.get("error") or payload.get("message")
+ if isinstance(detail, dict):
+ detail = detail.get("message")
+ except (ValueError, AttributeError):
+ detail = response.text.strip()
+ raise LlamaParseError(
+ response.status_code, str(detail or f"HTTP {response.status_code}")
+ )
+ return response
+
+ @classmethod
+ async def _json_request(
+ cls, client: httpx.AsyncClient, method: str, url: str, **kwargs: Any
+ ) -> dict[str, Any]:
+ response = await cls._request(client, method, url, **kwargs)
+ try:
+ payload = response.json()
+ except ValueError as exc:
+ raise LlamaParseError(502, "LlamaParse returned invalid JSON") from exc
+ if not isinstance(payload, dict):
+ raise LlamaParseError(502, "LlamaParse returned an invalid response object")
+ return payload
+
+ async def upload_file(
+ self, filename: str, file: BinaryIO, content_type: Optional[str]
+ ) -> dict[str, Any]:
+ return await self._json_request(
+ self.api,
+ "POST",
+ "/api/v1/beta/files",
+ params=self._scope(),
+ data={"purpose": "parse"},
+ files={"file": (filename, file, content_type or "application/octet-stream")},
+ )
+
+ async def create_job(
+ self, *, file_id: Optional[str] = None, source_url: Optional[str] = None
+ ) -> dict[str, Any]:
+ if bool(file_id) == bool(source_url):
+ raise ValueError("exactly one of file_id or source_url is required")
+ config = deepcopy(self.settings.parse_options)
+ config.update(tier=self.settings.tier, version=self.settings.version)
+ config.setdefault("client_name", "openviking-understanding-bridge")
+ images = config.setdefault("output_options", {}).setdefault("images_to_save", [])
+ for category in ("embedded", "layout"):
+ if category not in images:
+ images.append(category)
+ processing = config.setdefault("processing_options", {})
+ if self.settings.cost_optimizer:
+ processing["cost_optimizer"] = {"enable": True}
+ else:
+ processing.pop("cost_optimizer", None)
+ if not processing:
+ config.pop("processing_options")
+ config["file_id" if file_id else "source_url"] = file_id or source_url
+ return await self._json_request(
+ self.api, "POST", "/api/v2/parse", params=self._scope(), json=config
+ )
+
+ async def get_job(self, job_id: str, *, include_result: bool = False) -> dict[str, Any]:
+ params = self._scope()
+ if include_result:
+ params["expand"] = "markdown_full,markdown,images_content_metadata"
+ return await self._json_request(
+ self.api, "GET", f"/api/v2/parse/{quote(job_id, safe='')}", params=params
+ )
+
+ async def download_asset(self, url: str) -> bytes:
+ return (await self._request(self.downloads, "GET", url)).content
+
+
+class ArtifactSigner:
+ def __init__(self, secret: str, ttl_seconds: int):
+ self.secret = secret.encode()
+ self.ttl_seconds = ttl_seconds
+
+ def _signature(self, job_id: str, expires: int) -> str:
+ return hmac.new(self.secret, f"{job_id}:{expires}".encode(), hashlib.sha256).hexdigest()
+
+ def create_url(self, public_url: str, job_id: str) -> str:
+ expires = int(time.time()) + self.ttl_seconds
+ query = urlencode({"expires": expires, "signature": self._signature(job_id, expires)})
+ return f"{public_url}/artifacts/{quote(job_id, safe='')}.zip?{query}"
+
+ def verify(self, job_id: str, expires: str, signature: str) -> bool:
+ try:
+ expiry = int(expires)
+ except ValueError:
+ return False
+ return int(time.time()) <= expiry and hmac.compare_digest(
+ self._signature(job_id, expiry), signature
+ )
+
+
+def _markdown(result: dict[str, Any]) -> str:
+ markdown = result.get("markdown")
+ pages = markdown.get("pages") if isinstance(markdown, dict) else []
+ if not isinstance(pages, list):
+ pages = []
+ failed = [
+ str(page.get("page_number", index))
+ for index, page in enumerate(pages, start=1)
+ if isinstance(page, dict) and page.get("success") is False
+ ]
+ full = result.get("markdown_full")
+ if isinstance(full, str) and full.strip():
+ text = full.strip()
+ else:
+ parts = [
+ page.get("markdown")
+ for page in pages
+ if isinstance(page, dict) and page.get("success") is not False
+ ]
+ text = "\n\n".join(part.strip() for part in parts if isinstance(part, str) and part.strip())
+ if not text:
+ raise LlamaParseError(502, "completed LlamaParse job has no usable Markdown")
+ if failed:
+ label = "Page" if len(failed) == 1 else "Pages"
+ text += f"\n\n> {label} {', '.join(failed)} failed to parse."
+ return text
+
+
+def _safe_image_name(value: Any) -> str:
+ if not isinstance(value, str) or not value.strip():
+ raise LlamaParseError(502, "LlamaParse image has no filename")
+ name = value.strip()
+ if any(ord(character) < 32 for character in name) or ":" in name:
+ raise LlamaParseError(502, "LlamaParse image has an unsafe filename")
+ path = PurePosixPath(name.replace("\\", "/"))
+ if path.is_absolute() or len(path.parts) != 1 or path.name in {"", ".", ".."}:
+ raise LlamaParseError(502, "LlamaParse image has an unsafe filename")
+ return path.name
+
+
+def _make_zip(markdown: str, images: list[tuple[str, bytes]]) -> bytes:
+ output = io.BytesIO()
+ with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+ archive.writestr("content.md", markdown.encode())
+ for name, content in images:
+ archive.writestr(name, content)
+ return output.getvalue()
+
+
+async def build_artifact(client: LlamaParseClient, job_id: str) -> bytes:
+ result = await client.get_job(job_id, include_result=True)
+ job = result.get("job")
+ if not isinstance(job, dict) or str(job.get("status", "")).upper() != "COMPLETED":
+ raise LlamaParseError(409, "LlamaParse job is not complete")
+ metadata = result.get("images_content_metadata")
+ images_value = metadata.get("images") if isinstance(metadata, dict) else None
+ raw_images = images_value if isinstance(images_value, list) else []
+ sources: list[tuple[str, str]] = []
+ names = {"content.md"}
+ for image in raw_images:
+ name = _safe_image_name(image.get("filename") if isinstance(image, dict) else None)
+ url = image.get("presigned_url") if isinstance(image, dict) else None
+ if name.casefold() in names:
+ raise LlamaParseError(502, f"LlamaParse returned duplicate image: {name}")
+ if not isinstance(url, str) or not url.startswith("https://"):
+ raise LlamaParseError(502, f"LlamaParse image has no secure download URL: {name}")
+ sources.append((name, url))
+ names.add(name.casefold())
+ semaphore = asyncio.Semaphore(MAX_CONCURRENT_IMAGE_DOWNLOADS)
+
+ async def download(url: str) -> bytes:
+ async with semaphore:
+ return await client.download_asset(url)
+
+ tasks = [asyncio.create_task(download(url)) for _, url in sources]
+ try:
+ contents = await asyncio.gather(*tasks)
+ except BaseException:
+ for task in tasks:
+ task.cancel()
+ await asyncio.gather(*tasks, return_exceptions=True)
+ raise
+ images = [(source[0], content) for source, content in zip(sources, contents, strict=True)]
+ return await asyncio.to_thread(_make_zip, _markdown(result), images)
+
+
+def _source(payload: dict[str, Any]) -> tuple[str, str]:
+ inputs = payload.get("input")
+ content = (
+ inputs[0].get("content")
+ if isinstance(inputs, list) and len(inputs) == 1 and isinstance(inputs[0], dict)
+ else None
+ )
+ if not isinstance(content, list) or len(content) != 1 or not isinstance(content[0], dict):
+ raise BridgeError(400, "invalid_request", "input must contain one content item")
+ item = content[0]
+ if "lark_file" in item:
+ raise BridgeError(400, "unsupported_input", "credential-gated URLs are not supported")
+ if item.get("type") == "file":
+ file = item.get("file")
+ file_id = file.get("file_id") if isinstance(file, dict) else None
+ if isinstance(file_id, str) and file_id.strip():
+ return "file_id", file_id.strip()
+ raise BridgeError(400, "invalid_request", "file.file_id is required")
+ content_type = item.get("type")
+ url_fields = {
+ "input_file": "file_url",
+ "input_image": "image_url",
+ "input_audio": "audio_url",
+ }
+ url_field = url_fields.get(content_type) if isinstance(content_type, str) else None
+ if url_field:
+ url = item.get(url_field)
+ if isinstance(url, str) and url.startswith(("http://", "https://")):
+ return "source_url", url.strip()
+ raise BridgeError(400, "invalid_request", f"{url_field} must be an HTTP URL")
+ raise BridgeError(400, "unsupported_input", f"unsupported input type: {content_type}")
+
+
+class Bridge:
+ def __init__(self, settings: Settings, client: LlamaParseClient, owns_client: bool):
+ self.settings = settings
+ self.client = client
+ self.owns_client = owns_client
+ self.signer = ArtifactSigner(settings.bridge_api_key, settings.artifact_ttl_seconds)
+ self.artifacts: dict[str, tuple[float, bytes]] = {}
+ self.builds: dict[str, asyncio.Task[None]] = {}
+ self.build_slots = asyncio.Semaphore(MAX_CONCURRENT_ARTIFACT_BUILDS)
+
+ def _store_artifact(self, job_id: str, content: bytes) -> None:
+ if len(self.artifacts) >= MAX_CACHED_ARTIFACTS:
+ self.artifacts.pop(min(self.artifacts, key=lambda key: self.artifacts[key][0]))
+ self.artifacts[job_id] = (time.monotonic() + self.settings.artifact_ttl_seconds, content)
+
+ async def _build_artifact(self, job_id: str) -> None:
+ async with self.build_slots:
+ content = await build_artifact(self.client, job_id)
+ self._store_artifact(job_id, content)
+
+ def _build_done(self, job_id: str, task: asyncio.Task[None]) -> None:
+ if not task.cancelled() and task.exception() is None and self.builds.get(job_id) is task:
+ self.builds.pop(job_id, None)
+
+ def _prune(self) -> None:
+ now = time.monotonic()
+ for job_id in [key for key, (expires, _) in self.artifacts.items() if expires <= now]:
+ self.artifacts.pop(job_id)
+
+ async def _artifact_ready(self, job_id: str) -> bool:
+ self._prune()
+ if job_id in self.artifacts:
+ _, content = self.artifacts[job_id]
+ self.artifacts[job_id] = (
+ time.monotonic() + self.settings.artifact_ttl_seconds,
+ content,
+ )
+ return True
+ task = self.builds.get(job_id)
+ if task is None:
+ task = asyncio.create_task(self._build_artifact(job_id))
+ task.add_done_callback(lambda done: self._build_done(job_id, done))
+ self.builds[job_id] = task
+ return False
+ if not task.done():
+ return False
+ self.builds.pop(job_id, None)
+ await task
+ return job_id in self.artifacts
+
+ @asynccontextmanager
+ async def lifespan(self, _: FastAPI) -> AsyncIterator[None]:
+ try:
+ yield
+ finally:
+ for task in self.builds.values():
+ task.cancel()
+ await asyncio.gather(*self.builds.values(), return_exceptions=True)
+ if self.owns_client:
+ await self.client.aclose()
+
+ async def require_auth(self, authorization: Optional[str] = Header(default=None)) -> None:
+ expected = f"Bearer {self.settings.bridge_api_key}".encode()
+ if not hmac.compare_digest((authorization or "").encode(), expected):
+ raise BridgeError(401, "unauthorized", "invalid bridge API key")
+
+ async def create_file(
+ self, file: UploadFile, purpose: str = Form(default="user_data")
+ ) -> dict[str, Any]:
+ del purpose
+ filename = PurePosixPath((file.filename or "upload").replace("\\", "/")).name
+ if filename in {"", ".", ".."}:
+ filename = "upload"
+ result = await self.client.upload_file(filename, file.file, file.content_type)
+ if not isinstance(result.get("id"), str) or not result["id"]:
+ raise LlamaParseError(502, "LlamaParse file response has no id")
+ return result
+
+ async def create_response(self, payload: dict[str, Any]) -> dict[str, Any]:
+ source_name, value = _source(payload)
+ result = await self.client.create_job(
+ file_id=value if source_name == "file_id" else None,
+ source_url=value if source_name == "source_url" else None,
+ )
+ response_id = result.get("id")
+ if not isinstance(response_id, str) or not response_id:
+ raise LlamaParseError(502, "LlamaParse create response has no id")
+ return {"id": response_id, "object": "response", "status": "in_progress"}
+
+ async def get_response(self, response_id: str) -> dict[str, Any]:
+ result = await self.client.get_job(response_id)
+ job = result.get("job")
+ if not isinstance(job, dict):
+ raise LlamaParseError(502, "LlamaParse response has no job object")
+ status = str(job.get("status", "")).upper()
+ response: dict[str, Any] = {"id": response_id, "object": "response"}
+ if status == "COMPLETED":
+ if await self._artifact_ready(response_id):
+ response.update(
+ status="completed",
+ result={
+ "zip_url": self.signer.create_url(self.settings.public_url, response_id)
+ },
+ )
+ else:
+ response["status"] = "in_progress"
+ elif status in {"FAILED", "CANCELLED"}:
+ message = str(job.get("error_message") or f"LlamaParse job ended as {status}")
+ response.update(
+ status="failed",
+ output=[{"content": [{"type": "output_text", "text": message}]}],
+ )
+ elif status in {"PENDING", "RUNNING"}:
+ response["status"] = "in_progress"
+ else:
+ raise LlamaParseError(502, f"LlamaParse returned unknown job status: {status}")
+ return response
+
+ async def get_artifact(
+ self, job_id: str, expires: str = Query(...), signature: str = Query(...)
+ ) -> Response:
+ if not self.signer.verify(job_id, expires, signature):
+ raise BridgeError(
+ 403, "invalid_artifact_signature", "artifact URL is invalid or expired"
+ )
+ self._prune()
+ if job_id not in self.artifacts:
+ raise BridgeError(404, "artifact_not_found", "artifact is not ready or has expired")
+ return Response(content=self.artifacts[job_id][1], media_type="application/zip")
+
+
+async def _bridge_error(_: Request, error: Exception) -> JSONResponse:
+ assert isinstance(error, BridgeError)
+ return JSONResponse(
+ status_code=error.status_code,
+ content={"error": {"code": error.code, "message": str(error)}},
+ )
+
+
+async def _llama_error(_: Request, error: Exception) -> JSONResponse:
+ assert isinstance(error, LlamaParseError)
+ return JSONResponse(
+ status_code=error.status_code,
+ content={"error": {"code": f"llamaparse_http_{error.status_code}", "message": str(error)}},
+ )
+
+
+def create_app(
+ settings: Optional[Settings] = None, client: Optional[LlamaParseClient] = None
+) -> FastAPI:
+ resolved = settings or load_settings()
+ bridge = Bridge(resolved, client or LlamaParseClient(resolved), client is None)
+ app = FastAPI(title="OpenViking LlamaParse bridge", lifespan=bridge.lifespan)
+ app.add_exception_handler(BridgeError, _bridge_error)
+ app.add_exception_handler(LlamaParseError, _llama_error)
+ auth = [Depends(bridge.require_auth)]
+ app.add_api_route("/health", lambda: {"status": "ok"}, methods=["GET"])
+ app.add_api_route("/api/v3/files", bridge.create_file, methods=["POST"], dependencies=auth)
+ app.add_api_route(
+ "/api/v3/responses", bridge.create_response, methods=["POST"], dependencies=auth
+ )
+ app.add_api_route(
+ "/api/v3/responses/{response_id}",
+ bridge.get_response,
+ methods=["GET"],
+ dependencies=auth,
+ )
+ app.add_api_route("/artifacts/{job_id}.zip", bridge.get_artifact, methods=["GET"])
+ return app
diff --git a/examples/llamaparse-understanding-bridge/pyproject.toml b/examples/llamaparse-understanding-bridge/pyproject.toml
new file mode 100644
index 000000000..9d85dc921
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/pyproject.toml
@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openviking-llamaparse-bridge"
+version = "0.1.0"
+description = "LlamaParse v2 adapter for the OpenViking Understanding API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+ "fastapi>=0.115,<1",
+ "httpx>=0.27,<1",
+ "python-multipart>=0.0.20",
+ "uvicorn>=0.30,<1",
+]
+
+[project.optional-dependencies]
+test = ["mypy>=1", "pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.1"]
+
+[project.scripts]
+openviking-llamaparse-bridge = "openviking_llamaparse_bridge.__main__:main"
+
+[tool.setuptools.packages.find]
+include = ["openviking_llamaparse_bridge*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["B", "C", "E", "F", "I", "W"]
+ignore = ["B008", "E501"]
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+warn_unused_ignores = true
diff --git a/examples/llamaparse-understanding-bridge/tests/test_bridge.py b/examples/llamaparse-understanding-bridge/tests/test_bridge.py
new file mode 100644
index 000000000..79ca7276c
--- /dev/null
+++ b/examples/llamaparse-understanding-bridge/tests/test_bridge.py
@@ -0,0 +1,385 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Contract tests for the LlamaParse Understanding API bridge."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import zipfile
+from dataclasses import replace
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+import pytest
+
+from openviking_llamaparse_bridge import bridge
+from openviking_llamaparse_bridge.bridge import (
+ Bridge,
+ LlamaParseClient,
+ LlamaParseError,
+ Settings,
+ build_artifact,
+ create_app,
+ load_settings,
+)
+
+
+def settings() -> Settings:
+ return Settings(
+ llama_api_key="llx-test",
+ bridge_api_key="bridge-secret-with-at-least-32-chars",
+ llama_base_url="https://llama.test",
+ public_url="http://bridge.test",
+ timeout_seconds=5,
+ organization_id="org-1",
+ project_id="project-1",
+ )
+
+
+class FakeLlamaParseClient:
+ def __init__(self) -> None:
+ self.uploads: list[tuple[str, bytes]] = []
+ self.jobs: list[dict[str, str | None]] = []
+ self.status: dict[str, Any] = {"job": {"status": "PENDING"}}
+ self.result: dict[str, Any] = {}
+ self.asset_downloads = 0
+
+ async def upload_file(self, filename: str, file: Any, _: str | None) -> dict[str, Any]:
+ self.uploads.append((filename, file.read()))
+ return {"id": "file-1"}
+
+ async def create_job(
+ self, *, file_id: str | None = None, source_url: str | None = None
+ ) -> dict[str, Any]:
+ self.jobs.append({"file_id": file_id, "source_url": source_url})
+ return {"id": "job-1"}
+
+ async def get_job(self, job_id: str, *, include_result: bool = False) -> dict[str, Any]:
+ assert job_id == "job-1"
+ return self.result if include_result else self.status
+
+ async def download_asset(self, _: str) -> bytes:
+ self.asset_downloads += 1
+ return b"image-bytes"
+
+
+def _auth(settings: Settings) -> dict[str, str]:
+ return {"Authorization": f"Bearer {settings.bridge_api_key}"}
+
+
+async def bridge_client(settings: Settings):
+ llama = FakeLlamaParseClient()
+ app = create_app(settings, llama) # type: ignore[arg-type]
+ async with httpx.AsyncClient(
+ transport=httpx.ASGITransport(app=app), base_url="http://bridge.test"
+ ) as client:
+ yield client, llama
+
+
+def test_settings_keep_simple_defaults_and_validate_required_values() -> None:
+ values = {
+ "LLAMA_CLOUD_API_KEY": "llx-test",
+ "PARSER_BRIDGE_API_KEY": "bridge-secret-with-at-least-32-chars",
+ }
+
+ settings = load_settings(values)
+
+ assert settings.llama_base_url == "https://api.cloud.llamaindex.ai"
+ assert settings.tier == "agentic"
+ assert settings.cost_optimizer is True
+ with pytest.raises(ValueError, match="LLAMA_CLOUD_API_KEY"):
+ load_settings({**values, "LLAMA_CLOUD_API_KEY": ""})
+ with pytest.raises(ValueError, match="requires an agentic tier"):
+ load_settings(
+ {
+ **values,
+ "LLAMAPARSE_TIER": "cost_effective",
+ "LLAMAPARSE_COST_OPTIMIZER": "true",
+ }
+ )
+ with pytest.raises(ValueError, match="output_options.*object"):
+ load_settings({**values, "LLAMAPARSE_PARSE_OPTIONS_JSON": '{"output_options":null}'})
+
+
+async def test_llamaparse_client_maps_upload_parse_poll_and_asset_requests(
+ settings: Settings,
+) -> None:
+ requests: list[httpx.Request] = []
+
+ async def api_handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ if request.url.path == "/api/v1/beta/files":
+ body = await request.aread()
+ assert b'filename="report.pdf"' in body
+ return httpx.Response(200, json={"id": "file-1"})
+ if request.method == "POST":
+ payload = json.loads((await request.aread()).decode())
+ assert payload["file_id"] == "file-1"
+ assert payload["tier"] == "agentic"
+ assert payload["output_options"]["images_to_save"] == ["embedded", "layout"]
+ return httpx.Response(200, json={"id": "job-1"})
+ assert request.url.params["expand"] == ("markdown_full,markdown,images_content_metadata")
+ return httpx.Response(200, json={"job": {"status": "COMPLETED"}})
+
+ async def asset_handler(request: httpx.Request) -> httpx.Response:
+ assert "authorization" not in request.headers
+ return httpx.Response(200, content=b"image")
+
+ api = httpx.AsyncClient(
+ base_url=settings.llama_base_url,
+ headers={"Authorization": f"Bearer {settings.llama_api_key}"},
+ transport=httpx.MockTransport(api_handler),
+ )
+ assets = httpx.AsyncClient(transport=httpx.MockTransport(asset_handler))
+ client = LlamaParseClient(settings, api_client=api, download_client=assets)
+ try:
+ assert (await client.upload_file("report.pdf", io.BytesIO(b"data"), "application/pdf"))[
+ "id"
+ ] == "file-1"
+ assert (await client.create_job(file_id="file-1"))["id"] == "job-1"
+ assert (await client.get_job("job-1", include_result=True))["job"]["status"] == (
+ "COMPLETED"
+ )
+ assert await client.download_asset("https://assets.test/image.png") == b"image"
+ finally:
+ await api.aclose()
+ await assets.aclose()
+
+ assert all(request.headers["authorization"] == "Bearer llx-test" for request in requests)
+
+
+async def test_disabled_cost_optimizer_overrides_advanced_options(settings: Settings) -> None:
+ payload: dict[str, Any] = {}
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ payload.update(json.loads((await request.aread()).decode()))
+ return httpx.Response(200, json={"id": "job-1"})
+
+ configured = replace(
+ settings,
+ cost_optimizer=False,
+ parse_options={
+ "processing_options": {
+ "cost_optimizer": {"enable": True},
+ "ignore": {"ignore_diagonal_text": True},
+ }
+ },
+ )
+ api = httpx.AsyncClient(
+ base_url=settings.llama_base_url, transport=httpx.MockTransport(handler)
+ )
+ client = LlamaParseClient(configured, api_client=api)
+ try:
+ await client.create_job(file_id="file-1")
+ finally:
+ await client.aclose()
+ await api.aclose()
+
+ assert "cost_optimizer" not in payload["processing_options"]
+ assert payload["processing_options"]["ignore"] == {"ignore_diagonal_text": True}
+
+
+def test_asset_client_keeps_proxy_and_certificate_environment(
+ settings: Settings, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls: list[dict[str, Any]] = []
+
+ class Client:
+ def __init__(self, **kwargs: Any) -> None:
+ calls.append(kwargs)
+
+ monkeypatch.setattr(bridge.httpx, "AsyncClient", Client)
+
+ LlamaParseClient(settings)
+
+ assert calls[1].get("trust_env", True) is True
+ assert calls[1]["follow_redirects"] is True
+
+
+ ("content", "expected"),
+ [
+ (
+ {"type": "file", "file": {"file_id": "file-1"}},
+ {"file_id": "file-1", "source_url": None},
+ ),
+ (
+ {"type": "input_file", "file_url": "https://x.test/a.pdf"},
+ {"file_id": None, "source_url": "https://x.test/a.pdf"},
+ ),
+ (
+ {"type": "input_image", "image_url": "https://x.test/a.png"},
+ {"file_id": None, "source_url": "https://x.test/a.png"},
+ ),
+ (
+ {"type": "input_audio", "audio_url": "https://x.test/a.wav"},
+ {"file_id": None, "source_url": "https://x.test/a.wav"},
+ ),
+ ],
+)
+async def test_understanding_sources_map_to_llamaparse(
+ bridge_client: Any, settings: Settings, content: dict[str, Any], expected: dict[str, Any]
+) -> None:
+ client, llama = bridge_client
+ response = await client.post(
+ "/api/v3/responses",
+ headers=_auth(settings),
+ json={"input": [{"content": [content]}]},
+ )
+
+ assert response.json() == {"id": "job-1", "object": "response", "status": "in_progress"}
+ assert llama.jobs == [expected]
+
+
+ ("source_name", "upload_name"), [("../report.pdf", "report.pdf"), ("..", "upload")]
+)
+async def test_bridge_uploads_local_file(
+ bridge_client: Any, settings: Settings, source_name: str, upload_name: str
+) -> None:
+ client, llama = bridge_client
+
+ response = await client.post(
+ "/api/v3/files",
+ headers=_auth(settings),
+ files={"file": (source_name, b"document", "application/pdf")},
+ )
+
+ assert response.json()["id"] == "file-1"
+ assert llama.uploads == [(upload_name, b"document")]
+
+
+ ("content", "message"),
+ [
+ (
+ {
+ "type": "input_file",
+ "file_url": "https://example.feishu.cn/docx/a",
+ "lark_file": {"user_access_token": "secret"},
+ },
+ "credential-gated URLs",
+ ),
+ ({"type": "input_video", "video_url": "https://x.test/a.mp4"}, "input_video"),
+ ],
+)
+async def test_bridge_rejects_unsupported_inputs(
+ bridge_client: Any, settings: Settings, content: dict[str, Any], message: str
+) -> None:
+ client, llama = bridge_client
+
+ response = await client.post(
+ "/api/v3/responses",
+ headers=_auth(settings),
+ json={"input": [{"content": [content]}]},
+ )
+
+ assert response.status_code == 400
+ assert response.json()["error"]["code"] == "unsupported_input"
+ assert message in response.json()["error"]["message"]
+ assert llama.jobs == []
+
+
[email protected]("include_markdown_full", [True, False])
+async def test_completed_result_is_prebuilt_cached_and_downloadable(
+ bridge_client: Any, settings: Settings, include_markdown_full: bool
+) -> None:
+ client, llama = bridge_client
+ llama.status = {"job": {"status": "COMPLETED"}}
+ llama.result = {
+ "job": {"status": "COMPLETED"},
+ "markdown": {
+ "pages": [
+ {"page_number": 1, "markdown": "page one", "success": True},
+ {"page_number": 2, "markdown": "", "success": False},
+ ]
+ },
+ "images_content_metadata": {
+ "images": [{"filename": "chart.png", "presigned_url": "https://assets.test/chart.png"}]
+ },
+ }
+ if include_markdown_full:
+ llama.result["markdown_full"] = "page one"
+
+ first = await client.get("/api/v3/responses/job-1", headers=_auth(settings))
+ assert first.json()["status"] == "in_progress"
+ for _ in range(20):
+ await asyncio.sleep(0)
+ status = await client.get("/api/v3/responses/job-1", headers=_auth(settings))
+ if status.json()["status"] == "completed":
+ break
+ else:
+ pytest.fail("artifact did not become ready")
+
+ parsed = urlsplit(status.json()["result"]["zip_url"])
+ artifact = await client.get(f"{parsed.path}?{parsed.query}")
+ repeated = await client.get(f"{parsed.path}?{parsed.query}")
+
+ assert artifact.status_code == 200
+ assert repeated.content == artifact.content
+ assert llama.asset_downloads == 1
+ with zipfile.ZipFile(io.BytesIO(artifact.content)) as archive:
+ assert archive.namelist() == ["content.md", "chart.png"]
+ assert archive.read("content.md").decode() == ("page one\n\n> Page 2 failed to parse.")
+ assert archive.read("chart.png") == b"image-bytes"
+
+
+async def test_completed_build_is_cached_without_another_poll(settings: Settings) -> None:
+ llama = FakeLlamaParseClient()
+ llama.result = {"job": {"status": "COMPLETED"}, "markdown_full": "content"}
+ bridge = Bridge(settings, llama, owns_client=False) # type: ignore[arg-type]
+
+ assert await bridge._artifact_ready("job-1") is False
+ await asyncio.gather(*bridge.builds.values())
+ await asyncio.sleep(0)
+
+ assert "job-1" in bridge.artifacts
+ assert bridge.builds == {}
+
+
+ ("status_payload", "expected"),
+ [
+ ({"job": {"status": "RUNNING"}}, "in_progress"),
+ ({"job": {"status": "FAILED", "error_message": "bad PDF"}}, "failed"),
+ ],
+)
+async def test_bridge_maps_job_statuses(
+ bridge_client: Any, settings: Settings, status_payload: dict[str, Any], expected: str
+) -> None:
+ client, llama = bridge_client
+ llama.status = status_payload
+
+ response = await client.get("/api/v3/responses/job-1", headers=_auth(settings))
+
+ assert response.json()["status"] == expected
+ if expected == "failed":
+ assert response.json()["output"][0]["content"][0]["text"] == "bad PDF"
+
+
+async def test_bridge_requires_auth_and_rejects_invalid_artifact_url(
+ bridge_client: Any, settings: Settings
+) -> None:
+ client, _ = bridge_client
+
+ unauthorized = await client.get("/api/v3/responses/job-1")
+ invalid_artifact = await client.get("/artifacts/job-1.zip?expires=1&signature=bad")
+
+ assert unauthorized.status_code == 401
+ assert invalid_artifact.status_code == 403
+
+
+async def test_build_artifact_fails_when_no_usable_markdown_exists() -> None:
+ llama = FakeLlamaParseClient()
+ llama.result = {
+ "job": {"status": "COMPLETED"},
+ "markdown": {"pages": [{"page_number": 1, "success": False}]},
+ }
+
+ with pytest.raises(LlamaParseError, match="no usable Markdown"):
+ await build_artifact(llama, "job-1") # type: ignore[arg-type]