hexcore 2.2.0__tar.gz → 2.3.0__tar.gz

{hexcore-2.2.0/hexcore.egg-info → hexcore-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 2.2.0
+Version: 2.3.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -456,6 +456,127 @@ En ambos casos, es tu **EventBus** (o un consumidor como Procrastinate) el encar
 
 ---
 
+### Integración con Task Queues (Smart Routing)
+
+HexCore v2 hace que la delegación de tareas a **Celery**, **Procrastinate** o **ARQ** sea increíblemente sencilla y mágica a través del patrón de **Smart Routing**.
+
+Ya no necesitas instanciar buses separados para código síncrono y asíncrono. HexCore enruta automáticamente tus comandos y eventos hacia las colas de background usando simples decoradores.
+
+#### 1. Decoradores de Background
+
+HexCore ofrece 3 decoradores esenciales en `hexcore.domain.cqrs.decorators` para cubrir todos los casos de uso:
+
+1. **`@background_command(queue="...")`**: Aplícalo sobre una clase `Command`. Todo el comando y su handler se ejecutarán asíncronamente en el Worker. Ideal para operaciones pesadas iniciadas por el usuario (ej. Generar un reporte PDF masivo).
+2. **`@background_handler(queue="...")`**: Aplícalo sobre una función que maneje un evento (`DomainEvent`). Permite que un solo evento dispare algunas acciones síncronas rápidas y otras asíncronas lentas (ej. Enviar emails).
+3. **`@background_task(queue="...")`**: Aplícalo sobre funciones o utilidades genéricas que no pertenecen al modelo estricto de CQRS (ej. Limpiar base de datos, tareas tipo CRON).
+
+**Ejemplos de uso:**
+
+```python
+from hexcore.domain.cqrs.decorators import background_command, background_handler, background_task
+from hexcore.domain.cqrs.commands import Command
+
+# 1. Comando de ejecución asíncrona obligatoria
+@background_command(queue="high_priority")
+class SendEmailCommand(Command):
+    user_id: str
+    template: str
+
+# 2. Handler de evento asíncrono
+@background_handler(queue="analytics")
+async def send_analytics_on_user_created(event: UserCreatedEvent):
+    # Lógica costosa...
+    pass
+
+# 3. Tarea genérica (Non-CQRS)
+@background_task(queue="maintenance")
+async def clean_old_records_task(days_retention: int):
+    # Limpieza de base de datos...
+    pass
+```
+
+#### 2. Crear el Enqueuer (Adaptador)
+
+Implementa la interfaz genérica `ITaskEnqueuer` usando la SDK de tu Task Queue favorito:
+
+```python
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+class ProcrastinateEnqueuer(ITaskEnqueuer):
+    async def enqueue_command(self, command_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_command.defer_async(payload=payload)
+        
+    async def enqueue_handler(self, handler_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_handler.defer_async(handler_name=handler_name, payload=payload)
+    
+    async def enqueue_event(self, event_name: str, payload: dict, queue: str) -> None:
+        pass # Usualmente no se usa directamente si utilizas @background_handler
+        
+    async def enqueue_task(self, task_name: str, payload: dict, queue: str) -> None:
+        await process_generic_task.defer_async(task_name=task_name, payload=payload)
+```
+
+#### 3. Configurar tus Buses (Enrutamiento Automático)
+
+Al inyectar tu enqueuer en los buses estándar de memoria en tu API, estos adquieren la habilidad de enrutamiento inteligente. (Si usas un comando decorado pero no inyectas un enqueuer, HexCore levantará una excepción tempranamente).
+
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus, InMemoryEventBus
+
+enqueuer = ProcrastinateEnqueuer()
+serializer = PydanticSerializer()
+
+# El bus evalúa: ¿Tiene el comando @background_command? Si es así, usa el enqueuer.
+command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
+
+# El bus evalúa suscriptores: ¿Tienen @background_handler? Si es así, usa el enqueuer.
+event_bus = InMemoryEventBus(enqueuer=enqueuer, serializer=serializer)
+```
+
+#### 4. Ejecutar tareas genéricas
+
+Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
+
+```python
+# Así se encola una tarea genérica sin CQRS:
+await enqueuer.enqueue_task(
+    task_name=clean_old_records_task.__cqrs_task_name__, 
+    payload={"days_retention": 30},
+    queue=clean_old_records_task.__cqrs_queue__
+)
+```
+
+#### 5. Levantar el Worker (Consumidor Universal)
+
+En el entrypoint de tu worker (ej. Celery o Procrastinate), usa el `CQRSConsumer` de HexCore para deserializar y ejecutar los payloads interceptados. El consumidor usa resolución dinámica para invocar la función correcta automáticamente.
+
+```python
+from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+consumer = CQRSConsumer(
+    command_bus=command_bus, # Tu CommandBus configurado
+    event_bus=event_bus, 
+    serializer=serializer
+)
+
+@app.task(name="process_cqrs_command")
+async def process_cqrs_command(payload: dict):
+    # HexCore deserializa y ejecuta el Command usando el CommandBus local
+    await consumer.process_command(payload)
+
+@app.task(name="process_cqrs_handler")
+async def process_cqrs_handler(handler_name: str, payload: dict):
+    # HexCore resuelve y ejecuta exclusivamente el Event Handler asíncrono
+    await consumer.process_handler(handler_name, payload)
+
+@app.task(name="process_generic_task")
+async def process_generic_task(task_name: str, payload: dict):
+    # HexCore resuelve e inyecta los kwargs a la función pura
+    await consumer.process_task(task_name, payload)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

{hexcore-2.2.0 → hexcore-2.3.0}/README.md

@@ -430,6 +430,127 @@ En ambos casos, es tu **EventBus** (o un consumidor como Procrastinate) el encar
 
 ---
 
+### Integración con Task Queues (Smart Routing)
+
+HexCore v2 hace que la delegación de tareas a **Celery**, **Procrastinate** o **ARQ** sea increíblemente sencilla y mágica a través del patrón de **Smart Routing**.
+
+Ya no necesitas instanciar buses separados para código síncrono y asíncrono. HexCore enruta automáticamente tus comandos y eventos hacia las colas de background usando simples decoradores.
+
+#### 1. Decoradores de Background
+
+HexCore ofrece 3 decoradores esenciales en `hexcore.domain.cqrs.decorators` para cubrir todos los casos de uso:
+
+1. **`@background_command(queue="...")`**: Aplícalo sobre una clase `Command`. Todo el comando y su handler se ejecutarán asíncronamente en el Worker. Ideal para operaciones pesadas iniciadas por el usuario (ej. Generar un reporte PDF masivo).
+2. **`@background_handler(queue="...")`**: Aplícalo sobre una función que maneje un evento (`DomainEvent`). Permite que un solo evento dispare algunas acciones síncronas rápidas y otras asíncronas lentas (ej. Enviar emails).
+3. **`@background_task(queue="...")`**: Aplícalo sobre funciones o utilidades genéricas que no pertenecen al modelo estricto de CQRS (ej. Limpiar base de datos, tareas tipo CRON).
+
+**Ejemplos de uso:**
+
+```python
+from hexcore.domain.cqrs.decorators import background_command, background_handler, background_task
+from hexcore.domain.cqrs.commands import Command
+
+# 1. Comando de ejecución asíncrona obligatoria
+@background_command(queue="high_priority")
+class SendEmailCommand(Command):
+    user_id: str
+    template: str
+
+# 2. Handler de evento asíncrono
+@background_handler(queue="analytics")
+async def send_analytics_on_user_created(event: UserCreatedEvent):
+    # Lógica costosa...
+    pass
+
+# 3. Tarea genérica (Non-CQRS)
+@background_task(queue="maintenance")
+async def clean_old_records_task(days_retention: int):
+    # Limpieza de base de datos...
+    pass
+```
+
+#### 2. Crear el Enqueuer (Adaptador)
+
+Implementa la interfaz genérica `ITaskEnqueuer` usando la SDK de tu Task Queue favorito:
+
+```python
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+
+class ProcrastinateEnqueuer(ITaskEnqueuer):
+    async def enqueue_command(self, command_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_command.defer_async(payload=payload)
+        
+    async def enqueue_handler(self, handler_name: str, payload: dict, queue: str) -> None:
+        await process_cqrs_handler.defer_async(handler_name=handler_name, payload=payload)
+    
+    async def enqueue_event(self, event_name: str, payload: dict, queue: str) -> None:
+        pass # Usualmente no se usa directamente si utilizas @background_handler
+        
+    async def enqueue_task(self, task_name: str, payload: dict, queue: str) -> None:
+        await process_generic_task.defer_async(task_name=task_name, payload=payload)
+```
+
+#### 3. Configurar tus Buses (Enrutamiento Automático)
+
+Al inyectar tu enqueuer en los buses estándar de memoria en tu API, estos adquieren la habilidad de enrutamiento inteligente. (Si usas un comando decorado pero no inyectas un enqueuer, HexCore levantará una excepción tempranamente).
+
+```python
+from hexcore.application.cqrs.in_memory_buses import InMemoryCommandBus, InMemoryEventBus
+
+enqueuer = ProcrastinateEnqueuer()
+serializer = PydanticSerializer()
+
+# El bus evalúa: ¿Tiene el comando @background_command? Si es así, usa el enqueuer.
+command_bus = InMemoryCommandBus(registry=registry, enqueuer=enqueuer, serializer=serializer)
+
+# El bus evalúa suscriptores: ¿Tienen @background_handler? Si es así, usa el enqueuer.
+event_bus = InMemoryEventBus(enqueuer=enqueuer, serializer=serializer)
+```
+
+#### 4. Ejecutar tareas genéricas
+
+Para encolar la tarea genérica (`@background_task`), la llamas indirectamente pasándola por el enqueuer:
+
+```python
+# Así se encola una tarea genérica sin CQRS:
+await enqueuer.enqueue_task(
+    task_name=clean_old_records_task.__cqrs_task_name__, 
+    payload={"days_retention": 30},
+    queue=clean_old_records_task.__cqrs_queue__
+)
+```
+
+#### 5. Levantar el Worker (Consumidor Universal)
+
+En el entrypoint de tu worker (ej. Celery o Procrastinate), usa el `CQRSConsumer` de HexCore para deserializar y ejecutar los payloads interceptados. El consumidor usa resolución dinámica para invocar la función correcta automáticamente.
+
+```python
+from hexcore.infrastructure.workers.consumer import CQRSConsumer
+
+consumer = CQRSConsumer(
+    command_bus=command_bus, # Tu CommandBus configurado
+    event_bus=event_bus, 
+    serializer=serializer
+)
+
+@app.task(name="process_cqrs_command")
+async def process_cqrs_command(payload: dict):
+    # HexCore deserializa y ejecuta el Command usando el CommandBus local
+    await consumer.process_command(payload)
+
+@app.task(name="process_cqrs_handler")
+async def process_cqrs_handler(handler_name: str, payload: dict):
+    # HexCore resuelve y ejecuta exclusivamente el Event Handler asíncrono
+    await consumer.process_handler(handler_name, payload)
+
+@app.task(name="process_generic_task")
+async def process_generic_task(task_name: str, payload: dict):
+    # HexCore resuelve e inyecta los kwargs a la función pura
+    await consumer.process_task(task_name, payload)
+```
+
+---
+
 ## Referencias
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md): Pautas de colaboración.

