Sparrow Parse

A powerful Python library for parsing and extracting structured information from documents using Vision Language Models (VLMs). Part of the Sparrow ecosystem for intelligent document processing.

✨ Features

🔍 Document Data Extraction: Extract structured data from invoices, forms, tables, and complex documents
🤖 Multiple Backend Support: MLX (Apple Silicon), Ollama, Docker, Hugging Face Cloud GPU, Mistral OCR, and local GPU inference
📄 Multi-format Support: Images (PNG, JPG, JPEG) and multi-page PDFs
🎯 Schema Validation: JSON schema-based extraction with automatic validation
📊 Table Processing: Specialized table detection and extraction capabilities
🖼️ Image Annotation: Bounding box annotations for extracted data
💬 Text Instructions: Support for instruction-based text processing
⚡ Optimized Processing: Image cropping, resizing, and preprocessing capabilities
☁️ Cloud OCR Backend: Mistral OCR for enterprise-grade cloud document extraction

🚀 Quick Start

Installation

To run with MLX on macOS Silicon:

pip install sparrow-parse[mlx]

To run with Ollama on Linux/Windows:

pip install sparrow-parse

Additional Requirements:

For PDF processing: brew install poppler (macOS) or apt-get install poppler-utils (Linux)
For MLX backend: Apple Silicon Mac required
For Hugging Face: Valid HF token with GPU access

Basic Usage

from sparrow_parse.vlmb.inference_factory import InferenceFactory
from sparrow_parse.extractors.vllm_extractor import VLLMExtractor

# Initialize extractor
extractor = VLLMExtractor()

# Configure backend (MLX example)
config = {
    "method": "mlx",
    "model_name": "mlx-community/Mistral-Small-3.1-24B-Instruct-2503-8bit"
}

# Create inference instance
factory = InferenceFactory(config)
model_inference_instance = factory.get_inference_instance()

# Prepare input data
input_data = [{
    "file_path": "path/to/your/document.png",
    "text_input": "retrieve [{\"field_name\": \"str\", \"amount\": 0}]. return response in JSON format"
}]

# Run inference
results, num_pages = extractor.run_inference(
    model_inference_instance,
    input_data,
    debug=True
)

print(f"Extracted data: {results[0]}")

📖 Detailed Usage

Backend Configuration

MLX Backend (Apple Silicon)

config = {
    "method": "mlx",
    "model_name": "mlx-community/Qwen2.5-VL-72B-Instruct-4bit"
}

Ollama Backend

config = {
    "method": "ollama",
    "model_name": "mistral-small3.2:24b-instruct-2506-q8_0"
}

Hugging Face Backend

import os
config = {
    "method": "huggingface",
    "hf_space": "your-username/your-space",
    "hf_token": os.getenv('HF_TOKEN')
}

Local GPU Backend

config = {
    "method": "local_gpu",
    "device": "cuda",
    "model_path": "path/to/model.pth"
}

Input Data Formats

Document Processing

input_data = [{
    "file_path": "invoice.pdf",
    "text_input": "extract invoice data: {\"invoice_number\": \"str\", \"total\": 0, \"date\": \"str\"}"
}]

Text-Only Processing

input_data = [{
    "file_path": None,
    "text_input": "Summarize the key points about renewable energy."
}]

Advanced Options

Table Extraction Only

results, num_pages = extractor.run_inference(
    model_inference_instance,
    input_data,
    tables_only=True  # Extract only tables from document
)

Image Cropping

results, num_pages = extractor.run_inference(
    model_inference_instance,
    input_data,
    crop_size=60  # Crop 60 pixels from all borders
)

Bounding Box Annotations

results, num_pages = extractor.run_inference(
    model_inference_instance,
    input_data,
    apply_annotation=True  # Include bounding box coordinates
)

Generic Data Extraction

results, num_pages = extractor.run_inference(
    model_inference_instance,
    input_data,
    generic_query=True  # Extract all available data
)

🛠️ Utility Functions

PDF Processing

from sparrow_parse.helpers.pdf_optimizer import PDFOptimizer

pdf_optimizer = PDFOptimizer()
num_pages, output_files, temp_dir = pdf_optimizer.split_pdf_to_pages(
    file_path="document.pdf",
    debug_dir="./debug",
    convert_to_images=True
)

Image Optimization

from sparrow_parse.helpers.image_optimizer import ImageOptimizer

image_optimizer = ImageOptimizer()
cropped_path = image_optimizer.crop_image_borders(
    file_path="image.jpg",
    temp_dir="./temp",
    debug_dir="./debug",
    crop_size=50
)

Table Detection

from sparrow_parse.processors.table_structure_processor import TableDetector

detector = TableDetector()
cropped_tables = detector.detect_tables(
    file_path="document.png",
    local=True,
    debug=True
)

🎯 Use Cases & Examples

Invoice Processing

