ocrroute 0.8.0__py3-none-any.whl

AioOCR/__init__.py

@@ -0,0 +1,56 @@
+# coding=utf-8
+"""
+None
+"""
+from os.path import dirname, join, exists
+from inspect import getmembers, isclass
+from importlib import import_module
+from pkgutil import iter_modules
+
+# Import the base class for type checking.
+try:
+    from .engines.ocrplugin import OCRPlugin
+except:
+    from engines.ocrplugin import OCRPlugin
+
+# Dictionary to hold all discovered classes: {"ClassName": ClassObject}.
+AVAILABLE_PLUGINS = {}
+
+
+def _discoverOcrPlugins():
+    """
+    Dynamically loads all OCRPlugin subclasses from api/ and local/ packages.
+    """
+    for subPkg in ['api', 'local']:
+        packagePath = join(dirname(__file__), 'engines', subPkg)
+        if not exists(packagePath):
+            continue
+        # Iterate through all modules inside the subpackage directory.
+        for _, moduleName, isPkg in iter_modules([packagePath]):
+            if isPkg or moduleName.startswith("_"):
+                continue
+            fullModuleName = 'engines.{}.{}'.format(subPkg, moduleName)
+            try:
+                # Import the module relative to the root package.
+                try:
+                    module = import_module('.engines.{}.{}'.format(subPkg, moduleName), package=__package__)
+                except:
+                    module = import_module(fullModuleName, package=__package__)
+                # Inspect module members for OCRPlugin subclasses.
+                for name, obj in getmembers(module, isclass):
+                    # Check if it inherits from OCRPlugin (excluding OCRPlugin itself).
+                    if issubclass(obj, OCRPlugin) and obj is not OCRPlugin:
+                        # Ensure the class was defined in that module (not imported into it).
+                        if obj.__module__ == module.__name__:
+                            AVAILABLE_PLUGINS[name] = obj
+                            # Expose class at root level.
+                            globals()[name] = obj
+            except Exception as err:
+                # Optional: Handle or log import errors (e.g., missing local dependencies like easyocr, tesseract).
+                print('Warning: Could not import {}: {}'.format(fullModuleName, err))
+
+
+# Run plugin discovery
+_discoverOcrPlugins()
+# Export discovered plugin classes
+__all__ = list(AVAILABLE_PLUGINS.keys())

AioOCR/engines/__init__.py

@@ -0,0 +1,4 @@
+# coding=utf-8
+"""
+None
+"""

AioOCR/engines/api/__init__.py

@@ -0,0 +1,4 @@
+# coding=utf-8
+"""
+OCR API Modules.
+"""

AioOCR/engines/api/aimlapiocr.py

