betl 0.1.0__tar.gz

betl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published] # Se activará solo cuando publiques una Release en GitHub
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} # Llama al secreto seguro que guardamos
+      run: |
+        python -m twine upload dist/*

betl-0.1.0/.gitignore

@@ -0,0 +1,151 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before launching pyinstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.toml
+.cache
+.pytest_cache/
+.nofap
+.coverage
+.coverage.*
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the setups is
+#   specific to the developer, not the project.
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or fail.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#Poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm build standard temporary directory
+.pdm-build/
+
+# PEP 582 project packages
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

betl-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: betl
+Version: 0.1.0
+Summary: Una descripción corta de tu librería
+Project-URL: Homepage, https://github.com
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: ddddocr==1.6.1
+Requires-Dist: numpy==2.5.2
+Requires-Dist: opencv-contrib-python==4.10.0.84
+Requires-Dist: opencv-python==5.0.0.93
+Requires-Dist: paddleocr==3.7.0
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: pymupdf==1.28.2
+Requires-Dist: requests==2.34.2
+Description-Content-Type: text/markdown
+
+holamundo

betl-0.1.0/README.md

@@ -0,0 +1 @@
+holamundo

betl-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "betl"
+version = "0.1.0"
+description = "Una descripción corta de tu librería"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "ddddocr==1.6.1",
+    "numpy==2.5.2",
+    "opencv_contrib_python==4.10.0.84",
+    "opencv_python==5.0.0.93",
+    "paddleocr==3.7.0",
+    "pydantic==2.13.5",
+    "pymupdf==1.28.2",
+    "Requests==2.34.2",
+]
+[tool.hatch.build.targets.wheel]
+packages = ["src/core"]
+
+[project.urls]
+Homepage = "https://github.com"

betl-0.1.0/src/core/decorators/contract.py

@@ -0,0 +1,54 @@
+import inspect
+from typing import Optional, Dict, Any, Type
+from core.extractors.extraction_contract import ExtractionContract, ExtractionField
+
+# ==========================================
+# 2. Decorador de Clase (Ensamblador)
+# ==========================================
+def contract(
+    mapper_type: Optional[str] = None,
+    version: str = "1.0",
+    metadata: Optional[Dict[str, Any]] = None,
+):
+    """Decorador de clase que inyecta la configuración del ExtractionContract en la clase misma."""
+    def decorator(cls: Type) -> Type:
+        # Inyectamos los metadatos directamente en la clase para que 
+        # el método adaptar_a_dto pueda leer self._metadata
+        cls._metadata = metadata or {}
+        cls._metadata["mapper_type"] = mapper_type
+        cls._metadata["version"] = version
+        
+        contract_inst = ExtractionContract(
+            mapper_type=mapper_type, 
+            version=version, 
+            metadata=cls._metadata
+        )
+        cls_fields = {}
+
+        for attr_name, attr in inspect.getmembers(cls):
+            if hasattr(attr, "__extraction_field__"):
+                f_data = attr.__extraction_field__
+                cls_fields[f_data["name"]] = f_data
+                contract_inst.add_field(
+                    ExtractionField(
+                        name=f_data["name"],
+                        data_type=f_data["data_type"],
+                        description=f_data["description"],
+                        required=f_data["required"],
+                        regex=f_data["regex"],
+                        llm=f_data["llm"],
+                    )
+                )
+
+        cls._metadata["__fields_raw__"] = cls_fields
+        cls._extraction_contract = contract_inst # Guardamos la instancia del contrato internamente
+        
+        errores = contract_inst.validar()
+        if errores:
+            raise ValueError(f"Contrato declarativo '{cls.__name__}' inválido: {'; '.join(errores)}")
+
+        # Retornamos la CLASE original, ahora enriquecida. 
+        # Así, cuando MergerService haga `instancia = contrato()`, será una instancia de MiContratoRemate.
+        return cls
+
+    return decorator

betl-0.1.0/src/core/decorators/strategy.py

@@ -0,0 +1,40 @@
+import re
+from typing import Any, Callable, Dict, Optional
+from core.helpers.get_or_create_meta import _get_or_create_meta
+from core.extractors.extraction_contract import RegexObjective, LLMTarget
+
+
+# ==========================================
+# 3. Decoradores (Construcción del Contrato)
+# ==========================================
+def regex_strategy(pattern: str, flags: int = re.IGNORECASE, enabled: bool = True):
+    """Decorador para inyectar una regla de extracción basada en Regex."""
+    def decorator(func: Callable) -> Callable:
+        meta = _get_or_create_meta(func)
+        meta["regex"] = RegexObjective(enabled=enabled, pattern=pattern, flags=flags)
+        return func
+    return decorator
+
+def llm_strategy(
+    instruction: Optional[str] = None,
+    structure: Optional[Dict[str, Any]] = None,
+    enabled: bool = True,
+):
+    """Decorador para inyectar una instrucción o estructura objetivo para un LLM."""
+    def decorator(func: Callable) -> Callable:
+        meta = _get_or_create_meta(func)
+        meta["llm"] = LLMTarget(enabled=enabled, instruction=instruction, structure=structure)
+        return func
+    return decorator
+
+def campo(data_type: str = "string", description: Optional[str] = None, required: bool = False):
+    """Decorador para registrar propiedades base descriptivas del campo."""
+    def decorator(func: Callable) -> Callable:
+        meta = _get_or_create_meta(func)
+        meta.update({
+            "data_type": data_type,
+            "description": description,
+            "required": required,
+        })
+        return func
+    return decorator

betl-0.1.0/src/core/extractors/extraction_contract.py

@@ -0,0 +1,126 @@
+import re
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RegexObjective(BaseModel):
+    """Objetivo runtime de extracción mediante Regex. Solo describe QUÉ ejecutar."""
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    pattern: Optional[str] = None
+    flags: int = 0
+
+
+class LLMTarget(BaseModel):
+    """Objetivo runtime de extracción mediante LLM. Solo describe instrucción y estructura."""
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    instruction: Optional[str] = None
+    structure: Optional[Dict[str, Any]] = None
+
+
+class ExtractionField(BaseModel):
+    """Representa un campo objetivo de información a extraer."""
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    data_type: str = "string"
+    description: Optional[str] = None
+    required: bool = False
+    regex: Optional[RegexObjective] = None
+    llm: Optional[LLMTarget] = None
+
+
+class ExtractionContract(BaseModel):
+    """Contrato runtime que consolida los campos y estrategias de extracción."""
+    model_config = ConfigDict(extra="forbid")
+
+    mapper_type: Optional[str] = None
+    version: str = "1.0"
+    fields: Dict[str, ExtractionField] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    def add_field(self, field: ExtractionField) -> None:
+        """Agrega un campo al contrato normalizando su nombre."""
+        if not isinstance(field, ExtractionField):
+            raise TypeError("field debe ser una instancia de ExtractionField.")
+
+        nombre = field.name.strip()
+        if not nombre:
+            raise ValueError("El nombre del campo no puede estar vacío.")
+
+        if nombre in self.fields:
+            raise ValueError(f"El campo '{nombre}' ya existe en el ExtractionContract.")
+
+        if nombre != field.name:
+            field = field.model_copy(update={"name": nombre})
+
+        self.fields[nombre] = field
+
+    def get_field(self, nombre: str) -> Optional[ExtractionField]:
+        return self.fields.get(nombre)
+
+    def has_field(self, nombre: str) -> bool:
+        return nombre in self.fields
+
+    def count_fields(self) -> int:
+        return len(self.fields)
+
+    def get_regex_fields(self) -> Dict[str, ExtractionField]:
+        """Campos con estrategia Regex habilitada."""
+        return {
+            nombre: field
+            for nombre, field in self.fields.items()
+            if field.regex and field.regex.enabled
+        }
+
+    def get_llm_fields(self) -> Dict[str, ExtractionField]:
+        """Campos con estrategia LLM habilitada."""
+        return {
+            nombre: field
+            for nombre, field in self.fields.items()
+            if field.llm and field.llm.enabled
+        }
+
+    def validar(self) -> List[str]:
+        """Valida la consistencia interna y la validez sintáctica de las reglas."""
+        errores: List[str] = []
+
+        if not self.fields:
+            return ["El ExtractionContract no contiene campos."]
+
+        for nombre, field in self.fields.items():
+            nombre_limpio = nombre.strip()
+            
+            if not nombre_limpio:
+                errores.append("Existe un campo con nombre vacío en las llaves del contrato.")
+
+            if not field.name or not field.name.strip():
+                errores.append(f"El campo '{nombre}' tiene un atributo 'name' vacío.")
+            elif field.name.strip() != nombre_limpio:
+                errores.append(f"El nombre interno '{field.name}' no coincide con su clave '{nombre}'.")
+
+            if not field.data_type or not field.data_type.strip():
+                errores.append(f"El campo '{nombre}' no tiene especificado 'data_type'.")
+
+            # Validaciones para Regex
+            if field.regex and field.regex.enabled:
+                if not field.regex.pattern or not field.regex.pattern.strip():
+                    errores.append(f"El campo '{nombre}' tiene Regex habilitado pero 'pattern' está vacío.")
+                else:
+                    # Intento de compilación real para asegurar sintaxis
+                    try:
+                        re.compile(field.regex.pattern, field.regex.flags)
+                    except (re.error, ValueError, TypeError) as exc:
+                        errores.append(f"El campo '{nombre}' posee una Regex inválida ({field.regex.pattern}): {exc}")
+
+            # Validaciones para LLM
+            if field.llm and field.llm.enabled:
+                if not field.llm.instruction and not field.llm.structure:
+                    errores.append(
+                        f"El campo '{nombre}' tiene LLM habilitado pero carece de 'instruction' o 'structure'."
+                    )
+
+        return errores

betl-0.1.0/src/core/extractors/ocr/captcha.py

@@ -0,0 +1,120 @@
+import logging
+from pathlib import Path
+from typing import Union
+
+logger = logging.getLogger(__name__)
+
+
+class CaptchaExtractor:
+    """
+    Extractor especializado para CAPTCHAs.
+
+    Utiliza ddddocr cuando está disponible.
+
+    RESPONSABILIDAD
+    ---------------
+    Recibir una imagen CAPTCHA (bytes o ruta) y devolver el texto reconocido.
+    """
+
+    def __init__(self):
+        """
+        Inicializa ddddocr de manera opcional.
+        """
+        self.engine = None
+        self._inicializar()
+
+    # =====================================================================
+    # INICIALIZACIÓN
+    # =====================================================================
+
+    def _inicializar(self) -> None:
+        """
+        Inicializa el motor ddddocr.
+        """
+        try:
+            import ddddocr
+
+            self.engine = ddddocr.DdddOcr(show_ad=False)
+            logger.info("[CAPTCHA] Motor ddddocr inicializado correctamente.")
+
+        except Exception as exc:
+            logger.warning(
+                f"[CAPTCHA] ddddocr no está disponible: {exc}"
+            )
+            self.engine = None
+
+    # =====================================================================
+    # DISPONIBILIDAD
+    # =====================================================================
+
+    @property
+    def disponible(self) -> bool:
+        """
+        Indica si el motor CAPTCHA está disponible.
+        """
+        return self.engine is not None
+
+    # =====================================================================
+    # PUNTOS DE ENTRADA / EXTRAER
+    # =====================================================================
+
+    def resolver(self, image_input: Union[str, Path, bytes]) -> str:
+        """
+        Método de entrada flexible esperado por el orquestador.
+        Acepta rutas de archivo (str/Path) o bytes directamente.
+        """
+        if not image_input:
+            logger.warning("[CAPTCHA] Entrada vacía enviada a resolver().")
+            return ""
+
+        # Si recibe una ruta de archivo (str o Path)
+        if isinstance(image_input, (str, Path)):
+            path = Path(image_input)
+            if not path.is_file():
+                logger.error(f"[CAPTCHA] Archivo no encontrado: {path}")
+                return ""
+            try:
+                with open(path, "rb") as f:
+                    image_bytes = f.read()
+                return self.extraer(image_bytes)
+            except Exception as exc:
+                logger.error(f"[CAPTCHA] Error leyendo archivo de captcha: {exc}")
+                return ""
+
+        # Si ya son bytes directamente
+        elif isinstance(image_input, bytes):
+            return self.extraer(image_input)
+
+        else:
+            logger.error(f"[CAPTCHA] Tipo de entrada no soportado: {type(image_input)}")
+            return ""
+
+    def extraer(self, image_bytes: bytes) -> str:
+        """
+        Reconoce el texto de un CAPTCHA a partir de sus bytes.
+        """
+        if not image_bytes:
+            logger.warning("[CAPTCHA] Se recibió una imagen vacía.")
+            return ""
+
+        if not self.engine:
+            logger.warning("[CAPTCHA] El motor ddddocr no está disponible.")
+            return ""
+
+        try:
+            resultado = self.engine.classification(image_bytes)
+
+            if resultado is None:
+                return ""
+
+            texto = str(resultado).strip().upper()
+
+            logger.debug(
+                f"[CAPTCHA] CAPTCHA procesado exitosamente. Longitud={len(texto)}"
+            )
+
+            return texto
+
+        except Exception as exc:
+            logger.error(f"[CAPTCHA] Error procesando CAPTCHA: {exc}")
+            return ""