hexcore-2.3.0/hexcore/application/cqrs/in_memory_buses.py

@@ -0,0 +1,164 @@
+"""
+Implementaciones In-Memory de los buses CQRS con soporte para Enrutamiento Inteligente (Smart Routing).
+"""
+from __future__ import annotations
+
+import typing as t
+import logging
+
+from hexcore.domain.cqrs.buses import ICommandBus, IQueryBus, IEventBus
+from hexcore.domain.cqrs.commands import Command
+from hexcore.domain.cqrs.queries import Query
+from hexcore.domain.events import DomainEvent
+from hexcore.domain.cqrs.task_queues import ITaskEnqueuer
+from hexcore.domain.cqrs.serializer import ISerializer
+
+from .registry import HandlerRegistry
+from .pipeline import MiddlewarePipeline
+
+logger = logging.getLogger("hexcore.cqrs.buses")
+
+
+class InMemoryCommandBus(ICommandBus):
+    """
+    Bus de commands síncrono en memoria con Smart Routing.
+    Resuelve el handler desde el registry, ejecuta el pipeline de middlewares
+    y retorna el resultado.
+    
+    Si el comando está decorado con `@background_command` y se provee un `enqueuer`,
+    el comando es automáticamente encolado para su ejecución en segundo plano
+    sin bloquear el proceso actual (retornando None).
+    """
+
+    def __init__(
+        self,
+        registry: HandlerRegistry,
+        pipeline: MiddlewarePipeline | None = None,
+        enqueuer: ITaskEnqueuer | None = None,
+        serializer: ISerializer | None = None,
+    ) -> None:
+        self._registry = registry
+        self._pipeline = pipeline or MiddlewarePipeline()
+        self._enqueuer = enqueuer
+        self._serializer = serializer
+
+    async def dispatch(self, command: Command) -> t.Any:
+        cmd_type = type(command)
+        
+        # 1. Smart Routing: ¿Debe irse a background?
+        is_background = getattr(cmd_type, "__cqrs_background__", False)
+        
+        if is_background:
+            if not self._enqueuer or not self._serializer:
+                raise RuntimeError(
+                    f"El comando '{cmd_type.__name__}' requiere ejecución en background, "
+                    "pero el InMemoryCommandBus no tiene configurado un 'enqueuer' o 'serializer'."
+                )
+            
+            async def background_dispatcher(cmd: Command) -> None:
+                queue_name = getattr(cmd_type, "__cqrs_queue__", "default")
+                payload = self._serializer.serialize(cmd) # type: ignore
+                await self._enqueuer.enqueue_command(cmd_type.__name__, payload, queue=queue_name) # type: ignore
+                logger.debug("[SmartRouting] Comando %s enrutado a background (queue=%s)", cmd_type.__name__, queue_name)
+
+            await self._pipeline.execute(command, background_dispatcher)
+            return None
+
+        # 2. Ejecución Local Estándar
+        handler = self._registry.resolve_command_handler(cmd_type)
+
+        async def final_handler(cmd: t.Any) -> t.Any:
+            return await handler.handle(cmd)
+
+        return await self._pipeline.execute(command, final_handler)
+
+
+class InMemoryQueryBus(IQueryBus):
+    """
+    Bus de queries síncrono en memoria.
+    Las queries NUNCA pasan por buses asíncronos
+    (principio CQRS: las lecturas son siempre síncronas).
+    """
+
+    def __init__(
+        self,
+        registry: HandlerRegistry,
+        pipeline: MiddlewarePipeline | None = None,
+    ) -> None:
+        self._registry = registry
+        self._pipeline = pipeline or MiddlewarePipeline()
+
+    async def ask(self, query: Query[t.Any]) -> t.Any:
+        handler = self._registry.resolve_query_handler(type(query))
+
+        async def final_handler(q: t.Any) -> t.Any:
+            return await handler.handle(q)
+
+        return await self._pipeline.execute(query, final_handler)
+
+
+class InMemoryEventBus(IEventBus):
+    """
+    Bus de eventos en memoria con Smart Routing para Handlers Asíncronos.
+    
+    Permite publicar eventos a todos los suscriptores. Si un suscriptor
+    fue decorado con `@background_handler`, se enviará un mensaje al Task Queue
+    para que *solo* ese handler se ejecute en background para este evento.
+    """
+
+    def __init__(
+        self,
+        pipeline: MiddlewarePipeline | None = None,
+        enqueuer: ITaskEnqueuer | None = None,
+        serializer: ISerializer | None = None,
+    ) -> None:
+        self._handlers: dict[
+            type[DomainEvent],
+            list[t.Callable[[DomainEvent], t.Awaitable[None]]],
+        ] = {}
+        self._pipeline = pipeline or MiddlewarePipeline()
+        self._enqueuer = enqueuer
+        self._serializer = serializer
+
+    def subscribe(
+        self,
+        event_type: type[DomainEvent],
+        handler: t.Callable[[DomainEvent], t.Awaitable[None]],
+    ) -> None:
+        self._handlers.setdefault(event_type, []).append(handler)
+
+    async def publish(self, event: DomainEvent) -> None:
+        handlers = self._handlers.get(type(event), [])
+
+        for event_handler in handlers:
+            is_background = getattr(event_handler, "__cqrs_background_handler__", False)
+
+            if is_background:
+                # Enrutamiento hacia background
+                if not self._enqueuer or not self._serializer:
+                    raise RuntimeError(
+                        f"El handler de eventos '{event_handler.__name__}' requiere ejecución en background, "
+                        "pero el InMemoryEventBus no tiene configurado un 'enqueuer' o 'serializer'."
+                    )
+                
+                async def background_dispatcher(
+                    evt: t.Any,
+                    _h: t.Callable[..., t.Awaitable[None]] = event_handler,
+                ) -> None:
+                    handler_name = getattr(_h, "__cqrs_handler_name__")
+                    queue_name = getattr(_h, "__cqrs_queue__", "default")
+                    payload = self._serializer.serialize(evt) # type: ignore
+                    await self._enqueuer.enqueue_handler(handler_name, payload, queue=queue_name) # type: ignore
+                    logger.debug("[SmartRouting] EventHandler %s enrutado a background (queue=%s)", handler_name, queue_name)
+                    
+                await self._pipeline.execute(event, background_dispatcher)
+                
+            else:
+                # Ejecución local síncrona
+                async def final_handler(
+                    evt: t.Any,
+                    _h: t.Callable[..., t.Awaitable[None]] = event_handler,
+                ) -> None:
+                    await _h(evt)
+
+                await self._pipeline.execute(event, final_handler)

