codex-bot 0.1.0__py3-none-any.whl

codex_bot/__init__.py

@@ -0,0 +1,24 @@
+"""
+codex_bot — Feature-based Aiogram framework library.
+
+Reusable infrastructure for Telegram bots with stateless UI management,
+Redis Stream integration, and advanced FSM capabilities.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Codex Team"
+__license__ = "MIT"
+
+from codex_bot.base.base_orchestrator import BaseBotOrchestrator, PayloadT
+from codex_bot.director.director import Director
+from codex_bot.engine.factory.bot_builder import BotBuilder
+from codex_bot.sender.view_sender import ViewSender
+
+__all__ = [
+    "BaseBotOrchestrator",
+    "PayloadT",
+    "Director",
+    "BotBuilder",
+    "ViewSender",
+    "__version__",
+]

codex_bot/animation/__init__.py

@@ -0,0 +1,10 @@
+"""
+codex_bot.animation — Waiting animation service for Telegram UI.
+"""
+
+from codex_bot.animation.animation_service import AnimationType, UIAnimationService
+
+__all__ = [
+    "UIAnimationService",
+    "AnimationType",
+]

codex_bot/animation/animation_service.py

@@ -0,0 +1,298 @@
+"""
+UIAnimationService — Waiting animation service for Telegram UI.
+
+Three main scenarios: delayed fetch, polling loop, timed polling.
+"""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from codex_bot.base.view_dto import UnifiedViewDTO, ViewResultDTO
+
+if TYPE_CHECKING:
+    from codex_bot.sender.view_sender import ViewSender
+
+
+class AnimationType(Enum):
+    """Animation type for displaying progress.
+
+    Attributes:
+        PROGRESS_BAR: Fills from 0% to 100%.
+        INFINITE: Running indicator (snake).
+        NONE: No animation.
+    """
+
+    PROGRESS_BAR = "progress_bar"
+    INFINITE = "infinite"
+    NONE = "none"
+
+
+PollerFunc = Callable[[], Awaitable[tuple[UnifiedViewDTO, bool]]]
+"""Poller function type: returns ``(view, is_waiting)``."""
+
+
+class UIAnimationService:
+    """Service for waiting animation (Polling).
+
+    Three main scenarios:
+
+    - `run_delayed_fetch` — animation for N seconds → one request at the end.
+    - `run_polling_loop` — request loop until an event occurs.
+    - `run_timed_polling` — immediate request → animation based on duration.
+
+    Args:
+        sender: ViewSender instance for sending intermediate frames.
+
+    Example:
+        ```python
+        animation = UIAnimationService(sender=container.view_sender)
+
+        async def fetch_result() -> tuple[UnifiedViewDTO, bool]:
+            data = await api.get_status(user_id)
+            return build_view(data), data.is_pending
+
+        await animation.run_polling_loop(
+            check_func=fetch_result,
+            timeout=60.0,
+            loading_text="⏳ <b>Waiting...</b>",
+        )
+        ```
+    """
+
+    def __init__(self, sender: "ViewSender") -> None:
+        self.sender = sender
+
+    # =========================================================================
+    # Public Methods
+    # =========================================================================
+
+    async def run_delayed_fetch(
+        self,
+        fetch_func: PollerFunc,
+        delay: float = 3.0,
+        step_interval: float = 1.0,
+        loading_text: str = "🔍 <b>Searching...</b>",
+        animation_type: AnimationType = AnimationType.PROGRESS_BAR,
+    ) -> None:
+        """Animation for N seconds → one request at the end.
+
+        Used for: Search, Scan — show animation, then make one request to the backend.
+
+        Args:
+            fetch_func: Function to retrieve data (called once at the end).
+            delay: Total animation duration in seconds.
+            step_interval: Interval between animation frames.
+            loading_text: Text to display during animation.
+            animation_type: Animation type (PROGRESS_BAR or INFINITE).
+        """
+        steps = max(1, int(delay / step_interval))
+
+        for i in range(steps):
+            anim_str = self._generate_animation(i, steps, loading_text, animation_type)
+            temp_view = UnifiedViewDTO(content=ViewResultDTO(text=anim_str))
+            await self._send(temp_view)
+            await asyncio.sleep(step_interval)
+
+        view_dto, _ = await self._poll_check(fetch_func)
+        await self._send(view_dto)
+
+    async def run_polling_loop(
+        self,
+        check_func: PollerFunc,
+        timeout: float = 60.0,
+        step_interval: float = 2.0,
+        loading_text: str = "⏳ <b>Waiting...</b>",
+        animation_type: AnimationType = AnimationType.INFINITE,
+    ) -> None:
+        """Request loop until an event occurs.
+
+        Used for: Combat polling, Arena waiting — make requests every N seconds
+        while ``is_waiting=True``.
+
+        Args:
+            check_func: Status check function, returns ``(view, is_waiting)``.
+            timeout: Maximum waiting time in seconds.
+            step_interval: Interval between checks.
+            loading_text: Text to display while waiting.
+            animation_type: Animation type (usually INFINITE).
+        """
+        steps = int(timeout / step_interval)
+
+        for i in range(steps):
+            view_dto, is_waiting = await self._poll_check(check_func)
+
+            if is_waiting and view_dto.content:
+                anim_str = self._generate_animation(i, steps, loading_text, animation_type)
+                view_dto = self._inject_animation(view_dto, anim_str)
+
+            await self._send(view_dto)
+
+            if not is_waiting:
+                return
+
+            await asyncio.sleep(step_interval)
+
+    async def run_timed_polling(
+        self,
+        check_func: PollerFunc,
+        duration: float = 5.0,
+        step_interval: float = 1.0,
+        loading_text: str = "🚶 <b>Moving...</b>",
+        animation_type: AnimationType = AnimationType.PROGRESS_BAR,
+    ) -> None:
+        """Immediate request → animation based on duration from the result.
+
+        Used for: Move — request goes to background immediately, result is stored
+        in Redis, show Progress Bar based on time.
+
+        Args:
+            check_func: Check function that reads the result from state/Redis.
+            duration: Expected animation duration.
+            step_interval: Interval between frames.
+            loading_text: Text to display.
+            animation_type: Animation type (PROGRESS_BAR for timed).
+        """
+        steps = max(1, int(duration / step_interval))
+
+        for i in range(steps):
+            view_dto, is_waiting = await self._poll_check(check_func)
+
+            if not is_waiting:
+                await self._send(view_dto)
+                return
+
+            anim_str = self._generate_animation(i, steps, loading_text, animation_type)
+            view_dto = self._inject_animation(view_dto, anim_str)
+
+            await self._send(view_dto)
+            await asyncio.sleep(step_interval)
+
+        # Overflow: Backend slow response → Infinite mode
+        infinite_step = 0
+        while True:
+            view_dto, is_waiting = await self._poll_check(check_func)
+
+            if not is_waiting:
+                await self._send(view_dto)
+                return
+
+            anim_str = self._generate_animation(infinite_step, steps, loading_text, AnimationType.INFINITE)
+            view_dto = self._inject_animation(view_dto, anim_str)
+
+            await self._send(view_dto)
+            await asyncio.sleep(step_interval)
+            infinite_step += 1
+
+    # =========================================================================
+    # Private Helpers
+    # =========================================================================
+
+    async def _poll_check(self, func: PollerFunc) -> tuple[UnifiedViewDTO, bool]:
+        """Performs status check.
+
+        Args:
+            func: Poller function.
+
+        Returns:
+            Tuple ``(view, is_waiting)``.
+        """
+        result: Any = await func()
+        if isinstance(result, tuple):
+            return result
+        return result, False
+
+    def _inject_animation(self, view_dto: UnifiedViewDTO, anim_str: str) -> UnifiedViewDTO:
+        """Injects animation string into content, returns new DTO.
+
+        Looks for ``{ANIMATION}`` in text and replaces it, otherwise adds to the end.
+        Uses ``model_copy`` since DTO is frozen.
+
+        Args:
+            view_dto: Original DTO.
+            anim_str: Animation string.
+
+        Returns:
+            New ``UnifiedViewDTO`` with updated text.
+        """
+        if not view_dto.content:
+            return view_dto
+
+        original_text = view_dto.content.text
+        if "{ANIMATION}" in original_text:
+            new_text = original_text.replace("{ANIMATION}", anim_str)
+        else:
+            new_text = original_text + f"\n\n{anim_str}"
+
+        new_content = view_dto.content.model_copy(update={"text": new_text})
+        return view_dto.model_copy(update={"content": new_content})
+
+    async def _send(self, view_dto: UnifiedViewDTO) -> None:
+        """Sends View via sender.
+
+        Args:
+            view_dto: DTO to send.
+        """
+        await self.sender.send(view_dto)
+
+    # =========================================================================
+    # Animation Generators
+    # =========================================================================
+
+    def _generate_animation(
+        self,
+        step: int,
+        total_steps: int,
+        text: str,
+        animation_type: AnimationType,
+    ) -> str:
+        """Generates animation string depending on the type.
+
+        Args:
+            step: Current step.
+            total_steps: Total steps.
+            text: Base text.
+            animation_type: Animation type.
+
+        Returns:
+            String with text and ASCII indicator.
+        """
+        if animation_type == AnimationType.PROGRESS_BAR:
+            return self._gen_progress_bar(step, total_steps, text)
+        if animation_type == AnimationType.INFINITE:
+            return self._gen_infinite_bar(step, text)
+        return text
+
+    def _gen_infinite_bar(self, step: int, text: str) -> str:
+        """Running indicator: ``[■□□□□] → [□■□□□] → …``
+
+        Args:
+            step: Current step.
+            text: Base text.
+
+        Returns:
+            String with running indicator.
+        """
+        total_chars = 10
+        position = step % total_chars
+        bar = "□" * position + "■" + "□" * (total_chars - position - 1)
+        return f"{text} [{bar}]"
+
+    def _gen_progress_bar(self, step: int, total_steps: int, text: str) -> str:
+        """Filling indicator: ``[■■□□□] 40%``
+
+        Args:
+            step: Current step.
+            total_steps: Total steps.
+            text: Base text.
+
+        Returns:
+            String with progress bar and percentage.
+        """
+        percent = 1.0 if total_steps == 0 else step / total_steps
+        total_chars = 10
+        filled = int(total_chars * percent)
+        empty = total_chars - filled
+        bar = "■" * filled + "□" * empty
+        return f"{text} [{bar}] {int(percent * 100)}%"

codex_bot/base/__init__.py

@@ -0,0 +1,22 @@
+"""
+codex_bot.base — Base DTOs and abstract orchestrator.
+
+Exports all public classes of the module.
+"""
+
+from codex_bot.base.base_orchestrator import BaseBotOrchestrator, PayloadT
+from codex_bot.base.context_dto import BaseBotContext
+from codex_bot.base.view_dto import (
+    MessageCoordsDTO,
+    UnifiedViewDTO,
+    ViewResultDTO,
+)
+
+__all__ = [
+    "BaseBotOrchestrator",
+    "PayloadT",
+    "BaseBotContext",
+    "MessageCoordsDTO",
+    "UnifiedViewDTO",
+    "ViewResultDTO",
+]

codex_bot/base/base_orchestrator.py

@@ -0,0 +1,123 @@
+"""
+BaseBotOrchestrator — Abstract STATELESS feature orchestrator.
+
+The Orchestrator is the heart of each feature. It knows how to transform
+an incoming payload into a UnifiedViewDTO for sending to the user.
+
+IMPORTANT: The class must be Stateless — it does not store user state in self.
+Orchestrators are singletons shared between all concurrent requests.
+All context is passed through method arguments (director, payload).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from codex_bot.base.view_dto import UnifiedViewDTO, ViewResultDTO
+
+if TYPE_CHECKING:
+    from codex_bot.director.director import Director
+
+PayloadT = TypeVar("PayloadT")
+"""TypeVar for the orchestrator payload. A specific subclass specifies the type explicitly."""
+
+
+class BaseBotOrchestrator(ABC, Generic[PayloadT]):  # noqa: UP046
+    """Abstract STATELESS feature orchestrator.
+
+    Defines the contract for all orchestrators in the system.
+    The Director uses this interface for cross-feature transitions.
+
+    The class is a singleton — one instance handles requests from all users
+    concurrently. No mutable user state in ``self``.
+    All context (user_id, chat_id, FSM) is passed through the ``director``.
+
+    Subclasses must implement:
+        - ``render_content(payload, director)`` — main rendering logic.
+
+    Subclasses may override:
+        - ``handle_entry(director, payload)`` — entry point into the feature.
+
+    Args:
+        expected_state: FSM state string set when entering the feature.
+                        None — state does not change.
+
+    Example:
+        ```python
+        class BookingOrchestrator(BaseBotOrchestrator[BookingPayload]):
+            def __init__(self):
+                super().__init__(expected_state="BookingStates:main")
+
+            async def render_content(
+                self, payload: BookingPayload, director: Director
+            ) -> ViewResultDTO:
+                slots = await self.api.get_slots(director.user_id)
+                return ViewResultDTO(text=format_slots(slots), kb=build_kb(slots))
+        ```
+    """
+
+    def __init__(self, expected_state: str | None = None) -> None:
+        self.expected_state = expected_state
+
+    @abstractmethod
+    async def render_content(
+        self,
+        payload: PayloadT,
+        director: Director,
+    ) -> ViewResultDTO:
+        """Main logic for rendering feature content.
+
+        Must be implemented in each specific orchestrator.
+
+        Args:
+            payload: Data for rendering (DTO from backend, dict, etc.).
+            director: Context of the current request (user_id, chat_id, state).
+
+        Returns:
+            ViewResultDTO with text and keyboard.
+        """
+        ...
+
+    async def handle_entry(
+        self,
+        director: Director,
+        payload: PayloadT | None = None,
+    ) -> UnifiedViewDTO:
+        """Entry point into the feature. Called by the Director during set_scene().
+
+        The default implementation simply calls render(payload, director).
+        Override for complex feature initialization logic.
+
+        Args:
+            director: Context of the current request.
+            payload: Initial data for rendering.
+
+        Returns:
+            UnifiedViewDTO for sending to the user.
+        """
+        return await self.render(payload, director)
+
+    async def render(
+        self,
+        payload: PayloadT | None,
+        director: Director,
+    ) -> UnifiedViewDTO:
+        """Assembles UnifiedViewDTO from render_content().
+
+        Enriches the result with data from the director (chat_id, session_key).
+
+        Args:
+            payload: Data for rendering.
+            director: Context of the current request.
+
+        Returns:
+            UnifiedViewDTO ready to be sent via ViewSender.
+        """
+        content_view = await self.render_content(payload, director)  # type: ignore[arg-type]
+        return UnifiedViewDTO(content=content_view, menu=None).model_copy(
+            update={
+                "chat_id": director.chat_id,
+                "session_key": director.user_id,
+            }
+        )

