How bytefer/ollama-ocr works
1. This is a small TypeScript/Node.js library, not an application server. Its main job is to take a local image file, send it to a running Ollama instance with a vision model, and return extracted text.
2. The primary public boundary is src/index.ts. That is the package entry point and the API surface consumers import from: the OCR function, default prompts, and the custom error types/codes referenced in the README.
3. src/config.ts centralizes the library’s defaults and policy values. Based on the README, this is where you’d expect the built-in OCR prompts, markdown prompt, supported image types, default model names, and any Ollama connection settings to live.
4. src/util.ts is the support layer for local pre-processing and validation. Its responsibilities are likely file/path checks, image-type validation, file reading/encoding, and small helpers used by the OCR pipeline.
5. The core runtime flow is: caller provides filePath plus optional model and systemPrompt -> the library validates the file -> reads the image from disk -> builds an Ollama vision request -> sends it to the local Ollama server -> returns the model’s text response.
6. The external service boundary is important here: the only networked dependency is a locally running Ollama server. The actual OCR capability comes from whichever vision model is installed in Ollama, such as llama3.2-vision or minicpm-v.
7. Input handling is intentionally narrow. The README says the library supports .jpg, .jpeg, and .png only, so format checking is part of the architecture rather than a loose runtime detail. Unsupported files should fail fast through the custom error system.
8. Error handling is a first-class subsystem. The documented LlamaOCRError and ErrorCode values separate failure modes such as missing file, unsupported type, Ollama connection/server issues, and OCR processing failures. That makes the library’s boundary behavior explicit for consumers.
9. Output formatting is driven by prompts rather than separate post-processing. There are at least two prompt modes: plain OCR and markdown-preserving OCR. That means text structure preservation is mostly delegated to the vision model through prompt engineering.
10. The test area is lightweight and fixture-based. test/images and test/test.txt indicate local sample inputs and expected-output-style assets, with test/index.test.ts likely covering the public API and error paths end to end against those fixtures.
11. There is no persistent storage, queue, auth layer, or web UI in this repo. The architecture is a single-package library with a simple dependency chain: consumer code -> OCR library -> filesystem + Ollama server -> text result.
12. For an architecture diagram, the key boxes are: application consumer, exported OCR library, config/constants, utility helpers, local image files, Ollama server, and installed vision model. The main data flow is one-way from file path to model request to extracted text, with errors branching back to the caller.
Main entry points: index.ts API entry · index.test.ts Test suite · util.ts Helpers · config.ts Defaults
Components 16
Public API
Package entry point and consumer-facing surface
- Consumer · Application or script importing the library
- API entry · Exports OCR function, prompts, and error types
src/index.ts - Errors · LlamaOCRError and ErrorCode boundary for failures
- Extracted text · OCR text returned to caller
OCR Runtime
Validation, request building, and model execution
- Defaults · Built-in prompts, model defaults, image types, and Ollama settings
src/config.ts - Helpers · File checks, image validation, encoding, and small pipeline helpers
src/util.ts - OCR flow · Validates input, builds request, and returns extracted text
- OCR prompt · Default extraction prompt
- Markdown prompt · Prompt tuned to preserve markdown structure
External Boundaries
Filesystem and Ollama dependencies
- Image path · Local jpg, jpeg, or png file path
- Filesystem · Reads and validates local image files
- Image file · Local image content sent to OCR
test/images - Ollama server · Running local Ollama API endpoint
- Vision model · Installed multimodal model such as llama3.2-vision or minicpm-v
Tests
Fixture-based verification of public behavior
- Test suite · Public API and error-path coverage
test/index.test.ts - Expected text · Sample output/reference text
test/test.txt
Connections 18
- Consumer → API entry: imports · Consumer uses the package entry point
- API entry → OCR flow: exposes · Public OCR function is exported from the package
- API entry → Defaults: re-exports · Default prompts and library constants are surfaced to consumers
- API entry → Errors: re-exports · Custom error types and codes are part of the public API
- OCR flow → Helpers: uses · Pipeline relies on helpers for validation and file handling
- OCR flow → Defaults: reads defaults · Uses built-in prompts, models, and policy values
- OCR flow → OCR prompt: selects · Default OCR prompt mode
- OCR flow → Markdown prompt: selects · Markdown-preserving prompt mode
- OCR flow → Image path: accepts · Input begins as a local file path
- Helpers → Filesystem: validates · Checks existence, extension, and readable file content
- Filesystem → Image file: reads · Local image bytes are loaded from disk
- OCR flow → Ollama server: requests · Sends vision OCR request to local Ollama server
- Ollama server → Vision model: runs · Installed model performs the OCR inference
- Vision model → Extracted text: returns · Model response is surfaced as extracted text
- OCR flow → Errors: throws · Unsupported type, missing file, connection, and processing failures
- Test suite → API entry: verifies · Exercises the public API boundary
- Test suite → Image file: uses · Fixture images drive end-to-end checks
- Test suite → Expected text: compares · Expected output-style fixture for assertions