mistocr 0.1.5__tar.gz → 0.2.0__tar.gz

mistocr-0.2.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: mistocr
+Version: 0.2.0
+Summary: Simple batch OCR for PDFs using Mistral's state-of-the-art vision model
+Home-page: https://github.com/franckalbinet/mistocr
+Author: Solveit
+Author-email: nobody@fast.ai
+License: Apache Software License 2.0
+Keywords: nbdev jupyter notebook python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastcore
+Requires-Dist: mistralai
+Requires-Dist: pillow
+Requires-Dist: dotenv
+Requires-Dist: lisette
+Provides-Extra: dev
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# mistocr
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+**PDF OCR is a critical bottleneck in AI pipelines.** It’s often
+mentioned in passing, as if it’s a trivial step. Practice shows it’s far
+from it. Poorly converted PDFs mean garbage-in-garbage-out for
+downstream AI-system (RAG, …).
+
+When [Mistral AI](https://mistral.ai) released their [state-of-the-art
+OCR model](https://mistral.ai/fr/news/mistral-ocr) in March 2025, it
+opened new possibilities for large-scale document processing. While
+alternatives like [datalab.to](https://www.datalab.to) and
+[docling.ai](https://www.docling.ai) offer viable solutions, Mistral OCR
+delivers exceptional accuracy at a compelling price point.
+
+**mistocr** emerged from months of real-world usage across projects
+requiring large-scale processing of niche-domain PDFs. It addresses two
+fundamental challenges that raw OCR output leaves unsolved:
+
+- **Heading hierarchy restoration**: Even state-of-the-art OCR sometimes
+  produces inconsistent heading levels in large documents—a complex task
+  to get right. mistocr uses LLM-based analysis to restore proper
+  document structure, essential for downstream AI tasks.
+
+- **Visual content integration**: Charts, figures and diagrams are
+  automatically classified and described, then integrated into the
+  markdown. This makes visual information searchable and accessible for
+  downstream applications.
+
+- **Cost-efficient batch processing**: By exclusively using Mistral’s
+  batch API, mistocr cuts costs by 50% (\$0.50 vs \$1.00 per 1000 pages)
+  while eliminating the boilerplate code typically required.
+
+**In short**: Production-ready batch OCR with intelligent postprocessing
+that ensures your documents are actually usable for AI systems.
+
+## Get Started
+
+Install latest from [pypi](https://pypi.org/project/mistocr), then:
+
+``` sh
+$ pip install mistocr
+```
+
+Set your API keys:
+
+``` python
+import os
+os.environ['MISTRAL_API_KEY'] = 'your-key-here'
+os.environ['ANTHROPIC_API_KEY'] = 'your-key-here'  # for refine features (see Advanced Usage for other LLMs)
+```
+
+### Complete Pipeline
+
+Full pipeline with all features:
+
+``` python
+from mistocr.pipeline import pdf_to_md
+await pdf_to_md('files/test/resnet.pdf', 'files/test/md_test')
+```
+
+    Step 1/3: Running OCR on files/test/resnet.pdf...
+    Mistral batch job status: QUEUED
+    Mistral batch job status: RUNNING
+    Mistral batch job status: RUNNING
+    Step 2/3: Fixing heading hierarchy...
+    Step 3/3: Adding image descriptions...
+    Describing 7 images...
+    Saved descriptions to ocr_temp/resnet/img_descriptions.json
+    Adding descriptions to 12 pages...
+    Done! Enriched pages saved to files/test/md_test
+    Done!
+
+This will (as indicated by the output):
+
+1.  OCR the PDF using Mistral’s batch API
+2.  Fix heading hierarchy inconsistencies
+3.  Describe images (charts, diagrams) and add those descriptions into
+    the markdown Save everything to `files/test/md_test`
+
+The output structure will be:
+
+    files/test/md_test/
+    ├── img/
+    │   ├── img-0.jpeg
+    │   ├── img-1.jpeg
+    │   └── ...
+    ├── page_1.md
+    ├── page_2.md
+    └── ...
+
+Each page’s markdown will include inline image descriptions:
+
+```` markdown
+```markdown
+![Figure 1](img/img-0.jpeg)
+AI-generated image description:
+___
+A residual learning block...
+___
+```
+````
+
+To print the the processed markdown, you can use the
+[`read_pgs`](https://franckalbinet.github.io/mistocr/core.html#read_pgs)
+function. Here’s how:
+
+Then to read the fully processed document:
+
+``` python
+from mistocr.pipeline import read_pgs
+md = read_pgs('files/test/md_test')
+print(md[:500])
+```
+
+    # Deep Residual Learning for Image Recognition  ... page 1
+
+    Kaiming He Xiangyu Zhang Shaoqing Ren Jian Sun<br>Microsoft Research<br>\{kahe, v-xiangz, v-shren, jiansun\}@microsoft.com
+
+
+    ## Abstract ... page 1
+
+    Deeper neural networks are more difficult to train. We present a residual learning framework to ease the training of networks that are substantially deeper than those used previously. We explicitly reformulate the layers as learning residual functions with reference to the layer inputs, ins
+
+By default,
+[`read_pgs()`](https://franckalbinet.github.io/mistocr/core.html#read_pgs)
+joins all pages. Pass `join=False` to get a list of individual pages
+instead.
+
+### Advanced Usage
+
+**Batch process entire folders:**
+
+``` python
+from mistocr.core import ocr_pdf
+
+# Process all PDFs in a folder
+output_dirs = ocr_pdf('path/to/pdf_folder', dst='output_folder')
+```
+
+**Custom models and prompts for heading fixes:**
+
+``` python
+from mistocr.refine import fix_hdgs
+
+# Use a different model or custom prompt
+fix_hdgs('ocr_output/doc1', 
+         model='gpt-4o',
+         prompt=your_custom_prompt)
+```
+
+**Custom image description with rate limiting:**
+
+``` python
+from mistocr.refine import add_img_descs
+
+# Control API usage and customize descriptions
+await add_img_descs('ocr_output/doc1',
+                    model='claude-opus-4',
+                    semaphore=5,  # More concurrent requests
+                    delay=0.5)    # Shorter delay between calls
+```
+
+For complete control over each pipeline step, see the
+[core](https://fr.anckalbi.net/mistocr/core.html),
+[refine](https://fr.anckalbi.net/mistocr/refine.html), and
+[pipeline](https://fr.anckalbi.net/mistocr/pipeline.html) module
+documentation.
+
+## Known Limitations & Future Work
+
+`mistocr` is under active development. Current limitations include:
+
+- **No timeout on batch jobs**: Jobs poll indefinitely until completion.
+  If a job stalls, manual intervention is required.
+- **Limited error handling**: When batch jobs fail, error reporting and
+  recovery options are minimal.
+- **Progress monitoring**: Currently limited to periodic status prints.
+  Future versions will support callbacks or streaming updates for better
+  real-time monitoring.
+
+Contributions are welcome! If you encounter issues or have ideas for
+improvements, please open an issue or discussion on
+[GitHub](https://github.com/franckalbinet/mistocr).
+
+## Developer Guide
+
+If you are new to using `nbdev` here are some useful pointers to get you
+started.
+
+### Install mistocr in Development mode
+
+``` sh
+# make sure mistocr package is installed in development mode
+$ pip install -e .
+
+# make changes under nbs/ directory
+# ...
+
+# compile to have changes apply to mistocr
+$ nbdev_prepare
+```
+
+### Documentation
+
+Documentation can be found hosted on this GitHub
+[repository](https://github.com/franckalbinet/mistocr)’s
+[pages](https://franckalbinet.github.io/mistocr/). Additionally you can
+find package manager specific guidelines on
+[conda](https://anaconda.org/franckalbinet/mistocr) and
+[pypi](https://pypi.org/project/mistocr/) respectively.

mistocr-0.2.0/README.md

@@ -0,0 +1,213 @@
+# mistocr
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+**PDF OCR is a critical bottleneck in AI pipelines.** It’s often
+mentioned in passing, as if it’s a trivial step. Practice shows it’s far
+from it. Poorly converted PDFs mean garbage-in-garbage-out for
+downstream AI-system (RAG, …).
+
+When [Mistral AI](https://mistral.ai) released their [state-of-the-art
+OCR model](https://mistral.ai/fr/news/mistral-ocr) in March 2025, it
+opened new possibilities for large-scale document processing. While
+alternatives like [datalab.to](https://www.datalab.to) and
+[docling.ai](https://www.docling.ai) offer viable solutions, Mistral OCR
+delivers exceptional accuracy at a compelling price point.
+
+**mistocr** emerged from months of real-world usage across projects
+requiring large-scale processing of niche-domain PDFs. It addresses two
+fundamental challenges that raw OCR output leaves unsolved:
+
+- **Heading hierarchy restoration**: Even state-of-the-art OCR sometimes
+  produces inconsistent heading levels in large documents—a complex task
+  to get right. mistocr uses LLM-based analysis to restore proper
+  document structure, essential for downstream AI tasks.
+
+- **Visual content integration**: Charts, figures and diagrams are
+  automatically classified and described, then integrated into the
+  markdown. This makes visual information searchable and accessible for
+  downstream applications.
+
+- **Cost-efficient batch processing**: By exclusively using Mistral’s
+  batch API, mistocr cuts costs by 50% (\$0.50 vs \$1.00 per 1000 pages)
+  while eliminating the boilerplate code typically required.
+
+**In short**: Production-ready batch OCR with intelligent postprocessing
+that ensures your documents are actually usable for AI systems.
+
+## Get Started
+
+Install latest from [pypi](https://pypi.org/project/mistocr), then:
+
+``` sh
+$ pip install mistocr
+```
+
+Set your API keys:
+
+``` python
+import os
+os.environ['MISTRAL_API_KEY'] = 'your-key-here'
+os.environ['ANTHROPIC_API_KEY'] = 'your-key-here'  # for refine features (see Advanced Usage for other LLMs)
+```
+
+### Complete Pipeline
+
+Full pipeline with all features:
+
+``` python
+from mistocr.pipeline import pdf_to_md
+await pdf_to_md('files/test/resnet.pdf', 'files/test/md_test')
+```
+
+    Step 1/3: Running OCR on files/test/resnet.pdf...
+    Mistral batch job status: QUEUED
+    Mistral batch job status: RUNNING
+    Mistral batch job status: RUNNING
+    Step 2/3: Fixing heading hierarchy...
+    Step 3/3: Adding image descriptions...
+    Describing 7 images...
+    Saved descriptions to ocr_temp/resnet/img_descriptions.json
+    Adding descriptions to 12 pages...
+    Done! Enriched pages saved to files/test/md_test
+    Done!
+
+This will (as indicated by the output):
+
+1.  OCR the PDF using Mistral’s batch API
+2.  Fix heading hierarchy inconsistencies
+3.  Describe images (charts, diagrams) and add those descriptions into
+    the markdown Save everything to `files/test/md_test`
+
+The output structure will be:
+
+    files/test/md_test/
+    ├── img/
+    │   ├── img-0.jpeg
+    │   ├── img-1.jpeg
+    │   └── ...
+    ├── page_1.md
+    ├── page_2.md
+    └── ...
+
+Each page’s markdown will include inline image descriptions:
+
+```` markdown
+```markdown
+![Figure 1](img/img-0.jpeg)
+AI-generated image description:
+___
+A residual learning block...
+___
+```
+````
+
+To print the the processed markdown, you can use the
+[`read_pgs`](https://franckalbinet.github.io/mistocr/core.html#read_pgs)
+function. Here’s how:
+
+Then to read the fully processed document:
+
+``` python
+from mistocr.pipeline import read_pgs
+md = read_pgs('files/test/md_test')
+print(md[:500])
+```
+
+    # Deep Residual Learning for Image Recognition  ... page 1
+
+    Kaiming He Xiangyu Zhang Shaoqing Ren Jian Sun<br>Microsoft Research<br>\{kahe, v-xiangz, v-shren, jiansun\}@microsoft.com
+
+
+    ## Abstract ... page 1
+
+    Deeper neural networks are more difficult to train. We present a residual learning framework to ease the training of networks that are substantially deeper than those used previously. We explicitly reformulate the layers as learning residual functions with reference to the layer inputs, ins
+
+By default,
+[`read_pgs()`](https://franckalbinet.github.io/mistocr/core.html#read_pgs)
+joins all pages. Pass `join=False` to get a list of individual pages
+instead.
+
+### Advanced Usage
+
+**Batch process entire folders:**
+
+``` python
+from mistocr.core import ocr_pdf
+
+# Process all PDFs in a folder
+output_dirs = ocr_pdf('path/to/pdf_folder', dst='output_folder')
+```
+
+**Custom models and prompts for heading fixes:**
+
+``` python
+from mistocr.refine import fix_hdgs
+
+# Use a different model or custom prompt
+fix_hdgs('ocr_output/doc1', 
+         model='gpt-4o',
+         prompt=your_custom_prompt)
+```
+
+**Custom image description with rate limiting:**
+
+``` python
+from mistocr.refine import add_img_descs
+
+# Control API usage and customize descriptions
+await add_img_descs('ocr_output/doc1',
+                    model='claude-opus-4',
+                    semaphore=5,  # More concurrent requests
+                    delay=0.5)    # Shorter delay between calls
+```
+
+For complete control over each pipeline step, see the
+[core](https://fr.anckalbi.net/mistocr/core.html),
+[refine](https://fr.anckalbi.net/mistocr/refine.html), and
+[pipeline](https://fr.anckalbi.net/mistocr/pipeline.html) module
+documentation.
+
+## Known Limitations & Future Work
+
+`mistocr` is under active development. Current limitations include:
+
+- **No timeout on batch jobs**: Jobs poll indefinitely until completion.
+  If a job stalls, manual intervention is required.
+- **Limited error handling**: When batch jobs fail, error reporting and
+  recovery options are minimal.
+- **Progress monitoring**: Currently limited to periodic status prints.
+  Future versions will support callbacks or streaming updates for better
+  real-time monitoring.
+
+Contributions are welcome! If you encounter issues or have ideas for
+improvements, please open an issue or discussion on
+[GitHub](https://github.com/franckalbinet/mistocr).
+
+## Developer Guide
+
+If you are new to using `nbdev` here are some useful pointers to get you
+started.
+
+### Install mistocr in Development mode
+
+``` sh
+# make sure mistocr package is installed in development mode
+$ pip install -e .
+
+# make changes under nbs/ directory
+# ...
+
+# compile to have changes apply to mistocr
+$ nbdev_prepare
+```
+
+### Documentation
+
+Documentation can be found hosted on this GitHub
+[repository](https://github.com/franckalbinet/mistocr)’s
+[pages](https://franckalbinet.github.io/mistocr/). Additionally you can
+find package manager specific guidelines on
+[conda](https://anaconda.org/franckalbinet/mistocr) and
+[pypi](https://pypi.org/project/mistocr/) respectively.

mistocr-0.2.0/mistocr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{mistocr-0.1.5 → mistocr-0.2.0}/mistocr/_modidx.py

@@ -11,7 +11,7 @@ d = { 'settings': { 'branch': 'main',
                               'mistocr.core.create_batch_entry': ('core.html#create_batch_entry', 'mistocr/core.py'),
                               'mistocr.core.download_results': ('core.html#download_results', 'mistocr/core.py'),
                               'mistocr.core.get_api_key': ('core.html#get_api_key', 'mistocr/core.py'),
-                              'mistocr.core.ocr': ('core.html#ocr', 'mistocr/core.py'),
+                              'mistocr.core.ocr_pdf': ('core.html#ocr_pdf', 'mistocr/core.py'),
                               'mistocr.core.prep_pdf_batch': ('core.html#prep_pdf_batch', 'mistocr/core.py'),
                               'mistocr.core.read_pgs': ('core.html#read_pgs', 'mistocr/core.py'),
                               'mistocr.core.save_images': ('core.html#save_images', 'mistocr/core.py'),
@@ -20,12 +20,22 @@ d = { 'settings': { 'branch': 'main',
                               'mistocr.core.submit_batch': ('core.html#submit_batch', 'mistocr/core.py'),
                               'mistocr.core.upload_pdf': ('core.html#upload_pdf', 'mistocr/core.py'),
                               'mistocr.core.wait_for_job': ('core.html#wait_for_job', 'mistocr/core.py')},
+            'mistocr.pipeline': {'mistocr.pipeline.pdf_to_md': ('pipeline.html#pdf_to_md', 'mistocr/pipeline.py')},
             'mistocr.refine': { 'mistocr.refine.HeadingCorrections': ('refine.html#headingcorrections', 'mistocr/refine.py'),
+                                'mistocr.refine.ImgDescription': ('refine.html#imgdescription', 'mistocr/refine.py'),
+                                'mistocr.refine.add_descs_to_pg': ('refine.html#add_descs_to_pg', 'mistocr/refine.py'),
+                                'mistocr.refine.add_descs_to_pgs': ('refine.html#add_descs_to_pgs', 'mistocr/refine.py'),
+                                'mistocr.refine.add_img_descs': ('refine.html#add_img_descs', 'mistocr/refine.py'),
                                 'mistocr.refine.add_pg_hdgs': ('refine.html#add_pg_hdgs', 'mistocr/refine.py'),
                                 'mistocr.refine.apply_hdg_fixes': ('refine.html#apply_hdg_fixes', 'mistocr/refine.py'),
+                                'mistocr.refine.describe_img': ('refine.html#describe_img', 'mistocr/refine.py'),
+                                'mistocr.refine.describe_imgs': ('refine.html#describe_imgs', 'mistocr/refine.py'),
                                 'mistocr.refine.fix_hdg_hierarchy': ('refine.html#fix_hdg_hierarchy', 'mistocr/refine.py'),
-                                'mistocr.refine.fix_md_hdgs': ('refine.html#fix_md_hdgs', 'mistocr/refine.py'),
+                                'mistocr.refine.fix_hdgs': ('refine.html#fix_hdgs', 'mistocr/refine.py'),
                                 'mistocr.refine.fmt_hdgs_idx': ('refine.html#fmt_hdgs_idx', 'mistocr/refine.py'),
                                 'mistocr.refine.get_hdgs': ('refine.html#get_hdgs', 'mistocr/refine.py'),
+                                'mistocr.refine.limit': ('refine.html#limit', 'mistocr/refine.py'),
                                 'mistocr.refine.mk_fixes_lut': ('refine.html#mk_fixes_lut', 'mistocr/refine.py'),
-                                'mistocr.refine.read_pgs_pg': ('refine.html#read_pgs_pg', 'mistocr/refine.py')}}}
+                                'mistocr.refine.parse_r': ('refine.html#parse_r', 'mistocr/refine.py'),
+                                'mistocr.refine.read_pgs_pg': ('refine.html#read_pgs_pg', 'mistocr/refine.py'),
+                                'mistocr.refine.save_img_descs': ('refine.html#save_img_descs', 'mistocr/refine.py')}}}

{mistocr-0.1.5 → mistocr-0.2.0}/mistocr/core.py

@@ -4,7 +4,7 @@
 
 # %% auto 0
 __all__ = ['ocr_model', 'ocr_endpoint', 'get_api_key', 'upload_pdf', 'create_batch_entry', 'prep_pdf_batch', 'submit_batch',
-           'wait_for_job', 'download_results', 'save_images', 'save_page', 'save_pages', 'ocr', 'read_pgs']
+           'wait_for_job', 'download_results', 'save_images', 'save_page', 'save_pages', 'ocr_pdf', 'read_pgs']
 
 # %% ../nbs/00_core.ipynb 3
 from fastcore.all import *
@@ -79,10 +79,11 @@ def submit_batch(
 def wait_for_job(
     job:dict, # Job dict, 
     c:Mistral=None, # Mistral client, 
-    poll_interval:int=10 # Poll interval in seconds
+    poll_interval:int=1 # Poll interval in seconds
     ) -> dict: # Job dict (with status)  
     "Poll job until completion and return final job status"
     while job.status in ["QUEUED", "RUNNING"]:
+        print(f'Mistral batch job status: {job.status}')
         time.sleep(poll_interval)
         job = c.batch.jobs.get(job_id=job.id)
     return job
@@ -161,7 +162,7 @@ def _run_batch(entries:list[dict], c:Mistral, poll_interval:int=2) -> list[dict]
     return download_results(job, c)
 
 # %% ../nbs/00_core.ipynb 43
-def ocr(
+def ocr_pdf(
     path:str, # Path to PDF file or folder,
     dst:str='md', # Directory to save markdown pages, 
     inc_img:bool=True, # Include image in response, 
@@ -174,7 +175,7 @@ def ocr(
     results = _run_batch(entries, c, poll_interval)
     return L([save_pages(r['response']['body'], dst, r['custom_id']) for r in results])
 
-# %% ../nbs/00_core.ipynb 48
+# %% ../nbs/00_core.ipynb 47
 def read_pgs(
     path:str, # OCR output directory, 
     join:bool=True # Join pages into single string

mistocr-0.2.0/mistocr/pipeline.py

@@ -0,0 +1,37 @@
+"""End-to-End Pipeline: PDF OCR, Markdown Heading Correction, and AI Image Descriptions"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/02_pipeline.ipynb.
+
+# %% auto 0
+__all__ = ['pdf_to_md']
+
+# %% ../nbs/02_pipeline.ipynb 3
+from fastcore.all import *
+from .core import read_pgs, ocr_pdf
+from .refine import add_img_descs, fix_hdgs
+from pathlib import Path
+from asyncio import Semaphore, gather, sleep
+import os, json, shutil
+
+# %% ../nbs/02_pipeline.ipynb 4
+@delegates(add_img_descs)
+async def pdf_to_md(
+    pdf_path:str, # Path to input PDF file
+    dst:str, # Destination directory for output markdown
+    ocr_output:str=None, # Optional OCR output directory (defaults to pdf_path stem)
+    model:str='claude-sonnet-4-5', # Model to use for heading fixes and image descriptions
+    add_img_desc:bool=True, # Whether to add image descriptions
+    progress:bool=True, # Whether to show progress messages
+    **kwargs):
+    "Convert PDF to markdown with OCR, fixed heading hierarchy, and optional image descriptions"
+    n_steps = 3 if add_img_desc else 2
+    if progress: print(f"Step 1/{n_steps}: Running OCR on {pdf_path}...")
+    ocr_dirs = ocr_pdf(pdf_path, ocr_output or 'ocr_temp')
+    ocr_dir = ocr_dirs[0]
+    if progress: print(f"Step 2/{n_steps}: Fixing heading hierarchy...")
+    fix_hdgs(ocr_dir, model=model)
+    if add_img_desc:
+        if progress: print(f"Step 3/{n_steps}: Adding image descriptions...")
+        await add_img_descs(ocr_dir, dst=dst, model=model, progress=progress, **kwargs)
+    elif dst and Path(dst) != ocr_dir: shutil.copytree(ocr_dir, dst, dirs_exist_ok=True)
+    if progress: print("Done!")