codex-bot 0.1.0__tar.gz

codex_bot-0.1.0/.claude/project.md

@@ -0,0 +1,25 @@
+# codex-bot — agent quick reference
+
+## Memory
+`C:\Users\prime\.claude\projects\C--install-progect-codex-bot\memory\MEMORY.md`
+
+## Project
+- Package: `C:/install/progect/codex_bot/`
+- Source: `C:/install/progect/lily_website/src/telegram_bot/`
+- Status: все модули реализованы, идёт code review
+
+## Dev commands
+```bash
+cd C:/install/progect/codex_bot
+mkdocs build --strict      # проверка документации
+ruff check src/            # линтинг
+mypy src/                  # типы
+python -c "import codex_bot; print('ok')"
+```
+
+## Key conventions
+- Все DTO: `frozen=True`, мутации через `model_copy(update=...)`
+- Оркестраторы: stateless singleton, `Generic[PayloadT]`
+- Redis: SET NX (атомарно), не EXISTS + SET
+- ImportError: проверяем `e.name == module_path` (умный Fail Fast)
+- engine/ = инфраструктура "под капотом", не публичный API

codex_bot-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install -e \".[docs]\" -q)",
+      "Bash(python -c \"from codex_bot.base import BaseBotOrchestrator, UnifiedViewDTO, ViewResultDTO, BaseBotContext, MenuViewDTO, MessageCoordsDTO; print\\(''OK:'', BaseBotOrchestrator, UnifiedViewDTO\\)\")",
+      "Bash(mkdocs build --strict)",
+      "Bash(pip show mkdocs mkdocs-material)"
+    ]
+  }
+}

codex_bot-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs,all]"
+
+      - name: Build and deploy docs
+        run: |
+          mkdocs gh-deploy --force

codex_bot-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# --- Python Core ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+ENV/
+
+# --- Build & Distribution ---
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- Testing & Coverage ---
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+htmlcov/
+
+# --- Documentation ---
+site/
+docs/_build/
+
+# --- Linting & Typing ---
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# --- IDEs & Editors ---
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# --- Project Specific ---
+.env
+.envrc
+*.log
+# Temporary files from LocalesCompiler (if they leak into root)
+bot_locales_*

codex_bot-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+        args: ['--maxkb=2000']
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.44.0
+    hooks:
+      - id: markdownlint
+        args: ["--fix", "--disable", "MD013"]
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.2
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        additional_dependencies: ["bandit[toml]"]
+
+  # 2. Поиск "забытых" секретов и паролей (усиленный)
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        # Baseline will be added after manual creation

codex_bot-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-09
+
+### Added
+- **Initial Library Release**: Migration and adaptation of core infrastructure from production projects into a reusable feature-based framework.
+- **Feature-based Architecture**: Implementation of `BaseBotOrchestrator` and `Director` for stateless UI management.
+- **Redis Integration**: Stream processing, consumer groups support, and Redis-based dispatching.
+- **FSM Enhancements**: `GarbageStateRegistry` for automatic UI cleanup and advanced state management.
+- **Unified View System**: `ViewSender` and `UnifiedViewDTO` for consistent message rendering across different platforms.
+- **I18n Engine**: Custom Fluent-based locales compiler with isolation support.
+- **CLI Tools**: Scaffolding templates for rapid feature development.
+- **Multi-language Documentation**: Comprehensive guides and API references in English and Russian.
+- **DevOps Infrastructure**: Pre-commit hooks, Ruff/Mypy configurations, and GitHub Actions for docs.
+- **Final Polish**: Refined `Director` logic, `BotBuilder` factory, and `RouterBuilder` for better stability.
+- **Enhanced State Management**: Improved `StateManager` and `FSM` handlers for more robust session control.
+- **Redis Dispatcher Optimization**: Fine-tuned stream processing and error handling in `RedisDispatcher`.
+- **Test Coverage**: Added comprehensive unit tests for all core modules.
+
+### Changed
+- Refactored production code into a modular library structure.
+- Standardized DTOs and protocols for better extensibility.
+- Optimized Redis Stream processing for high-load scenarios.
+- Improved type safety across the entire codebase (Mypy strict mode).

