pyxtxt 0.3.1__tar.gz → 0.3.3__tar.gz

{pyxtxt-0.3.1/src/pyxtxt.egg-info → pyxtxt-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyxtxt
-Version: 0.3.1
+Version: 0.3.3
 Summary: A Python library for extracting text from different types of files (PDF, DOCX, PPTX, XLSX, ODT, ecc.).
 Author-email: Giuseppe Levi <giuseppe.levi@gmail.com>
 License: MIT License
@@ -264,17 +264,43 @@ text = xtxt("invoice.tiff")
 
 # AI-powered OCR with Ollama (install with: pip install pyxtxt[ocr-ollama])
 # Requires: ollama server running + gemma3:4b model
-from pyxtxt.estrattori.ocr_ollama import set_ollama_model, xtxt_image_describe
+from pyxtxt import (
+    xtxt, xtxt_image_describe, 
+    set_ollama_model, set_ollama_config, get_ollama_config
+)
 
 # Configure model (optional, default is gemma3:4b)
-set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b
-
-# Extract only text (OCR mode)
+set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b, gemma3:27b
+
+# Configure LLM parameters for better captions
+set_ollama_config(
+    language='italian',        # Language hint for captions
+    caption_length='long',     # short, medium, long
+    style='detailed',          # descriptive, technical, simple, detailed
+    temperature=0.2,           # Creativity level (0.0-1.0)
+    max_tokens=2000           # Maximum response length
+)
+
+# Extract only text (OCR mode) 
 text = xtxt("complex_document.png")
+print(f"Extracted text: {text}")
+
+# Extract text + detailed caption
+full_analysis = xtxt_image_describe("scientific_diagram.png")
+print(full_analysis)
+# Output example:
+# TEXT: Figura 2.1: Struttura molecolare del DNA
+# DESCRIPTION: Diagramma scientifico dettagliato che mostra la doppia elica del DNA 
+# con nucleotidi colorati, legami idrogeno evidenziati e etichette in italiano per 
+# le basi azotate (adenina, timina, citosina, guanina).
+
+# Check current configuration
+config = get_ollama_config()
+print(f"Current config: {config}")
 
-# Extract text + image description
-description = xtxt_image_describe(open("diagram.png", "rb"))
-# Output: "TEXT: Chart Title: Sales Report 2024\nDESCRIPTION: Bar chart showing quarterly sales data with blue bars"
+# Reset to defaults if needed
+from pyxtxt import reset_ollama_config
+reset_ollama_config()
 
 # From web images
 import requests
@@ -282,6 +308,32 @@ image_response = requests.get("https://example.com/document.png")
 text = xtxt(image_response.content)
 ```
 
+### Command-Line OCR Example
+
+A complete example script for command-line usage is available:
+
+```python
+# Download and run the example script
+import requests
+
+example_url = "https://raw.githubusercontent.com/yourusername/pyxtxt/main/ocr_example.py"
+with open("ocr_example.py", "wb") as f:
+    f.write(requests.get(example_url).content)
+
+# Usage examples:
+# python ocr_example.py document.png
+# python ocr_example.py chart.jpg --mode=describe --lang=italian --style=detailed
+# python ocr_example.py diagram.png --mode=describe --length=long --temp=0.3
+```
+
+The script supports:
+- **OCR mode**: Extract only text from images
+- **Describe mode**: Extract text + generate detailed captions
+- **Language hints**: Specify caption language (italian, english, etc.)
+- **Style control**: descriptive, technical, simple, detailed
+- **Length control**: short, medium, long captions
+- **Temperature**: Adjust LLM creativity (0.0-1.0)
+
 ### Show Available Formats
 ```python
 from pyxtxt import extxt_available_formats
@@ -367,7 +419,18 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ## 📊 Changelog
 
-### v0.2.4
+### v0.2.5 (Current Development)
+- ✅ **NEW**: AI-powered OCR with Ollama LLM integration
+- ✅ **NEW**: Advanced caption generation with configurable parameters
+- ✅ **NEW**: `set_ollama_config()` for fine-tuning LLM behavior
+- ✅ **NEW**: Language hints, style control (descriptive/technical/simple/detailed)
+- ✅ **NEW**: Caption length control (short/medium/long)
+- ✅ **NEW**: Temperature and token limit configuration
+- ✅ **NEW**: Command-line OCR example script with full parameter support
+- ✅ **ENHANCED**: OCR-Ollama mode with both text extraction and image description
+- ✅ Support for gemma3:4b, gemma3:12b, gemma3:27b, llava:7b, llava:13b models
+
+### v0.2.4 
 - ✅ **NEW**: Video transcription support (MP4, MOV, AVI, WebM, MKV)
 - ✅ **ENHANCED**: Audio transcription now supports video files
 - ✅ Whisper automatically extracts audio track from videos
@@ -375,15 +438,35 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ### v0.2.3
 - ✅ **NEW**: Audio transcription support (MP3, WAV, M4A, FLAC, etc.)
-- ✅ **NEW**: OCR from images (JPEG, PNG, TIFF, BMP, WebP)
-- ✅ **NEW**: Markdown, EPUB, RTF, EML, MSG, LaTeX support
-- ✅ Separate optional dependencies for heavy features (audio/OCR)
-- ✅ Performance optimizations with model caching
-- ✅ Improved multilingual OCR support (Italian/English)
-
-### v0.1.24+
-- ✅ Added support for `bytes` objects
-- ✅ Added support for `requests.Response` objects  
-- ✅ Added `xtxt_from_url()` helper function
-- ✅ Improved type hints and error handling
-- ✅ Enhanced web content processing capabilities
+- ✅ **NEW**: Traditional OCR from images (JPEG, PNG, TIFF, BMP, WebP) via EasyOCR
+- ✅ **NEW**: 6 additional format extractors: Markdown, EPUB, RTF, EML, MSG, LaTeX
+- ✅ **NEW**: Modular dependencies with `[audio]`, `[ocr]`, `[all]` installation groups
+- ✅ Performance optimizations with model caching for heavy operations
+- ✅ Improved multilingual OCR support with automatic language detection
+
+### v0.2.0-0.2.2
+- ✅ **MAJOR**: Architectural improvements with automatic extractor registration
+- ✅ **NEW**: 6 format extractors added in single session (md, epub, rtf, eml, msg, tex)
+- ✅ **FIXED**: Critical memory management issues in MSG extractor
+- ✅ **FIXED**: Documentation links and path references
+- ✅ **ENHANCED**: Error handling with graceful degradation for missing dependencies
+- ✅ Comprehensive testing across all newly supported formats
+
+### v0.1.24
+- ✅ **NEW**: Support for raw `bytes` objects (web downloads, API responses)
+- ✅ **NEW**: Support for `requests.Response` objects (direct HTTP processing)
+- ✅ **NEW**: `xtxt_from_url()` helper function for direct URL processing
+- ✅ **ENHANCED**: Web-ready architecture for modern applications
+- ✅ **FIXED**: Type hints and Optional[str] return types throughout codebase
+- ✅ **FIXED**: Critical bug in xlsx.py:46 (indentation error)
+- ✅ **REMOVED**: Debug print statements from production code
+
+### v0.1.0-0.1.23
+- ✅ **CORE**: Initial release with modular extractor architecture
+- ✅ **CORE**: Support for PDF, DOCX, PPTX, XLSX, ODT, HTML, XML, TXT formats
+- ✅ **CORE**: Legacy Office support (.doc, .xls, .ppt) with graceful handling
+- ✅ **CORE**: MIME type detection with python-magic
+- ✅ **CORE**: BytesIO buffer support for memory-efficient processing
+- ✅ **CORE**: Single dispatch pattern for type-based routing
+- ✅ **CORE**: Automatic dependency management with optional installs
+- ✅ **CORE**: Published to PyPI with proper package structure

{pyxtxt-0.3.1 → pyxtxt-0.3.3}/README.md

@@ -160,17 +160,43 @@ text = xtxt("invoice.tiff")
 
 # AI-powered OCR with Ollama (install with: pip install pyxtxt[ocr-ollama])
 # Requires: ollama server running + gemma3:4b model
-from pyxtxt.estrattori.ocr_ollama import set_ollama_model, xtxt_image_describe
+from pyxtxt import (
+    xtxt, xtxt_image_describe, 
+    set_ollama_model, set_ollama_config, get_ollama_config
+)
 
 # Configure model (optional, default is gemma3:4b)
-set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b
-
-# Extract only text (OCR mode)
+set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b, gemma3:27b
+
+# Configure LLM parameters for better captions
+set_ollama_config(
+    language='italian',        # Language hint for captions
+    caption_length='long',     # short, medium, long
+    style='detailed',          # descriptive, technical, simple, detailed
+    temperature=0.2,           # Creativity level (0.0-1.0)
+    max_tokens=2000           # Maximum response length
+)
+
+# Extract only text (OCR mode) 
 text = xtxt("complex_document.png")
+print(f"Extracted text: {text}")
+
+# Extract text + detailed caption
+full_analysis = xtxt_image_describe("scientific_diagram.png")
+print(full_analysis)
+# Output example:
+# TEXT: Figura 2.1: Struttura molecolare del DNA
+# DESCRIPTION: Diagramma scientifico dettagliato che mostra la doppia elica del DNA 
+# con nucleotidi colorati, legami idrogeno evidenziati e etichette in italiano per 
+# le basi azotate (adenina, timina, citosina, guanina).
+
+# Check current configuration
+config = get_ollama_config()
+print(f"Current config: {config}")
 
-# Extract text + image description
-description = xtxt_image_describe(open("diagram.png", "rb"))
-# Output: "TEXT: Chart Title: Sales Report 2024\nDESCRIPTION: Bar chart showing quarterly sales data with blue bars"
+# Reset to defaults if needed
+from pyxtxt import reset_ollama_config
+reset_ollama_config()
 
 # From web images
 import requests
@@ -178,6 +204,32 @@ image_response = requests.get("https://example.com/document.png")
 text = xtxt(image_response.content)
 ```
 
+### Command-Line OCR Example
+
+A complete example script for command-line usage is available:
+
+```python
+# Download and run the example script
+import requests
+
+example_url = "https://raw.githubusercontent.com/yourusername/pyxtxt/main/ocr_example.py"
+with open("ocr_example.py", "wb") as f:
+    f.write(requests.get(example_url).content)
+
+# Usage examples:
+# python ocr_example.py document.png
+# python ocr_example.py chart.jpg --mode=describe --lang=italian --style=detailed
+# python ocr_example.py diagram.png --mode=describe --length=long --temp=0.3
+```
+
+The script supports:
+- **OCR mode**: Extract only text from images
+- **Describe mode**: Extract text + generate detailed captions
+- **Language hints**: Specify caption language (italian, english, etc.)
+- **Style control**: descriptive, technical, simple, detailed
+- **Length control**: short, medium, long captions
+- **Temperature**: Adjust LLM creativity (0.0-1.0)
+
 ### Show Available Formats
 ```python
 from pyxtxt import extxt_available_formats
@@ -263,7 +315,18 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ## 📊 Changelog
 
-### v0.2.4
+### v0.2.5 (Current Development)
+- ✅ **NEW**: AI-powered OCR with Ollama LLM integration
+- ✅ **NEW**: Advanced caption generation with configurable parameters
+- ✅ **NEW**: `set_ollama_config()` for fine-tuning LLM behavior
+- ✅ **NEW**: Language hints, style control (descriptive/technical/simple/detailed)
+- ✅ **NEW**: Caption length control (short/medium/long)
+- ✅ **NEW**: Temperature and token limit configuration
+- ✅ **NEW**: Command-line OCR example script with full parameter support
+- ✅ **ENHANCED**: OCR-Ollama mode with both text extraction and image description
+- ✅ Support for gemma3:4b, gemma3:12b, gemma3:27b, llava:7b, llava:13b models
+
+### v0.2.4 
 - ✅ **NEW**: Video transcription support (MP4, MOV, AVI, WebM, MKV)
 - ✅ **ENHANCED**: Audio transcription now supports video files
 - ✅ Whisper automatically extracts audio track from videos
@@ -271,15 +334,35 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ### v0.2.3
 - ✅ **NEW**: Audio transcription support (MP3, WAV, M4A, FLAC, etc.)
-- ✅ **NEW**: OCR from images (JPEG, PNG, TIFF, BMP, WebP)
-- ✅ **NEW**: Markdown, EPUB, RTF, EML, MSG, LaTeX support
-- ✅ Separate optional dependencies for heavy features (audio/OCR)
-- ✅ Performance optimizations with model caching
-- ✅ Improved multilingual OCR support (Italian/English)
-
-### v0.1.24+
-- ✅ Added support for `bytes` objects
-- ✅ Added support for `requests.Response` objects  
-- ✅ Added `xtxt_from_url()` helper function
-- ✅ Improved type hints and error handling
-- ✅ Enhanced web content processing capabilities
+- ✅ **NEW**: Traditional OCR from images (JPEG, PNG, TIFF, BMP, WebP) via EasyOCR
+- ✅ **NEW**: 6 additional format extractors: Markdown, EPUB, RTF, EML, MSG, LaTeX
+- ✅ **NEW**: Modular dependencies with `[audio]`, `[ocr]`, `[all]` installation groups
+- ✅ Performance optimizations with model caching for heavy operations
+- ✅ Improved multilingual OCR support with automatic language detection
+
+### v0.2.0-0.2.2
+- ✅ **MAJOR**: Architectural improvements with automatic extractor registration
+- ✅ **NEW**: 6 format extractors added in single session (md, epub, rtf, eml, msg, tex)
+- ✅ **FIXED**: Critical memory management issues in MSG extractor
+- ✅ **FIXED**: Documentation links and path references
+- ✅ **ENHANCED**: Error handling with graceful degradation for missing dependencies
+- ✅ Comprehensive testing across all newly supported formats
+
+### v0.1.24
+- ✅ **NEW**: Support for raw `bytes` objects (web downloads, API responses)
+- ✅ **NEW**: Support for `requests.Response` objects (direct HTTP processing)
+- ✅ **NEW**: `xtxt_from_url()` helper function for direct URL processing
+- ✅ **ENHANCED**: Web-ready architecture for modern applications
+- ✅ **FIXED**: Type hints and Optional[str] return types throughout codebase
+- ✅ **FIXED**: Critical bug in xlsx.py:46 (indentation error)
+- ✅ **REMOVED**: Debug print statements from production code
+
+### v0.1.0-0.1.23
+- ✅ **CORE**: Initial release with modular extractor architecture
+- ✅ **CORE**: Support for PDF, DOCX, PPTX, XLSX, ODT, HTML, XML, TXT formats
+- ✅ **CORE**: Legacy Office support (.doc, .xls, .ppt) with graceful handling
+- ✅ **CORE**: MIME type detection with python-magic
+- ✅ **CORE**: BytesIO buffer support for memory-efficient processing
+- ✅ **CORE**: Single dispatch pattern for type-based routing
+- ✅ **CORE**: Automatic dependency management with optional installs
+- ✅ **CORE**: Published to PyPI with proper package structure

{pyxtxt-0.3.1 → pyxtxt-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyxtxt"
-version = "0.3.1"
+version = "0.3.3"
 description = "A Python library for extracting text from different types of files (PDF, DOCX, PPTX, XLSX, ODT, ecc.)."
 classifiers = [
   "Development Status :: 4 - Beta",

pyxtxt-0.3.3/src/pyxtxt/__init__.py

@@ -0,0 +1,15 @@
+from .core import xtxt, extxt_available_formats, xtxt_from_url
+
+# Import OCR-Ollama functions if available
+try:
+    from .estrattori.ocr_ollama import (
+        set_ollama_model, get_ollama_model, xtxt_image_describe,
+        set_ollama_config, get_ollama_config, reset_ollama_config
+    )
+    __all__ = [
+        "xtxt", "extxt_available_formats", "xtxt_from_url", 
+        "set_ollama_model", "get_ollama_model", "xtxt_image_describe",
+        "set_ollama_config", "get_ollama_config", "reset_ollama_config"
+    ]
+except ImportError:
+    __all__ = ["xtxt", "extxt_available_formats", "xtxt_from_url"]

pyxtxt-0.3.3/src/pyxtxt/estrattori/ocr_ollama.py

@@ -0,0 +1,245 @@
+# pyxtxt/extractors/image_ocr_ollama.py
+from . import register_extractor
+from io import BytesIO
+import base64
+
+try:
+    import ollama
+    from PIL import Image
+except ImportError:
+    ollama = None
+    Image = None
+
+# Global configuration for Ollama model and parameters
+OLLAMA_MODEL = "gemma3:4b"  # Default multimodal model
+OLLAMA_CONFIG = {
+    'language': 'auto',  # Language hint for caption generation
+    'caption_length': 'medium',  # short, medium, long
+    'style': 'descriptive',  # descriptive, technical, simple, detailed
+    'temperature': 0.1,  # Response creativity (0.0-1.0)
+    'max_tokens': 1500,  # Maximum response length
+    'confidence_threshold': 0.7,  # Minimum confidence for text extraction
+    'context': 'general'  # Context hint: general, cookbook, document, diagram, etc.
+}
+
+def set_ollama_model(model_name: str):
+    """
+    Set the Ollama model to use for OCR.
+    
+    Recommended multimodal models:
+    - gemma3:4b (default, balanced speed/quality)
+    - gemma3:12b (higher quality, slower)
+    - gemma3:27b (best quality, very slow)
+    - llava:7b (alternative vision model)
+    - llava:13b (higher quality LLAVA)
+    """
+    global OLLAMA_MODEL
+    OLLAMA_MODEL = model_name
+    print(f"✅ Ollama OCR model set to: {model_name}")
+
+def get_ollama_model():
+    """Get current Ollama model name"""
+    return OLLAMA_MODEL
+
+def set_ollama_config(**kwargs):
+    """
+    Configure Ollama LLM parameters for better caption generation.
+    
+    Parameters:
+    - language: Language hint ('auto', 'italian', 'english', 'spanish', etc.)
+    - caption_length: Caption length ('short', 'medium', 'long')
+    - style: Caption style ('descriptive', 'technical', 'simple', 'detailed')
+    - context: Content context ('general', 'cookbook', 'document', 'handwriting', 'technical')
+    - temperature: Response creativity 0.0-1.0 (default: 0.1)
+    - max_tokens: Maximum response length (default: 1500)
+    - confidence_threshold: Text extraction confidence 0.0-1.0 (default: 0.7)
+    
+    Examples:
+        set_ollama_config(language='italian', style='detailed')
+        set_ollama_config(context='document', caption_length='long')
+        set_ollama_config(context='handwriting', temperature=0.2)
+    """
+    global OLLAMA_CONFIG
+    for key, value in kwargs.items():
+        if key in OLLAMA_CONFIG:
+            OLLAMA_CONFIG[key] = value
+            print(f"✅ Ollama config updated: {key} = {value}")
+        else:
+            print(f"⚠️ Unknown config parameter: {key}")
+
+def get_ollama_config():
+    """Get current Ollama configuration"""
+    return OLLAMA_CONFIG.copy()
+
+def reset_ollama_config():
+    """Reset Ollama configuration to defaults"""
+    global OLLAMA_CONFIG
+    OLLAMA_CONFIG = {
+        'language': 'auto',
+        'caption_length': 'medium', 
+        'style': 'descriptive',
+        'temperature': 0.1,
+        'max_tokens': 1500,
+        'confidence_threshold': 0.7,
+        'context': 'general'
+    }
+    print("✅ Ollama configuration reset to defaults")
+
+if ollama and Image:
+    def xtxt_image_ocr_ollama(file_buffer, mode="ocr", model=None):
+        """
+        Extract text from images using Ollama with multimodal models.
+        
+        Args:
+            file_buffer: Image file buffer
+            mode: "ocr" (text only) or "describe" (text + description)  
+            model: Override default model (optional)
+        """
+        try:
+            # Use specified model or global default
+            current_model = model or OLLAMA_MODEL
+            
+            # Convert buffer to PIL Image
+            # Reset buffer position if it has read method
+            if hasattr(file_buffer, 'seek'):
+                file_buffer.seek(0)
+            image_data = file_buffer.read()
+            image = Image.open(BytesIO(image_data))
+            
+            # Convert to RGB if needed
+            if image.mode != 'RGB':
+                image = image.convert('RGB')
+            
+            # Convert image to base64
+            buffered = BytesIO()
+            image.save(buffered, format="PNG")
+            img_base64 = base64.b64encode(buffered.getvalue()).decode()
+            
+            # Get current configuration
+            config = OLLAMA_CONFIG
+            
+            # Build language hint
+            lang_hint = ""
+            if config['language'] != 'auto':
+                lang_hint = f"Text language: {config['language']}. "
+            
+            # Different prompts based on mode
+            if mode == "ocr":
+                prompt = f"""Look carefully at this image and extract ALL text that you can see, including:
+- Titles, headings, and main text content  
+- Small print, captions, labels, and annotations
+- Numbers, measurements, quantities, and symbols
+- Menu items, ingredient lists, cooking instructions
+- Any text in boxes, speech bubbles, or decorative elements
+
+IMPORTANT: 
+- Read carefully and include even small or partially visible text
+- Preserve the original formatting and line breaks where possible
+- {lang_hint}Process the text from left to right, top to bottom
+- If you cannot find any readable text at all, respond with 'NO_TEXT_FOUND'
+
+Extracted text:"""
+            
+            else:  # mode == "describe"
+                # Build style-specific prompts
+                style_prompts = {
+                    'descriptive': "Provide a clear, descriptive explanation",
+                    'technical': "Use technical terminology and precise descriptions", 
+                    'simple': "Use simple, easy-to-understand language",
+                    'detailed': "Provide comprehensive details about all visual elements"
+                }
+                
+                length_hints = {
+                    'short': "Keep descriptions brief (1-2 sentences)",
+                    'medium': "Provide moderate detail (2-4 sentences)",
+                    'long': "Give comprehensive descriptions (4-8 sentences)"
+                }
+                
+                style_instruction = style_prompts.get(config['style'], style_prompts['descriptive'])
+                length_instruction = length_hints.get(config['caption_length'], length_hints['medium'])
+                
+                # Context-specific hints (only when explicitly set)
+                context_hint = ""
+                context = config.get('context', 'general').lower()
+                if context == 'cookbook' or context == 'recipe':
+                    context_hint = """
+   - If this appears to be a recipe/cookbook page, include: ingredients, cooking steps, quantities, cooking times
+   - Mention any photos of prepared dishes or cooking techniques shown
+   - Note any special formatting like ingredient lists, step numbers, or cooking tips"""
+                elif context == 'document':
+                    context_hint = """
+   - Focus on document structure: headers, paragraphs, sections, page numbers
+   - Note any official formatting, letterheads, signatures, or stamps"""
+                elif context == 'handwriting' or context == 'notes':
+                    context_hint = """
+   - Pay special attention to handwritten text which may be harder to read
+   - Note any sketches, diagrams, or informal formatting typical of personal notes"""
+                elif context == 'technical' or context == 'diagram':
+                    context_hint = """
+   - Focus on technical elements: labels, measurements, specifications, diagrams
+   - Include any mathematical formulas, technical symbols, or engineering notations"""
+
+                prompt = f"""Analyze this image and provide:
+1. All visible text exactly as written (preserve formatting, line breaks, bullet points)
+2. Image description following these guidelines:
+   - {style_instruction}
+   - {length_instruction}
+   - {lang_hint}Focus on key visual elements, layout, and context{context_hint}
+
+Format:
+TEXT: [all visible text here, or NO_TEXT_FOUND if none]
+DESCRIPTION: [image description following the guidelines above]"""
+            
+            # Send request to Ollama with configured parameters
+            response = ollama.generate(
+                model=current_model,
+                prompt=prompt,
+                images=[img_base64],
+                options={
+                    'temperature': config['temperature'],
+                    'top_p': 0.9,
+                    'num_predict': config['max_tokens']
+                }
+            )
+            
+            # Extract and clean response
+            extracted_content = response.get('response', '').strip()
+            
+            # Handle no-text case for OCR mode
+            if mode == "ocr" and ('NO_TEXT_FOUND' in extracted_content or len(extracted_content) < 3):
+                return ""
+            
+            return extracted_content
+            
+        except Exception as e:
+            print(f"⚠️ Error extracting from image with Ollama {current_model}: {e}")
+            return ""
+    
+    # Wrapper functions for each mode
+    def xtxt_image_ocr_only(file_input):
+        """Traditional OCR: extract only visible text using Ollama"""
+        # Handle both file paths and buffers
+        if isinstance(file_input, str):
+            with open(file_input, 'rb') as f:
+                return xtxt_image_ocr_ollama(f, mode="ocr")
+        else:
+            return xtxt_image_ocr_ollama(file_input, mode="ocr")
+    
+    def xtxt_image_describe(file_input):
+        """OCR + Description: text + image context using Ollama"""
+        # Handle both file paths and buffers  
+        if isinstance(file_input, str):
+            with open(file_input, 'rb') as f:
+                return xtxt_image_ocr_ollama(f, mode="describe")
+        else:
+            return xtxt_image_ocr_ollama(file_input, mode="describe")
+    
+    # Register OCR-only version as default
+    # Note: Will override traditional EasyOCR if both modules are loaded
+    image_formats = [
+        "image/jpeg", "image/jpg", "image/png", 
+        "image/bmp", "image/tiff", "image/webp"
+    ]
+    
+    for format_type in image_formats:
+        register_extractor(format_type, xtxt_image_ocr_only, name="OCR-Ollama")

{pyxtxt-0.3.1 → pyxtxt-0.3.3/src/pyxtxt.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyxtxt
-Version: 0.3.1
+Version: 0.3.3
 Summary: A Python library for extracting text from different types of files (PDF, DOCX, PPTX, XLSX, ODT, ecc.).
 Author-email: Giuseppe Levi <giuseppe.levi@gmail.com>
 License: MIT License
@@ -264,17 +264,43 @@ text = xtxt("invoice.tiff")
 
 # AI-powered OCR with Ollama (install with: pip install pyxtxt[ocr-ollama])
 # Requires: ollama server running + gemma3:4b model
-from pyxtxt.estrattori.ocr_ollama import set_ollama_model, xtxt_image_describe
+from pyxtxt import (
+    xtxt, xtxt_image_describe, 
+    set_ollama_model, set_ollama_config, get_ollama_config
+)
 
 # Configure model (optional, default is gemma3:4b)
-set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b
-
-# Extract only text (OCR mode)
+set_ollama_model("gemma3:12b")  # or llava:7b, llava:13b, gemma3:27b
+
+# Configure LLM parameters for better captions
+set_ollama_config(
+    language='italian',        # Language hint for captions
+    caption_length='long',     # short, medium, long
+    style='detailed',          # descriptive, technical, simple, detailed
+    temperature=0.2,           # Creativity level (0.0-1.0)
+    max_tokens=2000           # Maximum response length
+)
+
+# Extract only text (OCR mode) 
 text = xtxt("complex_document.png")
+print(f"Extracted text: {text}")
+
+# Extract text + detailed caption
+full_analysis = xtxt_image_describe("scientific_diagram.png")
+print(full_analysis)
+# Output example:
+# TEXT: Figura 2.1: Struttura molecolare del DNA
+# DESCRIPTION: Diagramma scientifico dettagliato che mostra la doppia elica del DNA 
+# con nucleotidi colorati, legami idrogeno evidenziati e etichette in italiano per 
+# le basi azotate (adenina, timina, citosina, guanina).
+
+# Check current configuration
+config = get_ollama_config()
+print(f"Current config: {config}")
 
-# Extract text + image description
-description = xtxt_image_describe(open("diagram.png", "rb"))
-# Output: "TEXT: Chart Title: Sales Report 2024\nDESCRIPTION: Bar chart showing quarterly sales data with blue bars"
+# Reset to defaults if needed
+from pyxtxt import reset_ollama_config
+reset_ollama_config()
 
 # From web images
 import requests
@@ -282,6 +308,32 @@ image_response = requests.get("https://example.com/document.png")
 text = xtxt(image_response.content)
 ```
 
+### Command-Line OCR Example
+
+A complete example script for command-line usage is available:
+
+```python
+# Download and run the example script
+import requests
+
+example_url = "https://raw.githubusercontent.com/yourusername/pyxtxt/main/ocr_example.py"
+with open("ocr_example.py", "wb") as f:
+    f.write(requests.get(example_url).content)
+
+# Usage examples:
+# python ocr_example.py document.png
+# python ocr_example.py chart.jpg --mode=describe --lang=italian --style=detailed
+# python ocr_example.py diagram.png --mode=describe --length=long --temp=0.3
+```
+
+The script supports:
+- **OCR mode**: Extract only text from images
+- **Describe mode**: Extract text + generate detailed captions
+- **Language hints**: Specify caption language (italian, english, etc.)
+- **Style control**: descriptive, technical, simple, detailed
+- **Length control**: short, medium, long captions
+- **Temperature**: Adjust LLM creativity (0.0-1.0)
+
 ### Show Available Formats
 ```python
 from pyxtxt import extxt_available_formats
@@ -367,7 +419,18 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ## 📊 Changelog
 
-### v0.2.4
+### v0.2.5 (Current Development)
+- ✅ **NEW**: AI-powered OCR with Ollama LLM integration
+- ✅ **NEW**: Advanced caption generation with configurable parameters
+- ✅ **NEW**: `set_ollama_config()` for fine-tuning LLM behavior
+- ✅ **NEW**: Language hints, style control (descriptive/technical/simple/detailed)
+- ✅ **NEW**: Caption length control (short/medium/long)
+- ✅ **NEW**: Temperature and token limit configuration
+- ✅ **NEW**: Command-line OCR example script with full parameter support
+- ✅ **ENHANCED**: OCR-Ollama mode with both text extraction and image description
+- ✅ Support for gemma3:4b, gemma3:12b, gemma3:27b, llava:7b, llava:13b models
+
+### v0.2.4 
 - ✅ **NEW**: Video transcription support (MP4, MOV, AVI, WebM, MKV)
 - ✅ **ENHANCED**: Audio transcription now supports video files
 - ✅ Whisper automatically extracts audio track from videos
@@ -375,15 +438,35 @@ Pull requests, issues, and feedback are warmly welcome! 🚀
 
 ### v0.2.3
 - ✅ **NEW**: Audio transcription support (MP3, WAV, M4A, FLAC, etc.)
-- ✅ **NEW**: OCR from images (JPEG, PNG, TIFF, BMP, WebP)
-- ✅ **NEW**: Markdown, EPUB, RTF, EML, MSG, LaTeX support
-- ✅ Separate optional dependencies for heavy features (audio/OCR)
-- ✅ Performance optimizations with model caching
-- ✅ Improved multilingual OCR support (Italian/English)
-
-### v0.1.24+
-- ✅ Added support for `bytes` objects
-- ✅ Added support for `requests.Response` objects  
-- ✅ Added `xtxt_from_url()` helper function
-- ✅ Improved type hints and error handling
-- ✅ Enhanced web content processing capabilities
+- ✅ **NEW**: Traditional OCR from images (JPEG, PNG, TIFF, BMP, WebP) via EasyOCR
+- ✅ **NEW**: 6 additional format extractors: Markdown, EPUB, RTF, EML, MSG, LaTeX
+- ✅ **NEW**: Modular dependencies with `[audio]`, `[ocr]`, `[all]` installation groups
+- ✅ Performance optimizations with model caching for heavy operations
+- ✅ Improved multilingual OCR support with automatic language detection
+
+### v0.2.0-0.2.2
+- ✅ **MAJOR**: Architectural improvements with automatic extractor registration
+- ✅ **NEW**: 6 format extractors added in single session (md, epub, rtf, eml, msg, tex)
+- ✅ **FIXED**: Critical memory management issues in MSG extractor
+- ✅ **FIXED**: Documentation links and path references
+- ✅ **ENHANCED**: Error handling with graceful degradation for missing dependencies
+- ✅ Comprehensive testing across all newly supported formats
+
+### v0.1.24
+- ✅ **NEW**: Support for raw `bytes` objects (web downloads, API responses)
+- ✅ **NEW**: Support for `requests.Response` objects (direct HTTP processing)
+- ✅ **NEW**: `xtxt_from_url()` helper function for direct URL processing
+- ✅ **ENHANCED**: Web-ready architecture for modern applications
+- ✅ **FIXED**: Type hints and Optional[str] return types throughout codebase
+- ✅ **FIXED**: Critical bug in xlsx.py:46 (indentation error)
+- ✅ **REMOVED**: Debug print statements from production code
+
+### v0.1.0-0.1.23
+- ✅ **CORE**: Initial release with modular extractor architecture
+- ✅ **CORE**: Support for PDF, DOCX, PPTX, XLSX, ODT, HTML, XML, TXT formats
+- ✅ **CORE**: Legacy Office support (.doc, .xls, .ppt) with graceful handling
+- ✅ **CORE**: MIME type detection with python-magic
+- ✅ **CORE**: BytesIO buffer support for memory-efficient processing
+- ✅ **CORE**: Single dispatch pattern for type-based routing
+- ✅ **CORE**: Automatic dependency management with optional installs
+- ✅ **CORE**: Published to PyPI with proper package structure

pyxtxt-0.3.1/src/pyxtxt/__init__.py

@@ -1,8 +0,0 @@
-from .core import xtxt, extxt_available_formats, xtxt_from_url
-
-# Import OCR-Ollama functions if available
-try:
-    from .estrattori.ocr_ollama import set_ollama_model, get_ollama_model, xtxt_image_describe
-    __all__ = ["xtxt", "extxt_available_formats", "xtxt_from_url", "set_ollama_model", "get_ollama_model", "xtxt_image_describe"]
-except ImportError:
-    __all__ = ["xtxt", "extxt_available_formats", "xtxt_from_url"]

pyxtxt-0.3.1/src/pyxtxt/estrattori/ocr_ollama.py

@@ -1,125 +0,0 @@
-# pyxtxt/extractors/image_ocr_ollama.py
-from . import register_extractor
-from io import BytesIO
-import base64
-
-try:
-    import ollama
-    from PIL import Image
-except ImportError:
-    ollama = None
-    Image = None
-
-# Global configuration for Ollama model
-OLLAMA_MODEL = "gemma3:4b"  # Default multimodal model
-
-def set_ollama_model(model_name: str):
-    """
-    Set the Ollama model to use for OCR.
-    
-    Recommended multimodal models:
-    - gemma3:4b (default, balanced speed/quality)
-    - gemma3:12b (higher quality, slower)
-    - gemma3:27b (best quality, very slow)
-    - llava:7b (alternative vision model)
-    - llava:13b (higher quality LLAVA)
-    """
-    global OLLAMA_MODEL
-    OLLAMA_MODEL = model_name
-    print(f"✅ Ollama OCR model set to: {model_name}")
-
-def get_ollama_model():
-    """Get current Ollama model name"""
-    return OLLAMA_MODEL
-
-if ollama and Image:
-    def xtxt_image_ocr_ollama(file_buffer, mode="ocr", model=None):
-        """
-        Extract text from images using Ollama with multimodal models.
-        
-        Args:
-            file_buffer: Image file buffer
-            mode: "ocr" (text only) or "describe" (text + description)  
-            model: Override default model (optional)
-        """
-        try:
-            # Use specified model or global default
-            current_model = model or OLLAMA_MODEL
-            
-            # Convert buffer to PIL Image
-            image = Image.open(BytesIO(file_buffer.read()))
-            
-            # Convert to RGB if needed
-            if image.mode != 'RGB':
-                image = image.convert('RGB')
-            
-            # Convert image to base64
-            buffered = BytesIO()
-            image.save(buffered, format="PNG")
-            img_base64 = base64.b64encode(buffered.getvalue()).decode()
-            
-            # Different prompts based on mode
-            if mode == "ocr":
-                prompt = """Extract ALL visible text from this image exactly as it appears. 
-Rules:
-- Only return text that is actually written/printed in the image
-- Preserve reading order (left to right, top to bottom)  
-- Maintain line breaks and formatting
-- Include numbers, symbols, special characters
-- Do NOT add descriptions, interpretations, or context
-- If no text is visible, return 'NO_TEXT_FOUND'
-
-Extracted text:"""
-            
-            else:  # mode == "describe"
-                prompt = """Analyze this image and provide:
-1. All visible text exactly as written
-2. Brief description of the image content and context
-
-Format:
-TEXT: [all visible text here, or NO_TEXT_FOUND if none]
-DESCRIPTION: [brief image description and context]"""
-            
-            # Send request to Ollama
-            response = ollama.generate(
-                model=current_model,
-                prompt=prompt,
-                images=[img_base64],
-                options={
-                    'temperature': 0.1,  # Low temperature for accuracy
-                    'top_p': 0.9,
-                    'num_predict': 1500
-                }
-            )
-            
-            # Extract and clean response
-            extracted_content = response.get('response', '').strip()
-            
-            # Handle no-text case for OCR mode
-            if mode == "ocr" and ('NO_TEXT_FOUND' in extracted_content or len(extracted_content) < 3):
-                return ""
-            
-            return extracted_content
-            
-        except Exception as e:
-            print(f"⚠️ Error extracting from image with Ollama {current_model}: {e}")
-            return ""
-    
-    # Wrapper functions for each mode
-    def xtxt_image_ocr_only(file_buffer):
-        """Traditional OCR: extract only visible text using Ollama"""
-        return xtxt_image_ocr_ollama(file_buffer, mode="ocr")
-    
-    def xtxt_image_describe(file_buffer):
-        """OCR + Description: text + image context using Ollama"""
-        return xtxt_image_ocr_ollama(file_buffer, mode="describe")
-    
-    # Register OCR-only version as default
-    # Note: Will override traditional EasyOCR if both modules are loaded
-    image_formats = [
-        "image/jpeg", "image/jpg", "image/png", 
-        "image/bmp", "image/tiff", "image/webp"
-    ]
-    
-    for format_type in image_formats:
-        register_extractor(format_type, xtxt_image_ocr_only, name="OCR-Ollama")