hexcore-2.3.0/hexcore/domain/cqrs/decorators.py

@@ -0,0 +1,78 @@
+"""
+Decoradores para habilitar el enrutamiento inteligente (Smart Routing) de tareas, comandos
+y manejadores de eventos hacia Task Queues (Celery, Procrastinate, etc.) de forma transparente.
+"""
+from __future__ import annotations
+
+import typing as t
+
+
+def background_command(queue: str = "default") -> t.Callable[[t.Type[t.Any]], t.Type[t.Any]]:
+    """
+    Decora una clase `Command` para indicar que su ejecución debe enviarse siempre
+    a un procesador en segundo plano (Task Queue).
+    
+    Cuando el CommandBus detecta este decorador, no ejecutará el comando localmente,
+    sino que llamará a `ITaskEnqueuer.enqueue_command()`.
+    
+    Ejemplo:
+        @background_command(queue="emails")
+        class SendEmailCommand(Command):
+            ...
+    """
+    def wrapper(cls: t.Type[t.Any]) -> t.Type[t.Any]:
+        cls.__cqrs_background__ = True
+        cls.__cqrs_queue__ = queue
+        return cls
+
+    return wrapper
+
+
+def background_handler(queue: str = "default") -> t.Callable[[t.Callable[..., t.Any]], t.Callable[..., t.Any]]:
+    """
+    Decora un manejador de eventos (Event Handler) para indicar que su ejecución
+    debe ocurrir de forma asíncrona en un Worker de background.
+    
+    Cuando el EventBus detecta este decorador en un handler suscrito, en lugar de
+    ejecutarlo directamente, delegará la tarea a `ITaskEnqueuer.enqueue_handler()`.
+    
+    Ejemplo:
+        @background_handler(queue="analytics")
+        async def on_user_created(event: UserCreatedEvent):
+            ...
+    """
+    def wrapper(func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
+        func.__cqrs_background_handler__ = True
+        func.__cqrs_queue__ = queue
+        
+        # Guardamos el nombre calificado del handler para poder resolverlo luego en el Worker
+        if not hasattr(func, "__qualname__"):
+            func.__cqrs_handler_name__ = func.__name__
+        else:
+            func.__cqrs_handler_name__ = f"{func.__module__}.{func.__qualname__}"
+            
+        return func
+
+    return wrapper
+
+
+def background_task(queue: str = "default") -> t.Callable[[t.Callable[..., t.Any]], t.Callable[..., t.Any]]:
+    """
+    Decora una función genérica para convertirla en una Tarea de Background
+    (independiente de CQRS).
+    
+    La función original queda marcada, y puede ser registrada en el
+    `TaskManager` de HexCore o ejecutada directamente usando el `ITaskEnqueuer`.
+    """
+    def wrapper(func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
+        func.__cqrs_background_task__ = True
+        func.__cqrs_queue__ = queue
+        
+        if not hasattr(func, "__qualname__"):
+            func.__cqrs_task_name__ = func.__name__
+        else:
+            func.__cqrs_task_name__ = f"{func.__module__}.{func.__qualname__}"
+            
+        return func
+
+    return wrapper

hexcore-2.3.0/hexcore/domain/cqrs/task_queues.py

@@ -0,0 +1,64 @@
+"""
+Interfaces fundamentales para delegar mensajes a Task Queues (Celery, Procrastinate, RQ, ARQ).
+"""
+from __future__ import annotations
+
+import abc
+import typing as t
+
+if t.TYPE_CHECKING:
+    pass
+
+
+class ITaskEnqueuer(abc.ABC):
+    """
+    Puerto (Puerto de Salida) genérico para encolar tareas asíncronas
+    o en paralelo hacia un backend de colas de mensajes (Task Queue).
+    
+    Un adaptador concreto (ej. `CeleryTaskEnqueuer`) usará la SDK
+    nativa del worker para empujar el `payload`.
+    """
+
+    @abc.abstractmethod
+    async def enqueue_command(self, command_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola un comando de dominio serializado para ser ejecutado en background.
+        
+        Args:
+            command_name: Nombre calificado del comando (e.g. 'CreateUserCommand').
+            payload: Payload pre-serializado.
+            queue: Nombre de la cola de destino.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_event(self, event_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola un evento de dominio serializado para ser distribuido genéricamente.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_handler(self, handler_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola la ejecución de un *Event Handler Específico* para un evento.
+        Esto permite que un Evento dispare handlers asíncronos individuales.
+        
+        Args:
+            handler_name: Nombre calificado del handler (func.__cqrs_handler_name__).
+            payload: Payload pre-serializado del evento.
+            queue: Nombre de la cola.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def enqueue_task(self, task_name: str, payload: dict[str, t.Any], queue: str) -> None:
+        """
+        Encola una tarea genérica de background (independiente de CQRS).
+        
+        Args:
+            task_name: Nombre calificado de la tarea (func.__cqrs_task_name__).
+            payload: Argumentos serializados para la tarea.
+            queue: Nombre de la cola.
+        """
+        raise NotImplementedError

hexcore-2.3.0/hexcore/infrastructure/workers/consumer.py

@@ -0,0 +1,123 @@
+"""
+Consumidor Universal para colas de tareas (Celery, Procrastinate).
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+import typing as t
+
+from hexcore.domain.cqrs.buses import AbstractCommandBus, AbstractEventBus
+from hexcore.domain.cqrs.serializer import ISerializer
+from hexcore.domain.events import DomainEvent
+
+if t.TYPE_CHECKING:
+    from hexcore.domain.cqrs.commands import Command
+
+logger = logging.getLogger("hexcore.workers.consumer")
+
+
+def _resolve_callable(qualname: str) -> t.Callable[..., t.Any]:
+    """Resuelve un import por su nombre calificado (ej. 'myapp.events.on_user_created')."""
+    try:
+        module_path, func_name = qualname.rsplit(".", 1)
+        module = importlib.import_module(module_path)
+        return getattr(module, func_name) # type: ignore
+    except (ValueError, ModuleNotFoundError, AttributeError) as exc:
+        raise RuntimeError(f"No se pudo resolver el handler/tarea '{qualname}': {exc}") from exc
+
+
+class CQRSConsumer:
+    """
+    Ayudante universal para recibir mensajes serializados desde un Worker 
+    y despacharlos a los handlers locales usando buses en memoria.
+    
+    Uso (ej. Procrastinate):
+    
+        consumer = CQRSConsumer(local_cmd_bus, local_evt_bus, serializer)
+        
+        @app.task(name="process_cqrs_command")
+        async def process_cqrs_command(payload: dict):
+            await consumer.process_command(payload)
+    """
+
+    def __init__(
+        self,
+        command_bus: AbstractCommandBus,
+        event_bus: AbstractEventBus,
+        serializer: ISerializer,
+    ) -> None:
+        """
+        Args:
+            command_bus: El bus de comandos *local* (usualmente InMemoryCommandBus)
+                         que tiene registrados los handlers.
+            event_bus: El bus de eventos *local* (usualmente InMemoryEventBus).
+            serializer: El serializador usado (ej. PydanticSerializer).
+        """
+        self._command_bus = command_bus
+        self._event_bus = event_bus
+        self._serializer = serializer
+
+    async def process_command(self, payload: dict[str, t.Any]) -> None:
+        """
+        Deserializa un payload de comando y lo despacha al bus local.
+        """
+        try:
+            command = self._serializer.deserialize(payload)
+            cmd = t.cast("Command", command)
+            
+            logger.info("[CQRSConsumer] Procesando comando en background: %s", type(cmd).__qualname__)
+            await self._command_bus.dispatch(cmd)
+            
+        except Exception as exc:
+            logger.exception("[CQRSConsumer] Error procesando comando: %s", exc)
+            raise
+
+    async def process_event(self, payload: dict[str, t.Any]) -> None:
+        """
+        Deserializa un payload de evento y lo publica en el bus local
+        para que todos los handlers (suscriptores) locales lo consuman.
+        """
+        try:
+            event = self._serializer.deserialize(payload)
+            evt = t.cast(DomainEvent, event)
+            
+            logger.info("[CQRSConsumer] Procesando evento en background: %s", evt.event_name)
+            await self._event_bus.publish(evt)
+            
+        except Exception as exc:
+            logger.exception("[CQRSConsumer] Error procesando evento: %s", exc)
+            raise
+
+    async def process_handler(self, handler_name: str, payload: dict[str, t.Any]) -> None:
+        """
+        Deserializa el evento y ejecuta *específicamente* un handler decorado con `@background_handler`.
+        Esto es inyectado por el Smart Routing del EventBus.
+        """
+        try:
+            event = self._serializer.deserialize(payload)
+            evt = t.cast(DomainEvent, event)
+            
+            logger.info("[CQRSConsumer] Ejecutando EventHandler individual en background: %s", handler_name)
+            
+            handler_func = _resolve_callable(handler_name)
+            await handler_func(evt)
+            
+        except Exception as exc:
+            logger.exception("[CQRSConsumer] Error procesando EventHandler %s: %s", handler_name, exc)
+            raise
+
+    async def process_task(self, task_name: str, payload: dict[str, t.Any]) -> None:
+        """
+        Ejecuta una tarea genérica de background decorada con `@background_task`.
+        """
+        try:
+            logger.info("[CQRSConsumer] Ejecutando Task genérica en background: %s", task_name)
+            
+            task_func = _resolve_callable(task_name)
+            # El payload en tareas genéricas son los kwargs
+            await task_func(**payload)
+            
+        except Exception as exc:
+            logger.exception("[CQRSConsumer] Error ejecutando Task %s: %s", task_name, exc)
+            raise