docspectra 0.1.0__py3-none-any.whl

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/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/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/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/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

docspectra/parser/sniff.py

@@ -0,0 +1,97 @@
+"""Document-type sniffing: magic bytes first, extension fallback, no
+dependencies. Bytes win on conflict for routing; a filename declaring a
+binary extension is gated by :func:`validate_declared` before any
+provider runs.
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+_PDF = b'%PDF-'
+_ZIP = b'PK\x03\x04'
+_OLE2 = b'\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1'
+
+_IMAGES = (
+    (b'\xff\xd8\xff', 'jpg'),
+    (b'\x89PNG\r\n\x1a\n', 'png'),
+    (b'GIF87a', 'gif'),
+    (b'GIF89a', 'gif'),
+    (b'BM', 'bmp'),
+    (b'II*\x00', 'tiff'),
+    (b'MM\x00*', 'tiff'),
+    (b'\x00\x00\x00\x0cjP  \r\n\x87\n', 'jp2'),
+)
+
+# extension aliases, normalized to the canonical type
+_ALIASES = {'jpeg': 'jpg', 'tif': 'tiff', 'htm': 'html'}
+
+# OLE2 magic is coarse — the legacy office extensions form one family
+_FAMILY = {'doc': frozenset({'doc', 'ppt', 'xls'})}
+
+# types whose declared extension must verify against content magic: the
+# magic tables' codomain (zip parts + images + webp), family expanded
+_BINARY_TYPES = ({'pdf', 'docx', 'xlsx', 'pptx', 'webp'}
+                 | {t for _, t in _IMAGES} | set().union(*_FAMILY.values()))
+
+
+def sniff(data: bytes, name: str | None = None) -> str | None:
+    """Route bytes to a canonical document type. ``name`` feeds the
+    extension fallback when magic is inconclusive; None when neither
+    yields a type."""
+    if data.startswith(_PDF):
+        return 'pdf'
+    if data.startswith(_ZIP):
+        return _zip_type(data) or _extension_type(name)
+    if data.startswith(_OLE2):
+        return 'doc'  # coarse: doc/ppt/xls share the legacy chain
+    if t := _image_type(data):
+        return t
+    return _extension_type(name)
+
+
+def validate_declared(data: bytes, name: str | None = None) -> None:
+    """Gate a declared binary extension against content magic: raise
+    ValueError('file content is not a XXX') — XXX the extension's
+    canonical type — when the bytes do not verify. Text and unknown
+    extensions are never validated; the extension fallback owns them."""
+    declared = _extension_type(name)
+    if declared not in _BINARY_TYPES or _matches(data, declared):
+        return
+    raise ValueError(f'file content is not a {declared}')
+
+
+def _matches(data: bytes, declared: str) -> bool:
+    magic = sniff(data)  # no name: pure magic, extension fallback off
+    return magic is not None and declared in _FAMILY.get(magic, {magic})
+
+
+def _zip_type(data: bytes) -> str | None:
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as z:
+            for info in z.infolist():
+                if info.filename.startswith('word/'):
+                    return 'docx'
+                if info.filename.startswith('xl/'):
+                    return 'xlsx'
+                if info.filename.startswith('ppt/'):
+                    return 'pptx'
+    except (zipfile.BadZipFile, OSError):
+        return None
+    return None
+
+
+def _image_type(data: bytes) -> str | None:
+    if data.startswith(b'RIFF') and data[8:12] == b'WEBP':
+        return 'webp'
+    for magic, t in _IMAGES:
+        if data.startswith(magic):
+            return t
+    return None
+
+
+def _extension_type(name: str | None) -> str | None:
+    ext = Path(name or '').suffix.lower().lstrip('.')
+    return _ALIASES.get(ext, ext) or None

docspectra/providers/__init__.py

@@ -0,0 +1,42 @@
+"""Built-in provider engines. Core try-imports each module at init; a
+module whose extra is absent fails to import and is skipped silently."""
+
+from functools import wraps
+
+from opentelemetry.trace import get_tracer
+
+from docspectra.parser import Declined, ParseResult
+
+# shared by the provider engines; spans are no-ops until a host
+# registers a tracer provider
+tracer = get_tracer('docspectra')
+
+
+def traced(fn):
+    """One span per parse call, named after the engine module — engine
+    registrations and their span names can then never drift apart. The
+    span carries the outcome bookkeeping (outcome, decline reason,
+    input bytes, the meta diagnostics — never text: spans are an
+    account ledger like the sidecar, PII stays out; batch_id stays off
+    too, it points at remote state holding the file)."""
+    span_name = f'{fn.__module__.rsplit(".", 1)[-1]}.parse'
+
+    @wraps(fn)
+    async def wrapper(*args, **kwargs):
+        with tracer.start_as_current_span(span_name) as span:
+            result = await fn(*args, **kwargs)
+            if args and isinstance(args[0], (bytes, bytearray)):
+                span.set_attribute('parse.bytes', len(args[0]))
+            if isinstance(result, Declined):
+                span.set_attribute('parse.outcome', 'declined')
+                span.set_attribute('parse.reason', result.reason)
+            else:
+                span.set_attribute('parse.outcome', 'success')
+                span.set_attribute('parse.chars', len(result.text))
+                span.set_attribute('parse.images', len(result.images))
+                for key, value in result.meta.items():
+                    if key != 'batch_id':
+                        span.set_attribute(f'parse.{key}', value)
+            return result
+
+    return wrapper

docspectra/providers/_pdfscan.py

@@ -0,0 +1,122 @@
+"""Shared plumbing behind the local pdf engines (pdf-inspect and anydoc):
+the post-classify tail — two byte-side decline gates over pypdf (the
+word-strip fingerprint and the content-stream ratio) plus one text-side
+gate over the engine markdown (the table wall), the XObject image
+collection, and the markdown clean-up — pure pypdf plus regex, so either
+extra can host it without the other's engine."""
+
+from __future__ import annotations
+
+import io
+import re
+
+from pypdf import PdfReader
+
+from docspectra.parser import (Declined, ImageAsset, MAX_ASSETS,
+                               MAX_ASSET_BYTES, ParseResult)
+
+RATIO_THRESHOLD = 200  # B/char; measured 4,968 vs clean max 82 (parser.md §1)
+STRIP_W, STRIP_H = 80, 100  # pixel dims of word-shaped raster strips
+TABLE_SHARE_MIN = 0.7  # of all text chars; judgment call — measured wall
+# 0.99, corpus real tables a minority share (parser.md §1)
+WALL_ROW_CHARS = 500  # chars in one row; the engine's own paragraph-wall
+# constant, measured wall row ~1,300 (parser.md §1)
+_MIME = {'/DCTDecode': 'image/jpeg', '/JPXDecode': 'image/jp2',
+         '/CCITTFaxDecode': 'image/tiff'}
+
+_U_TAG = re.compile(r'</?u>')
+_BULLET = re.compile(r'^l ', re.MULTILINE)  # the engine renders bullets as 'l'
+
+
+def scan(data: bytes, text: str, **meta) -> ParseResult | Declined:
+    """The shared post-classify tail: the two pypdf gates and the
+    text-side table wall, image collection, and the cleaned ParseResult.
+    ``meta`` adds engine-specific diagnostics between ``pages`` and
+    ``skipped_assets``."""
+    reader = PdfReader(io.BytesIO(data))
+    for page in reader.pages:
+        if strip_hit(page):
+            return Declined('fingerprint_gate')
+    if ratio_hit(reader, len(text)) >= RATIO_THRESHOLD:
+        return Declined('ratio_gate')
+    if table_wall_hit(text):
+        return Declined('table_wall_gate')
+    images, skipped = collect_images(reader)
+    return ParseResult(text=clean(text), images=images,
+                       meta={'pages': len(reader.pages), **meta,
+                             'skipped_assets': skipped})
+
+
+def clean(markdown: str) -> str:
+    return _BULLET.sub('• ', _U_TAG.sub('', markdown))
+
+
+def table_wall_hit(text: str) -> bool:
+    """One markdown table swallowing the page's flowing prose — the
+    layout-band false positive of geometry-based table detection (a
+    borderless template frame reconstructed as a grid, reading order
+    scrambled). Both conditions matter: a document that merely carries
+    a real table stays, and a page of genuine data cells (high table
+    share, short rows) stays."""
+    lines = [line for line in text.splitlines() if line.strip()]
+    rows = [line for line in lines
+            if line.startswith('|') and line.strip('|- ')]
+    total = sum(map(len, lines))
+    return (bool(rows)
+            and sum(map(len, rows)) / total >= TABLE_SHARE_MIN
+            and max(map(len, rows)) > WALL_ROW_CHARS)
+
+
+def strip_hit(page) -> bool:
+    """A wide flat image XObject — a rasterized text strip among a real
+    text layer (the raster-strip class). Missing height counts as the threshold."""
+    return any(obj.get('/Width', 0) >= STRIP_W and obj.get('/Height', STRIP_H) <= STRIP_H
+               for _, obj in _iter_images(page))
+
+
+def ratio_hit(reader: PdfReader, nchars: int) -> float:
+    """Content-stream bytes per delivered text char; outlined glyphs
+    (the outlined-glyph class) inflate the stream without any text to show for it."""
+    nbytes = 0
+    for page in reader.pages:
+        if (contents := page.get_contents()) is not None:
+            nbytes += len(contents.get_data())
+    return nbytes / nchars if nchars else float('inf')
+
+
+def collect_images(reader: PdfReader) -> tuple[list[ImageAsset], int]:
+    images, skipped = [], 0
+    for page_no, page in enumerate(reader.pages, 1):
+        for key, obj in _iter_images(page):
+            if len(images) >= MAX_ASSETS:
+                skipped += 1
+                continue
+            try:
+                data = obj.get_data()
+            except Exception:
+                skipped += 1
+                continue
+            if len(data) > MAX_ASSET_BYTES:
+                skipped += 1
+                continue
+            # names are opaque per-engine keys: the engine emits no
+            # image references, so nothing in the text reconciles to them
+            images.append(ImageAsset(
+                name=f'p{page_no}-{str(key).lstrip("/")}',
+                mime=_MIME.get(str(obj.get('/Filter', '')), 'application/octet-stream'),
+                data=data, source=f'pdf p{page_no} {key}'))
+    return images, skipped
+
+
+def _iter_images(page):
+    """Yield (key, ImageObject) pairs from the page's own XObject dict —
+    the measured walk behind the fingerprint gate (parser.md §1)."""
+    resources = _deref(page.get('/Resources') or {})
+    for key, ref in _deref(resources.get('/XObject') or {}).items():
+        obj = _deref(ref)
+        if obj.get('/Subtype') == '/Image':
+            yield key, obj
+
+
+def _deref(obj):
+    return obj.get_object() if hasattr(obj, 'get_object') else obj

