roomkit 0.1.0__py3-none-any.whl

roomkit/core/hooks.py

@@ -0,0 +1,232 @@
+"""Hook engine for sync and async hook pipelines."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+from roomkit.models.context import RoomContext
+from roomkit.models.enums import ChannelDirection, ChannelType, HookExecution, HookTrigger
+from roomkit.models.event import RoomEvent
+from roomkit.models.hook import HookResult, InjectedEvent
+from roomkit.models.task import Observation, Task
+
+logger = logging.getLogger("roomkit.hooks")
+
+SyncHookFn = Callable[[RoomEvent, RoomContext], Coroutine[Any, Any, HookResult]]
+AsyncHookFn = Callable[[RoomEvent, RoomContext], Coroutine[Any, Any, None]]
+
+
+@dataclass
+class HookRegistration:
+    """A registered hook function.
+
+    Attributes:
+        trigger: When the hook fires (BEFORE_BROADCAST, AFTER_BROADCAST, etc.)
+        execution: SYNC (can block/modify) or ASYNC (fire-and-forget)
+        fn: The hook function
+        priority: Lower numbers run first (default: 0)
+        name: Optional name for logging and removal
+        timeout: Max execution time in seconds (default: 30.0)
+        channel_types: Only run for events from these channel types (None = all)
+        channel_ids: Only run for events from these channel IDs (None = all)
+        directions: Only run for events with these directions (None = all)
+    """
+
+    trigger: HookTrigger
+    execution: HookExecution
+    fn: SyncHookFn | AsyncHookFn
+    priority: int = 0
+    name: str = ""
+    timeout: float = 30.0
+    # Filters (None = match all)
+    channel_types: set[ChannelType] | None = None
+    channel_ids: set[str] | None = None
+    directions: set[ChannelDirection] | None = None
+
+
+@dataclass
+class IdentityHookRegistration:
+    """A registered identity hook function.
+
+    Attributes:
+        trigger: When the hook fires (ON_IDENTITY_AMBIGUOUS, ON_IDENTITY_UNKNOWN)
+        fn: The hook function
+        channel_types: Only run for events from these channel types (None = all)
+        channel_ids: Only run for events from these channel IDs (None = all)
+        directions: Only run for events with these directions (None = all)
+    """
+
+    trigger: HookTrigger
+    fn: Any  # IdentityHookFn - using Any to avoid circular import
+    channel_types: set[ChannelType] | None = None
+    channel_ids: set[str] | None = None
+    directions: set[ChannelDirection] | None = None
+
+
+@dataclass
+class SyncPipelineResult:
+    """Result of running the sync hook pipeline."""
+
+    allowed: bool = True
+    event: RoomEvent | None = None
+    reason: str | None = None
+    blocked_by: str | None = None
+    injected_events: list[InjectedEvent] = field(default_factory=list)
+    tasks: list[Task] = field(default_factory=list)
+    observations: list[Observation] = field(default_factory=list)
+    hook_errors: list[dict[str, str]] = field(default_factory=list)
+
+
+class HookEngine:
+    """Manages global and per-room hook registration and execution."""
+
+    def __init__(self) -> None:
+        self._global_hooks: list[HookRegistration] = []
+        self._room_hooks: dict[str, list[HookRegistration]] = {}
+
+    def register(self, hook: HookRegistration) -> None:
+        """Register a global hook."""
+        self._global_hooks.append(hook)
+
+    def add_room_hook(self, room_id: str, hook: HookRegistration) -> None:
+        """Register a hook for a specific room."""
+        self._room_hooks.setdefault(room_id, []).append(hook)
+
+    def remove_room_hook(self, room_id: str, name: str) -> bool:
+        """Remove a room hook by name."""
+        hooks = self._room_hooks.get(room_id, [])
+        for i, h in enumerate(hooks):
+            if h.name == name:
+                hooks.pop(i)
+                return True
+        return False
+
+    def _hook_matches_event(self, hook: HookRegistration, event: RoomEvent) -> bool:
+        """Check if a hook's filters match the given event."""
+        source = event.source
+
+        # All filters must pass (None means "match all")
+        type_ok = hook.channel_types is None or source.channel_type in hook.channel_types
+        id_ok = hook.channel_ids is None or source.channel_id in hook.channel_ids
+        dir_ok = hook.directions is None or source.direction in hook.directions
+
+        return type_ok and id_ok and dir_ok
+
+    def _get_hooks(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        execution: HookExecution,
+        event: RoomEvent | None = None,
+    ) -> list[HookRegistration]:
+        """Get merged global + room hooks filtered and sorted by priority.
+
+        Args:
+            room_id: The room ID to get hooks for
+            trigger: The hook trigger to filter by
+            execution: The execution mode to filter by
+            event: Optional event to filter hooks by channel_type/id/direction
+        """
+        all_hooks = [
+            h for h in self._global_hooks if h.trigger == trigger and h.execution == execution
+        ]
+        room_hooks = [
+            h
+            for h in self._room_hooks.get(room_id, [])
+            if h.trigger == trigger and h.execution == execution
+        ]
+        all_hooks.extend(room_hooks)
+
+        # Apply event-based filters if event is provided
+        if event is not None:
+            all_hooks = [h for h in all_hooks if self._hook_matches_event(h, event)]
+
+        all_hooks.sort(key=lambda h: h.priority)
+        return all_hooks
+
+    async def run_sync_hooks(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        event: RoomEvent,
+        context: RoomContext,
+    ) -> SyncPipelineResult:
+        """Run sync hooks sequentially. Stops on block, passes modified events."""
+        hooks = self._get_hooks(room_id, trigger, HookExecution.SYNC, event=event)
+        result = SyncPipelineResult(event=event)
+
+        for hook in hooks:
+            try:
+                current_event = result.event or event
+                fn = cast(SyncHookFn, hook.fn)
+                hook_result: HookResult = await asyncio.wait_for(
+                    fn(current_event, context), timeout=hook.timeout
+                )
+            except TimeoutError:
+                logger.warning(
+                    "Sync hook %s timed out after %.1fs",
+                    hook.name,
+                    hook.timeout,
+                    extra={"room_id": room_id},
+                )
+                result.hook_errors.append(
+                    {"hook": hook.name, "error": f"timeout ({hook.timeout}s)"}
+                )
+                continue
+            except Exception as exc:
+                logger.exception("Sync hook %s failed", hook.name, extra={"room_id": room_id})
+                result.hook_errors.append({"hook": hook.name, "error": str(exc)})
+                continue
+
+            result.injected_events.extend(hook_result.injected_events)
+            result.tasks.extend(hook_result.tasks)
+            result.observations.extend(hook_result.observations)
+
+            if hook_result.action == "block":
+                result.allowed = False
+                result.reason = hook_result.reason
+                result.blocked_by = hook.name
+                return result
+
+            if hook_result.action == "modify" and hook_result.event is not None:
+                result.event = hook_result.event
+
+        return result
+
+    async def run_async_hooks(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        event: RoomEvent,
+        context: RoomContext,
+    ) -> None:
+        """Run async hooks concurrently. Errors are logged, never raised."""
+        hooks = self._get_hooks(room_id, trigger, HookExecution.ASYNC, event=event)
+        if not hooks:
+            return
+
+        async def _run_one(hook: HookRegistration) -> None:
+            try:
+                await asyncio.wait_for(
+                    hook.fn(event, context),
+                    timeout=hook.timeout,
+                )
+            except TimeoutError:
+                logger.warning(
+                    "Async hook %s timed out after %.1fs",
+                    hook.name,
+                    hook.timeout,
+                    extra={"room_id": room_id},
+                )
+            except Exception:
+                logger.exception(
+                    "Async hook %s failed",
+                    hook.name,
+                    extra={"room_id": room_id},
+                )
+
+        await asyncio.gather(*[_run_one(hook) for hook in hooks], return_exceptions=True)

