documente_shared 0.1.202__tar.gz → 0.1.203__tar.gz

{documente_shared-0.1.202 → documente_shared-0.1.203}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: documente_shared
-Version: 0.1.202
+Version: 0.1.203
 Summary: Shared utilities for LlamitAI projects
 Author-email: Tech <tech@llamitai.com>
 License: MIT

documente_shared-0.1.203/PR_DESCRIPTION.md

@@ -0,0 +1,46 @@
+## Summary
+
+`invoke_lambda` construía un cliente boto3 nuevo en cada llamada, con 60s de `read_timeout` y los reintentos por defecto de botocore. Contra lambdas largas eso producía invocaciones duplicadas: la conexión moría en el VPC endpoint, el cliente esperaba de más y reintentaba, ejecutando la misma función hasta 5 veces. Este PR corrige la configuración del cliente y agrega las primitivas para recuperar el resultado desde S3 cuando la conexión se corta.
+
+## What Changed
+
+**`infrastructure/lambdas.py`**
+- `read_timeout` por defecto de 60 → 350, alineado al idle timeout del VPC endpoint
+- `retries` explícito: modo `standard` con 1 reintento, en vez del `legacy` con 5 que regía por omisión
+- `connect_timeout` de 30 y `tcp_keepalive`
+- El cliente se cachea por configuración (`functools.cache`) en vez de construirse en cada invocación
+
+**`infrastructure/lambda_job_results.py`** (nuevo)
+- `build_job_result_key(job_id, step_name)`: reconstruye el `jobs/{job_id}/{step_name}.json` que usan las lambdas, para no depender de que la respuesta traiga el `output_uri`
+- `wait_for_job_result(...)`: espera ese archivo con timeout y backoff fijo
+- `await_job_result(...)`: la operación completa que usan los consumidores — valida `job_id`, arma el key, loguea y espera
+
+**`infrastructure/s3_bucket.py`**
+- `get_json()`: lectura donde la ausencia del objeto devuelve `None` en vez de ser un error
+
+**`domain/entities/layout.py`**
+- `PageRange.label`: la property que las lambdas ya usan para nombrar su salida en S3
+
+## Why
+
+Las invocaciones salen por un Interface VPC Endpoint, que descarta los flujos TCP ociosos a los **350 segundos**. Una invocación sincrónica deja el flujo completamente ocioso mientras la lambda trabaja, así que cualquier función que pase de ese umbral pierde la conexión.
+
+El corte es **silencioso**: el NLB no manda nada, y el RST aparece solo si alguien escribe sobre la conexión muerta — cosa que un cliente que solo espera la respuesta nunca hace. Así que boto3 no se entera hasta que vence su propio `read_timeout`, y ahí reintenta.
+
+Sin bloque `retries` rige el modo `legacy`, que son **5 intentos**, y `ReadTimeoutError` es reintentable. El resultado era hasta 5 ejecuciones de la misma función no idempotente.
+
+**Sobre los valores elegidos:**
+
+- **`read_timeout=350`**: esperar más solo demora una falla que ya ocurrió, porque pasado ese punto el flujo está muerto y la respuesta no puede llegar.
+- **`max_attempts=1`**: un read timeout ahora significa *la invocación sigue corriendo del otro lado*, así que reintentar la duplica. Se probó `0`, pero con ese valor la lambda no llegaba a ejecutarse en el entorno real.
+- **Cliente cacheado**: construir un cliente carga los modelos del servicio y arma un connection pool nuevo, así que un cliente descartable pagaba un handshake TLS completo por invocación — justo el tramo de red que venía fallando.
+
+**Sobre `get_json`:** `get_bytes` no sirve para preguntar si un objeto existe. Su decorador `retry_on_size_integrity` trata la ausencia como un error a reintentar: duerme y termina levantando `RuntimeError`. `get_json` deja la ausencia como respuesta válida, que es lo que necesita un poll.
+
+**Sobre `PageRange.label`:** la copia de la entidad en vnext-tools ya tenía esta property y la usa para nombrar el archivo de salida. Agregarla acá hace que las dos copias vuelvan a coincidir, en vez de que cada consumidor replique la derivación.
+
+## Notas para el reviewer
+
+- **La versión quedó en `0.1.203`, no `0.1.203b`.** El pin actual de `documente-core` es `documente-shared==0.1.203b`, que no matchea una versión estable. Hay que alinear los dos antes de mergear.
+- La versión `0.1.203b0` ya publicada **no** contiene estos cambios: se publicó desde un árbol anterior. Hace falta publicar de nuevo.
+- El diagnóstico completo, con los valores medidos y las alternativas descartadas (entre ellas TCP keepalive por sysctl, que infraestructura probó y no resuelve el corte), está en `docs/lambda-extractores-timeout-350s.md` del PR de `documente-core`.

{documente_shared-0.1.202 → documente_shared-0.1.203}/documente_shared/domain/entities/layout.py

@@ -75,3 +75,9 @@ class PageRange(BaseModel):
     end: Optional[int] = None
 
     model_config = ConfigDict(extra="ignore")