docspectra/providers/anydoc.py

@@ -0,0 +1,65 @@
+"""Local superset engine (extra: anydoc): firecrawl-anydoc (Rust) over
+pdf plus every office family. The pdf branch runs the shared decline
+gates — classify from the engine's own ImageBased/Scanned rejection,
+the rest from ``_pdfscan``; office formats (doc/docx, xls/xlsx, ppt/pptx,
+odt/ods/odp, rtf, epub, csv) convert to markdown with their embedded
+images carried as ImageAssets. Docx headers and footers are page
+furniture the engine drops by design."""
+
+from __future__ import annotations
+
+import anydoc
+
+from docspectra.parser import (Declined, ImageAsset, MAX_ASSETS,
+                               MAX_ASSET_BYTES, ParseResult, provider,
+                               sniff)
+from docspectra.providers import traced
+from docspectra.providers._pdfscan import scan
+
+# sniff type → engine Format for the office branch; None lets the engine
+# detect from the bytes (the OLE2 family — 'doc' covers legacy doc/xls/ppt
+# alike, and xls has no Format name of its own). An explicit map, not a
+# passthrough: a sniff/engine vocabulary drift must fail here, not inside
+# the engine as a runtime error.
+_FORMAT: dict[str, str | None] = {
+    'docx': 'docx', 'doc': None,
+    'ppt': 'ppt', 'pptx': 'pptx', 'xls': None, 'xlsx': 'xlsx',
+    'odt': 'odt', 'ods': 'ods', 'odp': 'odp',
+    'rtf': 'rtf', 'epub': 'epub', 'csv': 'csv',
+}
+
+
+@provider('anydoc', ('pdf', *_FORMAT))
+@traced
+async def parse_anydoc(data: bytes, *, name: str | None = None) -> ParseResult | Declined:
+    # core already sniffed for routing; re-sniffed here because the
+    # provider contract carries (data, name) and the engine Format and
+    # the pdf/office branch both hang off the type
+    if (doc_type := sniff(data, name)) == 'pdf':
+        return _parse_pdf(data)
+    return _parse_office(data, doc_type)
+
+
+def _parse_pdf(data: bytes) -> ParseResult | Declined:
+    try:
+        text = anydoc.to_markdown_bytes(data)
+    except anydoc.UnsupportedError:
+        # the engine's own rejection: ImageBased/Scanned pages need OCR
+        return Declined('classify_gate')
+    return scan(data, text)
+
+
+def _parse_office(data: bytes, doc_type: str) -> ParseResult:
+    # signature-less formats (csv) must name their format explicitly
+    fmt = _FORMAT[doc_type]
+    text = anydoc.to_markdown_bytes(data, fmt)
+    images, skipped = [], 0
+    for asset in anydoc.to_document(data, fmt).assets:
+        if len(images) >= MAX_ASSETS or len(asset.data) > MAX_ASSET_BYTES:
+            skipped += 1
+            continue
+        images.append(ImageAsset(
+            name=asset.origin_part, mime=asset.media_type, data=asset.data,
+            source=f'anydoc {asset.origin_part}'))
+    return ParseResult(text=text, images=images,
+                       meta={'skipped_assets': skipped})

