Merge pull request #1 from DavidLMS/page-selection

Page selection

Author: DavidLMS

.env.example

@@ -15,4 +15,5 @@ DEFAULT_OLLAMA_SUMMARY_MODEL="mistral-small3.1"
 # Common Configuration
 DEFAULT_LANGUAGE="Spanish"
 DEFAULT_USE_MARKITDOWN="true"
-DEFAULT_USE_SUMMARY="false"
+DEFAULT_USE_SUMMARY="false"
+DEFAULT_PAGE_SELECTION=""

README.md

@@ -24,7 +24,7 @@ DescribePDF is an open-source tool designed to convert PDF files into detailed p
     <a href="https://github.com/DavidLMS/DescribePDF/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D">Report Bug</a>
     ·
     <a href="https://github.com/DavidLMS/DescribePDF/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BREQUEST%5D">Request Feature</a>
-  ·
+    ·
     <a href="https://github.com/DavidLMS/DescribePDF/wiki">Wiki</a>
 </p>
 
@@ -56,6 +56,7 @@ DescribePDF is an open-source tool designed to convert PDF files into detailed p
 
 - 📄 **Comprehensive Page Analysis** - Detailed descriptions of each page's visual and textual content
 - 🔍 **Context-Aware Descriptions** - Generates descriptions that understand the document's overall structure and purpose
+- 📑 **Selective Page Processing** - Process only specific pages or ranges for targeted analysis and faster results
 - 🌐 **Multilingual Support** - Generate descriptions in multiple languages
 - 📊 **Enhanced Extraction with Markitdown** - Optional integration with Markitdown for better text extraction
 - ☁️ **Cloud Model Support** - Compatible with powerful VLMs through OpenRouter
@@ -217,6 +218,7 @@ DEFAULT_OLLAMA_SUMMARY_MODEL="mistral-small3.1"
 DEFAULT_LANGUAGE="English"
 DEFAULT_USE_MARKITDOWN="true"
 DEFAULT_USE_SUMMARY="false"
