csf-scraper-python 0.1.1__py3-none-any.whl

csf_scraper/image_readers/csf_image_extractor.py

@@ -0,0 +1,29 @@
+"""Puente entre una ruta de archivo y un motor de lectura de imágenes."""
+
+import asyncio
+
+from csf_scraper.image_readers.ports.image_reader_port import ImageReaderPort
+from csf_scraper.ports.rfc_cif_extractor_port import RfcCifExtractorPort
+from csf_scraper.rfc_cif_data import RfcCifData
+from csf_scraper.value_objects.csf_image import CsfImage
+
+
+class CsfImageExtractor(RfcCifExtractorPort):
+    """Implementa :class:`~csf_scraper.ports.RfcCifExtractorPort` con un motor.
+
+    Lee la imagen de ``path``, la valida como :class:`CsfImage` y delega en el
+    :class:`~csf_scraper.image_readers.ports.ImageReaderPort` inyectado. Sirve
+    para cualquier motor (LLM u OCR) y así todos los extractores de imagen
+    comparten el mismo contrato público: ``extract(path) -> RfcCifData``.
+
+    La lectura del archivo se hace con :func:`asyncio.to_thread` para no
+    bloquear el bucle de eventos, y el motor se espera con ``await``.
+    """
+
+    def __init__(self, reader: ImageReaderPort) -> None:
+        self._reader = reader
+
+    async def extract(self, path: str) -> RfcCifData:
+        """Devuelve el RFC y el idCIF de la imagen de CSF en ``path``."""
+        image = await asyncio.to_thread(CsfImage.new_from_path, path)
+        return await self._reader.read(image)

csf_scraper/image_readers/ports/__init__.py

@@ -0,0 +1,5 @@
+"""Puertos de los lectores de imagen."""
+
+from csf_scraper.image_readers.ports.image_reader_port import ImageReaderPort
+
+__all__ = ["ImageReaderPort"]

csf_scraper/image_readers/ports/image_reader_port.py

@@ -0,0 +1,37 @@
+"""Puerto que abstrae el motor de lectura de imágenes (LLM multimodal u OCR)."""
+
+from abc import ABC, abstractmethod
+
+from csf_scraper.rfc_cif_data import RfcCifData
+from csf_scraper.value_objects.csf_image import CsfImage
+
+
+class ImageReaderPort(ABC):
+    """Extrae el :class:`RfcCifData` de la imagen ya materializada de una CSF.
+
+    Este es el contrato de un **motor**, no de un origen: recibe una
+    :class:`~csf_scraper.value_objects.CsfImage` en memoria y nunca toca el
+    disco. Para leer desde una ruta se usa
+    :class:`~csf_scraper.image_readers.CsfImageExtractor`, que adapta este
+    puerto al contrato público
+    :class:`~csf_scraper.ports.RfcCifExtractorPort`.
+
+    Reglas del contrato:
+
+    - No lee archivos: toda la validación de formato la hace :class:`CsfImage`.
+    - Devuelve :class:`RfcCifData` con los value objects ya construidos.
+    - Las implementaciones de la librería reportan sus fallos con excepciones
+      de la librería; en particular
+      :class:`~csf_scraper.exceptions.image_reader.ImageReadingException`. Un
+      motor externo puede propagar sus propias excepciones.
+
+    Implementaciones: :class:`~csf_scraper.image_readers.adapters.llms.GeminiImageReader`
+    (hereda de :class:`~csf_scraper.image_readers.LlmImageReaderService` y de
+    este puerto; sirve de base para otros proveedores) o un pipeline de OCR
+    (OpenCV + Tesseract).
+    """
+
+    @abstractmethod
+    async def read(self, image: CsfImage) -> RfcCifData:
+        """Devuelve el RFC y el idCIF leídos de ``image``."""
+        ...

csf_scraper/image_readers/schemas/__init__.py

@@ -0,0 +1,5 @@
+"""Esquemas de respuesta que los motores de lectura deben producir."""
+
+from csf_scraper.image_readers.schemas.rfc_cif_schema import RfcCifSchema
+
+__all__ = ["RfcCifSchema"]

