Ollama OCR

The Problem

Clients that need to extract structured text from scanned PDFs or images often rely on heavyweight OCR services or custom pipelines. Maintaining those pipelines, handling model selection, and scaling batch jobs can be time‑consuming, especially when the underlying code is hard to follow.

What This Does

Ollama-OCR provides a thin Python wrapper around Ollama vision‑language models. The core class lives in src/ollama_ocr/ocr_processor.py (OCRProcessor) and exposes process_image for single files and process_batch for directories. The Flask‑based driver in src/ollama_ocr/app.py offers a small CLI‑style entry point (main) that calls the processor, lists available models, and streams results. Installation is via pip install ollama-ocr and the requirements.txt file lists runtime dependencies.

How It Is Wired

Entry point – src/ollama_ocr/app.py:93 defines main. When invoked it:

1. Calls get_available_models (local) to query Ollama.
2. Instantiates OCRProcessor (from ocr_processor.py).
3. Dispatches to either process_single_image (line 65) or process_batch_images (line 79).

Core flow – process_single_image → process_image (in ocr_processor.py). process_image performs three internal calls (each resolved in the static graph):

After preprocessing, _encode_image builds a base‑64 payload and requests.post sends it to the Ollama API (base_url supplied at construction). The response is returned up the call chain to main.

Side effects – The only external interactions are:

• Filesystem – process_image may delete temporary files (os.remove).
• Network – a single POST request to the Ollama server per image.

Responsibility map

The import graph shows only three internal modules with a single import edge, so there are no circular dependencies. However, both ocr_processor.py and app.py contain deep nesting (max indentation depth 8), which inflates cognitive load and makes future changes riskier.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Ollama-OCR.git
cd Ollama-OCR

# Install runtime deps
pip install -r requirements.txt   # or pip install ollama-ocr (published package)

# Pull required Ollama models (as shown in README)
ollama pull llama3.2-vision:11b
ollama pull granite3.2-vision

Run the built‑in driver (the main function) directly:

python -m src.ollama_ocr.app
# or, from the repo root:
python src/ollama_ocr/app.py

For programmatic use, import the processor:

from ollama_ocr import OCRProcessor

ocr = OCRProcessor(
    model_name='llama3.2-vision:11b',
    base_url='http://localhost:11434/api/generate'
)
result = ocr.process_image(
    image_path='input/img.png',
    format_type='markdown',
    custom_prompt='Extract dates and names.',
    language='English'
)
print(result)

Real‑World Use

A document‑management service can drop incoming PDFs into the input/ folder, invoke OCRProcessor.process_batch via a scheduled job, and store the returned markdown in a searchable index. Because the processor talks to a local Ollama server, latency is low and no external API keys are required.

Code Health & Issues

• HIGH – Cognitive load – ocr_processor.py and app.py each have nesting depth 8. Refactor with early returns or helper functions to improve readability.
• MEDIUM – Dependabot missing – No .github/dependabot.yml; automated dependency updates are absent. Add a config to keep libraries patched.
• MEDIUM – No tests – Repository contains no tests/ directory; code paths are unverified.
• MEDIUM – No CI pipeline – No GitHub Actions or other CI files; builds are manual.
• LOW – No lockfile – requirements.txt is present without a requirements.lock or pipfile.lock, making reproducible installs harder.

The Bottom Line

Ollama-OCR delivers a usable wrapper around Ollama vision models with clear entry points and minimal external setup. The code works but suffers from deep nesting and a lack of automated testing or CI, which raises maintenance risk for production use. It is suitable for teams comfortable adding their own test suite and refactoring the control flow.