ergon-framework-python 0.2.5__tar.gz → 0.3.1__tar.gz

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ergon-framework-python
-Version: 0.2.5
+Version: 0.3.1
 Summary: Ergon internal task-oriented project bootstrapper
 Author-email: Ergondata Technologies <anza.vossos@protonmail.com>
 License-Expression: MIT
@@ -29,7 +29,7 @@ Requires-Dist: aio-pika>=9.0.0; extra == "all"
 Requires-Dist: aiobotocore>=2.13.0; extra == "all"
 Requires-Dist: asyncpg>=0.29.0; extra == "all"
 Requires-Dist: boto3>=1.35.0; extra == "all"
-Requires-Dist: ergon-platform-sdk<0.5,>=0.2.0; extra == "all"
+Requires-Dist: ergon-platform-sdk<0.6,>=0.5.1; extra == "all"
 Requires-Dist: httpx>=0.28.0; extra == "all"
 Requires-Dist: msal>=1.37.0; extra == "all"
 Requires-Dist: nylas>=6.0.0; extra == "all"
@@ -37,7 +37,7 @@ Requires-Dist: openpyxl>=3.1.5; extra == "all"
 Requires-Dist: pika>=1.3.0; extra == "all"
 Requires-Dist: requests>=2.32.5; extra == "all"
 Provides-Extra: ergon-platform
-Requires-Dist: ergon-platform-sdk<0.5,>=0.2.0; extra == "ergon-platform"
+Requires-Dist: ergon-platform-sdk<0.6,>=0.5.1; extra == "ergon-platform"
 Requires-Dist: httpx>=0.28.0; extra == "ergon-platform"
 Provides-Extra: excel
 Requires-Dist: openpyxl>=3.1.5; extra == "excel"

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ergon-framework-python"
-version = "0.2.5"
+version = "0.3.1"
 description = "Ergon internal task-oriented project bootstrapper"
 readme = "README.md"
 license = "MIT"