roomkit/core/inbound_router.py

@@ -0,0 +1,57 @@
+"""Inbound room router — determines which room an inbound message belongs to."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roomkit.models.enums import ChannelType, RoomStatus
+from roomkit.store.base import ConversationStore
+
+
+class InboundRoomRouter(ABC):
+    """Route an inbound message to a room (or ``None`` for auto-create)."""
+
+    @abstractmethod
+    async def route(
+        self,
+        channel_id: str,
+        channel_type: ChannelType,
+        participant_id: str | None = None,
+        channel_data: dict[str, Any] | None = None,
+    ) -> str | None:
+        """Return room_id for the message, or ``None`` to create a new room."""
+        ...
+
+
+class DefaultInboundRoomRouter(InboundRoomRouter):
+    """Default router: find room by channel binding, then by participant."""
+
+    def __init__(self, store: ConversationStore) -> None:
+        self._store = store
+
+    async def route(
+        self,
+        channel_id: str,
+        channel_type: ChannelType,
+        participant_id: str | None = None,
+        channel_data: dict[str, Any] | None = None,
+    ) -> str | None:
+        # Strategy 1: Find room by channel binding (current behavior)
+        room_id = await self._store.find_room_id_by_channel(
+            channel_id, status=str(RoomStatus.ACTIVE)
+        )
+        if room_id is not None:
+            return room_id
+
+        # Strategy 2: Find room by participant if available
+        if participant_id:
+            room = await self._store.find_latest_room(
+                participant_id=participant_id,
+                channel_type=str(channel_type),
+                status=str(RoomStatus.ACTIVE),
+            )
+            if room:
+                return room.id
+
+        return None

roomkit/core/locks.py

@@ -0,0 +1,66 @@
+"""Per-room async locking with LRU eviction."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections import OrderedDict
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+
+class RoomLockManager(ABC):
+    """Abstract base for per-room locking.
+
+    Implement this to plug in any locking backend (Redis, Postgres
+    advisory locks, etc.).  The library ships with ``InMemoryLockManager``
+    for single-process deployments.
+    """
+
+    @abstractmethod
+    @asynccontextmanager
+    async def locked(self, room_id: str) -> AsyncIterator[None]:
+        """Acquire an exclusive lock for *room_id*."""
+        yield  # pragma: no cover
+
+
+class InMemoryLockManager(RoomLockManager):
+    """In-process per-room asyncio locks with LRU eviction.
+
+    Suitable for single-process deployments.  For multi-process or
+    distributed setups, provide a custom ``RoomLockManager`` backed by
+    Redis, Postgres advisory locks, or similar.
+    """
+
+    def __init__(self, max_locks: int = 1024) -> None:
+        self._locks: OrderedDict[str, asyncio.Lock] = OrderedDict()
+        self._max_locks = max_locks
+
+    def _get_lock(self, room_id: str) -> asyncio.Lock:
+        if room_id in self._locks:
+            self._locks.move_to_end(room_id)
+            return self._locks[room_id]
+
+        lock = asyncio.Lock()
+        self._locks[room_id] = lock
+        self._evict()
+        return lock
+
+    def _evict(self) -> None:
+        while len(self._locks) > self._max_locks:
+            oldest_key, oldest_lock = next(iter(self._locks.items()))
+            if oldest_lock.locked():
+                break
+            self._locks.pop(oldest_key)
+
+    @asynccontextmanager
+    async def locked(self, room_id: str) -> AsyncIterator[None]:
+        """Acquire the lock for a room."""
+        lock = self._get_lock(room_id)
+        async with lock:
+            yield
+
+    @property
+    def size(self) -> int:
+        """Return the number of locks currently held."""
+        return len(self._locks)

