ergon-framework-python 0.2.0__tar.gz → 0.2.2__tar.gz

{ergon_framework_python-0.2.0 → ergon_framework_python-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ergon-framework-python
-Version: 0.2.0
+Version: 0.2.2
 Summary: Ergon internal task-oriented project bootstrapper
 Author-email: Ergondata Technologies <anza.vossos@protonmail.com>
 License-Expression: MIT
@@ -29,14 +29,14 @@ 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.1.0; extra == "all"
+Requires-Dist: ergon-platform-sdk>=0.2.0; extra == "all"
 Requires-Dist: httpx>=0.28.0; extra == "all"
 Requires-Dist: nylas>=6.0.0; extra == "all"
 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.1.0; extra == "ergon-platform"
+Requires-Dist: ergon-platform-sdk>=0.2.0; 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.0 → ergon_framework_python-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ergon-framework-python"
-version = "0.2.0"
+version = "0.2.2"
 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.1.0",
+    "ergon-platform-sdk>=0.2.0",
     "httpx>=0.28.0",
     "nylas>=6.0.0",
     "openpyxl>=3.1.5",
@@ -42,7 +42,7 @@ all = [
     "requests>=2.32.5",
 ]
 "ergon-platform" = [
-    "ergon-platform-sdk>=0.1.0",
+    "ergon-platform-sdk>=0.2.0",
     "httpx>=0.28.0",
 ]
 excel = ["openpyxl>=3.1.5"]

{ergon_framework_python-0.2.0 → ergon_framework_python-0.2.2}/src/ergon/__init__.py

@@ -10,4 +10,4 @@ __all__ = [
     "manager",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{ergon_framework_python-0.2.0 → ergon_framework_python-0.2.2}/src/ergon/connector/__init__.py

@@ -7,13 +7,23 @@ from .transaction import Transaction
 
 if TYPE_CHECKING:
     from .ergon_platform import (
+        AsyncErgonPlatformChannelsConnector,
         AsyncErgonPlatformConnector,
         CreateItemInput,
+        ErgonPlatformChannelsConfig,
+        ErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConsumerConfig,
+        ErgonPlatformChannelsProducerConfig,
         ErgonPlatformClient,
         ErgonPlatformConnector,
         ErgonPlatformConsumerConfig,
         ErgonPlatformProducerConfig,
     )
+
+    # NOTE: ``SendMessageInput`` is defined by both Nylas and Channels with
+    # different shapes. The top-level alias here points to the Nylas type
+    # (matches the pre-split lazy-export map); channels users must import it
+    # from ``ergon.connector.ergon_platform.channels``.
     from .excel import ExcelConnector, ExcelFetchConfig, ExcelRow, ExcelService
     from .nylas import (
         AckActionConfig,
@@ -76,6 +86,7 @@ _CONNECTOR_SUBPACKAGES = (
 
 _LAZY_EXPORTS = {
     "AckActionConfig": "nylas",
+    "AsyncErgonPlatformChannelsConnector": "ergon_platform",
     "AsyncErgonPlatformConnector": "ergon_platform",
     "AsyncNylasAuthService": "nylas",
     "AsyncNylasConnector": "nylas",
@@ -94,6 +105,10 @@ _LAZY_EXPORTS = {
     "AuthUrlConfig": "nylas",
     "CodeExchangeInput": "nylas",
     "CreateItemInput": "ergon_platform",
+    "ErgonPlatformChannelsConfig": "ergon_platform",
+    "ErgonPlatformChannelsConnector": "ergon_platform",
+    "ErgonPlatformChannelsConsumerConfig": "ergon_platform",
+    "ErgonPlatformChannelsProducerConfig": "ergon_platform",
     "ErgonPlatformClient": "ergon_platform",
     "ErgonPlatformConnector": "ergon_platform",
     "ErgonPlatformConsumerConfig": "ergon_platform",
@@ -148,6 +163,7 @@ def __dir__() -> list[str]:
 __all__ = [
     "AckActionConfig",
     "AsyncConnector",
+    "AsyncErgonPlatformChannelsConnector",
     "AsyncErgonPlatformConnector",
     "AsyncNylasAuthService",
     "AsyncNylasConnector",
@@ -169,6 +185,10 @@ __all__ = [
     "Connector",
     "ConnectorConfig",
     "CreateItemInput",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
     "ErgonPlatformClient",
     "ErgonPlatformConnector",
     "ErgonPlatformConsumerConfig",

ergon_framework_python-0.2.2/src/ergon/connector/ergon_platform/__init__.py

@@ -0,0 +1,110 @@
+"""Ergon Platform connectors — Workflows and Channels.
+
+The Ergon Platform SDK exposes several services (workflows, channels, agents,
+buckets, ...). This package groups every framework connector against that
+platform. Each service lives in its own sub-package (``workflows``,
+``channels``, ...) and reuses the shared credentials model
+(:class:`ErgonPlatformClient`) so a single API key drives every connector.
+
+Public workflow names are re-exported here for backward compatibility with the
+pre-split layout::
+
+    from ergon.connector.ergon_platform import ErgonPlatformConnector  # workflows
+
+New code is encouraged to import directly from the sub-package::
+
+    from ergon.connector.ergon_platform.workflows import ErgonPlatformConnector
+    from ergon.connector.ergon_platform.channels import ErgonPlatformChannelsConnector
+"""
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from .._lazy import exported_names, load_optional_export
+from .models import ErgonPlatformClient
+
+if TYPE_CHECKING:
+    from .channels import (
+        AsyncErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConfig,
+        ErgonPlatformChannelsConnector,
+        ErgonPlatformChannelsConsumerConfig,
+        ErgonPlatformChannelsProducerConfig,
+        ErgonPlatformChannelsService,
+        SendMessageInput,
+        SendMessagePayload,
+    )
+    from .workflows import (
+        AsyncErgonPlatformConnector,
+        CreateItemInput,
+        CreateItemPayload,
+        ErgonPlatformConnector,
+        ErgonPlatformConsumerConfig,
+        ErgonPlatformProducerConfig,
+        ErgonPlatformWorkflowsService,
+    )
+
+_SUBPACKAGES = ("channels", "workflows")
+
+# Backward-compat aliases: names that used to live under
+# ``ergon.connector.ergon_platform`` before the workflows/ split, plus the new
+# channels API surface. Every entry is loaded lazily from its sub-package to
+# keep the platform SDK out of the core import path.
+_LAZY_EXPORTS = {
+    # Workflows (pre-split names — kept for backward compatibility)
+    "AsyncErgonPlatformConnector": "workflows",
+    "CreateItemInput": "workflows",
+    "CreateItemPayload": "workflows",
+    "ErgonPlatformConnector": "workflows",
+    "ErgonPlatformConsumerConfig": "workflows",
+    "ErgonPlatformProducerConfig": "workflows",
+    "ErgonPlatformWorkflowsService": "workflows",
+    # Channels
+    "AsyncErgonPlatformChannelsConnector": "channels",
+    "ErgonPlatformChannelsConfig": "channels",
+    "ErgonPlatformChannelsConnector": "channels",
+    "ErgonPlatformChannelsConsumerConfig": "channels",
+    "ErgonPlatformChannelsProducerConfig": "channels",
+    "ErgonPlatformChannelsService": "channels",
+    "SendMessageInput": "channels",
+    "SendMessagePayload": "channels",
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _SUBPACKAGES:
+        module = import_module(f".{name}", __name__)
+        globals()[name] = module
+        return module
+    return load_optional_export(
+        name=name,
+        package=__name__,
+        exports=_LAZY_EXPORTS,
+        namespace=globals(),
+        extra="ergon-platform",
+        dependencies=("ergon_platform", "httpx"),
+    )
+
+
+def __dir__() -> list[str]:
+    return sorted(set(exported_names(globals(), _LAZY_EXPORTS)) | set(_SUBPACKAGES))
+
+
+__all__ = [
+    "AsyncErgonPlatformChannelsConnector",
+    "AsyncErgonPlatformConnector",
+    "CreateItemInput",
+    "CreateItemPayload",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
+    "ErgonPlatformChannelsService",
+    "ErgonPlatformClient",
+    "ErgonPlatformConnector",
+    "ErgonPlatformConsumerConfig",
+    "ErgonPlatformProducerConfig",
+    "ErgonPlatformWorkflowsService",
+    "SendMessageInput",
+    "SendMessagePayload",
+]

ergon_framework_python-0.2.2/src/ergon/connector/ergon_platform/async_connector.py

@@ -0,0 +1,5 @@
+"""Deprecated compatibility import for the async Workflows connector."""
+
+from .workflows.async_connector import AsyncErgonPlatformConnector
+
+__all__ = ["AsyncErgonPlatformConnector"]

ergon_framework_python-0.2.2/src/ergon/connector/ergon_platform/channels/__init__.py

@@ -0,0 +1,54 @@
+from typing import TYPE_CHECKING, Any
+
+from ..._lazy import exported_names, load_optional_export
+from .models import (
+    ChannelsActivityFilter,
+    ErgonPlatformChannelsConfig,
+    ErgonPlatformChannelsConsumerConfig,
+    ErgonPlatformChannelsProducerConfig,
+    InboxAttachmentFile,
+    SendMessageAttachment,
+    SendMessageInput,
+    SendMessagePayload,
+)
+
+if TYPE_CHECKING:
+    from .async_connector import AsyncErgonPlatformChannelsConnector
+    from .connector import ErgonPlatformChannelsConnector
+    from .services import ErgonPlatformChannelsService
+
+_LAZY_EXPORTS = {
+    "AsyncErgonPlatformChannelsConnector": "async_connector",
+    "ErgonPlatformChannelsConnector": "connector",
+    "ErgonPlatformChannelsService": "services",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return load_optional_export(
+        name=name,
+        package=__name__,
+        exports=_LAZY_EXPORTS,
+        namespace=globals(),
+        extra="ergon-platform",
+        dependencies=("ergon_platform", "httpx"),
+    )
+
+
+def __dir__() -> list[str]:
+    return exported_names(globals(), _LAZY_EXPORTS)
+
+
+__all__ = [
+    "AsyncErgonPlatformChannelsConnector",
+    "ChannelsActivityFilter",
+    "ErgonPlatformChannelsConnector",
+    "ErgonPlatformChannelsConfig",
+    "ErgonPlatformChannelsConsumerConfig",
+    "ErgonPlatformChannelsProducerConfig",
+    "ErgonPlatformChannelsService",
+    "InboxAttachmentFile",
+    "SendMessageAttachment",
+    "SendMessageInput",
+    "SendMessagePayload",
+]

ergon_framework_python-0.2.2/src/ergon/connector/ergon_platform/channels/adapters.py

@@ -0,0 +1,230 @@
+from typing import Any, Dict, List, Optional
+
+from ...transaction import Transaction
+from .models import ErgonPlatformChannelsConsumerConfig
+from .services.records import SdkRecord
+
+
+class ActivityAdapter:
+    """Map Channels activity events into the connector Transaction shape."""
+
+    _META_KEYS = (
+        "event_type",
+        "channel",
+        "direction",
+        "status",
+        "thread_id",
+        "correlation_id",
+        "provider_message_id",
+        "subject",
+        "from_address",
+        "to_addresses",
+        "address_id",
+        "consumption_status",
+        "acked_at",
+        "available_at",
+        "consumer_id",
+        "attempt_count",
+    )
+    _DELIVERY_KEYS = (
+        "subscription_id",
+        "lease_token",
+        "lease_expires_at",
+        "consumer_id",
+        "attempt_count",
+    )
+
+    @classmethod
+    def to_transaction(cls, event: Any, *, source: str) -> Transaction:
+        """To transaction."""
+        payload = SdkRecord.serialize(event)
+        payload = payload if isinstance(payload, dict) else {"value": payload}
+        metadata: Dict[str, Any] = {"source": source}
+        for key in cls._META_KEYS:
+            value = payload.get(key)
+            if value is not None:
+                metadata[key] = value
+        nested = payload.get("payload")
+        if isinstance(nested, dict):
+            metadata["message_payload"] = nested
+            attachments = cls.public_attachments(nested.get("attachments"))
+            if attachments:
+                metadata["attachments"] = attachments
+                metadata["has_attachment"] = True
+        return Transaction(
+            id=SdkRecord.first_id(
+                payload,
+                "id",
+                "log_id",
+                "message_id",
+                "provider_message_id",
+            ),
+            payload=payload,
+            metadata=metadata,
+        )
+
+    @classmethod
+    def claimed_transaction(cls, item: Any) -> Transaction:
+        """Claimed transaction."""
+        claimed = SdkRecord.serialize(item)
+        claimed = claimed if isinstance(claimed, dict) else {}
+        transaction = cls.to_transaction(
+            claimed.get("event"),
+            source="config_activity_claim",
+        )
+        metadata = dict(transaction.metadata or {})
+        delivery = claimed.get("delivery")
+        if isinstance(delivery, dict):
+            metadata["delivery"] = {key: delivery[key] for key in cls._DELIVERY_KEYS if delivery.get(key) is not None}
+        return transaction.model_copy(update={"metadata": metadata})
+
+    @staticmethod
+    def delivery(transaction: Transaction) -> Dict[str, Any]:
+        """Delivery."""
+        metadata = transaction.metadata or {}
+        delivery = metadata.get("delivery")
+        if not isinstance(delivery, dict):
+            raise ValueError("Transaction was not claimed and cannot be acknowledged or nacked")
+        if not delivery.get("subscription_id") or not delivery.get("lease_token"):
+            raise ValueError("Transaction claim is missing subscription_id or lease_token")
+        return delivery
+
+    @staticmethod
+    def belongs_to_address(
+        transaction: Transaction,
+        address_id: str,
+    ) -> bool:
+        """Belongs to address."""
+        metadata = transaction.metadata or {}
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            candidate = nested.get("address_id") or nested.get("channel_address_id")
+            if candidate is not None:
+                return str(candidate) == address_id
+        event = transaction.payload if isinstance(transaction.payload, dict) else {}
+        candidate = event.get("address_id") or event.get("channel_address_id")
+        if candidate is not None:
+            return str(candidate) == address_id
+        return True
+
+    @staticmethod
+    def attachment_id(attachment: Any) -> Optional[str]:
+        """Attachment id."""
+        if not isinstance(attachment, dict):
+            return None
+        for key in ("id", "resend_attachment_id", "attachment_id"):
+            value = attachment.get(key)
+            if value:
+                return str(value)
+        return None
+
+    @classmethod
+    def public_attachment(
+        cls,
+        item: Any,
+    ) -> Optional[Dict[str, Any]]:
+        """Public attachment."""
+        if not isinstance(item, dict):
+            return None
+        filename = str(item.get("filename") or item.get("name") or "").strip()
+        if not filename:
+            return None
+        attachment: Dict[str, Any] = {"filename": filename}
+        attachment_id = cls.attachment_id(item)
+        if attachment_id:
+            attachment["id"] = attachment_id
+        content_type = item.get("content_type")
+        if content_type:
+            attachment["content_type"] = content_type
+        size = item.get("size")
+        if size is not None:
+            attachment["size"] = size
+        content = item.get("content")
+        if isinstance(content, bytes):
+            attachment["content"] = content
+        return attachment
+
+    @classmethod
+    def public_attachments(cls, items: Any) -> List[Dict[str, Any]]:
+        """Public attachments."""
+        if not isinstance(items, list):
+            return []
+        attachments: List[Dict[str, Any]] = []
+        for item in items:
+            attachment = cls.public_attachment(item)
+            if attachment is not None:
+                attachments.append(attachment)
+        return attachments
+
+    @classmethod
+    def attachments(
+        cls,
+        transaction: Transaction,
+    ) -> List[Dict[str, Any]]:
+        """Attachments."""
+        metadata = transaction.metadata or {}
+        items = metadata.get("attachments")
+        if isinstance(items, list):
+            return [item for item in items if isinstance(item, dict)]
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            return cls.public_attachments(nested.get("attachments"))
+        payload = transaction.payload
+        if isinstance(payload, dict):
+            nested = payload.get("payload")
+            if isinstance(nested, dict):
+                return cls.public_attachments(nested.get("attachments"))
+        return []
+
+    @staticmethod
+    def with_attachments(
+        transaction: Transaction,
+        attachments: List[Dict[str, Any]],
+    ) -> Transaction:
+        """With the attachments."""
+        metadata = dict(transaction.metadata or {})
+        metadata["attachments"] = attachments
+        metadata["has_attachment"] = bool(attachments)
+        nested = metadata.get("message_payload")
+        if isinstance(nested, dict):
+            metadata["message_payload"] = {
+                **nested,
+                "attachments": attachments,
+            }
+        payload = transaction.payload
+        if isinstance(payload, dict):
+            payload = dict(payload)
+            inner = payload.get("payload")
+            if isinstance(inner, dict):
+                payload["payload"] = {
+                    **inner,
+                    "attachments": attachments,
+                }
+        return transaction.model_copy(update={"payload": payload, "metadata": metadata})
+
+    @staticmethod
+    def unseen(
+        transactions: List[Transaction],
+        seen_ids: set[str],
+    ) -> List[Transaction]:
+        fresh: List[Transaction] = []
+        """Unseen transactions."""
+        for transaction in transactions:
+            if not transaction.id or transaction.id in seen_ids:
+                continue
+            seen_ids.add(transaction.id)
+            fresh.append(transaction)
+        return fresh
+
+    @classmethod
+    def finalize_fetch(
+        cls,
+        transactions: List[Transaction],
+        config: ErgonPlatformChannelsConsumerConfig,
+        seen_ids: Optional[set[str]] = None,
+    ) -> List[Transaction]:
+        """Finalize the fetched transactions."""
+        transactions = config.effective_activity_filter().select(transactions)
+        if seen_ids is not None:
+            transactions = cls.unseen(transactions, seen_ids)
+        return transactions