+DEFAULT_PAGE_SELECTION=""
 ```
 
 ## Usage
@@ -238,6 +240,9 @@ describepdf document.pdf -o result.md
 # Change the output language
 describepdf document.pdf -l Spanish
 
+# Process only specific pages
+describepdf document.pdf --pages "1,3,5-10,15"
+
 # Use Markitdown and summary generation
 describepdf document.pdf --use-markitdown --use-summary
 
@@ -270,6 +275,7 @@ optional arguments:
                         VLM model to use
   -l LANGUAGE, --language LANGUAGE
                         Output language
+  --pages PAGES         Pages to process (e.g. '1,3,5-10,15')
   --use-markitdown      Use Markitdown for enhanced text extraction
   --use-summary         Generate and use a PDF summary
   --summary-model SUMMARY_MODEL
@@ -371,4 +377,4 @@ DescribePDF is released under the [MIT License](https://github.com/DavidLMS/Desc
 
 ## Contributing
 
-Contributions to DescribePDF are welcome! Whether you're improving the code, enhancing the documentation, or suggesting new features, your input is valuable. Please check out the [CONTRIBUTING.md](https://github.com/DavidLMS/DescribePDF/blob/main/CONTRIBUTING.md) file for guidelines on how to get started and make your contributions count.
+Contributions to DescribePDF are welcome! Whether you're improving the code, enhancing the documentation, or suggesting new features, your input is valuable. Please check out the [CONTRIBUTING.md](https://github.com/DavidLMS/DescribePDF/blob/main/CONTRIBUTING.md) file for guidelines on how to get started and make your contributions count.

describepdf/cli.py

@@ -61,6 +61,10 @@ def setup_cli_parser() -> argparse.ArgumentParser:
         help="VLM model to use (default: configured in .env)"
     )
 
+    parser.add_argument(
+        "--pages", 
+        help="Pages to process (e.g. '1,3,5-10,15'). Default: all pages."
+    )
     parser.add_argument(
         "-l", "--language", 
         help="Output language (default: configured in .env)"
@@ -157,6 +161,7 @@ def run_cli() -> None:
         "output_language": args.language if args.language else env_config.get("output_language"),
         "use_markitdown": args.use_markitdown if args.use_markitdown is not None else env_config.get("use_markitdown"),
         "use_summary": args.use_summary if args.use_summary is not None else env_config.get("use_summary"),
+        "page_selection": args.pages if args.pages else env_config.get("page_selection")
     }
 
     # Configure provider-specific settings
@@ -219,6 +224,11 @@ def run_cli() -> None:
     logger.info(f"Summary: {'Yes' if run_config['use_summary'] else 'No'}")
     if run_config.get('use_summary') and run_config.get('summary_llm_model'):
         logger.info(f"Summary model: {run_config['summary_llm_model']}")
+
+    if run_config.get('page_selection'):
+        logger.info(f"Page selection: {run_config['page_selection']}")
+    else:
+        logger.info("Page selection: All pages")
 
     # Create progress callback
     progress_callback = create_progress_callback()

describepdf/config.py

@@ -18,6 +18,8 @@
 SCRIPT_DIR = pathlib.Path(__file__).parent.parent.absolute()
 PROMPTS_DIR = pathlib.Path(SCRIPT_DIR) / "prompts"
 
+# Default configuration values
+
 # Default configuration values
 DEFAULT_CONFIG: Dict[str, Any] = {
     "openrouter_api_key": None,
@@ -30,7 +32,8 @@
 
     "output_language": "English",
     "use_markitdown": False,
-    "use_summary": False
+    "use_summary": False,
+    "page_selection": None
 }
 
 # Mapping of prompt template identifiers to their file names
@@ -90,6 +93,9 @@ def load_env_config() -> Dict[str, Any]:
 
     if os.getenv("DEFAULT_USE_SUMMARY"):
         loaded_config["use_summary"] = str(os.getenv("DEFAULT_USE_SUMMARY")).lower() == 'true'
+    
+    if os.getenv("DEFAULT_PAGE_SELECTION"):
+        loaded_config["page_selection"] = os.getenv("DEFAULT_PAGE_SELECTION")
 
     logger.info("Configuration loaded from environment variables.")
 

describepdf/core.py

@@ -24,22 +24,87 @@ class ConversionError(Exception):
     """Error raised during PDF conversion process."""
     pass
 
-def format_markdown_output(descriptions: List[str], original_filename: str) -> str:
+def parse_page_selection(selection_string: Optional[str], total_pages: int) -> List[int]:
+    """
+    Parse a page selection string into a list of page indices.
+    
+    Args:
+        selection_string: String with page selection (e.g. "1,3,5-10,15")
+        total_pages: Total number of pages in the document
+        
+    Returns:
+        List[int]: List of zero-based page indices to process
+    """
+    if not selection_string:
+        # Return all pages if selection is empty
+        return list(range(total_pages))
+        
+    page_indices = []
+    
+    try:
+        sections = selection_string.split(',')
+        for section in sections:
+            section = section.strip()
+            if not section:
+                continue
+                
+            if '-' in section:
+                # Handle page range
+                start, end = section.split('-', 1)
+                start_idx = int(start.strip()) - 1  # Convert to 0-based index
+                end_idx = int(end.strip()) - 1
+                
+                # Validate range
+                if start_idx < 0 or end_idx >= total_pages or start_idx > end_idx:
+                    logger.warning(f"Invalid page range: {section}. Must be between 1 and {total_pages}.")
+                    continue
+                    
+                page_indices.extend(range(start_idx, end_idx + 1))
+            else:
+                # Handle single page
+                page_idx = int(section) - 1  # Convert to 0-based index
+                
+                # Validate page number
+                if page_idx < 0 or page_idx >= total_pages:
+                    logger.warning(f"Invalid page number: {section}. Must be between 1 and {total_pages}.")
+                    continue
+                    
+                page_indices.append(page_idx)
+        
+        # Remove duplicates and sort
+        page_indices = sorted(set(page_indices))
+        
+        if not page_indices:
+            logger.warning("No valid pages specified. Processing all pages.")
+            return list(range(total_pages))
+            
+        return page_indices
+        
+    except ValueError as e:
+        logger.error(f"Error parsing page selection '{selection_string}': {e}. Processing all pages.")
+        return list(range(total_pages))
+
+def format_markdown_output(descriptions: List[str], original_filename: str, page_numbers: Optional[List[int]] = None) -> str:
     """
     Combine page descriptions into a single Markdown file.
 
     Args:
         descriptions: List of strings, each being a description of a page
         original_filename: Name of the original PDF file
+        page_numbers: List of actual page numbers corresponding to descriptions (1-based)
 
     Returns:
         str: Complete Markdown content
     """
     md_content = f"# Description of PDF: {original_filename}\n\n"
+    
     for i, desc in enumerate(descriptions):
-        md_content += f"## Page {i + 1}\n\n"
+        # Use actual page number if provided, otherwise use sequential numbering
+        page_num = page_numbers[i] if page_numbers else (i + 1)
+        md_content += f"## Page {page_num}\n\n"
         md_content += desc if desc else "*No description generated for this page.*"
         md_content += "\n\n---\n\n"
+    
     return md_content
 
 def convert_pdf_to_markdown(
@@ -175,7 +240,17 @@ def convert_pdf_to_markdown(
             page_processing_progress_start = pdf_load_progress
             total_page_progress_ratio = (0.98 - page_processing_progress_start) if total_pages > 0 else 0
 
-            for i, page in enumerate(pages):
+            # Parse page selection
+            page_selection = cfg.get("page_selection")
+            selected_indices = parse_page_selection(page_selection, total_pages)
+
+            if page_selection:
+                logger.info(f"Processing {len(selected_indices)} selected pages out of {total_pages} total pages.")
+            else:
+                logger.info(f"Processing all {total_pages} pages.")
+
+            for i in selected_indices:
+                page = pages[i]
                 page_num = i + 1
                 current_page_ratio = (page_num / total_pages) if total_pages > 0 else 1.0
 
@@ -306,7 +381,10 @@ def convert_pdf_to_markdown(
         # Generate final markdown
         final_progress = 0.99
         progress_callback(final_progress, "Combining page descriptions into final Markdown...")
-        final_markdown = format_markdown_output(all_descriptions, original_filename)
+
+        actual_page_numbers = [i + 1 for i in selected_indices] if 'selected_indices' in locals() else None
+
+        final_markdown = format_markdown_output(all_descriptions, original_filename, actual_page_numbers)
         logger.info("Final Markdown content assembled.")
 
         # Report completion

describepdf/ui.py

@@ -29,6 +29,7 @@ def convert_pdf_to_descriptive_markdown(
     ui_use_md: bool, 
     ui_use_sum: bool, 
     ui_sum_model: str, 
+    ui_page_selection: str,
     progress: gr.Progress = gr.Progress(track_tqdm=True)
 ) -> Tuple[str, gr.update, Optional[str]]:
     """
@@ -47,6 +48,7 @@ def convert_pdf_to_descriptive_markdown(
         ui_use_md: Whether to use Markitdown for enhanced text extraction
         ui_use_sum: Whether to generate a document summary for context
         ui_sum_model: Summary model name from UI (e.g., google/gemini-2.5-flash-preview)
+        ui_page_selection: Optional page selection string (e.g., "1,3,5-10")
         progress: Gradio progress tracker
         
     Returns:
@@ -72,7 +74,8 @@ def convert_pdf_to_descriptive_markdown(
         "output_language": ui_lang,
         "use_markitdown": ui_use_md,
         "use_summary": ui_use_sum,
-        "summary_llm_model": ui_sum_model if ui_sum_model else env_config.get("or_summary_model")
+        "summary_llm_model": ui_sum_model if ui_sum_model else env_config.get("or_summary_model"),
+        "page_selection": ui_page_selection.strip() if ui_page_selection.strip() else None
     }
 
     # Validate API key
@@ -243,6 +246,12 @@ def create_ui() -> gr.Blocks:
                     allow_custom_value=True,
                     info="Select or type the desired output language (e.g., English, Spanish)"
                 )
+                page_selection_input = gr.Textbox(
+                    label="Page Selection (Optional)", 
+                    value="",
+                    placeholder="Example: 1,3,5-10,15 (leave empty for all pages)",
+                    info="Specify individual pages or ranges to process"
+                )
                 with gr.Row():
                     use_markitdown_checkbox = gr.Checkbox(
                         label="Use Markitdown for extra text context",
@@ -263,7 +272,7 @@ def create_ui() -> gr.Blocks:
         # Connect UI components
         conversion_inputs = [
             pdf_input, api_key_input, vlm_model_input, output_language_input,
-            use_markitdown_checkbox, use_summary_checkbox, summary_llm_model_input
+            use_markitdown_checkbox, use_summary_checkbox, summary_llm_model_input, page_selection_input
         ]
         conversion_outputs = [
             progress_output, download_button, markdown_output

describepdf/ui_ollama.py

@@ -30,6 +30,7 @@ def convert_pdf_to_descriptive_markdown(
     ui_use_md: bool, 
     ui_use_sum: bool, 
     ui_sum_model: str, 
+    ui_page_selection: str,
     progress: gr.Progress = gr.Progress(track_tqdm=True)
 ) -> Tuple[str, gr.update, Optional[str]]:
     """
@@ -52,6 +53,7 @@ def convert_pdf_to_descriptive_markdown(
         ui_use_md: Whether to use Markitdown for enhanced text extraction
         ui_use_sum: Whether to generate a document summary for context
         ui_sum_model: Summary model name from UI (e.g., qwen2.5)
+        ui_page_selection: Optional page selection string (e.g., "1,3,5-10")
         progress: Gradio progress tracker
         
     Returns:
@@ -78,7 +80,8 @@ def convert_pdf_to_descriptive_markdown(
         "output_language": ui_lang,
         "use_markitdown": ui_use_md,
         "use_summary": ui_use_sum,
-        "summary_llm_model": ui_sum_model
+        "summary_llm_model": ui_sum_model,
+        "page_selection": ui_page_selection.strip() if ui_page_selection.strip() else None
     }
 
     # Create progress callback for Gradio
@@ -232,6 +235,12 @@ def create_ui() -> gr.Blocks:
                     allow_custom_value=True,
                     info="Select or type the desired output language (e.g., English, Spanish)"
                 )
+                page_selection_input = gr.Textbox(
+                    label="Page Selection (Optional)", 
+                    value="",
+                    placeholder="Example: 1,3,5-10,15 (leave empty for all pages)",
+                    info="Specify individual pages or ranges to process"
+                )
                 with gr.Row():
                     use_markitdown_checkbox = gr.Checkbox(
                         label="Use Markitdown for extra text context",
@@ -248,11 +257,10 @@ def create_ui() -> gr.Blocks:
                     allow_custom_value=True,
                     info="Select or type the Ollama LLM model name for summaries"
                 )
-
         # Connect UI components
         conversion_inputs = [
             pdf_input, ollama_endpoint_input, vlm_model_input, output_language_input,
-            use_markitdown_checkbox, use_summary_checkbox, summary_llm_model_input
+            use_markitdown_checkbox, use_summary_checkbox, summary_llm_model_input, page_selection_input
         ]
         conversion_outputs = [
             progress_output, download_button, markdown_output