roomkit/core/rate_limiter.py

@@ -0,0 +1,67 @@
+"""Token-bucket rate limiter for channel delivery."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from roomkit.models.channel import RateLimit
+
+
+class TokenBucketRateLimiter:
+    """Per-channel token bucket rate limiter.
+
+    Uses ``RateLimit.max_per_second`` for the bucket refill rate.
+    Falls back to ``max_per_minute / 60`` or ``max_per_hour / 3600``.
+
+    **Concurrency note:** This implementation relies on the CPython single-threaded
+    asyncio model. The ``acquire`` method reads and writes ``_buckets`` with no
+    ``await`` between the check and the set, making the token update atomic within
+    a single event-loop iteration. The ``wait`` method uses ``asyncio.sleep``
+    between acquire attempts, which is safe because each iteration re-reads the
+    bucket state after yielding control.
+    """
+
+    def __init__(self) -> None:
+        # channel_id -> (tokens, last_refill_time)
+        self._buckets: dict[str, tuple[float, float]] = {}
+
+    def _rate_per_second(self, rate_limit: RateLimit) -> float:
+        if rate_limit.max_per_second is not None:
+            return rate_limit.max_per_second
+        if rate_limit.max_per_minute is not None:
+            return rate_limit.max_per_minute / 60.0
+        if rate_limit.max_per_hour is not None:
+            return rate_limit.max_per_hour / 3600.0
+        return float("inf")
+
+    def _refill(self, channel_id: str, rate: float) -> float:
+        """Refill tokens and return current count."""
+        now = time.monotonic()
+        tokens, last_refill = self._buckets.get(channel_id, (rate, now))
+        elapsed = now - last_refill
+        tokens = min(tokens + elapsed * rate, rate)  # cap at rate (burst = 1s)
+        self._buckets[channel_id] = (tokens, now)
+        return tokens
+
+    def acquire(self, channel_id: str, rate_limit: RateLimit) -> bool:
+        """Try to acquire a token. Returns True if allowed, False if rate limited."""
+        rate = self._rate_per_second(rate_limit)
+        if rate == float("inf"):
+            return True
+
+        tokens = self._refill(channel_id, rate)
+        if tokens >= 1.0:
+            self._buckets[channel_id] = (tokens - 1.0, time.monotonic())
+            return True
+        return False
+
+    async def wait(self, channel_id: str, rate_limit: RateLimit) -> None:
+        """Wait until a token is available (queue instead of drop)."""
+        rate = self._rate_per_second(rate_limit)
+        if rate == float("inf"):
+            return
+
+        while not self.acquire(channel_id, rate_limit):
+            # Wait for one token to refill
+            await asyncio.sleep(1.0 / rate)

roomkit/core/retry.py

@@ -0,0 +1,49 @@
+"""Retry with exponential backoff for delivery operations."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from roomkit.models.channel import RetryPolicy
+
+logger = logging.getLogger("roomkit.retry")
+
+__all__ = ["RetryPolicy", "retry_with_backoff"]
+
+
+async def retry_with_backoff[T](
+    fn: Callable[..., Coroutine[Any, Any, T]],
+    policy: RetryPolicy,
+    *args: Any,
+    **kwargs: Any,
+) -> T:
+    """Execute *fn* with exponential backoff retry.
+
+    Raises the last exception if all retries are exhausted.
+    """
+    last_exc: Exception | None = None
+    for attempt in range(1 + policy.max_retries):
+        try:
+            return await fn(*args, **kwargs)
+        except Exception as exc:
+            last_exc = exc
+            if attempt >= policy.max_retries:
+                break
+            delay = min(
+                policy.base_delay_seconds * (policy.exponential_base**attempt),
+                policy.max_delay_seconds,
+            )
+            logger.warning(
+                "Attempt %d/%d failed, retrying in %.1fs",
+                attempt + 1,
+                policy.max_retries + 1,
+                delay,
+                extra={"attempt": attempt + 1, "delay": delay},
+            )
+            await asyncio.sleep(delay)
+
+    assert last_exc is not None
+    raise last_exc