+
+    @property
+    def label(self) -> str:
+        start_page = self.start if self.start is not None else 1
+        end_page = self.end if self.end is not None else "end"
+        return f"{start_page}-{end_page}"

documente_shared-0.1.203/documente_shared/infrastructure/lambda_job_results.py

@@ -0,0 +1,59 @@
+import time
+
+import structlog
+
+from documente_shared.infrastructure.s3_bucket import S3Bucket
+
+logger = structlog.get_logger()
+
+DEFAULT_JOB_RESULT_TIMEOUT = 960
+DEFAULT_JOB_RESULT_POLL_INTERVAL = 5
+
+
+def build_job_result_key(job_id: str, step_name: str) -> str:
+    return f"jobs/{job_id}/{step_name}.json"
+
+
+def wait_for_job_result(
+    s3_bucket: S3Bucket,
+    job_result_key: str,
+    timeout_seconds: int = DEFAULT_JOB_RESULT_TIMEOUT,
+    poll_interval_seconds: float = DEFAULT_JOB_RESULT_POLL_INTERVAL,
+) -> dict:
+    deadline = time.monotonic() + timeout_seconds
+    while True:
+        job_result = s3_bucket.get_json(file_key=job_result_key)
+        if job_result is not None:
+            return job_result
+        if time.monotonic() >= deadline:
+            timeout_message = (
+                f"Lambda job result not found after {timeout_seconds}s: "
+                f"s3://{s3_bucket.bucket_name}/{job_result_key}"
+            )
+            raise TimeoutError(timeout_message)
+        time.sleep(poll_interval_seconds)
+
+
+def await_job_result(
+    s3_bucket: S3Bucket,
+    job_id: str,
+    step_name: str,
+    connection_error: Exception,
+) -> tuple[str, dict]:
+    """La conexion murio en el VPC endpoint, que corta los flujos ociosos a los 350s y lo hace en
+    silencio. La lambda del otro lado sigue corriendo y va a escribir su resultado igual, asi
+    que en vez de reinvocarla se espera ese archivo en el key determinstico."""
+
+    if not job_id:
+        missing_job_id_message = "job_id es obligatorio para recuperar el resultado desde S3."
+        raise ValueError(missing_job_id_message)
+
+    job_result_key = build_job_result_key(job_id=job_id, step_name=step_name)
+    logger.warning(
+        "[shared.lambda_job_result.awaiting]",
+        job_id=job_id,
+        job_result_key=job_result_key,
+        reason=type(connection_error).__name__,
+    )
+    job_result = wait_for_job_result(s3_bucket=s3_bucket, job_result_key=job_result_key)
+    return job_result_key, job_result

documente_shared-0.1.203/documente_shared/infrastructure/lambdas.py

@@ -0,0 +1,35 @@
+import json
+from functools import cache
+
+import boto3
+from botocore.config import Config
+
+# Las invocaciones salen por un VPC endpoint, que descarta los flujos ociosos a los 350s 
+DEFAULT_LAMBDA_READ_TIMEOUT = 350
+
+
+@cache
+def _get_lambda_client(read_timeout: int):
+    lambda_config = Config(
+        read_timeout=read_timeout,
+        connect_timeout=30,
+        tcp_keepalive=True,
+        retries={"max_attempts": 1, "mode": "standard"},
+    )
+    return boto3.client("lambda", config=lambda_config)
+
+
+def invoke_lambda(
+    function_name: str,
+    payload: dict,
+    read_timeout: int = DEFAULT_LAMBDA_READ_TIMEOUT,
+) -> dict | list | None:
+    client = _get_lambda_client(read_timeout)
+
+    response = client.invoke(
+        FunctionName=function_name,
+        InvocationType="RequestResponse",
+        Payload=json.dumps(payload),
+    )
+
+    return json.loads(response["Payload"].read().decode("utf-8"))

{documente_shared-0.1.202 → documente_shared-0.1.203}/documente_shared/infrastructure/s3_bucket.py

@@ -1,12 +1,18 @@
-import boto3
+import json
 
 from dataclasses import dataclass
 from typing import Optional
 
+import boto3
+from botocore.exceptions import ClientError
+
 from documente_shared.domain.entities.document import remove_slash_from_path
 from documente_shared.application.retry_utils import retry_on_size_integrity
 
 
+MISSING_OBJECT_ERROR_CODES = ("NoSuchKey", "404")
+
+
 def remove_none_values(data: dict) -> dict:  # noqa: WPS110
     return {key: value for key, value in data.items() if value is not None}  # noqa: WPS110
 
@@ -39,6 +45,18 @@ class S3Bucket(object):
             return None
         return file_context["Body"] if "Body" in file_context else None
 
+    def get_json(self, file_key: str) -> Optional[dict]:
+        # Sin el retry de get(): aca la ausencia del objeto es una respuesta valida y no algo que
+        # convenga reintentar, asi que se puede usar para preguntar si un resultado ya esta.
+        cleaned_file_key = remove_slash_from_path(file_key)
+        try:
+            file_context = self._resource.Object(self.bucket_name, cleaned_file_key).get()
+        except ClientError as client_error:
+            if client_error.response["Error"]["Code"] in MISSING_OBJECT_ERROR_CODES:
+                return None
+            raise
+        return json.loads(file_context["Body"].read().decode("utf-8"))
+
     def upload(self, file_key: str, file_content, content_type: Optional[str] = None):
         cleaned_file_key = remove_slash_from_path(file_key)
         optional_params = {"ContentType": content_type}