codex_bot-0.1.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# codex-bot — AI Context
+
+Feature-based Aiogram framework library. MIT license, public GitHub.
+
+---
+
+## Agent Memory
+
+> **Memory directory:** `C:\Users\prime\.claude\projects\C--install-progect-codex-bot\memory\`
+>
+> Агент из любого проекта: читай `MEMORY.md` там — это индекс.
+> Детали в: `architecture.md`, `modules.md`, `fixes.md`
+
+---
+
+## Структура пакета
+
+```
+src/codex_bot/
+├── base/               ← BaseBotOrchestrator[T] (ABC), UnifiedViewDTO, ViewResultDTO
+├── director/           ← Director, OrchestratorProtocol, ContainerProtocol, SceneConfig
+├── fsm/                ← BaseStateManager, GarbageStateRegistry, common_fsm_router
+├── sender/             ← ViewSender (stateless), SenderManager, SenderKeys
+├── redis/              ← RedisRouter, BotRedisDispatcher, RedisStreamProcessor
+├── animation/          ← UIAnimationService, AnimationType
+├── helper/             ← ContextHelper
+├── url_signer/         ← UrlSignerService
+└── engine/             ← инфраструктура "под капотом"
+    ├── middlewares/    ← ThrottlingMiddleware, ContainerMiddleware, UserValidationMiddleware
+    ├── discovery/      ← FeatureDiscoveryService (service.py)
+    ├── factory/        ← BotBuilder (bot_builder.py)
+    ├── router_builder/ ← collect_feature_routers, build_main_router (router_builder.py)
+    ├── http/           ← BaseApiClient, ApiClientError (api_client.py)
+    └── i18n/           ← compile_locales (locales_compiler.py)
+```
+
+---
+
+## Стандарты (обязательно)
+
+- **Packaging**: Hatchling, PEP 621
+- **Docstrings**: Google style — Args / Returns / Example
+- **Docs**: MkDocs Material + mkdocstrings
+- **DTO**: `frozen=True, arbitrary_types_allowed=True`, мутации через `model_copy(update=...)`
+- **Оркестраторы**: stateless `Generic[PayloadT]`, `director` явный аргумент
+- **Fail Fast**: умный `except ImportError` (проверяем `e.name == module_path`)
+- **Redis**: SET NX вместо EXISTS + SET (атомарно, нет race condition)
+- **SecurityMiddleware**: удалён навсегда (иллюзорная защита + лишний HGETALL)

codex_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodexDLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_bot-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: codex-bot
+Version: 0.1.0
+Summary: Feature-based Aiogram framework library — reusable infrastructure for Telegram bots
+Author: Codex Team
+License: MIT
+License-File: LICENSE
+Keywords: aiogram,bot,framework,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: aiogram<4.0,>=3.4
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: all
+Requires-Dist: aiogram-i18n>=1.4; extra == 'all'
+Requires-Dist: arq>=0.25; extra == 'all'
+Requires-Dist: httpx<1.0,>=0.27; extra == 'all'
+Requires-Dist: redis[asyncio]<6.0,>=5.0; extra == 'all'
+Provides-Extra: arq
+Requires-Dist: arq>=0.25; extra == 'arq'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: http
+Requires-Dist: httpx<1.0,>=0.27; extra == 'http'
+Provides-Extra: i18n
+Requires-Dist: aiogram-i18n>=1.4; extra == 'i18n'
+Provides-Extra: redis
+Requires-Dist: redis[asyncio]<6.0,>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Codex Bot Framework
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Codex Bot** is a professional, feature-based framework built on top of [Aiogram 3.x](https://github.com/aiogram/aiogram). It provides a reusable, production-ready infrastructure for building complex, scalable Telegram bots with a focus on stateless UI management and high-load Redis integration.
+
+---
+
+## 🚀 Key Features
+
+- **Feature-based Architecture**: Organize your bot into independent, reusable features.
+- **Stateless Orchestrators**: Manage UI logic without storing state in memory, making your bot horizontally scalable.
+- **Redis Stream Integration**: Native support for high-load event processing with Consumer Groups.
+- **Advanced FSM**: Automatic UI cleanup with `GarbageStateRegistry` and structured state management.
+- **Unified View System**: Consistent message rendering across different platforms using DTOs.
+- **Fluent-based I18n**: Powerful localization engine with project-level isolation and automatic compilation.
+- **CLI Scaffolding**: Rapidly generate new features with pre-defined templates.
+
+---
+
+## 📦 Installation
+
+Install the core library:
+```bash
+pip install codex-bot
+```
+
+Install with optional dependencies:
+```bash
+pip install "codex-bot[redis,i18n,http]"
+```
+
+---
+
+## 🛠 Quick Start
+
+```python
+from codex_bot import BotBuilder, BaseBotOrchestrator, Director
+from codex_bot.base.view_dto import ViewResultDTO
+
+# 1. Define your feature orchestrator
+class MyFeatureOrchestrator(BaseBotOrchestrator[None]):
+    async def render_content(self, payload: None, director: Director) -> ViewResultDTO:
+        return ViewResultDTO(text="Hello from Codex Bot!")
+
+# 2. Build and run your bot
+builder = BotBuilder(token="YOUR_TELEGRAM_TOKEN")
+builder.register_orchestrator("main", MyFeatureOrchestrator())
+builder.run_polling()
+```
+
+---
+
+## 📚 Documentation
+
+- [English Documentation](https://codex-team.github.io/codex_bot/en_EN/)
+- [Русская документация](https://codex-team.github.io/codex_bot/ru_RU/)
+- [**Changelog**](CHANGELOG.md) — see what's new in the latest versions.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+
+---
+
+### 🇷🇺 Краткое описание (RU)
+**Codex Bot** — это профессиональный фреймворк для создания Telegram-ботов на базе Aiogram 3.x. Он предоставляет готовую инфраструктуру для разработки сложных и масштабируемых систем, используя архитектуру на основе "фич", stateless-оркестраторы и глубокую интеграцию с Redis Streams.

codex_bot-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Codex Bot Framework
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-bot.svg)](https://pypi.org/project/codex-bot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Codex Bot** is a professional, feature-based framework built on top of [Aiogram 3.x](https://github.com/aiogram/aiogram). It provides a reusable, production-ready infrastructure for building complex, scalable Telegram bots with a focus on stateless UI management and high-load Redis integration.
+
+---
+
+## 🚀 Key Features
+
+- **Feature-based Architecture**: Organize your bot into independent, reusable features.
+- **Stateless Orchestrators**: Manage UI logic without storing state in memory, making your bot horizontally scalable.
+- **Redis Stream Integration**: Native support for high-load event processing with Consumer Groups.
+- **Advanced FSM**: Automatic UI cleanup with `GarbageStateRegistry` and structured state management.
+- **Unified View System**: Consistent message rendering across different platforms using DTOs.
+- **Fluent-based I18n**: Powerful localization engine with project-level isolation and automatic compilation.
+- **CLI Scaffolding**: Rapidly generate new features with pre-defined templates.
+
+---
+
+## 📦 Installation
+
+Install the core library:
+```bash
+pip install codex-bot
+```
+
+Install with optional dependencies:
+```bash
+pip install "codex-bot[redis,i18n,http]"
+```
+
+---
+
+## 🛠 Quick Start
+
+```python
+from codex_bot import BotBuilder, BaseBotOrchestrator, Director
+from codex_bot.base.view_dto import ViewResultDTO
+
+# 1. Define your feature orchestrator
+class MyFeatureOrchestrator(BaseBotOrchestrator[None]):
+    async def render_content(self, payload: None, director: Director) -> ViewResultDTO:
+        return ViewResultDTO(text="Hello from Codex Bot!")
+
+# 2. Build and run your bot
+builder = BotBuilder(token="YOUR_TELEGRAM_TOKEN")
+builder.register_orchestrator("main", MyFeatureOrchestrator())
+builder.run_polling()
+```
+
+---
+
+## 📚 Documentation
+
+- [English Documentation](https://codex-team.github.io/codex_bot/en_EN/)
+- [Русская документация](https://codex-team.github.io/codex_bot/ru_RU/)
+- [**Changelog**](CHANGELOG.md) — see what's new in the latest versions.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+
+---
+
+### 🇷🇺 Краткое описание (RU)
+**Codex Bot** — это профессиональный фреймворк для создания Telegram-ботов на базе Aiogram 3.x. Он предоставляет готовую инфраструктуру для разработки сложных и масштабируемых систем, используя архитектуру на основе "фич", stateless-оркестраторы и глубокую интеграцию с Redis Streams.

codex_bot-0.1.0/docs/DOCUMENTATION_STANDARD.md

@@ -0,0 +1,142 @@
+# 🧭 Documentation Standard for codex-bot
+
+> **AUTHORITY:** This document defines how documentation is written, structured, and maintained in the `codex-bot` library.
+
+---
+
+## 1. 📜 Core Philosophy
+
+We maintain documentation in **two languages** to ensure international accessibility while keeping the local community engaged.
+
+### 🇬🇧 English (Primary / Technical Truth)
+
+- **Mandatory for:** All Pull Requests and technical specifications.
+- **Location:**
+  - `docs/api/` — Technical API reference (auto-generated from docstrings).
+  - `docs/en_EN/` — Conceptual guides and architectural mirroring.
+- **Content:**
+  - Full technical specifications.
+  - API documentation (via `docs/api/`).
+  - Code examples and integration guides.
+- **Goal:** Single source of truth. If code contradicts EN docs, it is a bug.
+
+### 🇷🇺 Russian (Secondary / Conceptual Hub)
+
+- **Optional for Contributors:** If you don't speak Russian, write EN docs. Maintainers will add RU translation.
+- **Location:** `docs/ru_RU/` (mirrors folder structure).
+- **Content:**
+  - Conceptual translation (the "why" and "how").
+  - Links to `docs/api/` for technical details instead of duplication.
+  - Architect's mental model and design decision explanations.
+- **Goal:** Help Russian-speaking developers understand the "why" behind the framework's architecture.
+
+---
+
+## 2. ☯️ Twin Realms Principle
+
+Documentation languages serve different purposes:
+
+### 🇬🇧 EN = Technical Truth
+
+- **For:** AI generators, external libraries, standards compliance.
+- **Format:** Granular (mirrors `src/codex_bot/` structure).
+- **Contains:**
+  - API Reference (in `docs/api/`).
+  - Mermaid Diagrams (Sequence, Class, ER).
+  - Integration patterns.
+
+### 🇷🇺 RU = Architect's Mind
+
+- **For:** Human developers, system understanding.
+- **Format:** Aggregated (1 folder = 1 README).
+- **Contains:**
+  - **The Why:** Why this solution (e.g., why Stateless Orchestrators) was chosen.
+  - **The Flow:** How data flows through the system (simplified).
+  - **Links:** References to `docs/api/` files for technical details.
+
+---
+
+## 3. 🗂️ Structure Mirroring Rule
+
+Documentation structure **MUST** mirror the code structure in `src/codex_bot/`.
+
+### Mapping Example
+
+| Code Location | Documentation Location (EN/RU) |
+|:---|:---|
+| `src/codex_bot/base/` | `docs/[lang]/architecture/base/` |
+| `src/codex_bot/engine/router_builder/` | `docs/[lang]/architecture/engine/router_builder/` |
+| `src/codex_bot/redis/` | `docs/[lang]/architecture/redis/` |
+
+### Why?
+
+- **1:1 Mapping:** Easy to find docs for any code module.
+- **No Orphans:** Prevents documentation from getting lost.
+- **Refactoring Safety:** When code moves, docs move with it.
+
+---
+
+## 4. 🧭 Navigation Standard
+
+Every documentation file must be easily navigable.
+
+### Breadcrumbs (Mandatory)
+
+Every file **MUST** start with a navigation header:
+
+```markdown
+[⬅️ Back](../README.md) | [🏠 Docs Root](../../README.md)
+```
+
+- **Back:** Links to the current directory's `README.md`.
+- **Docs Root:** Links to the documentation root (`docs/README.md`).
+
+### Index Files (README.md)
+
+Every directory **MUST** have a `README.md` acting as a navigation hub.
+
+**Required Structure:**
+
+1. **Header:** Emoji 📂 + Section Name.
+2. **Navigation:** Breadcrumbs.
+3. **Description:** Short summary (2-3 sentences).
+4. **Map:** Table or list of files in **logical reading order** (not alphabetical).
+
+---
+
+## 5. 📝 File Naming & Organization
+
+### Naming Conventions
+
+- **Format:** `snake_case.md` (e.g., `orchestrator_logic.md`).
+- **No Prefixes:** Do NOT use `01_`, `02_` prefixes in filenames.
+- **Reading Order:** Defined in `README.md` map.
+
+### Language Folders
+
+All documents **MUST** reside in:
+
+- `docs/api/` (Technical EN)
+- `docs/en_EN/` (Conceptual EN)
+- `docs/ru_RU/` (Conceptual RU)
+
+---
+
+## 6. ✅ Markdown Linting Rules (Strict)
+
+1. **MD047 (End with Newline):** Every file must end with exactly **one newline** (`\n`).
+2. **MD032 (List Spacing):** Blank line before and after any list.
+3. **MD007 (Indentation):** Use **2 spaces** for nested lists.
+
+---
+
+## 7. 🚫 Common Mistakes
+
+- **❌ Duplicating Code in RU Docs:** Link to `docs/api/` instead.
+- **❌ Numbered Prefixes:** Use `README.md` map for order.
+- **❌ Missing Breadcrumbs:** Always add the navigation header.
+- **❌ Language-neutral folders:** Use `en_EN` or `ru_RU`.
+
+---
+
+**Last Updated:** 2025-02-07

codex_bot-0.1.0/docs/README.md

@@ -0,0 +1,36 @@
+# 🤖 codex-bot Documentation
+
+Welcome to the official documentation for `codex-bot` — a feature-based Aiogram framework library for building scalable Telegram bots.
+
+---
+
+## 🌍 Choose Your Language
+
+| Language | Description |
+|:---|:---|
+| **[🇬🇧 English](./en_EN/README.md)** | Primary documentation, conceptual guides, and architecture. |
+| **[🇷🇺 Русский](./ru_RU/README.md)** | Conceptual translation and architect's mental model. |
+
+---
+
+## 📄 Technical Reference
+
+| Section | Description |
+|:---|:---|
+| **[🛠️ API Reference](./api/README.md)** | Full technical API documentation generated from code docstrings. |
+| **[🧭 Documentation Standard](./DOCUMENTATION_STANDARD.md)** | How we write and structure documentation in this project. |
+
+---
+
+## 🚀 Quick Install
+
+```bash
+pip install codex-bot                    # core only
+pip install codex-bot[redis]             # + Redis support
+pip install codex-bot[redis,arq,i18n]   # + background tasks + i18n
+pip install codex-bot[all]              # everything
+```
+
+---
+
+**Last Updated:** 2025-02-07

codex_bot-0.1.0/docs/api/README.md

@@ -0,0 +1,3 @@
+# API Reference
+
+Full API reference for `codex-bot` library modules.

codex_bot-0.1.0/docs/api/animation.md

@@ -0,0 +1,9 @@
+# animation — Waiting animation for Telegram UI
+
+## UIAnimationService
+
+::: codex_bot.animation.animation_service.UIAnimationService
+
+## AnimationType
+
+::: codex_bot.animation.animation_service.AnimationType