roomkit/core/router.py

@@ -0,0 +1,24 @@
+"""Abstract base classes for routing and transcoding."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from roomkit.models.channel import ChannelBinding
+from roomkit.models.event import EventContent
+
+
+class ContentTranscoder(ABC):
+    """Transcodes event content between channel capabilities."""
+
+    @abstractmethod
+    async def transcode(
+        self,
+        content: EventContent,
+        source_binding: ChannelBinding,
+        target_binding: ChannelBinding,
+    ) -> EventContent | None:
+        """Transcode content for the target channel's capabilities.
+
+        Return ``None`` to signal that the content cannot be represented.
+        """

roomkit/core/transcoder.py

@@ -0,0 +1,85 @@
+"""Default content transcoder with fallback conversions."""
+
+from __future__ import annotations
+
+from roomkit.core.router import ContentTranscoder
+from roomkit.models.channel import ChannelBinding
+from roomkit.models.enums import ChannelMediaType
+from roomkit.models.event import (
+    AudioContent,
+    CompositeContent,
+    EventContent,
+    LocationContent,
+    MediaContent,
+    RichContent,
+    TextContent,
+    VideoContent,
+)
+
+
+class DefaultContentTranscoder(ContentTranscoder):
+    """Transcodes content using simple fallback rules."""
+
+    async def transcode(
+        self,
+        content: EventContent,
+        source_binding: ChannelBinding,
+        target_binding: ChannelBinding,
+    ) -> EventContent | None:
+        """Transcode content for the target channel's capabilities.
+
+        Returns ``None`` if the content cannot be represented at all
+        on the target channel (signalling a transcoding failure).
+        """
+        target_types = target_binding.capabilities.media_types
+
+        if isinstance(content, TextContent):
+            return content
+
+        if isinstance(content, RichContent):
+            if ChannelMediaType.RICH in target_types:
+                return content
+            return TextContent(body=content.plain_text or content.body)
+
+        if isinstance(content, MediaContent):
+            if ChannelMediaType.MEDIA in target_types:
+                return content
+            caption = content.caption or content.filename or content.url
+            return TextContent(body=f"[Media: {caption}]")
+
+        if isinstance(content, AudioContent):
+            if ChannelMediaType.AUDIO in target_types:
+                return content
+            if content.transcript:
+                return TextContent(body=content.transcript)
+            return TextContent(body=f"[Voice message: {content.url}]")
+
+        if isinstance(content, VideoContent):
+            if ChannelMediaType.VIDEO in target_types:
+                return content
+            return TextContent(body=f"[Video: {content.url}]")
+
+        if isinstance(content, LocationContent):
+            if ChannelMediaType.LOCATION in target_types:
+                return content
+            label = content.label or content.address or ""
+            return TextContent(
+                body=f"[Location: {label} ({content.latitude}, {content.longitude})]"
+            )
+
+        if isinstance(content, CompositeContent):
+            parts: list[EventContent] = []
+            for part in content.parts:
+                transcoded = await self.transcode(part, source_binding, target_binding)
+                if transcoded is None:
+                    continue
+                parts.append(transcoded)
+            if not parts:
+                return None
+            # If all parts are text, flatten to single TextContent
+            text_parts = [p for p in parts if isinstance(p, TextContent)]
+            if len(text_parts) == len(parts):
+                return TextContent(body="\n".join(p.body for p in text_parts))
+            return CompositeContent(parts=parts)
+
+        return content

roomkit/identity/base.py

@@ -0,0 +1,27 @@
+"""Abstract base class for identity resolution."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.identity import IdentityResult
+
+
+class IdentityResolver(ABC):
+    """Resolves user identity from inbound messages."""
+
+    @abstractmethod
+    async def resolve(self, message: InboundMessage, context: RoomContext) -> IdentityResult:
+        """Resolve the identity of an inbound message sender.
+
+        Args:
+            message: The inbound message with sender information.
+            context: Current room context (room, bindings, participants).
+
+        Returns:
+            An identity result indicating identified, ambiguous, pending,
+            unknown, or rejected status.
+        """
+        ...