docspectra/providers/mineru.py

@@ -0,0 +1,213 @@
+"""Cloud engine (extra: mineru): MinerU extraction service via signed
+upload + batch poll, rate-limited by dual xtremeflow lanes (submit
+50/min, status 1000/min — the official ceilings, per-minute numbers
+divided by 60 into float rps). 429/5xx raise RetryException and retry
+through auto_backoff; other 4xx (quota, auth) surface as hard errors.
+Results are cached in-process keyed by (sha256, model_version) — memory
+only, never disk, evicted by count and byte budget."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import os
+import time
+import zipfile
+from collections import OrderedDict
+
+import httpx
+
+from docspectra.parser import (ImageAsset, MAX_ASSETS, MAX_ASSET_BYTES,
+                               ParseResult, provider)
+from docspectra.providers import traced
+
+from xtremeflow.scheduler.rate_limit import RetryException, auto_backoff
+from xtremeflow.scheduler.request import RequestRateScheduler  # deep import: not re-exported
+
+BASE = 'https://mineru.net/api/v4'
+POLL_INTERVAL = 2.0
+_CACHE_MAX = 8  # ~1 MB per file — roughly 8 MB resident
+_CACHE_BYTES = 8 * 1024 * 1024
+_UPLOAD_RETRIES = 3
+_MIME = {'jpg': 'image/jpeg', 'jpeg': 'image/jpeg', 'png': 'image/png',
+         'gif': 'image/gif', 'webp': 'image/webp', 'svg': 'image/svg+xml',
+         'bmp': 'image/bmp', 'tiff': 'image/tiff'}
+
+
+class MineruError(Exception):
+    """Hard error: quota, auth, timeout, or a failed extraction — falls
+    through the chain like any provider exception."""
+
+
+@provider('mineru', ('pdf', 'doc', 'docx', 'ppt', 'pptx', 'xls', 'xlsx',
+                     'png', 'jpg', 'jpeg', 'jp2', 'webp', 'gif', 'bmp', 'tiff'))
+@traced
+async def parse_mineru(data: bytes, *, name: str | None = None) -> ParseResult:
+    token = os.environ.get('MINERU_API_TOKEN')
+    if not token:
+        raise MineruError('MINERU_API_TOKEN is not set')
+    model = os.environ.get('MINERU_MODEL_VERSION', 'pipeline')
+    key = (hashlib.sha256(data).hexdigest(), model)
+    if cached := _cache_get(key):
+        # per-call facade: share the immutable payload, never the cached
+        # meta (a batch id for a batch this call never submitted)
+        return ParseResult(text=cached.text, images=cached.images,
+                           meta={'model_version': model, 'cache_hit': True})
+    timeout = float(os.environ.get('MINERU_TIMEOUT', '300'))
+    submit_lane, status_lane = _lanes()
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        task = await submit_lane.start_task(_apply_url(client, token, model, name))
+        batch_id, file_url = await task
+        await _upload(client, file_url, data)
+        zip_url = await _poll(client, token, batch_id, timeout, status_lane)
+        if not zip_url:
+            raise MineruError(f'mineru batch {batch_id} finished without a result zip')
+        result_zip = await _download(client, zip_url)
+        markdown, images, skipped = _unzip(result_zip)
+    result = ParseResult(
+        text=markdown, images=images,
+        meta={'model_version': model, 'batch_id': batch_id, 'skipped_assets': skipped})
+    _cache_put(key, result)
+    return result
+
+
+@auto_backoff()
+async def _apply_url(client: httpx.AsyncClient, token: str, model: str,
+                     name: str | None) -> tuple[str, str]:
+    res = await client.post(f'{BASE}/file-urls/batch', headers=_headers(token),
+                            json={'files': [{'name': name or 'file', 'data_id': 'f'}],
+                                  'model_version': model})
+    _check(res)
+    payload = res.json()
+    if payload.get('code') != 0:
+        raise MineruError(f'mineru file-urls failed: {payload.get("msg")}')
+    return payload['data']['batch_id'], payload['data']['file_urls'][0]
+
+
+async def _upload(client: httpx.AsyncClient, url: str, data: bytes) -> None:
+    """S3 single PUT is atomic — an interrupted PUT leaves no object, so
+    retrying the same signed URL is safe. Outside the lanes: S3 does not
+    count against mineru's submit rate."""
+    for attempt in range(_UPLOAD_RETRIES):
+        res = await client.put(url, content=data, timeout=120.0)
+        if res.status_code == 429 or res.status_code >= 500:
+            await asyncio.sleep(2 ** attempt)
+            continue
+        if res.status_code >= 400:
+            raise MineruError(f'mineru upload failed: {res.status_code}: {res.text[:200]}')
+        return
+    raise MineruError(f'mineru upload failed after {_UPLOAD_RETRIES} attempts: {res.status_code}')
+
+
+async def _poll(client: httpx.AsyncClient, token: str, batch_id: str,
+                timeout: float, status_lane: RequestRateScheduler) -> str:
+    deadline = time.monotonic() + timeout
+    while True:
+        task = await status_lane.start_task(_poll_once(client, token, batch_id))
+        item = await task
+        state = item['state']
+        if state == 'done':
+            return item.get('full_zip_url')
+        if state == 'failed':
+            raise MineruError(f'mineru extract failed: {item.get("err_msg")}')
+        if time.monotonic() >= deadline:
+            raise MineruError(f'mineru timed out after {timeout:.0f}s (state {state})')
+        await asyncio.sleep(POLL_INTERVAL)
+
+
+@auto_backoff()
+async def _poll_once(client: httpx.AsyncClient, token: str, batch_id: str) -> dict:
+    res = await client.get(f'{BASE}/extract-results/batch/{batch_id}',
+                           headers=_headers(token))
+    _check(res)
+    payload = res.json()
+    if payload.get('code') != 0:
+        raise MineruError(f'mineru extract-results failed: {payload.get("msg")}')
+    return payload['data']['extract_result'][0]
+
+
+async def _download(client: httpx.AsyncClient, zip_url: str) -> bytes:
+    res = await client.get(zip_url, timeout=120.0)
+    if res.status_code >= 400:
+        raise MineruError(f'mineru result download failed: {res.status_code}')
+    return res.content
+
+
+def _unzip(result_zip: bytes) -> tuple[str, list[ImageAsset], int]:
+    """Result zip → markdown (full.md) + ImageAssets; assets reconcile
+    with the markdown's ``![](images/...)`` references by name."""
+    markdown = ''
+    found = False
+    images: list[ImageAsset] = []
+    skipped = 0
+    with zipfile.ZipFile(io.BytesIO(result_zip)) as z:
+        for name in z.namelist():
+            if name.endswith('full.md'):
+                found = True
+                markdown = z.read(name).decode('utf-8', errors='replace')
+            elif name.startswith('images/') and not name.endswith('/'):
+                if len(images) >= MAX_ASSETS or z.getinfo(name).file_size > MAX_ASSET_BYTES:
+                    skipped += 1
+                    continue
+                ext = name.rsplit('.', 1)[-1].lower()
+                images.append(ImageAsset(name=name, mime=_MIME.get(ext, 'application/octet-stream'),
+                                         data=z.read(name), source=f'mineru {name}'))
+    if not found:
+        raise MineruError('mineru result zip has no full.md')
+    return markdown, images, skipped
+
+
+def _check(res: httpx.Response) -> None:
+    if res.status_code >= 400:
+        msg = f'mineru {res.status_code}: {res.text[:200]}'
+        if res.status_code == 429 or res.status_code >= 500:
+            retry_after = res.headers.get('Retry-After')
+            raise RetryException(msg, retry_after=float(retry_after) if retry_after else None)
+        raise MineruError(msg)
+
+
+def _headers(token: str) -> dict:
+    return {'Content-Type': 'application/json', 'Authorization': f'Bearer {token}'}
+
+
+_lanes_cache: tuple[RequestRateScheduler, RequestRateScheduler] | None = None
+
+
+def _lanes() -> tuple[RequestRateScheduler, RequestRateScheduler]:
+    global _lanes_cache
+    if _lanes_cache is None:
+        spec = dict(kv.split(':', 1) for kv in
+                    os.environ.get('MINERU_CONCURRENCY', 'submit:50|status:1000').split('|'))
+        missing = [k for k in ('submit', 'status') if k not in spec]
+        if missing:
+            raise ValueError(f'MINERU_CONCURRENCY is missing the {missing} lane')
+        _lanes_cache = (
+            RequestRateScheduler(max_rps=float(spec['submit']) / 60, max_concurrency=8),
+            RequestRateScheduler(max_rps=float(spec['status']) / 60, max_concurrency=32),
+        )
+    return _lanes_cache
+
+
+_cache: OrderedDict[tuple[str, str], ParseResult] = OrderedDict()
+_cache_bytes = 0
+
+
+def _result_size(result: ParseResult) -> int:
+    return len(result.text) + sum(len(img.data) for img in result.images)
+
+
+def _cache_get(key: tuple[str, str]) -> ParseResult | None:
+    if cached := _cache.get(key):
+        _cache.move_to_end(key)
+    return cached
+
+
+def _cache_put(key: tuple[str, str], result: ParseResult) -> None:
+    global _cache_bytes
+    _cache[key] = result
+    _cache.move_to_end(key)
+    _cache_bytes += _result_size(result)
+    while len(_cache) > _CACHE_MAX or _cache_bytes > _CACHE_BYTES:
+        _, old = _cache.popitem(last=False)
+        _cache_bytes -= _result_size(old)

