docspectra 0.1.0__tar.gz

docspectra-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Workspace Local
+.env
+.claude
+.DS_Store
+

docspectra-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

docspectra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flow Jiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docspectra-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: docspectra
+Version: 0.1.0
+Summary: DocSpectra: schema-driven document parsing — any file in, spectral JSON out
+Project-URL: Homepage, https://github.com/flowjzh/docspectra
+Project-URL: Repository, https://github.com/flowjzh/docspectra.git
+Project-URL: Issues, https://github.com/flowjzh/docspectra/issues
+Author-email: Flow Jiang <flowjzh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: documents,extraction,json-schema,llm,parsing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: opentelemetry-api>=1.40.0
+Requires-Dist: xtremeparse>=0.1.0
+Provides-Extra: anydoc
+Requires-Dist: firecrawl-anydoc; extra == 'anydoc'
+Requires-Dist: pypdf; extra == 'anydoc'
+Provides-Extra: mineru
+Requires-Dist: httpx>=0.27; extra == 'mineru'
+Requires-Dist: xtremeflow>=0.4.4; extra == 'mineru'
+Provides-Extra: pdf-inspect
+Requires-Dist: pdf-inspector; extra == 'pdf-inspect'
+Requires-Dist: pypdf; extra == 'pdf-inspect'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim[openai]>=2.30.0; extra == 'pydantic-ai'
+Description-Content-Type: text/markdown
+
+# DocSpectra
+
+<img width="600" alt="DocSpectra" src="https://github.com/user-attachments/assets/1d858fb3-67c5-41f6-b0db-3fb6ab39fe4a" />
+
+> **Any file in. Spectral JSON out. Fast.**
+
+DocSpectra is a schema-driven document-parsing library: hand it a file in
+any supported format and a JSON Schema, get back schema-conforming JSON —
+extracted by extreme-concurrency LLM specialists that chunk, route, fan
+out and self-correct (powered by
+[xtremeparse](https://github.com/flowjzh/xtremeparse)).
+
+```
+file + JSON schema ──► docspectra.parse ──► JSON
+```
+
+## Layout
+
+- `docspectra/parser` — file → text (provider engines as optional extras:
+  `pdf-inspect`, `anydoc`, `mineru`; magic-byte type routing;
+  file-level decline chains — a provider whose gate fires on a specific
+  file declines and the next engine takes it)
+- `docspectra/agents` — the only PydanticAI boundary (AgentRunner adapter)
+- `docspectra/service` — `parse`: file + JSON schema → JSON
+
+DocSpectra is deliberately generic: JSON Schema in and out, no document
+vendors, no HTTP server, no domain tools. Applications assemble it with
+their own schema sources and renderers (e.g. bridging
+[DocXCast](https://github.com/flowjzh/docxcast) templates).
+
+## Status
+
+Parser layer implemented and tested.

docspectra-0.1.0/README.md

@@ -0,0 +1,33 @@
+# DocSpectra
+
+<img width="600" alt="DocSpectra" src="https://github.com/user-attachments/assets/1d858fb3-67c5-41f6-b0db-3fb6ab39fe4a" />
+
+> **Any file in. Spectral JSON out. Fast.**
+
+DocSpectra is a schema-driven document-parsing library: hand it a file in
+any supported format and a JSON Schema, get back schema-conforming JSON —
+extracted by extreme-concurrency LLM specialists that chunk, route, fan
+out and self-correct (powered by
+[xtremeparse](https://github.com/flowjzh/xtremeparse)).
+
+```
+file + JSON schema ──► docspectra.parse ──► JSON
+```
+
+## Layout
+
+- `docspectra/parser` — file → text (provider engines as optional extras:
+  `pdf-inspect`, `anydoc`, `mineru`; magic-byte type routing;
+  file-level decline chains — a provider whose gate fires on a specific
+  file declines and the next engine takes it)
+- `docspectra/agents` — the only PydanticAI boundary (AgentRunner adapter)
+- `docspectra/service` — `parse`: file + JSON schema → JSON
+
+DocSpectra is deliberately generic: JSON Schema in and out, no document
+vendors, no HTTP server, no domain tools. Applications assemble it with
+their own schema sources and renderers (e.g. bridging
+[DocXCast](https://github.com/flowjzh/docxcast) templates).
+
+## Status
+
+Parser layer implemented and tested.

docspectra-0.1.0/docspectra/__init__.py

@@ -0,0 +1,8 @@
+"""DocSpectra: schema-driven document parsing — any file in, spectral JSON out."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version('docspectra')
+except PackageNotFoundError:
+    __version__ = '0.1.0'

docspectra-0.1.0/docspectra/agents/__init__.py

@@ -0,0 +1,209 @@
+"""The only PydanticAI boundary: xtremeparse's AgentRunner adapted here.
+Swapping agent frameworks means rewriting this module and nothing else."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Sequence
+
+import httpx
+from pydantic_ai import Agent, NativeOutput
+from pydantic_ai.models import Model
+from pydantic_ai.output import StructuredDict
+
+from xtremeparse.contracts import AgentResult, Issue, JSONSchema
+from xtremeparse.scheduling import report_tokens
+
+
+# qwen commercial/numeric models think by default and dashscope rejects
+# tool_choice='required' (structured output) while thinking — same quirk
+# argus works around; generalized to any qwen3.x numeric series
+_THINKING_OFF = re.compile(
+    r'^qwen-(plus|flash|turbo)(-.*)?$|'
+    r'^qwen3(\.\d+)?-(omni-flash|vl-plus|flash|plus|\d+b(-a\d+b)?)(-.*)?$')
+
+
+class PydanticAIRunner:
+    """Adapts the AgentRunner protocol to PydanticAI.
+
+    The shared ``content`` prefix rides its own system message (Agent
+    ``instructions``) so provider prefix caching sees identical bytes
+    across every call of one extraction; the unit card, scope and
+    feedback trail in the user message — a history round already
+    carries the card and scope, so the caller passes ``''`` for them
+    and only the per-round feedback is fresh. Structured output goes
+    through
+    the provider's native JSON-schema mode — tool-mode definitions
+    serialize ahead of the system message and displace the shared
+    prefix, killing cache reuse across specialists. Array-shaped result
+    schemas are wrapped in an ``items`` object (native output requires
+    an object schema) and unwrapped on the way out. StructuredDict
+    guarantees only a str-keyed dict — deep conformance is the injected
+    validator's job. Sampling defaults to temperature 0 (extraction is
+    deterministic-intent); ``model_settings`` overrides any field.
+    Actual token usage is reported to the dispatching scheduler via
+    xtremeparse's ``report_tokens``. ``tools`` is accepted (frozen
+    protocol) but not implemented yet."""
+
+    def __init__(self, model: Model, *, model_settings: dict | None = None,
+                 strict_output: bool = True):
+        self.model = model
+        # deterministic-intent extraction: sampling heat off by default
+        self.model_settings = {'temperature': 0, **(model_settings or {})}
+        # strict keeps the schema in a server-side grammar; without it some
+        # providers inject the schema into the prompt behind the payload and
+        # break the cacheable prefix — hosts whose strict grammar rejects
+        # the schema shape turn it off here
+        self.strict_output = strict_output
+
+    async def run(self, *, instructions: str, result_schema: JSONSchema, content: str,
+                  scope: str = None, tools: list = None, history: list = None,
+                  feedback: Sequence[Issue] = None) -> AgentResult:
+        if tools:
+            raise NotImplementedError('tool-calling is deferred; see design.md §5.1')
+        free = result_schema.get('type') == 'string'  # free-text mode: lib parses
+        wrapped = not free and result_schema.get('type') == 'array'
+        schema = _wrap(result_schema) if wrapped else result_schema
+        output_type = str if free else NativeOutput(StructuredDict(schema),
+                                                    strict=self.strict_output)
+        agent = Agent(self.model, output_type=output_type, instructions=content)
+        result = await agent.run(_tail(instructions, scope, feedback),
+                                 message_history=history,
+                                 model_settings=self._model_settings())
+        await report_tokens(result.usage.input_tokens + result.usage.output_tokens)
+        data = result.output.get('items') if wrapped else result.output
+        return AgentResult(data=data, history=result.all_messages())
+
+    def _model_settings(self):
+        settings = dict(self.model_settings)
+        if _THINKING_OFF.match(getattr(self.model, 'model_name', '')):
+            settings['extra_body'] = {'enable_thinking': False}
+        return settings
+
+
+def enable_tracing() -> None:
+    """Turn on the framework's native OTel span emission for every agent
+    (process-wide). Every adapter in this boundary provides this hook so
+    hosts enable tracing without naming the framework."""
+    Agent.instrument_all(True)
+
+
+def _json_body(body: dict) -> bytes:
+    """SDK serialization style — ensure_ascii would double CJK bytes."""
+    return json.dumps(body, ensure_ascii=False, separators=(',', ':')).encode()
+
+
+def _stripped_headers(headers: httpx.Headers) -> httpx.Headers:
+    """Headers for a rewritten body: the length/encoding headers are stale."""
+    headers = headers.copy()
+    headers.pop('content-length', None)
+    headers.pop('content-encoding', None)
+    return headers
+
+
+def marked_request(request: httpx.Request) -> httpx.Request:
+    """Rewrite a chat-completions request so its leading string-content
+    system message becomes a cache-marked content block (dashscope's
+    ``cache_control`` explicit-cache extension). The marker must close
+    the shared payload at a message boundary — marking mid-message does
+    not match. Non-matching shapes pass through untouched."""
+    body = json.loads(request.read())
+    messages = body.get('messages')
+    if (messages and messages[0].get('role') == 'system'
+            and isinstance(messages[0].get('content'), str)):
+        messages[0]['content'] = [{'type': 'text', 'text': messages[0]['content'],
+                                   'cache_control': {'type': 'ephemeral'}}]
+        return httpx.Request(request.method, request.url,
+                             headers=_stripped_headers(request.headers),
+                             content=_json_body(body))
+    return request
+
+
+def _unthinking(request: httpx.Request) -> httpx.Request:
+    """Drops ``enable_thinking: false`` into a chat-completions body."""
+    body = json.loads(request.read())
+    return httpx.Request(request.method, request.url,
+                         headers=_stripped_headers(request.headers),
+                         content=_json_body(body | {'enable_thinking': False}))
+
+
+def _rename_cache_write(response: httpx.Response) -> httpx.Response:
+    """Relabel dashscope's cache-write usage field to the OpenAI name
+    pydantic-ai reads (``prompt_tokens_details.cache_write_tokens``);
+    without the relabel the count never reaches the usage object or
+    the span."""
+    body = response.content
+    if b'"cache_creation_input_tokens"' not in body:
+        return response
+    return httpx.Response(response.status_code,
+                          headers=_stripped_headers(response.headers),
+                          content=body.replace(b'"cache_creation_input_tokens"',
+                                               b'"cache_write_tokens"'))
+
+
+class _WireTransport(httpx.AsyncHTTPTransport):
+    """Applies provider wire transforms — requests before they leave,
+    chat-completion responses as they return; the openai client beneath
+    is untouched."""
+
+    def __init__(self, transforms: list):
+        super().__init__()  # the base owns the connection pool
+        self.transforms = transforms
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith('/chat/completions'):
+            for transform in self.transforms:
+                request = transform(request)
+            response = await super().handle_async_request(request)
+            if 'application/json' in response.headers.get('content-type', ''):
+                await response.aread()  # a rewritable body must be read first
+                return _rename_cache_write(response)
+            return response
+        return await super().handle_async_request(request)
+
+
+def openai_model(base_url: str, api_key: str, model: str, *, explicit_cache: bool = False,
+                 thinking_off: bool = False,
+                 http_client: httpx.AsyncClient | None = None):
+    """A pydantic-ai Model for any OpenAI-compatible endpoint — the
+    provider mechanism lives inside the agents boundary; hosts pass
+    only deployment config. Requires the ``docspectra[pydantic-ai]`` extra.
+    ``explicit_cache`` marks the leading system message as a provider
+    cache block (dashscope explicit cache): paired with a runner that
+    puts the shared payload in Agent instructions, the call that runs
+    first pays cache creation once and every call behind it hits; the
+    wire transport relabels dashscope's non-standard cache-write usage
+    field so the count also lands on the span. Providers that reject
+    the extension must leave it off.
+    ``thinking_off`` drops ``enable_thinking: false`` into every request
+    — for consumers that build their own pydantic-ai agents outside the
+    runner's model_settings (pydantic-evals LLMJudge: tools +
+    tool_choice='required', which dashscope rejects while thinking).
+    A host ``http_client`` (proxies, connection tuning) is used
+    verbatim."""
+    try:
+        from pydantic_ai.models.openai import OpenAIChatModel
+        from pydantic_ai.providers.openai import OpenAIProvider
+    except ImportError as e:
+        raise ImportError('install the pydantic-ai extra: docspectra[pydantic-ai]') from e
+    if transforms := ([marked_request] if explicit_cache else []) \
+            + ([_unthinking] if thinking_off else []):
+        http_client = httpx.AsyncClient(transport=_WireTransport(transforms))
+    return OpenAIChatModel(model, provider=OpenAIProvider(
+        base_url=base_url, api_key=api_key, http_client=http_client))
+
+
+def _wrap(schema: JSONSchema) -> JSONSchema:
+    return {'type': 'object', 'properties': {'items': schema},
+            'required': ['items'], 'additionalProperties': False}
+
+
+def _tail(instructions: str, scope, feedback) -> str:
+    parts = [instructions] if instructions else []
+    if scope is not None:
+        parts.append(f'\n\n---\nAssigned material:\n{scope}')
+    if feedback:
+        lines = '\n'.join(f'- {i.path}: {i.message}' for i in feedback)
+        parts.append(f'\n\n---\nValidation errors to fix:\n{lines}')
+    return ''.join(parts)

docspectra-0.1.0/docspectra/parser/__init__.py

@@ -0,0 +1,38 @@
+"""File → text. Provider engines as optional extras (``docspectra[pdf-inspect]``,
+``docspectra[anydoc]``, ``docspectra[mineru]``), magic-byte type routing,
+and file-level decline chains: ``DOCSPECTRA_PARSER_CONFIG`` orders each type's
+chain and a provider whose gate fires on a specific file declines, letting the
+next engine take it."""
+
+from docspectra.parser.contracts import (Attempt, Declined, FileInput,
+                                         ImageAsset, MAX_ASSETS, MAX_ASSET_BYTES,
+                                         ParseResult)
+from docspectra.parser.core import (
+    ParseDeclinedError,
+    Provider,
+    configure,
+    parse,
+    parse_path,
+    provider,
+    register,
+)
+from docspectra.parser.sniff import sniff, validate_declared
+
+__all__ = [
+    'Attempt',
+    'Declined',
+    'FileInput',
+    'ImageAsset',
+    'MAX_ASSETS',
+    'MAX_ASSET_BYTES',
+    'ParseDeclinedError',
+    'ParseResult',
+    'Provider',
+    'configure',
+    'parse',
+    'parse_path',
+    'provider',
+    'register',
+    'sniff',
+    'validate_declared',
+]

docspectra-0.1.0/docspectra/parser/contracts.py

@@ -0,0 +1,64 @@
+"""Parser contracts: result shapes and control-flow values shared by core
+and providers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+FileInput = bytes | str | Path
+
+
+@dataclass
+class ImageAsset:
+    """One embedded image carried faithfully, uninterpreted.
+
+    ``name`` matches the ``![](...)`` reference in ParseResult.text;
+    ``source`` is engine provenance ('pdf p2', 'word/media/image1.png').
+    """
+
+    name: str
+    mime: str
+    data: bytes
+    source: str
+
+
+# payload-budget policy for ParseResult.images — every provider skips
+# assets over these limits and records the skip count in meta
+MAX_ASSETS = 50
+MAX_ASSET_BYTES = 5 * 1024 * 1024
+
+
+@dataclass
+class Attempt:
+    """One provider's outcome on a file, recorded by core on success and
+    failure alike — the eval suite reads routing through it."""
+
+    provider: str
+    outcome: Literal['success', 'declined', 'error']
+    reason: str | None = None
+
+
+@dataclass
+class Declined:
+    """Expected control flow: this engine cannot read *this* file, or
+    read it into a known false-positive shape (a gate fired). Never an
+    exception — the chain moves to the next provider."""
+
+    reason: str
+
+
+@dataclass
+class ParseResult:
+    """The outcome of a successful parse. ``format`` is constrained —
+    extend the Literal, never free-form. ``meta`` is provider diagnostics
+    (gate hits, page counts, task ids, timings). ``provider`` and
+    ``attempts`` are stamped by core, not the provider."""
+
+    text: str
+    provider: str = ''  # engine that accepted the file (core-stamped)
+    format: Literal['markdown'] = 'markdown'
+    images: list[ImageAsset] = field(default_factory=list)
+    attempts: list[Attempt] = field(default_factory=list)
+    meta: dict = field(default_factory=dict)

docspectra-0.1.0/docspectra/parser/core.py

@@ -0,0 +1,192 @@
+"""Provider registry, decline chains, and the async parse entry.
+
+Core carries zero parsing dependencies: built-in providers are in-tree
+modules under ``docspectra.providers``, try-imported at init — an absent
+extra is skipped silently (an installed-but-broken provider is recorded
+and surfaced in config errors instead). Engines declare themselves with
+:func:`provider`; chains are ordered by ``DOCSPECTRA_PARSER_CONFIG`` (a
+JSON env var mapping a document type to an ordered provider list),
+falling back to the derived default chain — the canonical order of
+installed providers that declared the type. Declines are return values,
+hard errors fall through; chain exhaustion raises
+:class:`ParseDeclinedError` with every attempt aggregated."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable, Sequence
+
+from docspectra.parser.contracts import Attempt, Declined, ParseResult
+from docspectra.parser.sniff import sniff, validate_declared
+
+_BUILTIN_MODULES = ('txt', 'pdf_inspect', 'anydoc', 'mineru')
+_BUILTIN_NAMES = {m.replace('_', '-') for m in _BUILTIN_MODULES}
+_CONFIG_ENV = 'DOCSPECTRA_PARSER_CONFIG'
+
+
+@dataclass
+class Provider:
+    """One engine: the async parse entry plus the types it declares."""
+
+    name: str
+    types: tuple[str, ...]
+    parse: Callable[..., Awaitable[ParseResult | Declined]]
+
+
+class ParseDeclinedError(Exception):
+    """Every provider in the chain declined or errored on this file.
+
+    ``attempts`` aggregates every outcome. A hard error raised through
+    the chain is chained as the cause.
+    """
+
+    def __init__(self, attempts: list[Attempt]):
+        self.attempts = attempts
+        detail = '; '.join(
+            f"{a.provider}: {a.outcome}" + (f' ({a.reason})' if a.reason else '')
+            for a in attempts
+        )
+        super().__init__(f'every provider declined: {detail}')
+
+
+_providers: dict[str, Provider] = {}  # keyed by normalized (hyphen) engine name
+_builtins_loaded = False
+_config: dict | None = None  # effective chain config; resolved from env on first use
+_import_errors: dict[str, str] = {}  # provider module → failure, when installed-but-broken
+
+
+def _norm(name: str) -> str:
+    return name.replace('_', '-')
+
+
+def register(name: str, types: Sequence[str], fn) -> None:
+    """Programmatic registration, same surface as the decorator. Names are
+    normalized (hyphen↔underscore) and registration is last-write-wins."""
+    _providers[_norm(name)] = Provider(_norm(name), tuple(types), fn)
+
+
+def provider(name: str, types: Sequence[str]):
+    """Declare an engine around an async ``parse(data, *, name=None)
+    -> ParseResult | Declined``."""
+
+    def deco(fn):
+        register(name, types, fn)
+        return fn
+
+    return deco
+
+
+def ensure_builtins() -> None:
+    global _builtins_loaded
+    if _builtins_loaded:
+        return
+    _builtins_loaded = True
+    for module in _BUILTIN_MODULES:
+        try:
+            importlib.import_module(f'docspectra.providers.{module}')
+        except ImportError as e:
+            if not isinstance(e, ModuleNotFoundError) \
+                    or (e.name or '').startswith('docspectra'):
+                _import_errors[_norm(module)] = f'{type(e).__name__}: {e}'
+
+
+def configure(config: dict | None = None) -> None:
+    """Pin chains to an explicit ``{type: [engine, ...]}`` mapping, or
+    reload them from DOCSPECTRA_PARSER_CONFIG (None, validated here —
+    the fail-fast hook a host calls at startup)."""
+    global _config
+    ensure_builtins()
+    _config = _validate(config) if config is not None else _env_config()
+
+
+async def parse(data: bytes, *, name: str | None = None) -> ParseResult:
+    """Parse one file (bytes are the contract) into a ParseResult,
+    walking the type's decline chain. Raises ValueError on unroutable
+    input, on a declared binary extension whose content fails magic
+    verification, or when no provider is installed; ParseDeclinedError
+    when every provider declines or errors."""
+    ensure_builtins()
+    validate_declared(data, name)  # declared-binary gate, before any provider
+    doc_type = sniff(data, name)
+    if doc_type is None:
+        raise ValueError(f'cannot determine document type of {name or "input"}')
+    chain = _chain_for(doc_type)
+    if not chain:
+        raise ValueError(f'no provider installed for document type {doc_type!r}')
+    attempts: list[Attempt] = []
+    cause = None
+    for provider_name in chain:
+        p = _providers[provider_name]
+        try:
+            result = await p.parse(data, name=name)
+        except Exception as e:
+            attempts.append(Attempt(p.name, 'error', f'{type(e).__name__}: {e}'))
+            cause = cause or e
+            continue
+        if isinstance(result, Declined):
+            attempts.append(Attempt(p.name, 'declined', result.reason))
+            continue
+        result.provider = p.name
+        result.attempts = [*attempts, Attempt(p.name, 'success')]
+        return result
+    raise ParseDeclinedError(attempts) from cause
+
+
+async def parse_path(path: str | Path) -> ParseResult:
+    """Convenience wrapper: read the file and parse it, name from the path."""
+    path = Path(path)
+    return await parse(path.read_bytes(), name=path.name)
+
+
+def _chain_for(doc_type: str) -> list[str]:
+    config = _effective_config()
+    if doc_type in config:
+        return list(config[doc_type])
+    # derived default chain: canonical order of installed providers that
+    # declared the type — extends automatically as built-ins are added
+    return [p.name for p in _providers.values() if doc_type in p.types]
+
+
+def _effective_config() -> dict:
+    global _config
+    if _config is None:
+        _config = _env_config()
+    return _config
+
+
+def _env_config() -> dict:
+    raw = os.environ.get(_CONFIG_ENV)
+    if not raw:
+        return {}
+    try:
+        config = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ValueError(f'{_CONFIG_ENV} is not valid JSON: {e}') from e
+    if not isinstance(config, dict):
+        raise ValueError(f'{_CONFIG_ENV} must be a JSON object of type → engine list')
+    return _validate(config)
+
+
+def _validate(config: dict) -> dict:
+    validated = {}
+    for doc_type, names in config.items():
+        if not isinstance(names, list) or not all(isinstance(n, str) for n in names):
+            raise ValueError(f'{_CONFIG_ENV}[{doc_type!r}] must be a list of engine names')
+        normed = []
+        for name in names:
+            key = _norm(name)
+            if key not in _providers:
+                if key in _BUILTIN_NAMES:
+                    detail = f' ({_import_errors[key]})' if key in _import_errors else ''
+                    raise ValueError(
+                        f'provider {name!r} is configured but not installed{detail} — '
+                        f'install the matching extra (docspectra[{key}])')
+                raise ValueError(
+                    f'unknown parser provider {name!r}; known: {sorted(_providers)}')
+            normed.append(key)
+        validated[doc_type] = normed
+    return validated