visual-parser 1.0.0__py3-none-any.whl

visual_parser/__init__.py

@@ -0,0 +1,20 @@
+"""
+visual_parser — Standalone Visual-RAG PDF Parser
+=================================================
+Detects new PDFs in a user-supplied directory, extracts text (via Nougat or
+lightweight PyMuPDF/PyPDFLoader), describes every figure/chart/schematic using
+a Vision LLM (OpenAI GPT-4o or Google Gemini), and writes three JSONL knowledge
+bases ready for any downstream RAG system:
+
+    01_chunks_kb.jsonl   – text chunks with stable IDs
+    02_visuals_kb.jsonl  – per-figure visual descriptions
+    03_metadata_kb.jsonl – document-level metadata (title, authors, DOI …)
+
+No chatbot, no vector store, no retrieval – just a robust parser.
+"""
+
+from visual_parser.config import ParserConfig
+from visual_parser.pipeline import run_pipeline
+
+__all__ = ["ParserConfig", "run_pipeline"]
+__version__ = "1.0.0"

visual_parser/__main__.py

@@ -0,0 +1,8 @@
+"""
+Enables:  python -m visual_parser --input-dir ./my_pdfs ...
+"""
+import sys
+from visual_parser.cli_main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

visual_parser/cli.py

@@ -0,0 +1,230 @@
+"""
+cli.py — Argument parser and main() entry point for the Visual-RAG PDF Parser.
+
+This module is the canonical home for CLI logic.  It is imported by:
+    • visual-parser.py          (top-level convenience script)
+    • visual_parser/__main__.py (enables: python -m visual_parser ...)
+    • pyproject.toml [project.scripts] (enables: visual-parser ...)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+USAGE_EXAMPLES = """
+Examples
+--------
+# Nougat (default) + GPT-5.5 vision
+python visual-parser.py --input-dir ./my_pdfs
+
+# Fast lightweight extraction + Gemini
+python visual-parser.py --input-dir ./my_pdfs \\
+    --text-mode lightweight \\
+    --vision-provider gemini \\
+    --vision-model gemini-1.5-pro
+
+# Write outputs to a separate directory
+python visual-parser.py --input-dir ./my_pdfs --output-dir ./output_kb
+
+# Force re-parse all PDFs (ignore tracking registry)
+python visual-parser.py --input-dir ./my_pdfs --rebuild
+
+# High-detail images for dense schematics
+python visual-parser.py --input-dir ./my_pdfs --vision-detail high
+
+# Verbose console logging
+python visual-parser.py --input-dir ./my_pdfs --log-level INFO
+"""
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="visual-parser",
+        description=(
+            "Visual-RAG PDF Parser — detects new PDFs, extracts text and "
+            "figure descriptions, and writes three JSONL knowledge bases:\n"
+            "  01_chunks_kb.jsonl   text chunks\n"
+            "  02_visuals_kb.jsonl  visual descriptions\n"
+            "  03_metadata_kb.jsonl document metadata"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=USAGE_EXAMPLES,
+    )
+
+    # ---- Paths --------------------------------------------------------------
+    io_group = p.add_argument_group("Paths")
+    io_group.add_argument(
+        "--input-dir", "-i",
+        required=True,
+        metavar="DIR",
+        help="Directory to scan for PDF files (searched recursively).",
+    )
+    io_group.add_argument(
+        "--output-dir", "-o",
+        default="",
+        metavar="DIR",
+        help="Directory where JSONL files are written. Defaults to --input-dir.",
+    )
+
+    # ---- Text extraction ----------------------------------------------------
+    text_group = p.add_argument_group("Text extraction")
+    text_group.add_argument(
+        "--text-mode",
+        choices=["nougat", "lightweight"],
+        default="nougat",
+        help=(
+            "nougat      — Nougat OCR model (best for scanned/complex PDFs, GPU recommended).\n"
+            "lightweight — PyMuPDF text layer + PyPDFLoader fallback (fast, no GPU needed)."
+        ),
+    )
+    text_group.add_argument(
+        "--nougat-model",
+        default="facebook/nougat-small",
+        metavar="MODEL_ID",
+        help="HuggingFace model ID for Nougat (default: facebook/nougat-small).",
+    )
+    text_group.add_argument(
+        "--chunk-size",
+        type=int,
+        default=500,
+        metavar="N",
+        help="Target characters per text chunk (default: 500).",
+    )
+    text_group.add_argument(
+        "--chunk-overlap",
+        type=int,
+        default=100,
+        metavar="N",
+        help="Overlap characters between adjacent chunks (default: 100).",
+    )
+
+    # ---- Vision LLM ---------------------------------------------------------
+    vision_group = p.add_argument_group("Vision LLM (figure descriptions & metadata)")
+    vision_group.add_argument(
+        "--vision-provider",
+        choices=["gpt", "gemini"],
+        default="gpt",
+        help=(
+            "gpt    — OpenAI GPT-5.5  (set OPENAI_API_KEY in .env).\n"
+            "gemini — Google Gemini   (set GEMINI_API_KEY in .env)."
+        ),
+    )
+    vision_group.add_argument(
+        "--vision-model",
+        default=None,
+        metavar="MODEL_NAME",
+        help=(
+            "Vision model name. Omit to use the latest for each provider:\n"
+            "  gpt    → gpt-5.5            (also: gpt-5.4, gpt-5.3-chat-latest, gpt-5.2, gpt-5.1, gpt-5, gpt-4o, gpt-4.1)\n"
+            "  gemini → gemini-3-pro-preview (also: gemini-2.5-flash, gemini-1.5-pro)"
+        ),
+    )
+    vision_group.add_argument(
+        "--vision-detail",
+        choices=["low", "high", "auto"],
+        default="low",
+        help=(
+            "Image detail level (GPT only).\n"
+            "low  — faster/cheaper (default, recommended for most use cases).\n"
+            "high — better for dense schematics with small text."
+        ),
+    )
+    vision_group.add_argument(
+        "--reasoning-effort",
+        choices=["minimal", "none", "low", "medium", "high", "xhigh"],
+        default="medium",
+        help=(
+            "Reasoning effort for GPT-5.x models (ignored for Gemini and older GPT).\n"
+            "  minimal/none — minimum reasoning, depending on model.\n"
+            "  low          — light reasoning.\n"
+            "  medium       — balanced (default).\n"
+            "  high         — deeper reasoning, slower.\n"
+            "  xhigh        — maximum depth (gpt-5.2, gpt-5.4, and gpt-5.5)."
+        ),
+    )
+    vision_group.add_argument(
+        "--metadata-pages",
+        type=int,
+        default=2,
+        metavar="N",
+        help="Number of front pages sent to the vision LLM for metadata extraction (default: 2).",
+    )
+
+    # ---- Performance --------------------------------------------------------
+    perf_group = p.add_argument_group("Performance")
+    perf_group.add_argument(
+        "--max-workers",
+        type=int,
+        default=4,
+        metavar="N",
+        help="Thread-pool size for parallel PDF processing (default: 4).",
+    )
+
+    # ---- Misc ---------------------------------------------------------------
+    misc_group = p.add_argument_group("Miscellaneous")
+    misc_group.add_argument(
+        "--rebuild",
+        action="store_true",
+        help=(
+            "Reprocess ALL PDFs, ignoring the 04_processed_pdfs.txt registry. "
+            "Use after changing prompts, chunking strategy, or switching models."
+        ),
+    )
+    misc_group.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="ERROR",
+        help="Verbosity level written to 05_pipeline.log (default: ERROR).",
+    )
+
+    return p
+
+
+def main(argv=None) -> int:
+    """
+    Parse CLI arguments, build a :class:`~visual_parser.config.ParserConfig`,
+    validate it, and hand off to :func:`~visual_parser.pipeline.run_pipeline`.
+
+    Returns 0 on success, 1 on configuration error.
+    """
+    parser = _build_arg_parser()
+    args   = parser.parse_args(argv)
+
+    # Default vision model per provider when not explicitly set
+    if args.vision_model is None:
+        args.vision_model = (
+            "gpt-5.5" if args.vision_provider == "gpt" else "gemini-3-pro-preview"
+        )
+
+    from visual_parser.config import ParserConfig
+
+    config = ParserConfig(
+        input_dir             = os.path.abspath(args.input_dir),
+        output_dir            = os.path.abspath(args.output_dir) if args.output_dir else "",
+        text_mode             = args.text_mode,
+        nougat_model          = args.nougat_model,
+        chunk_size            = args.chunk_size,
+        chunk_overlap         = args.chunk_overlap,
+        vision_provider       = args.vision_provider,
+        gpt_vision_model      = args.vision_model if args.vision_provider == "gpt"    else "gpt-5.5",
+        gemini_vision_model   = args.vision_model if args.vision_provider == "gemini" else "gemini-3-pro-preview",
+        gpt_reasoning_effort  = args.reasoning_effort,
+        vision_detail         = args.vision_detail,
+        metadata_pages        = args.metadata_pages,
+        max_workers           = args.max_workers,
+        rebuild               = args.rebuild,
+        log_level             = args.log_level,
+    )
+
+    try:
+        config.validate()
+    except ValueError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+
+    from visual_parser.pipeline import run_pipeline
+    run_pipeline(config)
+    return 0

visual_parser/cli_main.py

@@ -0,0 +1,223 @@
+"""
+cli_main.py - ASCII-safe CLI entry point for the Visual-RAG PDF Parser.
+
+This module exists to keep Windows console help output stable for the
+installed ``visual-parser`` command and ``python -m visual_parser``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+USAGE_EXAMPLES = """
+Examples
+--------
+# Nougat (default) + GPT-5.5 vision
+python visual-parser.py --input-dir ./my_pdfs
+
+# Fast lightweight extraction + Gemini
+python visual-parser.py --input-dir ./my_pdfs \\
+    --text-mode lightweight \\
+    --vision-provider gemini \\
+    --vision-model gemini-1.5-pro
+
+# Write outputs to a separate directory
+python visual-parser.py --input-dir ./my_pdfs --output-dir ./output_kb
+
+# Force re-parse all PDFs (ignore tracking registry)
+python visual-parser.py --input-dir ./my_pdfs --rebuild
+
+# High-detail images for dense schematics
+python visual-parser.py --input-dir ./my_pdfs --vision-detail high
+
+# Verbose console logging
+python visual-parser.py --input-dir ./my_pdfs --log-level INFO
+"""
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="visual-parser",
+        description=(
+            "Visual-RAG PDF Parser - detects new PDFs, extracts text and "
+            "figure descriptions, and writes three JSONL knowledge bases:\n"
+            "  01_chunks_kb.jsonl   text chunks\n"
+            "  02_visuals_kb.jsonl  visual descriptions\n"
+            "  03_metadata_kb.jsonl document metadata"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=USAGE_EXAMPLES,
+    )
+
+    io_group = parser.add_argument_group("Paths")
+    io_group.add_argument(
+        "--input-dir",
+        "-i",
+        required=True,
+        metavar="DIR",
+        help="Directory to scan for PDF files (searched recursively).",
+    )
+    io_group.add_argument(
+        "--output-dir",
+        "-o",
+        default="",
+        metavar="DIR",
+        help="Directory where JSONL files are written. Defaults to --input-dir.",
+    )
+
+    text_group = parser.add_argument_group("Text extraction")
+    text_group.add_argument(
+        "--text-mode",
+        choices=["nougat", "lightweight"],
+        default="nougat",
+        help=(
+            "nougat      - Nougat OCR model (best for scanned/complex PDFs, GPU recommended).\n"
+            "lightweight - PyMuPDF text layer + PyPDFLoader fallback (fast, no GPU needed)."
+        ),
+    )
+    text_group.add_argument(
+        "--nougat-model",
+        default="facebook/nougat-small",
+        metavar="MODEL_ID",
+        help="HuggingFace model ID for Nougat (default: facebook/nougat-small).",
+    )
+    text_group.add_argument(
+        "--chunk-size",
+        type=int,
+        default=500,
+        metavar="N",
+        help="Target characters per text chunk (default: 500).",
+    )
+    text_group.add_argument(
+        "--chunk-overlap",
+        type=int,
+        default=100,
+        metavar="N",
+        help="Overlap characters between adjacent chunks (default: 100).",
+    )
+
+    vision_group = parser.add_argument_group("Vision LLM (figure descriptions & metadata)")
+    vision_group.add_argument(
+        "--vision-provider",
+        choices=["gpt", "gemini"],
+        default="gpt",
+        help=(
+            "gpt    - OpenAI GPT-5.4  (set OPENAI_API_KEY in .env).\n"
+            "gemini - Google Gemini   (set GEMINI_API_KEY in .env)."
+        ),
+    )
+    vision_group.add_argument(
+        "--vision-model",
+        default=None,
+        metavar="MODEL_NAME",
+        help=(
+            "Vision model name. Omit to use the latest for each provider:\n"
+            "  gpt    -> gpt-5.4            (also: gpt-5.5, gpt-5.3-chat-latest, gpt-5.2, gpt-5.1, gpt-5, gpt-4o, gpt-4.1)\n"
+            "  gemini -> gemini-3-pro-preview (also: gemini-2.5-flash, gemini-1.5-pro)"
+        ),
+    )
+    vision_group.add_argument(
+        "--vision-detail",
+        choices=["low", "high", "auto"],
+        default="low",
+        help=(
+            "Image detail level (GPT only).\n"
+            "low  - faster/cheaper (default, recommended for most use cases).\n"
+            "high - better for dense schematics with small text."
+        ),
+    )
+    vision_group.add_argument(
+        "--reasoning-effort",
+        choices=["minimal", "none", "low", "medium", "high", "xhigh"],
+        default="medium",
+        help=(
+            "Reasoning effort for GPT-5.x models (ignored for Gemini and older GPT).\n"
+            "  minimal/none - minimum reasoning, depending on model.\n"
+            "  low    - light reasoning.\n"
+            "  medium - balanced (default).\n"
+            "  high   - deeper reasoning, slower.\n"
+            "  xhigh  - maximum depth (gpt-5.2, gpt-5.4, and gpt-5.5)."
+        ),
+    )
+    vision_group.add_argument(
+        "--metadata-pages",
+        type=int,
+        default=2,
+        metavar="N",
+        help="Number of front pages sent to the vision LLM for metadata extraction (default: 2).",
+    )
+
+    perf_group = parser.add_argument_group("Performance")
+    perf_group.add_argument(
+        "--max-workers",
+        type=int,
+        default=4,
+        metavar="N",
+        help="Thread-pool size for parallel PDF processing (default: 4).",
+    )
+
+    misc_group = parser.add_argument_group("Miscellaneous")
+    misc_group.add_argument(
+        "--rebuild",
+        action="store_true",
+        help=(
+            "Reprocess ALL PDFs, ignoring the 04_processed_pdfs.txt registry. "
+            "Use after changing prompts, chunking strategy, or switching models."
+        ),
+    )
+    misc_group.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="ERROR",
+        help="Verbosity level written to 05_pipeline.log (default: ERROR).",
+    )
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    if args.vision_model is None:
+        args.vision_model = (
+            "gpt-5.4" if args.vision_provider == "gpt" else "gemini-3-pro-preview"
+        )
+
+    from visual_parser.config import ParserConfig
+
+    config = ParserConfig(
+        input_dir=os.path.abspath(args.input_dir),
+        output_dir=os.path.abspath(args.output_dir) if args.output_dir else "",
+        text_mode=args.text_mode,
+        nougat_model=args.nougat_model,
+        chunk_size=args.chunk_size,
+        chunk_overlap=args.chunk_overlap,
+        vision_provider=args.vision_provider,
+        gpt_vision_model=args.vision_model if args.vision_provider == "gpt" else "gpt-5.4",
+        gemini_vision_model=(
+            args.vision_model if args.vision_provider == "gemini" else "gemini-3-pro-preview"
+        ),
+        gpt_reasoning_effort=args.reasoning_effort,
+        vision_detail=args.vision_detail,
+        metadata_pages=args.metadata_pages,
+        max_workers=args.max_workers,
+        rebuild=args.rebuild,
+        log_level=args.log_level,
+    )
+
+    try:
+        config.validate()
+    except ValueError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+
+    from visual_parser.pipeline import run_pipeline
+
+    summary = run_pipeline(config)
+    if summary.get("failed_basenames"):
+        return 2
+    return 0