codex_bot/base/context_dto.py

@@ -0,0 +1,42 @@
+"""
+Context DTOs — Immutable context of a Telegram event.
+
+BaseBotContext contains the minimum necessary set of data
+for any orchestrator to work: user_id, chat_id, message_id.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseBotContext(BaseModel):
+    """
+    Base immutable context for a Telegram event.
+
+    Extracted from Message or CallbackQuery via ContextHelper.
+    Contains only identifiers — no business logic.
+
+    Attributes:
+        user_id: Telegram ID of the user. Used as a session key.
+        chat_id: ID of the chat (private, group, channel).
+        message_id: ID of the message that triggered the event.
+        message_thread_id: ID of the topic in a supergroup (if applicable).
+        session_key: Key for state storage (defaults to user_id).
+
+    Example:
+        ```python
+        ctx = BaseBotContext(user_id=123, chat_id=123, message_id=42)
+        print(ctx.session_key)  # 123
+        ```
+    """
+
+    user_id: int
+    chat_id: int
+    message_id: int | None = None
+    message_thread_id: int | None = None
+
+    model_config = ConfigDict(frozen=True)
+
+    @property
+    def session_key(self) -> int:
+        """Key for storing state in Redis (defaults to user_id)."""
+        return self.user_id

codex_bot/base/view_dto.py

@@ -0,0 +1,93 @@
+"""
+View DTOs — Immutable response objects from the Orchestrator.
+
+All DTOs are frozen (frozen=True) for safe transfer
+between asynchronous services without the risk of race conditions.
+If you need to change a field — use model_copy(update={...}).
+"""
+
+from typing import Literal
+
+from aiogram.types import InlineKeyboardMarkup
+from pydantic import BaseModel, ConfigDict
+
+
+class ViewResultDTO(BaseModel):
+    """DTO for representing a single message (text + keyboard).
+
+    Attributes:
+        text: HTML-text of the message.
+        kb: Inline keyboard. None — without a keyboard.
+
+    Example:
+        ```python
+        view = ViewResultDTO(text="Hello!", kb=my_keyboard)
+        ```
+    """
+
+    text: str
+    kb: InlineKeyboardMarkup | None = None
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+
+class MessageCoordsDTO(BaseModel):
+    """Telegram message coordinates (chat_id + message_id).
+
+    Attributes:
+        chat_id: Chat ID.
+        message_id: Message ID in the chat.
+
+    Example:
+        ```python
+        coords = MessageCoordsDTO(chat_id=123456, message_id=42)
+        ```
+    """
+
+    chat_id: int
+    message_id: int
+
+    model_config = ConfigDict(frozen=True)
+
+
+class UnifiedViewDTO(BaseModel):
+    """Unified immutable response DTO from the Orchestrator.
+
+    Contains optional Menu and Content blocks, as well as metadata
+    for routing and UI management (deletion, history clearing).
+
+    Attributes:
+        content: Main content block (text + buttons).
+        menu: Navigation menu block. None — menu is not updated.
+        clean_history: If True — ViewSender will delete previous UI messages.
+        alert_text: Text for a popup alert (for CallbackQuery).
+        trigger_message_id: ID of the trigger message (e.g., /start) for deletion.
+        chat_id: Target chat ID. Filled by the Director.
+        session_key: Session key (user_id or channel session). Filled by the Director.
+        mode: Sending mode — strictly ``"channel"``, ``"topic"``, or ``"user"``.
+        message_thread_id: Topic ID in a supergroup.
+
+    Example:
+        ```python
+        view = UnifiedViewDTO(
+            content=ViewResultDTO(text="Content"),
+            menu=ViewResultDTO(text="Menu"),
+        )
+        # To change chat_id after creation — use model_copy:
+        view = view.model_copy(update={"chat_id": 123456})
+        ```
+    """
+
+    content: ViewResultDTO | None = None
+    menu: ViewResultDTO | None = None
+    clean_history: bool = False
+    alert_text: str | None = None
+    trigger_message_id: int | None = None
+
+    # --- Routing & Session (filled by Director) ---
+    chat_id: int | str | None = None
+    session_key: int | str | None = None
+    mode: Literal["channel", "topic", "user"] | None = None
+    message_thread_id: int | None = None
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)

codex_bot/cli/__init__.py

@@ -0,0 +1,11 @@
+"""
+codex_bot.cli — Project management commands.
+
+Usage:
+    codex-bot create-feature my_feature
+    codex-bot create-feature my_feature --type redis
+"""
+
+from codex_bot.cli.commands import main
+
+__all__ = ["main"]