docvision 0.2.0__py3-none-any.whl

docvision/__init__.py

@@ -0,0 +1,4 @@
+from .__version__ import __version__
+from .core import DocumentParser, ParsingMode
+
+__all__ = ["__version__", "ParsingMode", "DocumentParser"]

docvision/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

docvision/core/__init__.py

@@ -0,0 +1,27 @@
+from .client import VLMClient
+from .constants import (
+    CONTINUE_PROMPT,
+    DEFAULT_SYSTEM_PROMPT,
+    DEFAULT_USER_PROMPT,
+    FIX_PROMPT,
+    TRANSCRIPTION,
+)
+from .parser import DocumentParser
+from .types import (
+    AgenticParseState,
+    ParseResult,
+    ParsingMode,
+)
+
+__all__ = [
+    "VLMClient",
+    "DocumentParser",
+    "ParsingMode",
+    "ParseResult",
+    "AgenticParseState",
+    "DEFAULT_SYSTEM_PROMPT",
+    "DEFAULT_USER_PROMPT",
+    "TRANSCRIPTION",
+    "CONTINUE_PROMPT",
+    "FIX_PROMPT",
+]

docvision/core/client.py

@@ -0,0 +1,163 @@
+import asyncio
+import os
+from typing import Any, Dict, List, Optional, Type
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+
+
+class VLMClient:
+    """
+    A client for interacting with Vision Language Models (VLMs) via OpenAI-compatible APIs.
+
+    Attributes:
+        model_name: Name of the model to use.
+        max_tokens: Maximum number of tokens for the completion.
+        temperature: Sampling temperature.
+        timeout: Request timeout in seconds.
+        max_retries: Number of retry attempts.
+        retry_delay: Delay between retries in seconds.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://api.openai.com/v1",
+        api_key: Optional[str] = None,
+        model_name: str = "gpt-4o-mini",
+        max_tokens: int = 4096,
+        temperature: float = 0.1,
+        timeout: int = 300,
+        max_retries: int = 3,
+        retry_delay: float = 2.0,
+    ):
+        """
+        Initialize the VLMClient.
+
+        Args:
+            base_url: The base URL for the API.
+            api_key: The API key. If not provided, it will look for the OPENAI_API_KEY environment variable.
+            model_name: The name of the model to use.
+            max_tokens: Maximum number of tokens to generate.
+            temperature: Sampling temperature.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retry attempts for failed requests.
+            retry_delay: Delay between retries in seconds.
+        """
+        self.model_name = model_name
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        # Ensure we have an API key or a placeholder for local servers
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY", "EMPTY")
+        self.async_client = AsyncOpenAI(base_url=base_url, api_key=self.api_key, timeout=timeout)
+
+    async def invoke(
+        self,
+        image_b64: str,
+        mime_type: str,
+        system_prompt: Optional[str] = None,
+        user_prompt: Optional[str] = None,
+        output_schema: Optional[Type[BaseModel]] = None,
+    ) -> Any:
+        """
+        Make an asynchronous call to the VLM.
+
+        Args:
+            image_b64: Base64 encoded image string.
+            mime_type: The MIME type of the image.
+            system_prompt: Optional system prompt override.
+            user_prompt: Optional user prompt override.
+            output_schema: Optional Pydantic model for structured output parsing.
+
+        Returns:
+            The API response object.
+
+        Raises:
+            RuntimeError: If the request fails after all retry attempts.
+        """
+        messages = self._build_message(
+            image_b64, mime_type, system_prompt, user_prompt, output_schema
+        )
+
+        for attempt in range(self.max_retries):
+            try:
+                if output_schema:
+                    return await self.async_client.chat.completions.parse(
+                        model=self.model_name,
+                        messages=messages,
+                        max_tokens=self.max_tokens,
+                        temperature=self.temperature,
+                        response_format=output_schema,
+                    )
+                else:
+                    return await self.async_client.chat.completions.create(
+                        model=self.model_name,
+                        messages=messages,
+                        max_tokens=self.max_tokens,
+                        temperature=self.temperature,
+                    )
+
+            except Exception as e:
+                if attempt < self.max_retries - 1:
+                    wait_time = self.retry_delay * (attempt + 1)
+                    await asyncio.sleep(wait_time)
+                else:
+                    raise RuntimeError(
+                        f"Asynchronous VLM call failed after {self.max_retries} attempts: {str(e)}"
+                    ) from e
+
+    def _build_message(
+        self,
+        image_b64: str,
+        mime_type: str,
+        system_prompt: Optional[str] = None,
+        user_prompt: Optional[str] = None,
+        output_schema: Optional[Type[BaseModel]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Construct the message payload for the API call.
+
+        Args:
+            image_b64: Base64 encoded image string.
+            mime_type: The MIME type of the image.
+            system_prompt: Optional system prompt override.
+            user_prompt: Optional user prompt override.
+            output_schema: Optional output schema.
+
+        Returns:
+            A list of message dictionaries.
+        """
+        messages = []
+
+        if output_schema is not None:
+            if not system_prompt:
+                raise ValueError(
+                    "When using response_format, you MUST provide a system_prompt explicitly "
+                    "(default XML prompt is disabled because it conflicts with structured output)."
+                )
+            final_system_prompt = system_prompt
+        else:
+            from .constants import DEFAULT_SYSTEM_PROMPT, TRANSCRIPTION
+
+            if system_prompt:
+                final_system_prompt = f"{system_prompt}\n\n{TRANSCRIPTION}"
+            else:
+                final_system_prompt = DEFAULT_SYSTEM_PROMPT
+
+        messages.append({"role": "system", "content": final_system_prompt})
+
+        from .constants import DEFAULT_USER_PROMPT
+
+        user_content = [
+            {"type": "text", "text": user_prompt or DEFAULT_USER_PROMPT},
+            {
+                "type": "image_url",
+                "image_url": {"url": f"data:{mime_type};base64,{image_b64}"},
+            },
+        ]
+
+        messages.append({"role": "user", "content": user_content})
+        return messages