@@ -34,7 +34,7 @@ all = [
     "aiobotocore>=2.13.0",
     "asyncpg>=0.29.0",
     "boto3>=1.35.0",
-    "ergon-platform-sdk>=0.2.0,<0.5",
+    "ergon-platform-sdk>=0.5.1,<0.6",
     "httpx>=0.28.0",
     "msal>=1.37.0",
     "nylas>=6.0.0",
@@ -43,7 +43,7 @@ all = [
     "requests>=2.32.5",
 ]
 "ergon-platform" = [
-    "ergon-platform-sdk>=0.2.0,<0.5",
+    "ergon-platform-sdk>=0.5.1,<0.6",
     "httpx>=0.28.0",
 ]
 excel = ["openpyxl>=3.1.5"]

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/__init__.py

@@ -10,4 +10,4 @@ __all__ = [
     "manager",
 ]
 
-__version__ = "0.2.5"
+__version__ = "0.3.1"

ergon_framework_python-0.3.1/src/ergon/connector/ergon_platform/_client.py

@@ -0,0 +1,52 @@
+import os
+import socket
+from typing import Optional
+
+from .models import ErgonPlatformClient
+
+_ERGON_PLATFORM_IMPORT_ERROR = (
+    "The 'ergon-platform' connector dependencies are not installed. "
+    "Install them with: pip install 'ergon-framework-python[ergon-platform]'"
+)
+
+
+def _get_ergon_client():
+    try:
+        from ergon_platform import ErgonClient  # type: ignore[reportMissingImports]
+    except ImportError as exc:
+        raise ImportError(_ERGON_PLATFORM_IMPORT_ERROR) from exc
+    return ErgonClient
+
+
+def default_consumer_id() -> str:
+    """One identity per worker process: ``<hostname>:<pid>``.
+
+    Pull only phases fence item claims by this value; two processes must never
+    share it, two batches of the same process should.
+    """
+    host = socket.gethostname().split(".")[0] or "worker"
+    safe_host = "".join(ch if (ch.isalnum() or ch in "._:@-") else "-" for ch in host)
+    return f"{safe_host}:{os.getpid()}"[:128]
+
+
+def create_ergon_client(config: ErgonPlatformClient, *, consumer_id: Optional[str] = None):
+    """Build the SDK client. ``consumer_id`` adds ``X-Ergon-Consumer-Id`` to every request."""
+    ErgonClient = _get_ergon_client()
+    if consumer_id is None:
+        return ErgonClient(
+            client_id=config.client_id,
+            client_secret=config.client_secret,
+            base_url=config.base_url,
+            company_id=config.company_id,
+            timeout=config.timeout,
+            max_retries=config.max_retries,
+        )
+    return ErgonClient(
+        client_id=config.client_id,
+        client_secret=config.client_secret,
+        base_url=config.base_url,
+        company_id=config.company_id,
+        consumer_id=consumer_id,
+        timeout=config.timeout,
+        max_retries=config.max_retries,
+    )

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/connector/ergon_platform/channels/connector.py

@@ -208,6 +208,10 @@ class ErgonPlatformChannelsConnector(Connector):
         if requeue and transaction.id:
             self._seen_event_ids.discard(transaction.id)
 
+    def release_transaction(self, transaction: Transaction) -> None:
+        """Give back a fetched but unstarted inbox event (worker shutdown): requeued with no delay."""
+        self.nack_transaction(transaction, requeue=True, delay_seconds=0)
+
     def download_attachments(
         self,
         transaction: Transaction,

ergon_framework_python-0.3.1/src/ergon/connector/ergon_platform/workflows/_mode.py

@@ -0,0 +1,88 @@
+"""Consumer mode resolution shared by the sync and async workflow connectors.
+
+A connector consumes one phase. Standard phases are served by the historical
+list-and-claim loop; *Pull only* phases by ``POST /phases/{id}/items/pull``
+under a consumer id. ``mode="auto"`` reads the phase kind once, on the first
+call that needs it, and the connector then behaves like the matching kind for
+the rest of its life. Phase kind is fixed at creation, so there is nothing to
+re-check later.
+"""
+
+import logging
+from typing import Any, Callable, Optional
+
+from .._client import create_ergon_client, default_consumer_id
+from ..models import ErgonPlatformClient
+from ._operations import ErgonPlatformWorkflowsService
+from .models import ErgonPlatformConsumerConfig
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_NACK_RELEASE_DELAY_SECONDS = 10
+DEFAULT_NACK_REASON = "nack_transaction"
+
+
+class ConsumerModeState:
+    """Lazily decides list-claim vs pull for one connector and swaps in the fenced client."""
+
+    def __init__(
+        self,
+        client_config: ErgonPlatformClient,
+        consumer_config: Optional[ErgonPlatformConsumerConfig],
+        service: ErgonPlatformWorkflowsService,
+        set_client: Callable[[Any], None],
+    ) -> None:
+        self._client_config = client_config
+        self._consumer_config = consumer_config
+        self._service = service
+        self._set_client = set_client
+        self._pull: Optional[bool] = None
+        self.consumer_id: Optional[str] = None
+        if consumer_config is not None and consumer_config.mode == "pull":
+            self._enable_pull()
+            self._pull = True
+
+    @property
+    def resolved(self) -> Optional[bool]:
+        return self._pull
+
+    def is_pull(self) -> bool:
+        if self._pull is not None:
+            return self._pull
+        config = self._consumer_config
+        if config is None:
+            return False
+        if config.mode == "list_claim":
+            pull = False
+        else:
+            try:
+                pull = self._service.is_pull_phase(config.workflow_id, config.phase_id)
+            except Exception:
+                logger.warning(
+                    "Could not read the kind of phase %s; consuming it as a standard phase. "
+                    "Set consumer_config.mode explicitly to silence this.",
+                    config.phase_id,
+                    exc_info=True,
+                )
+                pull = False
+        if pull:
+            self._enable_pull()
+        self._pull = pull
+        return pull
+
+    def _enable_pull(self) -> None:
+        config = self._consumer_config
+        assert config is not None
+        self.consumer_id = config.consumer_id or default_consumer_id()
+        fenced = create_ergon_client(self._client_config, consumer_id=self.consumer_id)
+        previous = self._service.client
+        self._service.client = fenced
+        self._set_client(fenced)
+        if previous is not fenced:
+            close = getattr(previous, "close", None)
+            if callable(close):
+                try:
+                    close()
+                except Exception:
+                    logger.debug("Closing the unfenced client failed", exc_info=True)
+        logger.info("Phase %s is Pull only; consuming with consumer id %s", config.phase_id, self.consumer_id)

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/connector/ergon_platform/workflows/_operations.py

@@ -1,5 +1,7 @@
+import logging
 import math
 import mimetypes
+import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -21,6 +23,15 @@ from .utils import (
     latest_status_entry,
 )
 
+logger = logging.getLogger(__name__)
+
+RELEASE_DELAY_DEPRECATION = (
+    "release_item(delay_seconds=...) relies on the item override "
+    "visibility_timeout_on_release_minutes, which the platform removes on 2026-11-27 "
+    "(ergon-platform #664). Make the phase 'Pull only' and the same call becomes a defer, "
+    "or call defer_transaction / fail_transaction directly."
+)
+
 
 class ErgonPlatformWorkflowsService:
     """Workflows HTTP, pagination, claim, and attachment service."""
@@ -142,10 +153,16 @@ class ErgonPlatformWorkflowsService:
         delay_seconds: Optional[int] = None,
         **fields: Any,
     ) -> Any:
+        """Release a claim on a standard phase; ``delay_seconds`` hides the item once.
+
+        The delay uses the deprecated item override; see :data:`RELEASE_DELAY_DEPRECATION`.
+        """
         if delay_seconds is not None:
             if delay_seconds < 0:
                 raise ValueError("delay_seconds must be a non-negative integer")
             if delay_seconds > 0:
+                warnings.warn(RELEASE_DELAY_DEPRECATION, DeprecationWarning, stacklevel=3)
+                logger.warning(RELEASE_DELAY_DEPRECATION)
                 release_minutes = math.ceil(delay_seconds / 60)
                 self.client.workflows.items.update(
                     item_id,
@@ -153,6 +170,74 @@ class ErgonPlatformWorkflowsService:
                 )
         return self.client.workflows.items.release(item_id, {**(data or {}), **fields})
 
+    # -- Pull only phases ---------------------------------------------------
+
+    def get_phase(self, workflow_id: str, phase_id: str) -> Any:
+        """The phase row from ``GET /workflows/{id}/phases`` (there is no single-phase GET)."""
+        phases = extract_items(self.client.workflows.workflow(workflow_id).phases())
+        for phase in phases:
+            if str(get_value(phase, "id", "")) == str(phase_id):
+                return phase
+        raise LookupError(f"Phase {phase_id} not found in workflow {workflow_id}")
+
+    def is_pull_phase(self, workflow_id: str, phase_id: str) -> bool:
+        return str(get_value(self.get_phase(workflow_id, phase_id), "kind", "")) == "pull"
+
+    def pull_items(
+        self,
+        workflow_id: str,
+        phase_id: str,
+        *,
+        limit: int,
+        filters: Optional[List[Dict[str, Any]]] = None,
+        wait_seconds: Optional[int] = None,
+    ) -> List[Transaction]:
+        """``POST /phases/{id}/items/pull``: atomically claim up to ``limit`` visible items."""
+        body: Dict[str, Any] = {"max": max(1, min(int(limit), 100))}
+        if filters:
+            body["filter"] = {"filters": list(filters)}
+        if wait_seconds:
+            body["wait_seconds"] = int(wait_seconds)
+        response = self.client.workflows.phases.pull_items(phase_id, body)
+        return [item_to_transaction(item, workflow_id) for item in extract_items(response)]
+
+    def complete_item(self, item_id: str, *, reason: Optional[str] = None) -> Any:
+        body: Dict[str, Any] = {}
+        if reason:
+            body["reason"] = reason
+        return self.client.workflows.items.complete(item_id, body)
+
+    def fail_item(
+        self,
+        item_id: str,
+        *,
+        reason: str,
+        delay_seconds: Optional[int] = None,
+        details: Optional[str] = None,
+    ) -> Any:
+        body: Dict[str, Any] = {"reason": reason}
+        if delay_seconds is not None:
+            if delay_seconds < 0:
+                raise ValueError("delay_seconds must be a non-negative integer")
+            body["delay_seconds"] = int(delay_seconds)
+        if details:
+            body["details"] = details
+        return self.client.workflows.items.fail(item_id, body)
+
+    def defer_item(self, item_id: str, *, delay_seconds: int, reason: Optional[str] = None) -> Any:
+        if delay_seconds < 1:
+            raise ValueError("defer requires delay_seconds >= 1")
+        body: Dict[str, Any] = {"delay_seconds": int(delay_seconds)}
+        if reason:
+            body["reason"] = reason
+        return self.client.workflows.items.defer(item_id, body)
+
+    def extend_claim(self, item_id: str, *, seconds: Optional[int] = None) -> Any:
+        body: Dict[str, Any] = {}
+        if seconds is not None:
+            body["seconds"] = int(seconds)
+        return self.client.workflows.items.extend_claim(item_id, body)
+
     def get_pipeline_result(
         self,
         workflow_id: str,

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/connector/ergon_platform/workflows/async_connector.py

@@ -6,6 +6,7 @@ from ...connector import AsyncConnector
 from ...transaction import Transaction
 from .._client import create_ergon_client
 from ..models import ErgonPlatformClient
+from ._mode import DEFAULT_NACK_REASON, DEFAULT_NACK_RELEASE_DELAY_SECONDS, ConsumerModeState
 from ._operations import ErgonPlatformWorkflowsService
 from .models import (
     CreateItemPayload,
@@ -29,6 +30,21 @@ class AsyncErgonPlatformConnector(AsyncConnector):
         self._operations = self.service
         self._consumer_config = consumer_config
         self._producer_config = producer_config or ErgonPlatformProducerConfig()
+        self._mode = ConsumerModeState(client, consumer_config, self.service, self._set_client)
+
+    def _set_client(self, client: Any) -> None:
+        self.client = client
+
+    async def is_pull_async(self) -> bool:
+        """True when the consumed phase is Pull only (resolved once, on first use)."""
+        if self._mode.resolved is not None:
+            return self._mode.resolved
+        return await asyncio.to_thread(self._mode.is_pull)
+
+    @property
+    def consumer_id(self) -> Optional[str]:
+        """The ``X-Ergon-Consumer-Id`` this connector claims under; None on standard phases."""
+        return self._mode.consumer_id
 
     async def fetch_transactions_async(
         self,
@@ -41,6 +57,19 @@ class AsyncErgonPlatformConnector(AsyncConnector):
 
         config = self._consumer_config
         limit = batch_size or config.batch_size
+        if await self.is_pull_async():
+            if kwargs:
+                logger.debug("Ignoring list params %s on Pull only phase %s", sorted(kwargs), config.phase_id)
+            return await asyncio.to_thread(
+                lambda: self._operations.pull_items(
+                    config.workflow_id,
+                    config.phase_id,
+                    limit=limit,
+                    filters=config.pull_filters,
+                    wait_seconds=config.pull_wait_seconds,
+                )
+            )
+
         params: Dict[str, Any] = {**config.list_params, **kwargs}
         if config.unassigned:
             params.pop("assigned_to", None)
@@ -117,12 +146,15 @@ class AsyncErgonPlatformConnector(AsyncConnector):
         )
 
     async def ack_transaction(self, transaction: Transaction, phase_id: Optional[str] = None) -> None:
+        """Route to ``phase_id`` / ``ack_phase_id``; on a Pull only phase with no target, complete the stay."""
         target_phase = phase_id
         if target_phase is None and self._consumer_config is not None:
             target_phase = self._consumer_config.ack_phase_id
-        if not target_phase:
+        if target_phase:
+            await asyncio.to_thread(lambda: self.client.workflows.items.route(transaction.id, to_phase_id=target_phase))
             return
-        await asyncio.to_thread(lambda: self.client.workflows.items.route(transaction.id, to_phase_id=target_phase))
+        if await self.is_pull_async():
+            await asyncio.to_thread(lambda: self._operations.complete_item(transaction.id))
 
     async def release_item(
         self,
@@ -132,6 +164,9 @@ class AsyncErgonPlatformConnector(AsyncConnector):
         delay_seconds: Optional[int] = None,
         **fields: Any,
     ) -> Any:
+        """Give the item back. ``delay_seconds`` > 0 is a defer on Pull only phases."""
+        if delay_seconds and await self.is_pull_async():
+            return await asyncio.to_thread(lambda: self._operations.defer_item(item_id, delay_seconds=delay_seconds))
         return await asyncio.to_thread(
             lambda: self._operations.release_item(
                 item_id,
@@ -141,9 +176,29 @@ class AsyncErgonPlatformConnector(AsyncConnector):
             )
         )
 
-    async def nack_transaction(self, transaction: Transaction, requeue: bool = True, delay_seconds: int = 10) -> None:
+    async def nack_transaction(
+        self,
+        transaction: Transaction,
+        requeue: bool = True,
+        delay_seconds: Optional[int] = None,
+        *,
+        reason: Optional[str] = None,
+        details: Optional[str] = None,
+    ) -> None:
+        """Hand the item back after a failure; see :meth:`ErgonPlatformConnector.nack_transaction`."""
         if requeue:
-            await asyncio.to_thread(lambda: self._operations.release_item(transaction.id, delay_seconds=delay_seconds))
+            if await self.is_pull_async():
+                await asyncio.to_thread(
+                    lambda: self._operations.fail_item(
+                        transaction.id,
+                        reason=reason or DEFAULT_NACK_REASON,
+                        delay_seconds=delay_seconds,
+                        details=details,
+                    )
+                )
+                return
+            resolved_delay = DEFAULT_NACK_RELEASE_DELAY_SECONDS if delay_seconds is None else delay_seconds
+            await asyncio.to_thread(lambda: self._operations.release_item(transaction.id, delay_seconds=resolved_delay))
             return
 
         target_phase = self._consumer_config.nack_phase_id if self._consumer_config is not None else None
@@ -152,6 +207,39 @@ class AsyncErgonPlatformConnector(AsyncConnector):
 
         await asyncio.to_thread(lambda: self.client.workflows.items.route(transaction.id, to_phase_id=target_phase))
 
+    # -- Pull only outcomes ----------------------------------------------------
+
+    async def complete_transaction(self, transaction: Transaction, *, reason: Optional[str] = None) -> Any:
+        await self.is_pull_async()
+        return await asyncio.to_thread(lambda: self._operations.complete_item(transaction.id, reason=reason))
+
+    async def fail_transaction(
+        self,
+        transaction: Transaction,
+        *,
+        reason: str,
+        delay_seconds: Optional[int] = None,
+        details: Optional[str] = None,
+    ) -> Any:
+        await self.is_pull_async()
+        return await asyncio.to_thread(
+            lambda: self._operations.fail_item(
+                transaction.id, reason=reason, delay_seconds=delay_seconds, details=details
+            )
+        )
+
+    async def defer_transaction(
+        self, transaction: Transaction, *, delay_seconds: int, reason: Optional[str] = None
+    ) -> Any:
+        await self.is_pull_async()
+        return await asyncio.to_thread(
+            lambda: self._operations.defer_item(transaction.id, delay_seconds=delay_seconds, reason=reason)
+        )
+
+    async def extend_claim(self, transaction: Transaction, *, seconds: Optional[int] = None) -> Any:
+        await self.is_pull_async()
+        return await asyncio.to_thread(lambda: self._operations.extend_claim(transaction.id, seconds=seconds))
+
     async def close(self) -> None:
         await asyncio.to_thread(self.client.close)
 

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/connector/ergon_platform/workflows/connector.py

@@ -5,6 +5,7 @@ from ...connector import Connector
 from ...transaction import Transaction
 from .._client import create_ergon_client
 from ..models import ErgonPlatformClient
+from ._mode import DEFAULT_NACK_REASON, DEFAULT_NACK_RELEASE_DELAY_SECONDS, ConsumerModeState
 from ._operations import ErgonPlatformWorkflowsService
 from .models import (
     CreateItemPayload,
@@ -28,6 +29,20 @@ class ErgonPlatformConnector(Connector):
         self._operations = self.service
         self._consumer_config = consumer_config
         self._producer_config = producer_config or ErgonPlatformProducerConfig()
+        self._mode = ConsumerModeState(client, consumer_config, self.service, self._set_client)
+
+    def _set_client(self, client: Any) -> None:
+        self.client = client
+
+    @property
+    def is_pull(self) -> bool:
+        """True when the consumed phase is Pull only (resolved once, on first use)."""
+        return self._mode.is_pull()
+
+    @property
+    def consumer_id(self) -> Optional[str]:
+        """The ``X-Ergon-Consumer-Id`` this connector claims under; None on standard phases."""
+        return self._mode.consumer_id
 
     def fetch_transactions(
         self,
@@ -40,6 +55,17 @@ class ErgonPlatformConnector(Connector):
 
         config = self._consumer_config
         limit = batch_size or config.batch_size
+        if self.is_pull:
+            if kwargs:
+                logger.debug("Ignoring list params %s on Pull only phase %s", sorted(kwargs), config.phase_id)
+            return self._operations.pull_items(
+                config.workflow_id,
+                config.phase_id,
+                limit=limit,
+                filters=config.pull_filters,
+                wait_seconds=config.pull_wait_seconds,
+            )
+
         params: Dict[str, Any] = {**config.list_params, **kwargs}
         if config.unassigned:
             params.pop("assigned_to", None)
@@ -105,12 +131,15 @@ class ErgonPlatformConnector(Connector):
         )
 
     def ack_transaction(self, transaction: Transaction, phase_id: Optional[str] = None) -> None:
+        """Route to ``phase_id`` / ``ack_phase_id``; on a Pull only phase with no target, complete the stay."""
         target_phase = phase_id
         if target_phase is None and self._consumer_config is not None:
             target_phase = self._consumer_config.ack_phase_id
-        if not target_phase:
+        if target_phase:
+            self.client.workflows.items.route(transaction.id, to_phase_id=target_phase)
             return
-        self.client.workflows.items.route(transaction.id, to_phase_id=target_phase)
+        if self.is_pull:
+            self._operations.complete_item(transaction.id)
 
     def release_item(
         self,
@@ -120,6 +149,9 @@ class ErgonPlatformConnector(Connector):
         delay_seconds: Optional[int] = None,
         **fields: Any,
     ) -> Any:
+        """Give the item back. ``delay_seconds`` > 0 is a defer on Pull only phases."""
+        if self.is_pull and delay_seconds:
+            return self._operations.defer_item(item_id, delay_seconds=delay_seconds)
         return self._operations.release_item(
             item_id,
             data,
@@ -127,8 +159,40 @@ class ErgonPlatformConnector(Connector):
             **fields,
         )
 
-    def nack_transaction(self, transaction: Transaction, requeue: bool = True, delay_seconds: int = 10) -> None:
+    def release_transaction(self, transaction: Transaction) -> None:
+        """Give back a transaction that was fetched but never started (worker shutdown).
+
+        A plain release: no failure reason, no cooldown, so it is picked up again right away.
+        """
+        self.release_item(transaction.id)
+
+    def nack_transaction(
+        self,
+        transaction: Transaction,
+        requeue: bool = True,
+        delay_seconds: Optional[int] = None,
+        *,
+        reason: Optional[str] = None,
+        details: Optional[str] = None,
+    ) -> None:
+        """Hand the item back after a failure.
+
+        Pull only phase: ``fail`` (counts an attempt; the platform moves the item
+        to Exceptions at ``max_attempts``), retried after ``delay_seconds`` or the
+        phase retry policy. Standard phase: release with a ``delay_seconds``
+        cooldown (default 10 s). ``requeue=False`` routes to ``nack_phase_id`` on both.
+        """
         if requeue:
+            if self.is_pull:
+                self._operations.fail_item(
+                    transaction.id,
+                    reason=reason or DEFAULT_NACK_REASON,
+                    delay_seconds=delay_seconds,
+                    details=details,
+                )
+                return
+            if delay_seconds is None:
+                delay_seconds = DEFAULT_NACK_RELEASE_DELAY_SECONDS
             self._operations.release_item(transaction.id, delay_seconds=delay_seconds)
             return
 
@@ -139,6 +203,35 @@ class ErgonPlatformConnector(Connector):
         self.client.workflows.items.route(transaction.id, to_phase_id=target_phase)
         logger.debug("Item %s moved to nack phase %s", transaction.id, target_phase)
 
+    # -- Pull only outcomes ----------------------------------------------------
+
+    def complete_transaction(self, transaction: Transaction, *, reason: Optional[str] = None) -> Any:
+        """Mark the current stay done; the item stays in the phase and pull skips it."""
+        self.is_pull  # resolve the mode so the call carries the consumer id
+        return self._operations.complete_item(transaction.id, reason=reason)
+
+    def fail_transaction(
+        self,
+        transaction: Transaction,
+        *,
+        reason: str,
+        delay_seconds: Optional[int] = None,
+        details: Optional[str] = None,
+    ) -> Any:
+        """Record a failed attempt; visible again after ``delay_seconds`` (or the phase retry policy)."""
+        self.is_pull
+        return self._operations.fail_item(transaction.id, reason=reason, delay_seconds=delay_seconds, details=details)
+
+    def defer_transaction(self, transaction: Transaction, *, delay_seconds: int, reason: Optional[str] = None) -> Any:
+        """Put the item back without counting an attempt; hidden for ``delay_seconds``."""
+        self.is_pull
+        return self._operations.defer_item(transaction.id, delay_seconds=delay_seconds, reason=reason)
+
+    def extend_claim(self, transaction: Transaction, *, seconds: Optional[int] = None) -> Any:
+        """Push the claim expiry out; call from long steps so the claim does not lapse."""
+        self.is_pull
+        return self._operations.extend_claim(transaction.id, seconds=seconds)
+
     def close(self) -> None:
         self.client.close()
 

{ergon_framework_python-0.2.5 → ergon_framework_python-0.3.1}/src/ergon/connector/ergon_platform/workflows/models.py

@@ -1,7 +1,9 @@
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from pydantic import BaseModel, Field
 
+ConsumerMode = Literal["auto", "list_claim", "pull"]
+
 # Status buckets returned by the Ergon Platform attachment pipeline.
 SUCCESS_STATUSES = {"completed", "complete", "succeeded", "success", "processed", "ready"}
 FAILURE_STATUSES = {"failed", "error", "errored", "skipped", "oversized"}
@@ -41,6 +43,37 @@ class ErgonPlatformConsumerConfig(BaseModel):
         default_factory=dict,
         description="Extra query params forwarded to the items listing endpoint",
     )
+    mode: ConsumerMode = Field(
+        default="auto",
+        description=(
+            "How items are taken from the phase. 'list_claim' lists and claims one by one "
+            "(standard phases). 'pull' uses POST /phases/{id}/items/pull with a consumer id "
+            "(Pull only phases): atomic claim with expiry, fail/defer/complete outcomes, "
+            "attempt limit handled by the platform. 'auto' (default) reads the phase kind "
+            "once, on the first fetch, and picks the matching behaviour."
+        ),
+    )
+    pull_filters: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description=(
+            "Pull mode only. Field filters a pulled item must match, same shape as the "
+            "'filters' list of POST /items/query (e.g. [{'field_id': ..., 'op': 'eq', 'value': ...}])."
+        ),
+    )
+    pull_wait_seconds: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=30,
+        description="Pull mode only. Long-poll up to this many seconds when the phase has no visible item.",
+    )
+    consumer_id: Optional[str] = Field(
+        default=None,
+        description=(
+            "Pull mode only. Worker identity sent as X-Ergon-Consumer-Id; claims taken under it "
+            "expire and are fenced against other consumers. Defaults to '<hostname>:<pid>'. "
+            "Allowed: [A-Za-z0-9._:@-]{1,128}."
+        ),
+    )
 
 
 class ErgonPlatformProducerConfig(BaseModel):