visual_parser/config.py

@@ -0,0 +1,168 @@
+"""
+config.py — Central configuration for visual_parser.
+
+All settings are read from environment variables (populated from a .env file
+at project root via python-dotenv).  Every field has a sensible default so
+the tool works out-of-the-box; the user only *needs* to supply an API key for
+the chosen vision model.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Optional
+
+from dotenv import load_dotenv
+
+# Load .env: order = global < CWD < explicit (later overrides earlier)
+def _load_env():
+    # 1) Global: one .env for all runs (any --input-dir).
+    # Prefer the current product name, but keep the legacy directory for compatibility.
+    global_env_candidates = [
+        Path.home() / ".config" / "visual-parser" / ".env",
+        Path.home() / ".config" / "visual-rag" / ".env",
+    ]
+    for global_env in global_env_candidates:
+        if global_env.is_file():
+            load_dotenv(global_env)
+    # 2) Current working directory
+    load_dotenv()
+    # 3) Explicit path (Docker /env/.env or VISUAL_PARSER_ENV_FILE)
+    env_file = os.environ.get("VISUAL_PARSER_ENV_FILE")
+    if env_file and os.path.isfile(env_file):
+        load_dotenv(env_file)
+_load_env()
+
+
+# ---------------------------------------------------------------------------
+# Text-extraction modes
+# ---------------------------------------------------------------------------
+TextMode = Literal["nougat", "lightweight"]
+"""
+nougat      – Facebook Nougat transformer model (best for scanned / complex PDFs)
+lightweight – PyMuPDF text layer + PyPDFLoader fallback (fast, digital PDFs)
+"""
+
+# ---------------------------------------------------------------------------
+# Vision-LLM providers
+# ---------------------------------------------------------------------------
+VisionProvider = Literal["gpt", "gemini"]
+
+
+@dataclass
+class ParserConfig:
+    """
+    Single source of truth for every knob in the pipeline.
+
+    Instantiate directly or call :func:`ParserConfig.from_env` to read from
+    environment variables / a .env file.
+    """
+
+    # --- Paths ---------------------------------------------------------------
+    input_dir: str = ""
+    """Directory that will be scanned recursively for PDF files."""
+
+    output_dir: str = ""
+    """
+    Directory where JSONL knowledge bases are written.
+    Defaults to *input_dir* when left empty.
+    """
+
+    # --- Text extraction -----------------------------------------------------
+    text_mode: TextMode = "nougat"
+    """Which text-extraction engine to use ('nougat' or 'lightweight')."""
+
+    nougat_model: str = "facebook/nougat-small"
+    """HuggingFace model identifier for Nougat."""
+
+    chunk_size: int = 500
+    """Target character count per text chunk."""
+
+    chunk_overlap: int = 100
+    """Character overlap between adjacent chunks."""
+
+    # --- Vision LLM ----------------------------------------------------------
+    vision_provider: VisionProvider = "gpt"
+    """Which vision LLM to use for figure descriptions and metadata ('gpt' or 'gemini')."""
+
+    # OpenAI
+    openai_api_key: str = field(default_factory=lambda: os.getenv("OPENAI_API_KEY", ""))
+    gpt_vision_model: str = "gpt-5.4"
+    """Default GPT vision model. Also accepts: gpt-5.5, gpt-5.3-chat-latest, gpt-5.2, gpt-5.1, gpt-5, gpt-4o, gpt-4.1"""
+
+    # GPT-5.x reasoning effort: none | low | medium | high | xhigh
+    # Older gpt-5 uses minimal | low | medium | high.
+    gpt_reasoning_effort: str = "medium"
+
+    # Google Gemini
+    gemini_api_key: str = field(default_factory=lambda: os.getenv("GEMINI_API_KEY", ""))
+    gemini_vision_model: str = "gemini-3-pro-preview"
+    """Latest Gemini vision model.  Also accepts: gemini-2.5-flash, gemini-1.5-pro"""
+
+    # --- Vision detail -------------------------------------------------------
+    vision_detail: Literal["low", "high", "auto"] = "low"
+    """
+    Image detail level sent to the vision API.
+    'low'  → faster & cheaper (recommended for figure detection at scale).
+    'high' → higher fidelity (use for small-text schematics).
+    """
+
+    # --- Metadata extraction -------------------------------------------------
+    metadata_pages: int = 2
+    """Number of front pages to send to the vision LLM for metadata extraction."""
+
+    # --- Parallelism ---------------------------------------------------------
+    max_workers: int = 4
+    """Thread-pool size for parallel PDF processing."""
+
+    # --- Misc ----------------------------------------------------------------
+    rebuild: bool = False
+    """If True, reprocess all PDFs even if already recorded in 04_processed_pdfs.txt."""
+
+    log_level: str = "ERROR"
+
+    # -------------------------------------------------------------------------
+
+    @classmethod
+    def from_env(cls) -> "ParserConfig":
+        """Construct a ParserConfig reading every setting from environment variables."""
+        return cls(
+            input_dir            = os.getenv("VISUAL_PARSER_INPUT_DIR", ""),
+            output_dir           = os.getenv("VISUAL_PARSER_OUTPUT_DIR", ""),
+            text_mode            = os.getenv("VISUAL_PARSER_TEXT_MODE", "nougat"),           # type: ignore[arg-type]
+            nougat_model         = os.getenv("VISUAL_PARSER_NOUGAT_MODEL", "facebook/nougat-small"),
+            chunk_size           = int(os.getenv("VISUAL_PARSER_CHUNK_SIZE", "500")),
+            chunk_overlap        = int(os.getenv("VISUAL_PARSER_CHUNK_OVERLAP", "100")),
+            vision_provider      = os.getenv("VISUAL_PARSER_VISION_PROVIDER", "gpt"),        # type: ignore[arg-type]
+            openai_api_key       = os.getenv("OPENAI_API_KEY", ""),
+            gpt_vision_model     = os.getenv("VISUAL_PARSER_GPT_VISION_MODEL", "gpt-5.4"),
+            gpt_reasoning_effort = os.getenv("VISUAL_PARSER_GPT_REASONING_EFFORT", "medium"),
+            gemini_api_key       = os.getenv("GEMINI_API_KEY", ""),
+            gemini_vision_model  = os.getenv("VISUAL_PARSER_GEMINI_VISION_MODEL", "gemini-3-pro-preview"),
+            vision_detail        = os.getenv("VISUAL_PARSER_VISION_DETAIL", "low"),          # type: ignore[arg-type]
+            metadata_pages       = int(os.getenv("VISUAL_PARSER_METADATA_PAGES", "2")),
+            max_workers          = int(os.getenv("VISUAL_PARSER_MAX_WORKERS", "4")),
+            rebuild              = os.getenv("VISUAL_PARSER_REBUILD", "false").lower() == "true",
+            log_level            = os.getenv("VISUAL_PARSER_LOG_LEVEL", "ERROR"),
+        )
+
+    def effective_output_dir(self) -> str:
+        """Return output_dir, falling back to input_dir when not set."""
+        return self.output_dir if self.output_dir else self.input_dir
+
+    def validate(self) -> None:
+        """Raise ValueError for obviously bad configurations."""
+        if not self.input_dir:
+            raise ValueError("input_dir must be set.")
+        if not Path(self.input_dir).is_dir():
+            raise ValueError(f"input_dir does not exist: {self.input_dir!r}")
+        if self.text_mode not in ("nougat", "lightweight"):
+            raise ValueError(f"text_mode must be 'nougat' or 'lightweight', got {self.text_mode!r}")
+        if self.vision_provider not in ("gpt", "gemini"):
+            raise ValueError(f"vision_provider must be 'gpt' or 'gemini', got {self.vision_provider!r}")
+        if self.vision_provider == "gpt" and not self.openai_api_key:
+            raise ValueError("OPENAI_API_KEY must be set when vision_provider='gpt'.")
+        if self.vision_provider == "gemini" and not self.gemini_api_key:
+            raise ValueError("GEMINI_API_KEY must be set when vision_provider='gemini'.")