roomkit/identity/mock.py

@@ -0,0 +1,49 @@
+"""Mock identity resolver for testing."""
+
+from __future__ import annotations
+
+from roomkit.identity.base import IdentityResolver
+from roomkit.models.context import RoomContext
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.enums import IdentificationStatus
+from roomkit.models.identity import Identity, IdentityResult
+
+
+class MockIdentityResolver(IdentityResolver):
+    """Resolves identity from a pre-configured mapping.
+
+    Supports three resolution outcomes:
+    - **Identified**: sender_id found in ``mapping`` → single identity.
+    - **Ambiguous**: sender_id found in ``ambiguous`` → multiple candidates.
+    - **Unknown/Pending**: no match → status controlled by ``unknown_status``.
+    """
+
+    def __init__(
+        self,
+        mapping: dict[str, Identity] | None = None,
+        ambiguous: dict[str, list[Identity]] | None = None,
+        unknown_status: IdentificationStatus = IdentificationStatus.UNKNOWN,
+    ) -> None:
+        self._mapping = mapping or {}
+        self._ambiguous = ambiguous or {}
+        self._unknown_status = unknown_status
+
+    async def resolve(self, message: InboundMessage, context: RoomContext) -> IdentityResult:
+        # Exact match → identified
+        identity = self._mapping.get(message.sender_id)
+        if identity:
+            return IdentityResult(
+                status=IdentificationStatus.IDENTIFIED,
+                identity=identity,
+            )
+
+        # Multiple candidates → ambiguous
+        candidates = self._ambiguous.get(message.sender_id)
+        if candidates:
+            return IdentityResult(
+                status=IdentificationStatus.AMBIGUOUS,
+                candidates=candidates,
+            )
+
+        # No match
+        return IdentityResult(status=self._unknown_status)