pdf-to-markdown-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{pdf_to_markdown_cli-0.2.1 → pdf_to_markdown_cli-0.4.0}/MANIFEST.in

@@ -2,8 +2,8 @@
 include README.md
 include LICENSE
 
-# Include the package source directory
-recursive-include docs_to_md *
+# Include the package source directory (now within src/)
+recursive-include src/docs_to_md *
 
 # Exclude development/cache/temporary files and directories
 global-exclude *.py[cod]

{pdf_to_markdown_cli-0.2.1/pdf_to_markdown_cli.egg-info → pdf_to_markdown_cli-0.4.0}/PKG-INFO

@@ -1,9 +1,31 @@
 Metadata-Version: 2.4
 Name: pdf-to-markdown-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: CLI tool to convert PDF files (and other documents) to markdown using the Marker API.
-Home-page: https://github.com/SokolskyNikita/pdf-to-markdown-cli
 Author: Nikita Sokolsky
+License: MIT License
+        
+        Copyright (c) 2025 SokolskyNikita
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/SokolskyNikita/pdf-to-markdown-cli
 Project-URL: Bug Tracker, https://github.com/SokolskyNikita/pdf-to-markdown-cli/issues
 Keywords: pdf,markdown,converter,cli,document,marker,md
 Classifier: Development Status :: 4 - Beta
@@ -28,17 +50,7 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: ratelimit>=2.0
 Requires-Dist: requests>=2.0
 Requires-Dist: tqdm>=4.0
-Dynamic: author
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
 Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # PDF to Markdown CLI (via the Datalab Marker API)
 
@@ -108,11 +120,19 @@ pdf-to-md /path/to/file.pdf --max
 - `--force`: Force OCR on all pages
 - `--pages`: Add page delimiters
 - `--max`: Enable all OCR enhancements (equivalent to --llm --strip --force)
-- `--max-pages`: Maximum number of pages to process from the start of the file
+- `-mp`, `--max-pages`: Maximum number of pages to process from the start of the file
 - `--no-chunk`: Disable PDF chunking
-- `--chunk-size`: Set PDF chunk size in pages (default: 25)
-- `--output-dir`: Output directory (default: "converted")
-- `--cache-dir`: Cache directory (default: ".marker_cache")
+- `-cs`, `--chunk-size`: Set PDF chunk size in pages (default: 25)
+- `-o`, `--output-dir`: Absolute path to the output directory. If not provided, output files will be saved in the same directory as their corresponding input files.
+- `-v`, `--verbose`: Enable verbose (DEBUG level) logging
+
+### Output Structure
+
+By default, output files are saved in the same directory as the input file with the format `[input-filename].[format]`. For example, converting `/data/report.pdf` to markdown will result in `/data/report.md`.
+
+If an output file with the same name already exists, the new file will be automatically renamed using a numeric suffix (e.g., `[input-filename]_1.[format]`, `[input-filename]_2.[format]`, etc.) to avoid overwriting.
+
+If you specify `--output-dir /path/to/output`, the output file will be placed in that directory (e.g., `/path/to/output/report.md`). The same automatic renaming logic applies if a file with the same name exists in the target directory.
 
 ### API
 