invoice_schema = {
    "invoice_number": "str",
    "date": "str", 
    "vendor_name": "str",
    "total_amount": 0,
    "line_items": [{
        "description": "str",
        "quantity": 0,
        "price": 0.0
    }]
}

input_data = [{
    "file_path": "invoice.pdf",
    "text_input": f"extract invoice data: {json.dumps(invoice_schema)}"
}]

Financial Tables

table_schema = [{
    "instrument_name": "str",
    "valuation": 0,
    "currency": "str or null"
}]

input_data = [{
    "file_path": "financial_report.png", 
    "text_input": f"retrieve {json.dumps(table_schema)}. return response in JSON format"
}]

Form Processing

form_schema = {
    "applicant_name": "str",
    "application_date": "str",
    "fields": [{
        "field_name": "str",
        "field_value": "str or null"
    }]
}

⚙️ Configuration Options

Parameter	Type	Default	Description
`tables_only`	bool	False	Extract only tables from documents
`generic_query`	bool	False	Extract all available data without schema
`crop_size`	int	None	Pixels to crop from image borders
`apply_annotation`	bool	False	Include bounding box coordinates
`ocr_callback`	str	None	Callback for OCR
`debug_dir`	str	None	Directory to save debug images
`debug`	bool	False	Enable debug logging
`mode`	str	None	Set to "static" for mock responses

🔧 Troubleshooting

Common Issues

Import Errors:

# For MLX backend on non-Apple Silicon
pip install sparrow-parse --no-deps
pip install -r requirements.txt --exclude mlx-vlm

# For missing poppler
brew install poppler  # macOS
sudo apt-get install poppler-utils  # Ubuntu/Debian

Memory Issues:

Use smaller models or reduce image resolution
Enable image cropping to reduce processing load
Process single pages instead of entire PDFs

Model Loading Errors:

Verify model name and availability
Check HF token permissions for private models
Ensure sufficient disk space for model downloads

Performance Tips

Image Size: Resize large images before processing
Batch Processing: Process multiple pages together when possible
Model Selection: Choose appropriate model size for your hardware
Caching: Models are cached after first load

📚 API Reference

VLLMExtractor Class

class VLLMExtractor:
    def run_inference(
        self,
        model_inference_instance,
        input_data: List[Dict],
        tables_only: bool = False,
        generic_query: bool = False, 
        crop_size: Optional[int] = None,
        apply_annotation: bool = False,
        ocr_callback: Optional[str] = None, 
        debug_dir: Optional[str] = None,
        debug: bool = False,
        mode: Optional[str] = None
    ) -> Tuple[List[str], int]

InferenceFactory Class

class InferenceFactory:
    def __init__(self, config: Dict)
    def get_inference_instance(self) -> ModelInference

🏗️ Development

Building from Source

# Clone repository
git clone https://github.com/katanaml/sparrow.git
cd sparrow/sparrow-data/parse

# Create virtual environment
python -m venv .env_sparrow_parse
source .env_sparrow_parse/bin/activate  # Linux/Mac
# or
.env_sparrow_parse\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Build package
pip install setuptools wheel
python setup.py sdist bdist_wheel

# Install locally
pip install -e .

Running Tests

python -m pytest tests/

📄 Supported File Formats

Format	Extension	Multi-page	Notes
PNG	.png	❌	Recommended for tables/forms
JPEG	.jpg, .jpeg	❌	Good for photos/scanned docs
PDF	.pdf	✅	Automatically split into pages

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

📞 Support

📜 License

Commercial Licensing: Free for organizations with revenue under $5M USD annually. Contact us for commercial licensing options.

👥 Authors

Katana ML
Andrej Baranovskij

⭐ Star us on GitHub if you find Sparrow Parse useful!

Metadata

Release files for sparrow-parse 1.5.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sparrow-parse 1.5.8
File	Size	Uploaded
sparrow_parse-1.5.8.tar.gz	31.1 kB	Aug 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sparrow-parse 1.5.8
File	Interpreter	ABI	Platform	Reset
sparrow_parse-1.5.8-py3-none-any.whl 37.4 kB Aug 25, 2026	Python 3	none	any	Details

Total release size: 68.5 kB

Release files / sparrow_parse-1.5.8.tar.gz

Download URL	sparrow_parse-1.5.8.tar.gz
Size	31.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`eeaa866193cee802a4f5f6115ef0065459638403f4154e2482134df22e32932c`
BLAKE2b-256 checksum How to use checksums	`eca90952dcd28e1b11fad8d68cea315949aad9aff61a691deebdb85711019a39`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.10`

Release files / sparrow_parse-1.5.8-py3-none-any.whl

Download URL	sparrow_parse-1.5.8-py3-none-any.whl
Size	37.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f9b76fc0d0a4db1947a22f0473897d5f02c9d595447eaf6b6dc6f9736b261fd4`
BLAKE2b-256 checksum How to use checksums	`adba81f9119b2c54dcdefb7248b5097017a25e325dc2975edc4dd643118df831`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.10`