csf_scraper/image_readers/schemas/rfc_cif_schema.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel, Field
+
+
+class RfcCifSchema(BaseModel):
+    """Datos que el LLM debe devolver de una imagen de Constancia de Situación Fiscal (CSF).
+
+    Se usa como ``output_cls`` del programa multimodal de LlamaIndex, que
+    adjunta automáticamente al prompt el JSON Schema de esta clase.
+    """
+
+    rfc: str = Field(
+        min_length=1,
+        description=(
+            "Registro Federal de Contribuyentes (RFC) de la persona física o moral. "
+            "Ubicación en la imagen:\n"
+            "1. En el renglón 'RFC:' de la sección 'Datos de Identificación del "
+            "Contribuyente'.\n"
+            "2. Arriba del texto 'Registro Federal de Contribuyentes', a la derecha "
+            "del código QR.\n"
+            "3. Debajo del código de barras vertical del lado derecho del encabezado.\n"
+            "Formato: Cadena alfanumérica en mayúsculas de 12 caracteres (persona moral) o 13 "
+            "caracteres (persona física) sin espacios, guiones ni puntos.\n"
+            "Ejemplos válidos: 'SME2009297K7', 'MEPF050926N61', 'TME990513J64'."
+        ),
+    )
+    id_cif: str = Field(
+        min_length=1,
+        description=(
+            "Identificador de la Cédula de Identificación Fiscal (idCIF).\n"
+            "Ubicación en la imagen:\n"
+            "Se encuentra EXCLUSIVAMENTE dentro del recuadro de la 'CÉDULA DE "
+            "IDENTIFICACIÓN FISCAL' "
+            "(a la derecha del código QR), sobre la leyenda 'VALIDA TU INFORMACIÓN FISCAL', "
+            "antecedido por la etiqueta 'idCIF:'.\n"
+            "Formato: Extraer ÚNICAMENTE los números (de 8 a 13 dígitos consecutivos), "
+            "omitiendo el prefijo 'idCIF:', espacios, guiones o cualquier otro carácter.\n"
+            "Ejemplos válidos:\n"
+            "- Si dice 'idCIF: 20090374035', extraer únicamente '20090374035'.\n"
+            "- Si dice 'idCIF: 25020218873', extraer únicamente '25020218873'.\n"
+            "- Si dice 'idCIF: 15080334415', extraer únicamente '15080334415'."
+        ),
+    )

csf_scraper/image_readers/services/__init__.py

@@ -0,0 +1,18 @@
+"""Servicios compartidos por los adaptadores de lectura de imagen."""
+
+from csf_scraper.image_readers.adapters.llms.prompts import CSF_PROMPT, RETRY_PROMPT
+from csf_scraper.image_readers.services.llm_image_reader_service import (
+    MAX_RETRIES,
+    MAX_RETRY_BACKOFF,
+    RETRY_BACKOFF,
+    LlmImageReaderService,
+)
+
+__all__ = [
+    "CSF_PROMPT",
+    "MAX_RETRIES",
+    "MAX_RETRY_BACKOFF",
+    "RETRY_BACKOFF",
+    "RETRY_PROMPT",
+    "LlmImageReaderService",
+]

csf_scraper/image_readers/services/llm_image_reader_service.py