@@ -176,3 +196,7 @@ For regular use after installation, use the `pdf-to-md` command.
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Future Considerations
+
+While this project currently uses a modern structure (`pyproject.toml`, `src` layout), future development might involve migrating to a standardized project template, such as [simonw/python-lib](https://github.com/simonw/python-lib), to further align with community best practices and potentially simplify workflows like automated PyPI publishing via Trusted Publishers.

{pdf_to_markdown_cli-0.2.1 → pdf_to_markdown_cli-0.4.0}/README.md

@@ -66,11 +66,19 @@ pdf-to-md /path/to/file.pdf --max
 - `--force`: Force OCR on all pages
 - `--pages`: Add page delimiters
 - `--max`: Enable all OCR enhancements (equivalent to --llm --strip --force)
-- `--max-pages`: Maximum number of pages to process from the start of the file
+- `-mp`, `--max-pages`: Maximum number of pages to process from the start of the file
 - `--no-chunk`: Disable PDF chunking
-- `--chunk-size`: Set PDF chunk size in pages (default: 25)
-- `--output-dir`: Output directory (default: "converted")
-- `--cache-dir`: Cache directory (default: ".marker_cache")
+- `-cs`, `--chunk-size`: Set PDF chunk size in pages (default: 25)
+- `-o`, `--output-dir`: Absolute path to the output directory. If not provided, output files will be saved in the same directory as their corresponding input files.
+- `-v`, `--verbose`: Enable verbose (DEBUG level) logging
+
+### Output Structure
+
+By default, output files are saved in the same directory as the input file with the format `[input-filename].[format]`. For example, converting `/data/report.pdf` to markdown will result in `/data/report.md`.
+
+If an output file with the same name already exists, the new file will be automatically renamed using a numeric suffix (e.g., `[input-filename]_1.[format]`, `[input-filename]_2.[format]`, etc.) to avoid overwriting.
+
+If you specify `--output-dir /path/to/output`, the output file will be placed in that directory (e.g., `/path/to/output/report.md`). The same automatic renaming logic applies if a file with the same name exists in the target directory.
 
 ### API
 
@@ -133,4 +141,8 @@ For regular use after installation, use the `pdf-to-md` command.
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Future Considerations
+
+While this project currently uses a modern structure (`pyproject.toml`, `src` layout), future development might involve migrating to a standardized project template, such as [simonw/python-lib](https://github.com/simonw/python-lib), to further align with community best practices and potentially simplify workflows like automated PyPI publishing via Trusted Publishers.

pdf_to_markdown_cli-0.4.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdf-to-markdown-cli"
+version = "0.4.0"
+description = "CLI tool to convert PDF files (and other documents) to markdown using the Marker API."
+readme = "README.md"
+authors = [
+    { name = "Nikita Sokolsky" },
+]
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing",
+    "Topic :: Utilities",
+]
+keywords = ["pdf", "markdown", "converter", "cli", "document", "marker", "md"]
+dependencies = [
+    "backoff>=2.0",
+    "diskcache>=5.0",
+    "filetype>=1.0",
+    "pikepdf>=8.0",
+    "pydantic>=2.0",
+    "ratelimit>=2.0",
+    "requests>=2.0",
+    "tqdm>=4.0",
+]
+
+# Define project URLs
+[project.urls]
+"Homepage" = "https://github.com/SokolskyNikita/pdf-to-markdown-cli"
+"Bug Tracker" = "https://github.com/SokolskyNikita/pdf-to-markdown-cli/issues"
+
+# Define console script entry point
+[project.scripts]
+pdf-to-md = "docs_to_md.main:main"
+
+# Just in case: Configure setuptools to find packages in src/
+[tool.setuptools.packages.find]
+where = ["src"]

pdf_to_markdown_cli-0.4.0/src/docs_to_md/api/client.py

@@ -0,0 +1,183 @@
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+import backoff
+import filetype
+import requests
+from ratelimit import limits, sleep_and_retry
+
+from docs_to_md.api.models import (
+    MarkerStatus,
+    StatusEnum,
+    SubmitResponse,
+    SUPPORTED_MIME_TYPES,
+)
+from docs_to_md.utils.exceptions import APIError
+from docs_to_md.utils.file_utils import FileIO
+
+# Client-side constants
+MAX_REQUESTS_PER_MINUTE = 150
+REQUEST_TIMEOUT_SECONDS = 30
+MAX_RETRIES = 3
+
+logger = logging.getLogger(__name__)
+
+
+class MarkerClient:
+    BASE_MARKER_API_ENDPOINT = "https://www.datalab.to/api/v1/marker"
+
+    # See datalab_marker_api_docs.md#authentication for API key details
+    def __init__(self, api_key: str):
+        if not api_key or not api_key.strip():
+            raise APIError("API key is required")
+
+        self.headers = {"X-Api-Key": api_key.strip()}
+
+    @sleep_and_retry
+    @limits(calls=MAX_REQUESTS_PER_MINUTE, period=60)
+    @backoff.on_exception(
+        backoff.expo,
+        (requests.exceptions.RequestException, json.JSONDecodeError),
+        max_tries=MAX_RETRIES,
+    )
+    def submit_file(
+        self,
+        file_path: Path,
+        output_format: str = "markdown",
+        langs: str = "English",
+        use_llm: bool = False,
+        strip_existing_ocr: bool = False,
+        disable_image_extraction: bool = False,
+        force_ocr: bool = False,
+        paginate: bool = False,
+        max_pages: Optional[int] = None,
+    ) -> Optional[str]:
+        """Submit a file for conversion via the Marker API.
+        See datalab_marker_api_docs.md#marker for API parameter details.
+        """
+        try:
+            if not file_path.exists():
+                raise APIError(f"File not found: {file_path}")
+
+            file_data = FileIO.read_file(file_path)
+            kind = filetype.guess(file_data)
+
+            # Supported types listed in datalab_marker_api_docs.md#supported-file-types
+            if not kind or kind.mime not in SUPPORTED_MIME_TYPES:
+                raise APIError(
+                    f"Unsupported file type: {kind.mime if kind else 'unknown'}"
+                )
+
+            form_data = {
+                "file": (file_path.name, file_data, kind.mime),
+                "langs": (None, langs),
+                "force_ocr": (None, force_ocr),
+                "paginate": (None, paginate),
+                "strip_existing_ocr": (None, strip_existing_ocr),
+                "disable_image_extraction": (None, disable_image_extraction),
+                "use_llm": (None, use_llm),
+                "output_format": (None, output_format),
+                "max_pages": (None, max_pages),
+            }
+
+            response = requests.post(
+                self.BASE_MARKER_API_ENDPOINT,
+                files=form_data,
+                headers=self.headers,
+                timeout=REQUEST_TIMEOUT_SECONDS,
+            )
+            response.raise_for_status()  # Default handling for HTTP errors,
+            submit_response = SubmitResponse.model_validate(response.json())
+
+            if not submit_response.success:
+                logger.error(
+                    f"API request failed: {submit_response.error or 'Unknown error'}"
+                )
+                return None
+
+            logger.info(
+                f"Successfully submitted file {file_path.name}. Request ID: {submit_response.request_id}"
+            )
+            return submit_response.request_id
+
+        except Exception as e:
+            logger.error(f"Error submitting file {file_path}: {e}")
+            return None
+
+    def _handle_status_error(
+        self, status_code: int, request_id: str
+    ) -> Optional[MarkerStatus]:
+        """Handle non-200 status codes from the check_status endpoint."""
+        logger.error(f"API returned status code {status_code} for request {request_id}")
+        # Specific handling for non-fatal polling errors
+        if status_code == 404:
+            # Treat not found as still processing, might appear later
+            return MarkerStatus(status=StatusEnum.PROCESSING, error="Request not found")
+        elif status_code == 401:
+            return MarkerStatus(status=StatusEnum.FAILED, error="Authentication failed")
+        elif status_code == 429:
+            # Treat rate limit as still processing, should retry later
+            return MarkerStatus(
+                status=StatusEnum.PROCESSING, error="Rate limit exceeded"
+            )
+        # For other non-200 errors, return None to indicate failure to get status
+        return None
+
+    @sleep_and_retry
+    @limits(calls=MAX_REQUESTS_PER_MINUTE, period=60)
+    @backoff.on_exception(
+        backoff.expo,
+        (requests.exceptions.RequestException, json.JSONDecodeError),
+        max_tries=MAX_RETRIES,
+    )
+    def check_status(self, request_id: str) -> Optional[MarkerStatus]:
+        """
+        Check the status of a conversion request.
+        See datalab_marker_api_docs.md#marker for polling details.
+
+        Returns:
+            MarkerStatus object with current status, or None if the check fails.
+        """
+        if not request_id:
+            logger.error("Empty Marker request ID provided, skipping status check")
+            return None
+
+        try:
+            response = requests.get(
+                f"{self.BASE_MARKER_API_ENDPOINT}/{request_id}",
+                headers=self.headers,
+                timeout=REQUEST_TIMEOUT_SECONDS,
+            )
+
+            if response.status_code != 200:
+                return self._handle_status_error(response.status_code, request_id)
+
+            data = response.json()
+            # Handle potential empty response from API
+            if not data:
+                logger.error(f"Empty response for request {request_id}")
+                return None
+
+            status = MarkerStatus.model_validate(data)
+            return status
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON response for request {request_id}: {e}")
+            return None
+        except (
+            requests.exceptions.RequestException
+        ) as e:  # Consolidated network/request errors
+            logger.error(f"Request error checking status for {request_id}: {e}")
+            return None
+        except Exception as e:  # Catch-all for validation or other unexpected errors
+            logger.error(f"Unexpected error checking status for {request_id}: {e}")
+            return None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # No specific cleanup needed for this client
+        pass

{pdf_to_markdown_cli-0.2.1 → pdf_to_markdown_cli-0.4.0/src}/docs_to_md/api/models.py

@@ -44,9 +44,37 @@ class ApiParams:
     force_ocr: bool = False
     paginate: bool = False
     max_pages: Optional[int] = None
+    
+# Map of supported output formats to their extensions
+SUPPORTED_FORMAT_EXTENSIONS = {
+    "markdown": ".md",
+    "json": ".json",
+    "html": ".html",
+    "txt": ".txt"
+}
 
+SUPPORTED_IMAGE_EXTENSIONS: Set[str] = {
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "tiff"
+}
 
-# Supported mime types according to API docs
+SUPPORTED_INPUT_EXTENSIONS: Set[str] = {
+    "pdf",
+    "docx",
+    "doc",
+    "pptx",
+    "ppt",
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "tiff"
+}
+
+# Supported mime types according to datalab_marker_api_docs.md#supported-file-types
 SUPPORTED_MIME_TYPES: Set[str] = {
     # PDF
     'application/pdf',

{pdf_to_markdown_cli-0.2.1 → pdf_to_markdown_cli-0.4.0/src}/docs_to_md/config/cli.py

@@ -1,61 +1,57 @@
 import argparse
-from pathlib import Path
+from pathlib import Path    
+import os
+from typing import Optional
+import importlib.metadata
 
 from docs_to_md.config.settings import Config
-from docs_to_md.utils.exceptions import ConfigurationError
-from docs_to_md.utils.file_utils import get_env_var
+from docs_to_md.utils.exceptions import ConfigurationError, FileError
 
 
 def parse_args() -> argparse.Namespace:
-    """
-    Parse command line arguments.
-    
-    Returns:
-        Parsed arguments namespace
-    """
+    # Get package version dynamically
+    try:
+        __version__ = importlib.metadata.version('pdf-to-markdown-cli')
+    except importlib.metadata.PackageNotFoundError:
+        __version__ = 'unknown' # Fallback if package not installed
+        
     parser = argparse.ArgumentParser(
         description="Process PDF files using Marker API.",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter
     )
     
-    # Required arguments
+    # Add version argument
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'pdf-to-markdown-cli version: {__version__}'
+    )
+    
     parser.add_argument("input", help="Input file or directory path")
     
-    # Output format
     parser.add_argument("--json", action="store_true", help="Output in JSON format")
     
-    # OCR settings
-    parser.add_argument("--langs", default="English", help="Comma-separated OCR languages")
+    parser.add_argument("-l", "--langs", default="English", help="Comma-separated OCR languages")
     parser.add_argument("--llm", action="store_true", help="Use LLM for enhanced processing")
     parser.add_argument("--strip", action="store_true", help="Redo OCR processing")
     parser.add_argument("--noimg", action="store_true", help="Disable image extraction")
     parser.add_argument("--force", action="store_true", help="Force OCR on all pages")
     parser.add_argument("--pages", action="store_true", help="Add page delimiters")
-    parser.add_argument("--max-pages", type=int, help="Maximum number of pages to process from the start of the file")
+    parser.add_argument("-mp", "--max-pages", type=int, help="Maximum number of pages to process from the start of the file")
     
-    # Advanced settings
     parser.add_argument("--max", action="store_true", help="Enable all OCR enhancements (LLM, strip OCR, force OCR)")
     parser.add_argument("--no-chunk", action="store_true", help="Disable PDF chunking (sets chunk size to 1 million)")
     parser.add_argument("-cs", "--chunk-size", type=int, help="Set PDF chunk size in pages", default=25)
-    parser.add_argument("--output-dir", help="Output directory", default="converted")
-    parser.add_argument("--cache-dir", help="Cache directory", default=".docs_to_md_cache")
+    parser.add_argument("-o", "--output-dir", help="Absolute path to the output directory (default: same directory as input file)", default=None)
+
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose (DEBUG level) logging")
     
     return parser.parse_args()
 
 
 def create_config_from_args() -> Config:
-    """
-    Create configuration from command line arguments.
-    
-    Returns:
-        Config object with settings from command line
-        
-    Raises:
-        ConfigurationError: If required arguments are missing
-    """
     args = parse_args()
     
-    # Get API key from environment
     try:
         api_key = get_env_var("MARKER_PDF_KEY")
     except Exception as e:
@@ -67,8 +63,7 @@ def create_config_from_args() -> Config:
     config = Config(
         api_key=api_key,
         input_path=args.input,
-        output_dir=Path(args.output_dir),
-        cache_dir=Path(args.cache_dir),
+        output_dir=Path(args.output_dir) if args.output_dir else None,
         output_format="json" if args.json else "markdown",
         langs=args.langs,
         use_llm=args.llm or args.max,
@@ -80,7 +75,13 @@ def create_config_from_args() -> Config:
         max_pages=args.max_pages
     )
     
-    # Validate the configuration
     config.validate()
     
-    return config 
+    return config 
+
+def get_env_var(name: str, required: bool = True) -> Optional[str]:
+    """Get environment variable with optional requirement."""
+    value = os.getenv(name)
+    if required and not value:
+        raise FileError(f"Required environment variable {name} is not set")
+    return value

pdf_to_markdown_cli-0.4.0/src/docs_to_md/config/settings.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+import logging
+
+from docs_to_md.api.models import SUPPORTED_FORMAT_EXTENSIONS
+from docs_to_md.utils.exceptions import ConfigurationError
+
+logger = logging.getLogger(__name__)
+SETTINGS_DIR_NAME = ".docs_to_md"
+
+
+@dataclass
+class Config:
+    """Global configuration for marker PDF conversion."""
+    api_key: str
+    
+    input_path: str
+    output_dir: Optional[Path] = None
+    cache_dir: Path = Path.home() / SETTINGS_DIR_NAME / "cache" # Root directory for cache files
+    root_tmp_dir: Path = Path.home() / SETTINGS_DIR_NAME / "tmp" # Root directory for temporary files
+    
+    output_format: str = "markdown"
+    langs: str = "English"
+    chunk_size: int = 25
+    
+    use_llm: bool = False
+    strip_existing_ocr: bool = False
+    disable_image_extraction: bool = False
+    force_ocr: bool = False
+    paginate: bool = False
+    max_pages: Optional[int] = None
+            
+    def validate(self) -> None:
+        if not self.api_key:
+            raise ConfigurationError("API key is required")
+                    
+        if not self.input_path:
+            raise ConfigurationError("Input path is required")
+            
+        if not Path(self.input_path).exists():
+            raise ConfigurationError(f"Input path does not exist: {self.input_path}")
+        
+        if self.chunk_size < 1:
+            raise ConfigurationError("Chunk size must be at least 1")
+            
+        if self.max_pages is not None and self.max_pages < 1:
+            raise ConfigurationError("Max pages must be at least 1")
+            
+        if not self.output_format or self.output_format not in SUPPORTED_FORMAT_EXTENSIONS:
+            raise ConfigurationError(f"Unsupported output format: {self.output_format}")
+            
+        if self.output_dir is not None and not self.output_dir.is_absolute():
+            raise ConfigurationError(f"Output directory must be an absolute path: {self.output_dir}")

pdf_to_markdown_cli-0.4.0/src/docs_to_md/core/paths.py

@@ -0,0 +1,80 @@
+import logging
+import random
+import string
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+# import os # Not used
+
+from docs_to_md.utils.exceptions import FileError
+from docs_to_md.api.models import SUPPORTED_FORMAT_EXTENSIONS
+
+logger = logging.getLogger(__name__)
+
+
+def generate_unique_key(length: int = 8) -> str:
+    """Generates a random alphanumeric key of the specified length."""
+    characters = string.ascii_letters + string.digits
+    return "".join(random.choices(characters, k=length))
+
+
+@dataclass(frozen=True)
+class OutputPaths:
+    """Holds the determined output paths for a conversion."""
+
+    markdown_path: Path
+    images_dir: Path
+    unique_key: str # Add the key for potential later use
+
+
+def determine_output_paths(
+    input_file: Path, output_dir_config: Optional[Path], output_format: str
+) -> OutputPaths:
+    """
+    Determines the final output markdown path and images directory path
+    using a unique key for each run.
+    The image directory path is determined but not created here.
+    """
+    if not input_file.is_file():
+        raise ValueError(f"Input path must be a file: {input_file}")
+
+    unique_key = generate_unique_key()
+    logger.debug(f"Generated unique key for run: {unique_key}")
+
+    base_output_dir = output_dir_config if output_dir_config else input_file.parent
+    try:
+        # Still ensure the base output directory exists
+        base_output_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        raise FileError(
+            f"Could not create or access base output directory {base_output_dir}: {e}"
+        ) from e
+
+    # Use the imported mapping to get the desired file extension (remove the leading dot)
+    file_extension = SUPPORTED_FORMAT_EXTENSIONS.get(output_format, output_format)
+    if file_extension.startswith("."):
+        file_extension = file_extension[1:]  # Remove leading dot if present
+
+    markdown_filename_base = input_file.stem
+    final_markdown_filename = f"{markdown_filename_base}_{unique_key}.{file_extension}"
+    final_markdown_path = base_output_dir / final_markdown_filename
+
+    logger.debug(f"Determined final markdown path: {final_markdown_path}")
+
+    # Determine image directory path (placed in the same dir as the markdown file)
+    image_dir_name = f"images_{unique_key}"
+    final_images_dir = base_output_dir / image_dir_name
+
+    # Note: The image directory is NOT created here.
+    # Creation should happen later, only if images are actually extracted.
+
+    logger.info(
+        f"Determined final paths: Markdown='{final_markdown_path}', Images='{final_images_dir}'"
+    )
+
+    return OutputPaths(
+        markdown_path=final_markdown_path,
+        images_dir=final_images_dir,
+        unique_key=unique_key
+    )