Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(parser): add LlamaParse v2 bridge (#4824)
Hao Zhe84bbf79711f3
diff --git a/examples/llamaparse-understanding-bridge/.dockerignore b/examples/llamaparse-understanding-bridge/.dockerignorenew file mode 100644index 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-infodiff --git a/examples/llamaparse-understanding-bridge/.env.example b/examples/llamaparse-understanding-bridge/.env.examplenew file mode 100644index 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=300diff --git a/examples/llamaparse-understanding-bridge/.gitignore b/examples/llamaparse-understanding-bridge/.gitignorenew file mode 100644index 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/Dockerfilenew file mode 100644index 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.mdnew file mode 100644index 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__.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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 appdiff --git a/examples/llamaparse-understanding-bridge/pyproject.toml b/examples/llamaparse-understanding-bridge/pyproject.tomlnew file mode 100644index 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 = truediff --git a/examples/llamaparse-understanding-bridge/tests/test_bridge.py b/examples/llamaparse-understanding-bridge/tests/test_bridge.pynew file mode 100644index 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]