@@ -0,0 +1,195 @@
+# coding=utf-8
+"""
+AI/ML API OCR plugin (api.aimlapi.com/v1/ocr).
+AIMLAPI is a model aggregator: one API key gives access to hundreds of
+models, including Mistral's OCR line through a dedicated OCR route::
+    POST https://api.aimlapi.com/v1/ocr
+    Authorization: Bearer <key>
+    {"model": "mistral-ocr-latest", "document": {"type": "image_url", "image_url": "..."}}
+Setup: create a key at https://aimlapi.com/app/keys (new accounts get
+a small free allowance; paid plans unlock volume). Limits per the API
+schema: 50 MB per file, up to 1,000 pages.
+Available models: 'mistral-ocr-latest' (default), 'mistral-ocr-2512',
+'mistral-ocr-3'. The reply carries one markdown string per page plus
+page dimensions; the hosted generation returns NO text coordinates
+(bounding boxes exist only for extracted figures/images), so reading
+order is preserved with synthesized row boxes in the same unified
+structure as every other plugin -- if you need true text geometry
+from Mistral, use the direct ``mistralocr.py`` plugin whose OCR 4
+``include_blocks`` feature provides it.
+Local files, PIL images and raw bytes are sent inline as base64 data
+URIs; public URLs pass through untouched.
+"""
+from base64 import b64encode
+from os.path import dirname
+from requests import post
+from os import environ
+from sys import path
+from re import sub
+
+if dirname(__file__) not in path:
+    path.append(dirname(__file__))
+if dirname(dirname(__file__)) not in path:
+    path.append(dirname(dirname(__file__)))
+
+try:
+    from .ocrplugin import OCRPlugin, OCRError
+except:
+    from engines.ocrplugin import OCRPlugin, OCRError
+
+_ENDPOINT = 'https://api.aimlapi.com/v1/ocr'
+_MODELS = ('mistral-ocr-latest', 'mistral-ocr-2512', 'mistral-ocr-3')
+
+
+class AimlApiOcr(OCRPlugin):
+    """
+    AimlApiOcr class.
+    """
+    DEFAULT_MODEL = 'mistral-ocr-latest'
+    MODELS = _MODELS
+
+    def __init__(self, *args, **kwargs):
+        """
+        :param api: AIMLAPI key (or ``api=``, or the AIMLAPI_API_KEY environment variable).
+        :param model: OCR model id (default 'mistral-ocr-latest'; see _MODELS).
+        :param pages: optional list of 0-based page indices, or a string like '0,2-4' (PDFs).
+        :param docType: force 'document' or 'image' routing when the URL auto-detection guesses wrong.
+        :param includeImages: request extracted images as base64
+                                (default False; ignored by the unified structure anyway).
+        :param imageLimit: max images to extract (optional).
+        :param imageMinSize: min side of images to extract (optional).
+        :param image: image/PDF source (path, URL, PIL, bytes...).
+        :param kwargs: other settings (endpoint, timeout, retries, proxy...).
+        """
+        api = kwargs.pop('api', environ.get('AIMLAPI_API_KEY', ''))
+        model = kwargs.pop('model', 'mistral-ocr-latest')
+        if model not in _MODELS:
+            raise OCRError('Unknown model {!r}; choose from {}'.format(model, ', '.join(_MODELS)))
+        self.__m_pages = kwargs.pop('pages', None)
+        self.__m_docType = kwargs.pop('docType', None)
+        self.__m_includeImages = bool(kwargs.pop('includeImages', False))
+        self.__m_imageLimit = kwargs.pop('imageLimit', None)
+        self.__m_imageMinSize = kwargs.pop('imageMinSize', None)
+        kwargs.setdefault('timeout', 120)
+        kwargs.setdefault('endpoint', _ENDPOINT)
+        super(AimlApiOcr, self).__init__(*args, **kwargs)
+        self.setOnline(True)
+        self.setApi(api)
+        self.setModel(model)
+
+    # ------------------------------------------------------------------ #
+    # Document building.                                                 #
+    # ------------------------------------------------------------------ #
+    def _document(self):
+        kind = self.imageKind()
+        source = self.getImage()
+        if kind == 'url':
+            is_pdf = source.lower().split('?')[0].endswith('.pdf')
+            if self.__m_docType:
+                is_pdf = self.__m_docType == 'document'
+            if is_pdf:
+                return {'type': 'document_url', 'document_url': source}
+            return {'type': 'image_url', 'image_url': source}
+        if kind == 'array':
+            from io import BytesIO
+            from PIL import Image
+            buffer = BytesIO()
+            Image.fromarray(source).save(buffer, format='PNG')
+            data = buffer.getvalue()
+        elif kind in ('path', 'pil', 'bytes', 'buffer'):
+            data = self.imageBytes()
+        else:
+            raise OCRError(
+                "Image source '{}' is not an existing file, URL, or "
+                "supported type. Check the path (the current working "
+                "directory matters for relative paths).".format(source))
+        if len(data) > 50 * 1024 * 1024:
+            raise OCRError("File exceeds AIMLAPI's 50 MB limit.")
+        encoded = b64encode(data).decode('ascii')
+        if data[:5] == b'%PDF-':
+            return {'type': 'document_url', 'document_url': 'data:application/pdf;base64,' + encoded}
+        mime = ('image/jpeg' if data[:3] == b'\xff\xd8\xff' else 'image/png')
+        return {'type': 'image_url', 'image_url': 'data:{};base64,{}'.format(mime, encoded)}
+
+    # ------------------------------------------------------------------ #
+    # Result mapping                                                     #
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _field(obj, *names):
+        for name in names:
+            if isinstance(obj, dict) and name in obj:
+                return obj[name]
+            value = getattr(obj, name, None)
+            if value is not None:
+                return value
+        return None
+
+    @classmethod
+    def _markdownToRows(cls, markdown, start_row=0):
+        words = []
+        row = start_row
+        for line in (markdown or '').splitlines():
+            line = sub(r'^[#>\s]+', '', line)
+            line = sub(r'!\[[^\]]*\]\([^)]*\)', '', line)
+            line = sub(r'\|', ' ', line).strip()
+            if not line or set(line) <= set('-: '):
+                continue
+            words.append(cls.makeWord(line, 0.0, float(row * 10), 1.0, 8.0))
+            row += 1
+        return words
+
+    # ------------------------------------------------------------------ #
+    # OCR                                                                #
+    # ------------------------------------------------------------------ #
+    def _run(self, image, *args, **kwargs):
+        """
+        :return: list of word dicts for the base class to assemble.
+        """
+        if not self.getApi():
+            raise OCRError(
+                'No AIMLAPI key. Create one at '
+                'https://aimlapi.com/app/keys and pass api=... or set the AIMLAPI_API_KEY environment variable.')
+        body = {'model': self.getModel(), 'document': self._document()}
+        if self.__m_pages is not None:
+            body['pages'] = (list(self.__m_pages) if isinstance(self.__m_pages, (list, tuple)) else self.__m_pages)
+        if self.__m_includeImages:
+            body['include_image_base64'] = True
+        if self.__m_imageLimit is not None:
+            body['image_limit'] = int(self.__m_imageLimit)
+        if self.__m_imageMinSize is not None:
+            body['image_min_size'] = int(self.__m_imageMinSize)
+        request_kwargs = {
+            'json': body,
+            'headers': {
+                'Authorization': 'Bearer {}'.format(self.getApi()),
+                'Content-Type': 'application/json',
+            },
+            'timeout': self.getTimeout(),
+        }
+        if self.getProxy():
+            request_kwargs['proxies'] = self.getProxy()
+        reply = post(self.getEndpoint(), **request_kwargs)
+        if reply.status_code in (401, 403):
+            raise OCRError(
+                'AIMLAPI rejected the key (HTTP {}): check it at '
+                'https://aimlapi.com/app/keys. API said: {}'.format(reply.status_code, (reply.text or '')[:200]))
+        if reply.status_code == 402:
+            raise OCRError('AIMLAPI says the account is out of credits: top up at https://aimlapi.com. API said: ' + (
+                    reply.text or '')[:200])
+        if reply.status_code == 429:
+            raise OCRError('AIMLAPI rate limit hit: ' + (reply.text or '')[:200])
+        if not reply.ok:
+            raise OCRError('HTTP {} from AIMLAPI: {}'.format(reply.status_code, (reply.text or '')[:300].strip()))
+        payload = reply.json()
+        error = payload.get('error') if isinstance(payload, dict) else None
+        if error:
+            raise OCRError('AIMLAPI error: {}'.format(str(error)[:300]))
+        pages = self._field(payload, 'pages') or []
+        pages = sorted(pages, key=lambda p: self._field(p, 'index') or 0)
+        words = []
+        for page in pages:
+            markdown = self._field(page, 'markdown') or ''
+            words.extend(self._markdownToRows(markdown, start_row=len(words)))
+        if not words:
+            raise OCRError('AIMLAPI OCR returned no text for this document.')
+        return words