docspectra/providers/pdf_inspect.py

@@ -0,0 +1,21 @@
+"""Local pdf engine (extra: pdf-inspect): pdf-inspector extraction with
+a sampling-classify decline gate (raster pages); the fingerprint/ratio
+gates, image collection, and post-processing live in ``_pdfscan``."""
+
+from __future__ import annotations
+
+import pdf_inspector
+
+from docspectra.parser import Declined, ParseResult, provider
+from docspectra.providers import traced
+from docspectra.providers._pdfscan import scan
+
+
+@provider('pdf-inspect', ('pdf',))
+@traced
+async def parse_pdf(data: bytes, *, name: str | None = None) -> ParseResult | Declined:
+    det = pdf_inspector.process_pdf_bytes(data)
+    if det.pages_needing_ocr:
+        return Declined('classify_gate')
+    return scan(data, det.markdown or '', pdf_type=str(det.pdf_type),
+                encoding_issues=det.has_encoding_issues)

docspectra/providers/txt.py

@@ -0,0 +1,15 @@
+"""txt/md passthrough — the one built-in provider that needs no extra."""
+
+from __future__ import annotations
+
+from docspectra.parser import Declined, ParseResult, provider
+from docspectra.providers import traced
+
+
+@provider('txt', ('txt', 'md', 'markdown'))
+@traced
+async def parse_txt(data: bytes, *, name: str | None = None) -> ParseResult | Declined:
+    try:
+        return ParseResult(text=data.decode('utf-8-sig'))
+    except UnicodeDecodeError:
+        return Declined('utf-8 decode failed')