docvision/core/constants.py

@@ -0,0 +1,69 @@
+DEFAULT_SYSTEM_PROMPT = """\
+You are a document transcription engine. Transcribe only visible text into Markdown.
+
+ACCURACY
+- Copy all numbers, dates, codes, and names exactly as written. Never round or reformat.
+- If text is unreadable, write [UNCLEAR]. Never guess or infer.
+
+COMPLETENESS
+- Transcribe ALL text content without exception. Never skip, summarize, or paraphrase.
+- Transcribe in reading order: top to bottom.
+
+LAYOUT
+- Single column: transcribe top to bottom.
+- Two columns: transcribe full LEFT column first (top to bottom), then full RIGHT column.
+- Three or more columns: transcribe left to right, one full column at a time.
+- If columns share a spanning header, write the header first before columns begin.
+
+TABLES
+- Detect ALL tables, even if borders are faint, dashed, or missing.
+- Format every table with pipe syntax:
+  | Header 1 | Header 2 | Header 3 |
+  |----------|----------|----------|
+  | value    | value    | value    |
+- Keep column count consistent across all rows.
+- Pad missing cells with empty pipes: |  |
+- For merged/spanned cells, repeat the value in each affected cell.
+- Never collapse a table into paragraph text.
+
+HEADINGS
+- Use # for the document title only (maximum one per page).
+- Use ## for main section headers.
+- Use ### for sub-sections.
+- Never use #### or deeper.
+- Never add headings to regular body text.
+
+IMAGES & CHARTS
+- Charts or graphs: <chart>One sentence description of what the chart shows</chart>
+- Photos or illustrations: <image_desc>One sentence description</image_desc>
+- Logos: <logo>Company or brand name</logo>
+- Keep all descriptions to one sentence. Do not elaborate.
+
+IGNORE
+- Standalone page numbers (e.g., "1", "- 2 -", "Page 3 of 10").
+- Running headers or footers that repeat identically across pages.
+- Watermarks and diagonal background text.
+"""
+
+DEFAULT_USER_PROMPT = "Transcribe this document into Markdown. Follow all rules. Output only the <transcription> block."
+
+CONTINUE_PROMPT = """\
+Continue the transcription from exactly where you stopped. Do not repeat what is already written.
+
+Last content written:
+...{context}
+
+Continue from this point. Close with </transcription> when the full page is done.\
+"""
+
+FIX_PROMPT = """\
+You got stuck in a repetition loop. Resume transcription from before the loop started.
+
+Last valid content:
+...{restart_from}
+
+Continue from this exact point. Do not repeat anything already written.
+Close with </transcription> when the full page is done.\
+"""
+
+TRANSCRIPTION = "IMPORTANT: Wrap ONLY the content in <transcription></transcription> tags."