codex-platform 0.5.1__tar.gz → 0.5.2__tar.gz

{codex_platform-0.5.1 → codex_platform-0.5.2}/CHANGELOG.md

@@ -5,6 +5,17 @@ Grouped by `Added` · `Changed` · `Deprecated` · `Removed` · `Fixed`.
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-05-07
+
+### Added
+- Added the framework-agnostic `codex_platform.messaging` package with notification delivery, campaign, threading, renderer, and SMTP primitives.
+
+### Deprecated
+- Deprecated `codex_platform.notifications` modules in favor of `codex_platform.messaging` compatibility re-exports.
+
+### Fixed
+- Reduced Redis Streams consumer latency by using configurable blocking `XREADGROUP` reads instead of relying on the processor polling interval for normal wakeups.
+
 ## [0.5.1] - 2026-04-30
 
 ### Fixed

{codex_platform-0.5.1 → codex_platform-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-platform
-Version: 0.5.1
+Version: 0.5.2
 Summary: Modular async infrastructure (Redis, Streams, ARQ, Notifications) built for Codex, designed for independent use.
 Project-URL: Homepage, https://github.com/codexdlc/codex-platform
 Project-URL: Documentation, https://codexdlc.github.io/codex-platform/

{codex_platform-0.5.1 → codex_platform-0.5.2}/docs/en/api/index.md

@@ -6,7 +6,8 @@ Auto-generated from source docstrings (Google style). If code behavior contradic
 
 | Module | Description |
 | :--- | :--- |
-| [notifications](notifications/index.md) | Multi-channel notification engine |
+| [messaging](messaging/index.md) | Framework-agnostic messaging engine |
+| [notifications](notifications/index.md) | Deprecated compatibility path for messaging |
 | [redis_service](redis_service/index.md) | Async Redis abstraction with typed operations |
 | [streams](streams/index.md) | Redis Streams producer/consumer event bus |
 | [workers.arq](workers/arq/index.md) | ARQ background worker base infrastructure |

codex_platform-0.5.2/docs/en/api/messaging/audience.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.audience
+
+::: codex_platform.messaging.audience

codex_platform-0.5.2/docs/en/api/messaging/campaigns/dto.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.campaigns.dto
+
+::: codex_platform.messaging.campaigns.dto

codex_platform-0.5.2/docs/en/api/messaging/campaigns/index.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.campaigns
+
+::: codex_platform.messaging.campaigns

codex_platform-0.5.2/docs/en/api/messaging/campaigns/protocols.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.campaigns.protocols
+
+::: codex_platform.messaging.campaigns.protocols

codex_platform-0.5.2/docs/en/api/messaging/channels.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.channels
+
+::: codex_platform.messaging.channels

codex_platform-0.5.2/docs/en/api/messaging/clients/smtp.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.clients.smtp
+
+::: codex_platform.messaging.clients.smtp

codex_platform-0.5.2/docs/en/api/messaging/delivery/arq.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.delivery.arq
+
+::: codex_platform.messaging.delivery.arq

codex_platform-0.5.2/docs/en/api/messaging/delivery/base.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.delivery.base
+
+::: codex_platform.messaging.delivery.base

codex_platform-0.5.2/docs/en/api/messaging/delivery/direct.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.delivery.direct
+
+::: codex_platform.messaging.delivery.direct

codex_platform-0.5.2/docs/en/api/messaging/dto.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.dto
+
+::: codex_platform.messaging.dto

codex_platform-0.5.2/docs/en/api/messaging/index.md

@@ -0,0 +1,8 @@
+<!-- type: REFERENCE -->
+
+# messaging
+
+Framework-agnostic messaging primitives. This package is the primary import
+path for the former `codex_platform.notifications` API.
+
+::: codex_platform.messaging

codex_platform-0.5.2/docs/en/api/messaging/orchestrator.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.orchestrator
+
+::: codex_platform.messaging.orchestrator

codex_platform-0.5.2/docs/en/api/messaging/registry.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.registry
+
+::: codex_platform.messaging.registry

codex_platform-0.5.2/docs/en/api/messaging/renderer.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.renderer
+
+::: codex_platform.messaging.renderer

codex_platform-0.5.2/docs/en/api/messaging/threading.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.threading
+
+::: codex_platform.messaging.threading

codex_platform-0.5.2/docs/en/api/messaging/workers_contract.md

@@ -0,0 +1,5 @@
+<!-- type: REFERENCE -->
+
+# messaging.workers_contract
+
+::: codex_platform.messaging.workers_contract

codex_platform-0.5.2/docs/en/api/notifications/index.md

@@ -0,0 +1,8 @@
+<!-- type: REFERENCE -->
+
+# notifications
+
+Deprecated compatibility path. New code should import from
+`codex_platform.messaging`.
+
+::: codex_platform.notifications

{codex_platform-0.5.1 → codex_platform-0.5.2}/mkdocs.yml

@@ -100,6 +100,26 @@ nav:
               - Поток данных: ru/architecture/workers/data_flow.md
   - API Reference:
       - Overview: en/api/index.md
+      - Messaging:
+          - Overview: en/api/messaging/index.md
+          - DTOs: en/api/messaging/dto.md
+          - Channels: en/api/messaging/channels.md
+          - Orchestrator: en/api/messaging/orchestrator.md
+          - Registry: en/api/messaging/registry.md
+          - Renderer: en/api/messaging/renderer.md
+          - Threading: en/api/messaging/threading.md
+          - Audience: en/api/messaging/audience.md
+          - Workers Contract: en/api/messaging/workers_contract.md
+          - Clients:
+              - SMTP: en/api/messaging/clients/smtp.md
+          - Campaigns:
+              - Overview: en/api/messaging/campaigns/index.md
+              - DTOs: en/api/messaging/campaigns/dto.md
+              - Protocols: en/api/messaging/campaigns/protocols.md
+          - Delivery:
+              - Base Protocol: en/api/messaging/delivery/base.md
+              - ARQ: en/api/messaging/delivery/arq.md
+              - Direct: en/api/messaging/delivery/direct.md
       - Notifications:
           - Overview: en/api/notifications/index.md
           - DTOs: en/api/notifications/dto.md

codex_platform-0.5.2/src/codex_platform/messaging/__init__.py

@@ -0,0 +1,68 @@
+"""Framework-agnostic messaging primitives for codex-platform."""
+
+from .audience import AudienceBuilder
+from .campaigns import CampaignBatchDTO, CampaignDispatcher, CampaignRecipientDraft
+from .channels import NotificationChannel
+from .clients.smtp import AsyncEmailClient
+from .delivery import ArqNotificationAdapter, DirectNotificationAdapter, NotificationAdapter
+from .dto import (
+    NotificationPayloadDTO,
+    NotificationRecipient,
+    RenderedNotificationDTO,
+    TemplateNotificationDTO,
+    ThreadHeadersDTO,
+)
+from .interfaces import ContentCacheAdapter, ContentProvider
+from .orchestrator import BaseDeliveryOrchestrator, DeliveryChannel
+from .registry import ChannelRegistry
+from .renderer import TemplateRenderer, resolve_template_path
+from .threading import (
+    CODEX_THREAD_HEADER,
+    LEGACY_LILY_THREAD_HEADER,
+    build_message_id,
+    build_thread_key,
+    parse_references,
+    render_email_headers,
+    serialize_references,
+)
+from .workers_contract import (
+    PAYLOAD_SCHEMA_VERSION,
+    TASK_SEND_CAMPAIGN,
+    TASK_SEND_NOTIFICATION,
+    TASK_SEND_RENDERED,
+)
+
+__all__ = [
+    "AudienceBuilder",
+    "CampaignBatchDTO",
+    "CampaignDispatcher",
+    "CampaignRecipientDraft",
+    "NotificationChannel",
+    "NotificationPayloadDTO",
+    "TemplateNotificationDTO",
+    "RenderedNotificationDTO",
+    "NotificationRecipient",
+    "ThreadHeadersDTO",
+    "ContentProvider",
+    "ContentCacheAdapter",
+    "DeliveryChannel",
+    "AsyncEmailClient",
+    "BaseDeliveryOrchestrator",
+    "ChannelRegistry",
+    "TemplateRenderer",
+    "resolve_template_path",
+    "NotificationAdapter",
+    "ArqNotificationAdapter",
+    "DirectNotificationAdapter",
+    "CODEX_THREAD_HEADER",
+    "LEGACY_LILY_THREAD_HEADER",
+    "build_message_id",
+    "build_thread_key",
+    "parse_references",
+    "render_email_headers",
+    "serialize_references",
+    "PAYLOAD_SCHEMA_VERSION",
+    "TASK_SEND_NOTIFICATION",
+    "TASK_SEND_RENDERED",
+    "TASK_SEND_CAMPAIGN",
+]

codex_platform-0.5.2/src/codex_platform/messaging/audience.py

@@ -0,0 +1,23 @@
+"""Audience selection contracts for campaign messaging."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+from .campaigns.dto import CampaignRecipientDraft
+
+
+class AudienceBuilder(Protocol):
+    """Materializes campaign recipients from a host-defined filter."""
+
+    def count(self, audience_filter: dict[str, Any]) -> int:
+        """Return the number of recipients matching the filter."""
+        ...
+
+    def materialize(self, audience_filter: dict[str, Any]) -> Iterable[CampaignRecipientDraft]:
+        """Stream recipient drafts matching the filter."""
+        ...
+
+
+__all__ = ["AudienceBuilder"]

codex_platform-0.5.2/src/codex_platform/messaging/campaigns/__init__.py

@@ -0,0 +1,6 @@
+"""Campaign messaging DTOs and protocols."""
+
+from .dto import CampaignBatchDTO, CampaignRecipientDraft
+from .protocols import CampaignDispatcher
+
+__all__ = ["CampaignRecipientDraft", "CampaignBatchDTO", "CampaignDispatcher"]

codex_platform-0.5.2/src/codex_platform/messaging/campaigns/dto.py

@@ -0,0 +1,46 @@
+"""Campaign messaging DTOs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from codex_core.core import BaseDTO
+from pydantic import model_validator
+
+from codex_platform.messaging.workers_contract import PAYLOAD_SCHEMA_VERSION
+
+
+class CampaignRecipientDraft(BaseDTO):
+    """Recipient data needed by a campaign batch worker."""
+
+    recipient_id: str
+    email: str
+    first_name: str = ""
+    last_name: str = ""
+    locale: str = "de"
+    unsubscribe_token: str | None = None
+
+
+class CampaignBatchDTO(BaseDTO):
+    """One campaign batch payload for the worker callback contract."""
+
+    schema_version: int = PAYLOAD_SCHEMA_VERSION
+    campaign_id: str
+    template_name: str | None = None
+    html_content: str | None = None
+    subject: str
+    recipients: list[CampaignRecipientDraft]
+    base_context: dict[str, Any] = {}
+    callback_url: str
+    callback_token: str
+
+    @model_validator(mode="after")
+    def validate_rendering_mode(self) -> CampaignBatchDTO:
+        """Require exactly one campaign rendering mode."""
+
+        if bool(self.template_name) == bool(self.html_content):
+            raise ValueError("exactly one of template_name or html_content must be set")
+        return self
+
+
+__all__ = ["CampaignRecipientDraft", "CampaignBatchDTO"]

codex_platform-0.5.2/src/codex_platform/messaging/campaigns/protocols.py

@@ -0,0 +1,18 @@
+"""Campaign messaging protocols."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .dto import CampaignBatchDTO
+
+
+class CampaignDispatcher(Protocol):
+    """Enqueues campaign batches for worker-side delivery."""
+
+    def enqueue_batch(self, batch: CampaignBatchDTO) -> str:
+        """Enqueue a batch and return the backend job identifier."""
+        ...
+
+
+__all__ = ["CampaignDispatcher"]

{codex_platform-0.5.1/src/codex_platform/notifications → codex_platform-0.5.2/src/codex_platform/messaging}/channels.py

@@ -1,8 +1,4 @@
-"""
-codex_platform.notifications.channels
-=======================================
-Enum of supported notification delivery channels.
-"""
+"""Enum of supported notification delivery channels."""
 
 from enum import StrEnum
 

{codex_platform-0.5.1/src/codex_platform/notifications → codex_platform-0.5.2/src/codex_platform/messaging}/clients/__init__.py

@@ -1,3 +1,5 @@
+"""Built-in messaging delivery clients."""
+
 from .smtp import AsyncEmailClient
 
 __all__ = ["AsyncEmailClient"]

{codex_platform-0.5.1/src/codex_platform/notifications → codex_platform-0.5.2/src/codex_platform/messaging}/clients/smtp.py

@@ -1,18 +1,15 @@
-"""
-codex_platform.workers.notifications.email
-========================================
-Async SMTP email client — implements ``DeliveryChannel``.
+"""Async SMTP email client implementing the messaging delivery channel."""
 
-Creates persistent SMTP connection config at init time.
-For multi-tenant: create separate instances with different settings.
-
-Requires: pip install codex-tools[notifications]
-"""
+from __future__ import annotations
 
 import logging
 from email.message import EmailMessage
+from email.utils import formataddr
 from typing import Any
 
+from codex_platform.messaging.dto import ThreadHeadersDTO
+from codex_platform.messaging.threading import render_email_headers
+
 log = logging.getLogger(__name__)
 
 try:
@@ -21,28 +18,14 @@ try:
     _AIOSMTP_AVAILABLE = True
 except ImportError as e:
     if e.name == "aiosmtplib":
+        aiosmtplib = None  # type: ignore[assignment]
         _AIOSMTP_AVAILABLE = False
     else:
         raise
 
 
 class AsyncEmailClient:
-    """
-    Async SMTP email sender. Implements ``DeliveryChannel``.
-
-    Usage:
-        client = AsyncEmailClient(
-            smtp_host="mail.example.com", smtp_port=465,
-            smtp_user="user", smtp_password="pass",  # pragma: allowlist secret
-            smtp_from_email="noreply@example.com",
-        )
-        success = await client.send(
-            to="user@example.com",
-            subject="Hello",
-            html_content="<b>Hi</b>",
-            text_content="Hi",
-        )
-    """
+    """Async SMTP email sender."""
 
     def __init__(
         self,
@@ -52,6 +35,7 @@ class AsyncEmailClient:
         smtp_password: str | None = None,  # pragma: allowlist secret
         smtp_from_email: str | None = None,
         smtp_use_tls: bool = False,
+        smtp_from_name: str = "",
     ) -> None:
         self.smtp_host = smtp_host
         self.smtp_port = smtp_port
@@ -59,9 +43,11 @@ class AsyncEmailClient:
         self.smtp_password = smtp_password
         self.smtp_from_email = smtp_from_email
         self.smtp_use_tls = smtp_use_tls
+        self.smtp_from_name = smtp_from_name
 
     def is_available(self) -> bool:
-        """Returns True if the client is configured (non-localhost host)."""
+        """Returns True if the client is configured with a non-localhost host."""
+
         return bool(self.smtp_host and self.smtp_host != "localhost")
 
     async def send(
@@ -70,30 +56,14 @@ class AsyncEmailClient:
         subject: str,
         html_content: str | None,
         text_content: str | None,
+        headers: ThreadHeadersDTO | None = None,
         timeout: int = 15,
     ) -> bool:
-        """
-        Send email via SMTP.
-
-        Args:
-            to: Recipient email address.
-            subject: Email subject line.
-            html_content: HTML body (preferred). Used as HTML part.
-            text_content: Plain-text body (fallback for HTML-disabled clients).
-                          If None and html_content is provided, a generic fallback
-                          is used.
-            timeout: SMTP connection timeout in seconds.
-
-        Returns:
-            True on success.
-
-        Raises:
-            RuntimeError: If aiosmtplib is not installed.
-            aiosmtplib.SMTPException: On SMTP delivery failure.
-        """
+        """Send email via SMTP."""
+
         if not _AIOSMTP_AVAILABLE:
-            raise RuntimeError("aiosmtplib not installed. Run: pip install codex-tools[notifications]")
-        await self._send_smtp(to, subject, html_content, text_content, timeout)
+            raise RuntimeError("aiosmtplib not installed. Run: pip install codex-platform[notifications]")
+        await self._send_smtp(to, subject, html_content, text_content, headers, timeout)
         log.info("AsyncEmailClient | sent to='%s'", to)
         return True
 
@@ -103,13 +73,22 @@ class AsyncEmailClient:
         subject: str,
         html_content: str | None,
         text_content: str | None,
+        headers: ThreadHeadersDTO | None,
         timeout: int,
     ) -> None:
         message = EmailMessage()
-        message["From"] = self.smtp_from_email
+        message["From"] = (
+            formataddr((self.smtp_from_name, self.smtp_from_email))
+            if self.smtp_from_name and self.smtp_from_email
+            else self.smtp_from_email
+        )
         message["To"] = to
         message["Subject"] = subject
 
+        if headers is not None:
+            for name, value in render_email_headers(headers).items():
+                message[name] = value
+
         plain = text_content or "Please enable HTML to view this email."
         message.set_content(plain)
 
@@ -132,3 +111,6 @@ class AsyncEmailClient:
             send_kwargs["password"] = self.smtp_password
 
         await aiosmtplib.send(message, **send_kwargs)
+
+
+__all__ = ["AsyncEmailClient", "_AIOSMTP_AVAILABLE", "aiosmtplib"]

codex_platform-0.5.2/src/codex_platform/messaging/delivery/__init__.py

@@ -0,0 +1,11 @@
+"""Delivery adapters for messaging payloads."""
+
+from .arq import ArqNotificationAdapter
+from .base import NotificationAdapter
+from .direct import DirectNotificationAdapter
+
+__all__ = [
+    "NotificationAdapter",
+    "ArqNotificationAdapter",
+    "DirectNotificationAdapter",
+]

codex_platform-0.5.2/src/codex_platform/messaging/delivery/arq.py

@@ -0,0 +1,38 @@
+"""ARQ delivery adapter for messaging payloads."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from arq.connections import ArqRedis
+
+from .base import NotificationAdapter
+
+log = logging.getLogger(__name__)
+
+
+class ArqNotificationAdapter(NotificationAdapter):
+    """Notification adapter that enqueues tasks into an ARQ/Redis queue."""
+
+    def __init__(self, pool: ArqRedis) -> None:
+        self.pool = pool
+
+    def enqueue(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """Sync enqueue wrapper. Prefer ``enqueue_async`` in async contexts."""
+
+        import asyncio
+
+        return asyncio.get_event_loop().run_until_complete(self.enqueue_async(task_name, payload))
+
+    async def enqueue_async(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """Enqueue a notification task into the ARQ queue."""
+
+        log.debug("ArqNotificationAdapter | enqueueing task=%s", task_name)
+        job = await self.pool.enqueue_job(task_name, payload_dict=payload)
+        job_id = getattr(job, "job_id", None)
+        log.info("ArqNotificationAdapter | task=%s job_id=%s", task_name, job_id)
+        return job_id
+
+
+__all__ = ["ArqNotificationAdapter"]

codex_platform-0.5.2/src/codex_platform/messaging/delivery/base.py

@@ -0,0 +1,16 @@
+"""Protocol definition for notification delivery adapters."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class NotificationAdapter(Protocol):
+    """Contract for notification delivery transport."""
+
+    def enqueue(self, task_name: str, payload: dict[str, Any]) -> str | None:
+        """Deliver or enqueue a serialized notification payload."""
+        ...
+
+
+__all__ = ["NotificationAdapter"]

codex_platform-0.5.2/src/codex_platform/messaging/delivery/direct.py

@@ -0,0 +1,76 @@
+"""Direct in-process delivery adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from .base import NotificationAdapter
+
+log = logging.getLogger(__name__)
+
+
+class DirectNotificationAdapter(NotificationAdapter):
+    """Adapter for synchronous in-process notification delivery."""
+
+    def __init__(self, config: Any) -> None:
+        self.config = config
+
+    def enqueue(self, _task_name: str, payload: dict[str, Any]) -> str | None:
+        """Deliver a notification synchronously via the orchestrator pipeline."""
+
+        from codex_platform.messaging.dto import (
+            NotificationPayloadDTO,
+            RenderedNotificationDTO,
+            TemplateNotificationDTO,
+        )
+        from codex_platform.messaging.orchestrator import BaseDeliveryOrchestrator
+        from codex_platform.messaging.registry import ChannelRegistry
+
+        log.debug("DirectNotificationAdapter | starting direct delivery")
+
+        registry = ChannelRegistry()
+        _register_default_channels(registry, self.config)
+        channels = registry.build_channels(self.config)
+        orchestrator = BaseDeliveryOrchestrator(channels=channels)
+
+        payload_dto: NotificationPayloadDTO
+        if "html_content" in payload:
+            payload_dto = RenderedNotificationDTO(**payload)
+        elif "template_name" in payload and "context_key" in payload:
+            payload_dto = TemplateNotificationDTO(**payload)
+        else:
+            payload_dto = NotificationPayloadDTO(**payload)
+        asyncio.run(orchestrator.deliver(payload_dto))
+
+        notification_id = payload.get("notification_id")
+        log.info("DirectNotificationAdapter | delivered notification_id=%s", notification_id)
+        return notification_id
+
+
+def _register_default_channels(registry: Any, config: Any) -> None:
+    """Register default SMTP channel from config when available."""
+
+    try:
+        from codex_platform.messaging.clients.smtp import AsyncEmailClient
+
+        smtp_host = getattr(config, "SMTP_HOST", "")
+        if smtp_host:
+            registry.register(
+                "smtp",
+                lambda cfg: AsyncEmailClient(
+                    smtp_host=getattr(cfg, "SMTP_HOST", ""),
+                    smtp_port=getattr(cfg, "SMTP_PORT", 587),
+                    smtp_user=getattr(cfg, "SMTP_USER", None),
+                    smtp_password=getattr(cfg, "SMTP_PASSWORD", None),
+                    smtp_from_email=getattr(cfg, "SMTP_FROM_EMAIL", None),
+                    smtp_use_tls=getattr(cfg, "SMTP_USE_TLS", False),
+                    smtp_from_name=getattr(cfg, "SMTP_FROM_NAME", ""),
+                ),
+            )
+    except ImportError:
+        pass
+
+
+__all__ = ["DirectNotificationAdapter", "_register_default_channels"]