docspectra/service/__init__.py

@@ -0,0 +1,5 @@
+"""The parse service: file + JSON schema → JSON (parser → xtremeparse extractor)."""
+
+from docspectra.service.parse import GenericIssue, ParseService, schema_validator
+
+__all__ = ['ParseService', 'schema_validator', 'GenericIssue']

docspectra/service/parse.py

@@ -0,0 +1,60 @@
+"""The parse service: file + JSON schema → JSON (parser → extractor)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from jsonschema import Draft202012Validator
+
+from xtremeparse import Extractor, ExtractionResult
+
+from docspectra.parser import FileInput, parse as parse_file, parse_path
+
+
+class ParseService:
+    """One file and one JSON Schema in, best-effort schema-shaped JSON
+    out — validated and self-corrected against a generic JSON Schema
+    validator (hosts with their own validator, e.g. docxcast, inject it
+    through the extractor directly)."""
+
+    def __init__(self, runner, *, scheduler=None):
+        self._extractor = Extractor(runner, scheduler=scheduler)
+
+    async def parse(self, data: FileInput, schema: dict, *,
+                    name: str | None = None, validator=None) -> ExtractionResult:
+        document = await parse_file(data, name=name) if isinstance(data, bytes) \
+            else await parse_path(data)
+        return await self._extractor.extract(document.text, schema,
+                                             validator=validator or schema_validator(schema))
+
+
+@dataclass
+class GenericIssue:
+    """JSON-Schema error shaped to the Issue protocol; array indices
+    render bracketed (`jobs[0].company`) so correction routing matches."""
+
+    path: str
+    message: str
+    code: str
+    expected: object = None
+    got: object = None
+
+
+def schema_validator(schema: dict):
+    """Validate data against a JSON Schema, returning error-level issues."""
+    validator = Draft202012Validator(schema)
+
+    def validate(data: dict) -> list:
+        return [GenericIssue(_path(e), e.message, e.validator) for e in validator.iter_errors(data)]
+
+    return validate
+
+
+def _path(error) -> str:
+    path = ''
+    for part in error.absolute_path:
+        if isinstance(part, int):
+            path = f'{path}[{part}]'
+        else:
+            path = f'{path}.{part}' if path else str(part)
+    return path or '$'

docspectra-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+docspectra/__init__.py,sha256=BFvaJmQhD1jgrnqnoUXnTbd4Q34pjXJDvIH-Yp-vJqI,248
+docspectra/agents/__init__.py,sha256=0_Cilm03Cxyr-J5joWKtv-a0dVT0ouPOOxRJTtEheLA,10239
+docspectra/parser/__init__.py,sha256=OHaFVRg6oSJRh3WwM9Rs9tTa7ubK5pZp-ynl4JpIbZQ,1057
+docspectra/parser/contracts.py,sha256=bLr7q5ypU6xaXJ3aWLqiaOYS4a2aYOp3QhFH5aT3MdA,1855
+docspectra/parser/core.py,sha256=YB-uXbKTgpUcSrKcgJHDtc-qK0HRlzy_ypZW15gJxds,7156
+docspectra/parser/sniff.py,sha256=YGJW-9przYVpqLhr5d3VUX2zGNyEwGf4K7YF3e84m_0,3282
+docspectra/providers/__init__.py,sha256=HxwE6bzjhpLFVwa-VH07-TeyFMs0iJ5Xog5HjLcX-jc,1780
+docspectra/providers/_pdfscan.py,sha256=8tOyZ-GUIk0M34-quEkyMXP2C3ziRuGiFKPq0Tx0bM4,5104
+docspectra/providers/anydoc.py,sha256=UT_o6ReffKls3RztTCvDh7C3uzWaYYJMWLPkOrw0ebE,2752
+docspectra/providers/mineru.py,sha256=s02CMeUEhmRNuvPXnEYd1xYAD_ftSjPbBxIJN9OfMWk,8904
+docspectra/providers/pdf_inspect.py,sha256=GyDauwjQBrowa1a14hSSaxLQDfXMW64ZJ34a7_OPdHM,800
+docspectra/providers/txt.py,sha256=Fg8vCB7tpotEZIxPKh_eTgej6A6Nb1O0EwtLxnaBYEA,502
+docspectra/service/__init__.py,sha256=yG6mGKeariyx4EeQcMM2kDrvx99vETxaKCAIqwI2hXw,236
+docspectra/service/parse.py,sha256=zXmRkHHs6fk7qm7rEh4SgyuNPzA3cEO0VzS3SrNbB_Q,1980
+docspectra-0.1.0.dist-info/METADATA,sha256=adDfdK8pxcTpeQIYo-IjSlJdgJO8R3YaNhA91DdacZo,2943
+docspectra-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+docspectra-0.1.0.dist-info/licenses/LICENSE,sha256=h8-551rXql0Z6aYn_7eita2vDlYtGqP12OGxrmlaQ74,1067
+docspectra-0.1.0.dist-info/RECORD,,

docspectra-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docspectra-0.1.0.dist-info/licenses/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.