OCR cache

How the caches behave (what is stored, for how long, what is never stored) is described in Caching. Pass a cache as ocr_cache= to UnifiedDocumentLoader or to the convenience functions; the loader wraps its provider in CachedOCR.

doc2mark.create_ocr_cache(provider='none', *, redis_url=None, fallback='memory', ttl_seconds=3600, max_age_seconds=43200, max_refreshes=10, max_entries=1024, key_prefix='doc2mark:ocr:ocr-cache-v7', refusal_ttl_seconds=600.0)[source]

Create an OCR cache backend from a small provider name (refusal_ttl_seconds: see REFUSAL_TTL_SECONDS).

Parameters:

  • provider (str | None)

  • redis_url (str | None)

  • fallback (str)

  • ttl_seconds (float)

  • max_age_seconds (float | None)

  • max_refreshes (int | None)

  • max_entries (int)

  • key_prefix (str)

  • refusal_ttl_seconds (float)

Return type:

OCRCache | None

class doc2mark.OCRCache[source]

Bases: ABC

Interface for OCR result caches.

abstractmethod cleanup()[source]

Remove expired entries and return the number removed.

Return type:

int

abstractmethod clear()[source]

Clear all cached entries.

Return type:

None

abstractmethod get(key)[source]

Return a cached OCR result, or None on miss.

Parameters:

key (str)

Return type:

OCRResult | None

abstractmethod set(key, result, ttl_seconds=None)[source]

Store an OCR result, for ttl_seconds when given (then a hit does not extend it), else for the cache’s TTL.

Parameters:

  • key (str)

  • result (OCRResult)

  • ttl_seconds (float | None)

Return type:

None

abstractmethod stats()[source]

Return cache statistics.

Return type:

Dict[str, Any]

class doc2mark.MemoryOCRCache(ttl_seconds=3600, max_age_seconds=43200, max_entries=1024, max_refreshes=10, time_func=None, refusal_ttl_seconds=600.0)[source]

Bases: OCRCache

Thread-safe in-memory OCR cache with TTL, max-age, and refresh bounds.

Parameters:

  • ttl_seconds (float)

  • max_age_seconds (float | None)

  • max_entries (int)

  • max_refreshes (int | None)

  • time_func (Callable[[], float] | None)

  • refusal_ttl_seconds (float)

cleanup()[source]

Remove expired entries and return the number removed.

Return type:

int

clear()[source]

Clear all cached entries.

Return type:

None

get(key)[source]

Return a cached OCR result, or None on miss.

Parameters:

key (str)

Return type:

OCRResult | None

set(key, result, ttl_seconds=None)[source]

Store an OCR result, for ttl_seconds when given (then a hit does not extend it), else for the cache’s TTL.

Parameters:

  • key (str)

  • result (OCRResult)

  • ttl_seconds (float | None)

Return type:

None

stats()[source]

Return cache statistics.

Return type:

Dict[str, Any]

class doc2mark.RedisOCRCache(redis_url, ttl_seconds=3600, max_age_seconds=43200, max_refreshes=10, key_prefix='doc2mark:ocr:ocr-cache-v7', time_func=None, refusal_ttl_seconds=600.0)[source]

Bases: OCRCache

Redis-backed OCR cache.

Redis is imported lazily so doc2mark remains importable without the optional redis extra. The constructor verifies the connection with ping().

Parameters:

  • redis_url (str)

  • ttl_seconds (float)

  • max_age_seconds (float | None)

  • max_refreshes (int | None)

  • key_prefix (str)

  • time_func (Callable[[], float] | None)

  • refusal_ttl_seconds (float)

cleanup()[source]

Remove expired entries and return the number removed.

Return type:

int

clear()[source]

Clear all cached entries.

Return type:

None

get(key)[source]

Return a cached OCR result, or None on miss.

Parameters:

key (str)

Return type:

OCRResult | None

set(key, result, ttl_seconds=None)[source]

Store an OCR result, for ttl_seconds when given (then a hit does not extend it), else for the cache’s TTL.

Parameters:

  • key (str)

  • result (OCRResult)

  • ttl_seconds (float | None)

Return type:

None

stats()[source]

Return cache statistics.

Return type:

Dict[str, Any]

class doc2mark.NoOpOCRCache[source]

Bases: OCRCache

Cache implementation that always misses.

cleanup()[source]

Remove expired entries and return the number removed.

Return type:

int

clear()[source]

Clear all cached entries.

Return type:

None

get(key)[source]

Return a cached OCR result, or None on miss.

Parameters:

key (str)

Return type:

OCRResult | None

set(key, result, ttl_seconds=None)[source]

Store an OCR result, for ttl_seconds when given (then a hit does not extend it), else for the cache’s TTL.

Parameters:

  • key (str)

  • result (OCRResult)

  • ttl_seconds (float | None)

Return type:

None

stats()[source]

Return cache statistics.

Return type:

Dict[str, Any]

class doc2mark.ocr.cache.CachedOCR(wrapped, cache, cache_version='ocr-cache-v7')[source]

Bases: BaseOCR

OCR provider wrapper that checks a cache before calling the provider.

Parameters:
batch_process_images(images, **kwargs)[source]

Process multiple images in batch using LangChain.

This is the primary method for OCR processing. All implementations must use LangChain for efficient batch processing.

Parameters:

  • images (List[bytes]) – List of image data as bytes

  • **kwargs – Additional provider-specific options

Returns:

List of OCRResult objects in the same order as input

Return type:

List[OCRResult]