AioOCR/engines/api/apininjasocr.py

@@ -0,0 +1,182 @@
+# coding=utf-8
+"""
+API Ninjas Image-to-Text OCR plugin
+(https://api-ninjas.com/api/imagetotext).
+API Ninjas is an API marketplace; its Image to Text endpoint does OCR
+with word-level bounding boxes::
+    POST https://api.api-ninjas.com/v1/imagetotext
+    X-Api-Key: <key>
+    multipart: image=<JPEG or PNG file>
+Setup: sign up free at https://api-ninjas.com to get an API key
+instantly, then pass it as ``api=`` or set the API_NINJAS_API_KEY
+environment variable.
+Know the limits going in: the endpoint accepts ONLY JPEG/PNG (this
+plugin auto-converts other raster formats and rejects PDFs), free
+accounts can upload images up to 200 KB each (5 MB on premium), and
+commercial use requires a premium subscription.
+The reply is a JSON array of detections::
+    [{"text": "API", "bounding_box": {"x1": 60, "y1": 72, "x2": 163, "y2": 118}}, ...]
+-- word-level PIXEL coordinates (OCR.Space granularity), mapped
+straight into the exact unified structure shared by every plugin.
+"""
+from os.path import dirname
+from requests import post
+from os import environ
+from sys import path
+
+if dirname(__file__) not in path:
+    path.append(dirname(__file__))
+if dirname(dirname(__file__)) not in path:
+    path.append(dirname(dirname(__file__)))
+
+try:
+    from .ocrplugin import OCRPlugin, OCRError
+except:
+    from engines.ocrplugin import OCRPlugin, OCRError
+
+_ENDPOINT = 'https://api.api-ninjas.com/v1/imagetotext'
+_FREE_LIMIT = 200 * 1024  # 200 KB on the free tier.
+_PREMIUM_LIMIT = 5 * 1024 * 1024  # 5 MB on premium.
+
+
+class ApiNinjasOcr(OCRPlugin):
+    """
+    ApiNinjasOcr class.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """
+        :param api: API Ninjas key (or ``api=``, or the API_NINJAS_API_KEY environment variable).
+        :param image: image source (path, URL, PIL, bytes...).
+        :param kwargs: other settings (endpoint override, timeout, retries, proxy...).
+        """
+        api = kwargs.pop('api', environ.get('API_NINJAS_API_KEY', ''))
+        kwargs.setdefault('endpoint', _ENDPOINT)
+        kwargs.setdefault('timeout', 60)
+        super(ApiNinjasOcr, self).__init__(*args, **kwargs)
+        self.setOnline(True)
+        self.setApi(api)
+
+    # ------------------------------------------------------------------ #
+    # Request building                                                   #
+    # ------------------------------------------------------------------ #
+    def _fileTuple(self):
+        """
+        Multipart 'image' as JPEG/PNG (the only accepted formats).
+        """
+        kind = self.imageKind()
+        if kind == 'url':
+            from requests import get
+            reply = get(self.getImage(), timeout=self.getTimeout())
+            reply.raise_for_status()
+            data = reply.content
+        elif kind == 'array':
+            from io import BytesIO
+            from PIL import Image
+            buffer = BytesIO()
+            Image.fromarray(self.getImage()).save(buffer, format='PNG')
+            data = buffer.getvalue()
+        elif kind in ('path', 'pil', 'bytes', 'buffer'):
+            data = self.imageBytes()
+        else:
+            raise OCRError(
+                "Image source '{}' is not an existing file, URL, or "
+                "supported type. Check the path (the current working "
+                "directory matters for relative paths).".format(self.getImage()))
+        if data[:5] == b'%PDF-':
+            raise OCRError(
+                'API Ninjas imagetotext accepts only JPEG/PNG images, '
+                'not PDFs. Convert the page to an image first, or use '
+                'a PDF-capable plugin (MistralOcr, GlmOcr, OlmOcr).')
+        if data[:3] == b'\xff\xd8\xff':
+            name, mime = 'image.jpg', 'image/jpeg'
+        elif data[:8] == b'\x89PNG\r\n\x1a\n':
+            name, mime = 'image.png', 'image/png'
+        else:
+            # Other raster formats (webp, bmp, gif...): convert to PNG.
+            from io import BytesIO
+            from PIL import Image
+            buffer = BytesIO()
+            Image.open(BytesIO(data)).convert('RGB').save(buffer, format='PNG')
+            data = buffer.getvalue()
+            name, mime = 'image.png', 'image/png'
+        if len(data) > _PREMIUM_LIMIT:
+            raise OCRError(
+                'Image is {:.1f} MB but API Ninjas accepts at most '
+                '5 MB (premium) / 200 KB (free tier). Downscale or recompress it first.'.format(len(data) / 1048576.0))
+        return name, data, mime
+
+    # ------------------------------------------------------------------ #
+    # Result mapping                                                     #
+    # ------------------------------------------------------------------ #
+    def _wordsFromReply(self, payload):
+        """
+        [{text, bounding_box:{x1,y1,x2,y2}}] -> unified word dicts.
+        Coordinates are coerced with float(): sister endpoints have
+        been seen returning them as strings.
+        """
+        words = []
+        for entry in payload if isinstance(payload, list) else []:
+            if not isinstance(entry, dict):
+                continue
+            text = str(entry.get('text', '')).strip()
+            if not text:
+                continue
+            box = entry.get('bounding_box') or {}
+            try:
+                x1 = float(box['x1'])
+                y1 = float(box['y1'])
+                x2 = float(box['x2'])
+                y2 = float(box['y2'])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if x2 <= x1 or y2 <= y1:
+                continue
+            words.append(self.makeWord(
+                text, x1, y1, x2 - x1, y2 - y1))
+        return words
+
+    # ------------------------------------------------------------------ #
+    # OCR                                                                #
+    # ------------------------------------------------------------------ #
+    def _run(self, image, *args, **kwargs):
+        """
+        :return: list of word dicts for the base class to assemble (WORD-level pixel boxes; the base class groups them
+                 into lines geometrically).
+        """
+        if not self.getApi():
+            raise OCRError(
+                'No API Ninjas key. Sign up free at https://api-ninjas.com to get one instantly, then '
+                'pass api=... or set the API_NINJAS_API_KEY environment variable.')
+        name, data, mime = self._fileTuple()
+        request_kwargs = {'files': {'image': (name, data, mime)}, 'headers': {'X-Api-Key': self.getApi()},
+                          'timeout': self.getTimeout()}
+        if self.getProxy():
+            request_kwargs['proxies'] = self.getProxy()
+        reply = post(self.getEndpoint(), **request_kwargs)
+        if reply.status_code in (401, 403):
+            raise OCRError(
+                'API Ninjas rejected the key (HTTP {}): check it in '
+                'your account at https://api-ninjas.com. API said: {}'.format(
+                    reply.status_code, (reply.text or '')[:200]))
+        if reply.status_code == 400 and len(data) > _FREE_LIMIT:
+            raise OCRError(
+                'API Ninjas rejected the upload (HTTP 400). The image '
+                'is {:.0f} KB; free accounts are limited to 200 KB '
+                'per image (5 MB on premium) -- recompress/downscale '
+                'it or upgrade. API said: {}'.format(len(data) / 1024.0, (reply.text or '')[:200]))
+        if reply.status_code == 429:
+            raise OCRError('API Ninjas rate limit hit: ' + (reply.text or '')[:200])
+        if not reply.ok:
+            raise OCRError('HTTP {} from API Ninjas: {}'.format(
+                reply.status_code, (reply.text or '')[:300].strip()))
+        try:
+            payload = reply.json()
+        except ValueError:
+            raise OCRError('API Ninjas returned a non-JSON reply: ' + (reply.text or '')[:200])
+        if isinstance(payload, dict) and payload.get('error'):
+            raise OCRError('API Ninjas error: {}'.format(str(payload['error'])[:250]))
+        words = self._wordsFromReply(payload)
+        if not words:
+            raise OCRError('API Ninjas found no text in this image.')
+        return words