{documente_shared-0.1.202 → documente_shared-0.1.203}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "documente_shared"
-version = "0.1.202"
+version = "0.1.203"
 description = "Shared utilities for LlamitAI projects"
 authors = [{ name = "Tech", email = "tech@llamitai.com" }]
 license = { text = "MIT" }

{documente_shared-0.1.202 → documente_shared-0.1.203}/uv.lock

@@ -154,7 +154,7 @@ wheels = [
 
 [[package]]
 name = "documente-shared"
-version = "0.1.202"
+version = "0.1.203"
 source = { editable = "." }
 dependencies = [
     { name = "boto3" },
@@ -200,7 +200,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -263,17 +263,17 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-    { name = "decorator" },
-    { name = "exceptiongroup" },
-    { name = "jedi" },
-    { name = "matplotlib-inline" },
-    { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
-    { name = "prompt-toolkit" },
-    { name = "pygments" },
-    { name = "stack-data" },
-    { name = "traitlets" },
-    { name = "typing-extensions" },
+    { name = "colorama", marker = "python_full_version < '3.11' and sys_platform == 'win32'" },
+    { name = "decorator", marker = "python_full_version < '3.11'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "jedi", marker = "python_full_version < '3.11'" },
+    { name = "matplotlib-inline", marker = "python_full_version < '3.11'" },
+    { name = "pexpect", marker = "python_full_version < '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit", marker = "python_full_version < '3.11'" },
+    { name = "pygments", marker = "python_full_version < '3.11'" },
+    { name = "stack-data", marker = "python_full_version < '3.11'" },
+    { name = "traitlets", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/e5/61/1810830e8b93c72dcd3c0f150c80a00c3deb229562d9423807ec92c3a539/ipython-8.38.0.tar.gz", hash = "sha256:9cfea8c903ce0867cc2f23199ed8545eb741f3a69420bfcf3743ad1cec856d39", size = 5513996, upload-time = "2026-01-05T10:59:06.901Z" }
 wheels = [
@@ -288,17 +288,17 @@ resolution-markers = [
     "python_full_version >= '3.11'",
 ]
 dependencies = [
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-    { name = "decorator" },
-    { name = "ipython-pygments-lexers" },
-    { name = "jedi" },
-    { name = "matplotlib-inline" },
-    { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
-    { name = "prompt-toolkit" },
-    { name = "pygments" },
-    { name = "stack-data" },
-    { name = "traitlets" },
-    { name = "typing-extensions", marker = "python_full_version < '3.12'" },
+    { name = "colorama", marker = "python_full_version >= '3.11' and sys_platform == 'win32'" },
+    { name = "decorator", marker = "python_full_version >= '3.11'" },
+    { name = "ipython-pygments-lexers", marker = "python_full_version >= '3.11'" },
+    { name = "jedi", marker = "python_full_version >= '3.11'" },
+    { name = "matplotlib-inline", marker = "python_full_version >= '3.11'" },
+    { name = "pexpect", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit", marker = "python_full_version >= '3.11'" },
+    { name = "pygments", marker = "python_full_version >= '3.11'" },
+    { name = "stack-data", marker = "python_full_version >= '3.11'" },
+    { name = "traitlets", marker = "python_full_version >= '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version == '3.11.*'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a6/60/2111715ea11f39b1535bed6024b7dec7918b71e5e5d30855a5b503056b50/ipython-9.10.0.tar.gz", hash = "sha256:cd9e656be97618a0676d058134cd44e6dc7012c0e5cb36a9ce96a8c904adaf77", size = 4426526, upload-time = "2026-02-02T10:00:33.594Z" }
 wheels = [
@@ -310,7 +310,7 @@ name = "ipython-pygments-lexers"
 version = "1.1.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "pygments" },
+    { name = "pygments", marker = "python_full_version >= '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/ef/4c/5dd1d8af08107f88c7f741ead7a40854b8ac24ddf9ae850afbcf698aa552/ipython_pygments_lexers-1.1.1.tar.gz", hash = "sha256:09c0138009e56b6854f9535736f4171d855c8c08a563a0dcd8022f78355c7e81", size = 8393, upload-time = "2025-01-17T11:24:34.505Z" }
 wheels = [

documente_shared-0.1.202/documente_shared/infrastructure/lambdas.py

@@ -1,15 +0,0 @@
-import json
-import boto3
-from botocore.config import Config
-
-
-def invoke_lambda(function_name: str, payload: dict, read_timeout: int = 60) -> dict | list | None:
-    client = boto3.client("lambda", config=Config(read_timeout=read_timeout))
-
-    response = client.invoke(
-        FunctionName=function_name,
-        InvocationType="RequestResponse",
-        Payload=json.dumps(payload),
-    )
-
-    return json.loads(response["Payload"].read().decode("utf-8"))