@@ -0,0 +1,328 @@
+"""Base común de los adaptadores de imagen basados en un LLM multimodal.
+
+:class:`LlmImageReaderService` concentra exactamente cinco responsabilidades y
+nada más:
+
+1. **Armado del prompt** — el texto canónico (:data:`CSF_PROMPT`) más la
+   realimentación del intento anterior cuando toca reintentar.
+2. **Armado de la imagen del mensaje** — la CSF viaja como un único
+   :class:`~llama_index.core.base.llms.types.ImageBlock`.
+3. **Reintentos por respuestas inválidas** — cuando los value objects
+   :class:`~csf_scraper.value_objects.Rfc` y
+   :class:`~csf_scraper.value_objects.IdCif` rechazan el formato de negocio, se
+   vuelve a interrogar al modelo pasándole el error como contexto.
+4. **Reintentos por errores de API** — cuando el proveedor responde que está
+   saturado, caído o inalcanzable, se vuelve a intentar tras una espera
+   creciente. El adaptador traduce las excepciones de su proveedor con
+   :meth:`LlmImageReaderService._translate_api_exception`, de modo que esta
+   clase —y el resto de la librería— nunca importe las excepciones de Gemini,
+   OpenAI, etc.
+5. **Parseo al DTO** — un :class:`~csf_scraper.image_readers.RfcCifSchema` ya
+   tipado se mapea a :class:`~csf_scraper.rfc_cif_data.RfcCifData`.
+
+Lo que **no** vive aquí es el transporte hacia el proveedor ni el acceso al
+sistema de archivos. Cada adaptador concreto (``GeminiImageReader``, …) crea su
+cliente de LlamaIndex, lo entrega como ``llm_provider`` y expone ``read()``
+delegando en el *método plantilla*
+:meth:`LlmImageReaderService._run_program`. Ese método arma la imagen y el
+prompt de cada intento, ejecuta el ``MultiModalLLMCompletionProgram`` mediante
+:meth:`LlmImageReaderService._image_to_schema` y mapea la respuesta a
+:class:`~csf_scraper.rfc_cif_data.RfcCifData`. La lectura desde una **ruta** la
+hace :class:`~csf_scraper.image_readers.CsfImageExtractor`, que adapta cualquier
+:class:`~csf_scraper.image_readers.ImageReaderPort` al contrato público
+:class:`~csf_scraper.ports.RfcCifExtractorPort`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import ClassVar, cast
+
+import httpx
+from llama_index.core.base.llms.types import ImageBlock
+from llama_index.core.llms.llm import LLM
+from llama_index.core.program import MultiModalLLMCompletionProgram
+
+from csf_scraper.exceptions.image_reader import (
+    CifFromImageNotFoundException,
+    ImageReaderApiException,
+    ImageReaderUnavailableException,
+    ImageReadingException,
+    RfcFromImageNotFoundException,
+)
+from csf_scraper.exceptions.value_objects import (
+    InvalidIdCifFormatException,
+    InvalidRfcFormatException,
+)
+from csf_scraper.image_readers.adapters.llms.prompts.llm_image_reader_prompt import (
+    CSF_PROMPT,
+    RETRY_PROMPT,
+)
+from csf_scraper.image_readers.schemas.rfc_cif_schema import RfcCifSchema
+from csf_scraper.rfc_cif_data import RfcCifData
+from csf_scraper.value_objects.csf_image import CsfImage
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+logger = logging.getLogger(__name__)
+
+#: Número de envíos al modelo antes de rendirse.
+MAX_RETRIES = 3
+
+#: Espera inicial, en segundos, antes de reintentar tras un error de API. Se
+#: duplica en cada intento (1, 2, 4, …) hasta :data:`MAX_RETRY_BACKOFF`.
+RETRY_BACKOFF = 1.0
+
+#: Tope de la espera entre reintentos, en segundos.
+MAX_RETRY_BACKOFF = 30.0
+
+#: Prompt canónico. Todos los adaptadores LLM parten de este texto.
+
+
+#: Errores provocados por la *respuesta* del modelo. Se reintentan
+#: realimentando el mensaje de error al prompt.
+_RESPONSE_ERRORS: tuple[type[Exception], ...] = (
+    InvalidRfcFormatException,
+    InvalidIdCifFormatException,
+    RfcFromImageNotFoundException,
+    CifFromImageNotFoundException,
+)
+
+#: Errores de transporte genéricos. ``TimeoutError``/``ConnectionError`` vienen
+#: de la stdlib y los de ``httpx`` los usan por igual todos los SDK de LLM que
+#: esta librería puede albergar; ninguno es específico de un proveedor.
+_TRANSPORT_ERRORS: tuple[type[Exception], ...] = (
+    TimeoutError,
+    ConnectionError,
+    httpx.TimeoutException,
+    httpx.TransportError,
+)
+
+
+class LlmImageReaderService(ABC):
+    """Base de los adaptadores de imagen basados en un LLM multimodal.
+
+    Aporta el *método plantilla* :meth:`_run_program`, que arma el prompt, arma
+    la imagen, ejecuta el programa multimodal del proveedor y mapea el resultado
+    a :class:`RfcCifData`, reintentando tanto cuando los value objects rechazan
+    el formato de negocio de los datos obtenidos como cuando la API del
+    proveedor falla de forma temporal.
+
+    El adaptador concreto hereda de esta clase e implementa
+    :class:`~csf_scraper.image_readers.ports.ImageReaderPort` exponiendo un
+    ``read()`` que delega en :meth:`_run_program` con su propio
+    ``llm_provider``::
+
+        class MiImageReader(LlmImageReaderService, ImageReaderPort):
+            @property
+            def provider(self) -> str:
+                return "mi-proveedor"
+
+            async def read(self, image):
+                return await self._run_program(
+                    image=image, llm_provider=self._llm_provider
+                )
+    """
+
+    #: Prompt base. Una subclase puede reescribirlo sin tocar la lógica.
+    prompt: ClassVar[str] = CSF_PROMPT
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        max_retries: int = MAX_RETRIES,
+        retry_backoff: float = RETRY_BACKOFF,
+    ) -> None:
+        if max_retries < 1:
+            raise ValueError(f"max_retries must be at least 1, got {max_retries}.")
+        if retry_backoff < 0:
+            raise ValueError(f"retry_backoff must be zero or positive, got {retry_backoff}.")
+        self._model = model
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+
+    @property
+    def model(self) -> str:
+        """Nombre del modelo con el que trabaja el adaptador."""
+        return self._model
+
+    @property
+    @abstractmethod
+    def provider(self) -> str:
+        """Identificador del proveedor (``"gemini"``, …)."""
+
+    async def _run_program(self, image: CsfImage, llm_provider: LLM) -> RfcCifData:
+        """Lee el RFC y el idCIF de ``image``, reintentando si hace falta.
+
+        Es el *método plantilla*: arma la imagen y el prompt de cada intento,
+        delega la ejecución del programa multimodal en :meth:`_image_to_schema`
+        y mapea la respuesta a :class:`RfcCifData`.
+
+        Se reintenta en dos casos:
+
+        - **Respuesta inválida**: los value objects rechazan el formato de
+          negocio. El error viaja de vuelta al prompt para que el modelo se
+          corrija.
+        - **Error de API reintentable**: el proveedor está saturado, caído o no
+          es alcanzable. Se espera un tiempo creciente (ver
+          :data:`RETRY_BACKOFF`) y se repite el *mismo* prompt, porque el
+          problema no está en la imagen ni en la respuesta.
+
+        Un error de API no reintentable (credenciales inválidas, petición mal
+        formada) o cualquier otra excepción inesperada se propaga de inmediato:
+        repetirla daría el mismo resultado.
+        """
+        image_documents = self._build_image_documents(image)
+
+        previous_error: str | None = None
+        last_error: Exception | None = None
+        last_cause: Exception | None = None
+
+        for attempt in range(1, self._max_retries + 1):
+            retry_prompt = self._build_prompt(previous_error=previous_error, attempt=attempt)
+
+            try:
+                schema = await self._image_to_schema(
+                    image_documents=image_documents,
+                    retry_prompt=retry_prompt,
+                    llm_provider=llm_provider,
+                )
+
+                return self._to_rfc_cif_data(schema)
+            except _RESPONSE_ERRORS as exception:
+                last_error = exception
+                previous_error = str(exception)
+                self._log_retry(attempt, exception)
+                # Sin espera: la corrección viaja en el prompt del reintento.
+                continue
+            except Exception as exception:
+                api_error = self._translate_api_exception(exception)
+                if api_error is None:
+                    raise ImageReadingException(
+                        f"The {self.provider} engine failed to read the image.",
+                        provider=self.provider,
+                        model=self.model,
+                    ) from exception
+                if not api_error.retryable:
+                    raise api_error from exception
+
+                last_error = api_error
+                last_cause = exception
+                # El error no proviene de la respuesta del modelo: se repite el
+                # prompt canónico en lugar de realimentar el fallo de la API.
+                previous_error = None
+                self._log_retry(attempt, api_error)
+
+            await self._wait_before_retry(attempt)
+
+        if last_error is not None:
+            raise last_error from last_cause
+        raise ImageReadingException(  # pragma: no cover - max_retries >= 1
+            f"The {self.provider} engine did not process the image.",
+            provider=self.provider,
+            model=self.model,
+        )
+
+    def _translate_api_exception(self, exception: Exception) -> ImageReaderApiException | None:
+        """Traduce una excepción del proveedor a una de la librería.
+
+        Es el punto de extensión de los adaptadores: cada uno mapea los tipos de
+        error de su SDK a :class:`ImageReaderApiException` (o a sus derivadas
+        :class:`ImageReaderUnavailableException` y
+        :class:`ImageReaderAuthenticationException`), marcando ``retryable``.
+
+        Devolver ``None`` significa «no sé qué es»: la plantilla envuelve la
+        excepción original en :class:`ImageReadingException` sin reintentar.
+
+        La implementación base solo reconoce los errores de transporte de la
+        stdlib, que no pertenecen a ningún proveedor en particular.
+        """
+        if isinstance(exception, _TRANSPORT_ERRORS):
+            return ImageReaderUnavailableException(
+                f"The {self.provider} service is not reachable.",
+                provider=self.provider,
+                model=self.model,
+            )
+        return None
+
+    async def _wait_before_retry(self, attempt: int) -> None:
+        """Espera un tiempo creciente entre intentos (1, 2, 4, … segundos).
+
+        No espera tras el último intento: ya no queda nada que reintentar.
+        """
+        if attempt >= self._max_retries:
+            return
+        delay = self._retry_delay(attempt)
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+    def _retry_delay(self, attempt: int) -> float:
+        """Segundos de espera antes del intento ``attempt + 1``.
+
+        Crece exponencialmente desde ``retry_backoff`` y se topa en
+        :data:`MAX_RETRY_BACKOFF` para no esperar indefinidamente.
+        """
+        if self._retry_backoff == 0:
+            return 0.0
+        return min(self._retry_backoff * float(2 ** (attempt - 1)), MAX_RETRY_BACKOFF)
+
+    async def _image_to_schema(
+        self,
+        image_documents: Sequence[ImageBlock],
+        retry_prompt: str,
+        llm_provider: LLM,
+    ) -> RfcCifSchema:
+        """Ejecuta el programa multimodal del proveedor para un intento."""
+        program = MultiModalLLMCompletionProgram.from_defaults(
+            output_cls=RfcCifSchema,
+            image_documents=list(image_documents),
+            prompt_template_str=retry_prompt,
+            multi_modal_llm=llm_provider,
+        )
+        return cast(RfcCifSchema, await program.acall())
+
+    def _build_image_documents(self, image: CsfImage) -> list[ImageBlock]:
+        """Convierte la CSF en el bloque de imagen que consume el programa."""
+        return [
+            ImageBlock(
+                image=image.as_bytes(),
+                image_mimetype=image.get_mime_type(),
+            )
+        ]
+
+    def _to_rfc_cif_data(self, schema: RfcCifSchema) -> RfcCifData:
+        """Mapea la respuesta tipada del modelo al DTO de la librería.
+
+        Delega el formato de negocio en :class:`Rfc` y :class:`IdCif`, cuyas
+        excepciones disparan el siguiente reintento.
+        """
+        rfc = schema.rfc.strip()
+        id_cif = schema.id_cif.strip()
+
+        if not rfc:
+            raise RfcFromImageNotFoundException("The LLM response does not contain an RFC value.")
+        if not id_cif:
+            raise CifFromImageNotFoundException("The LLM response does not contain an idCIF value.")
+
+        return RfcCifData(rfc=Rfc(rfc), id_cif=IdCif(id_cif))
+
+    def _build_prompt(self, *, previous_error: str | None, attempt: int) -> str:
+        """Devuelve el prompt del intento ``attempt``, con realimentación opcional."""
+        if previous_error is None:
+            return self.prompt
+        return self.prompt + RETRY_PROMPT.format(previous_attempt=attempt - 1, error=previous_error)
+
+    def _log_retry(self, attempt: int, exception: Exception) -> None:
+        if attempt >= self._max_retries:
+            return
+        logger.warning(
+            "The %s engine could not read the image (attempt %d/%d): %s",
+            self.provider,
+            attempt,
+            self._max_retries,
+            exception,
+        )

csf_scraper/pdf_reader/__init__.py

@@ -0,0 +1,7 @@
+"""Lectura de la Constancia de Situación Fiscal en PDF."""
+
+from csf_scraper.pdf_reader.csf_pdf_extractor import CsfPdfExtractor, PdfTextProvider
+from csf_scraper.pdf_reader.pdf_csf_text_parser import PdfCsfTextParser
+from csf_scraper.pdf_reader.pdf_to_text import PdfToText
+
+__all__ = ["CsfPdfExtractor", "PdfCsfTextParser", "PdfTextProvider", "PdfToText"]

csf_scraper/pdf_reader/csf_pdf_extractor.py

@@ -0,0 +1,33 @@
+"""Extracción del RFC y el idCIF a partir de un archivo PDF de CSF."""
+
+from typing import Protocol
+
+from csf_scraper.pdf_reader.pdf_csf_text_parser import PdfCsfTextParser
+from csf_scraper.pdf_reader.pdf_to_text import PdfToText
+from csf_scraper.ports.rfc_cif_extractor_port import RfcCifExtractorPort
+from csf_scraper.rfc_cif_data import RfcCifData
+
+
+class PdfTextProvider(Protocol):
+    """Fuente del texto de un PDF; permite sustituir ``pdftotext`` en los tests."""
+
+    async def extract(self, path: str) -> str:
+        """Devuelve el texto plano del PDF en ``path``."""
+        ...
+
+
+class CsfPdfExtractor(RfcCifExtractorPort):
+    """Implementa :class:`RfcCifExtractorPort` leyendo CSFs en PDF.
+
+    Convierte el PDF a texto (``pdftotext`` por omisión, de forma asíncrona) y
+    delega el *parsing* en :class:`PdfCsfTextParser`. El proveedor de texto se
+    puede inyectar para probar el extractor sin invocar el binario.
+    """
+
+    def __init__(self, text_provider: PdfTextProvider | None = None) -> None:
+        self._text_provider: PdfTextProvider = text_provider or PdfToText()
+
+    async def extract(self, path: str) -> RfcCifData:
+        """Devuelve el RFC y el idCIF del PDF en ``path``."""
+        contents = await self._text_provider.extract(path)
+        return PdfCsfTextParser(contents).extract()

csf_scraper/pdf_reader/pdf_csf_text_parser.py

@@ -0,0 +1,54 @@
+"""Análisis del texto de una CSF para obtener su RFC y su idCIF."""
+
+from csf_scraper.exceptions.pdf_reader import (
+    CifFromPdfNotFoundException,
+    EmptyPdfContentException,
+    RfcFromPdfNotFoundException,
+)
+from csf_scraper.rfc_cif_data import RfcCifData
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+
+class PdfCsfTextParser:
+    """Obtiene el RFC y el idCIF de las líneas de texto de una CSF.
+
+    Es la pieza de *parsing* pura: recibe el texto (salida de ``pdftotext``) y
+    no conoce el origen ni el binario. :class:`~csf_scraper.pdf_reader.CsfPdfExtractor`
+    lo combina con un proveedor de texto para implementar
+    :class:`~csf_scraper.ports.RfcCifExtractorPort`.
+    """
+
+    def __init__(self, contents: str) -> None:
+        if not contents:
+            raise EmptyPdfContentException("Cannot read pdf contents.")
+        self._lines = contents.split("\n")
+
+    def get_rfc(self) -> str | None:
+        """RFC encontrado tras la etiqueta ``RFC:``, o ``None`` si no existe."""
+        return self._clean_value(self._first_line_starting_with("RFC:"))
+
+    def get_cif_id(self) -> str | None:
+        """idCIF encontrado tras la etiqueta ``idCIF:``, o ``None`` si no existe."""
+        return self._clean_value(self._first_line_starting_with("idCIF:"))
+
+    def extract(self) -> RfcCifData:
+        """Devuelve el RFC y el idCIF validados de la CSF en texto."""
+        rfc = self.get_rfc()
+        cif = self.get_cif_id()
+
+        if rfc is None:
+            raise RfcFromPdfNotFoundException("Cannot obtain rfc from given PDF")
+        if cif is None:
+            raise CifFromPdfNotFoundException("Cannot obtain cif from given PDF")
+        return RfcCifData(rfc=Rfc(rfc), id_cif=IdCif(cif))
+
+    def _first_line_starting_with(self, prefix: str) -> str:
+        return next((line for line in self._lines if line.startswith(prefix)), "")
+
+    @staticmethod
+    def _clean_value(entry: str) -> str | None:
+        parts = entry.split(":")
+        if len(parts) < 2:
+            return None
+        return parts[1].strip()

csf_scraper/pdf_reader/pdf_to_text.py

@@ -0,0 +1,36 @@
+"""Conversión de PDF a texto mediante el binario ``pdftotext``."""
+
+import asyncio
+import subprocess
+
+from csf_scraper.exceptions.pdf_reader import PdfToTextConvertException
+
+
+class PdfToText:
+    """Extrae el contenido de un PDF usando ``pdftotext`` (paquete ``poppler-utils``)."""
+
+    def __init__(self, executable: str = "pdftotext") -> None:
+        self._executable = executable
+
+    async def extract(self, path: str) -> str:
+        """Devuelve el texto del PDF; lanza :class:`PdfToTextConvertException` si falla.
+
+        ``pdftotext`` es un proceso externo y bloqueante, así que se ejecuta en
+        un hilo aparte con :func:`asyncio.to_thread`; el bucle de eventos sigue
+        libre mientras el binario convierte el archivo.
+        """
+        command = self.build_command(path)
+        result = await asyncio.to_thread(subprocess.run, command, capture_output=True, check=False)
+        if result.returncode != 0:
+            raise PdfToTextConvertException(
+                f"Running pdftotext exit with error (exit code {result.returncode})",
+                command,
+                result.returncode,
+                result.stdout.decode("utf-8", errors="replace"),
+                result.stderr.decode("utf-8", errors="replace"),
+            )
+        return result.stdout.decode("utf-8", errors="replace")
+
+    def build_command(self, pdf_file: str) -> list[str]:
+        """Argumentos con los que se invoca a ``pdftotext``."""
+        return [self._executable, "-eol", "unix", "-raw", "-q", pdf_file, "-"]

csf_scraper/persona.py

@@ -0,0 +1,64 @@
+"""Modelo base para los datos fiscales de una persona."""
+
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from csf_scraper.date_parser import DateField
+from csf_scraper.regimen import Regimen
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+
+class Persona(BaseModel):
+    """Datos fiscales comunes a una persona moral o física."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    rfc: Rfc | None = None
+    id_cif: IdCif | None = None
+    fecha_inicio_operaciones: DateField = None
+    situacion_contribuyente: str = ""
+    fecha_ultimo_cambio_situacion: DateField = None
+    entidad_federativa: str = ""
+    municipio_delegacion: str = ""
+    colonia: str = ""
+    tipo_vialidad: str = ""
+    nombre_vialidad: str = ""
+    numero_exterior: str = ""
+    numero_interior: str = ""
+    codigo_postal: str = ""
+    correo_electronico: str = ""
+    al: str = ""
+    regimenes: list[Regimen] = Field(default_factory=list)
+    extra_data: dict[str, Any] = Field(default_factory=dict)
+
+    #: Títulos del HTML que se buscan y el campo (o clave de ``extra_data``) que alimentan.
+    field_titles: ClassVar[dict[str, str]] = {
+        "fecha_inicio_operaciones": "Fecha de Inicio de operaciones:",
+        "situacion_contribuyente": "Situación del contribuyente:",
+        "fecha_ultimo_cambio_situacion": "Fecha del último cambio de situación:",
+        "entidad_federativa": "Entidad Federativa:",
+        "municipio_delegacion": "Municipio o delegación:",
+        "colonia": "Colonia:",
+        "localidad": "Localidad:",
+        "tipo_vialidad": "Tipo de vialidad:",
+        "nombre_vialidad": "Nombre de la vialidad:",
+        "numero_exterior": "Número exterior:",
+        "numero_interior": "Número interior:",
+        "codigo_postal": "CP:",
+        "correo_electronico": "Correo electrónico:",
+        "al": "AL:",
+    }
+
+    def is_fisica(self) -> bool:
+        """Indica si la persona es física (RFC de 13 caracteres)."""
+        return self.rfc.is_fisica() if self.rfc is not None else False
+
+    def is_moral(self) -> bool:
+        """Indica si la persona es moral (RFC de 12 caracteres)."""
+        return self.rfc.is_moral() if self.rfc is not None else False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Devuelve los datos como un diccionario plano (envoltura de :meth:`model_dump`)."""
+        return self.model_dump()