Skip to content

Standalone aiogram-idle

Install Idle independently from PyPI:

uv pip install 'aiogram-idle==0.3.1'

Python 3.10+ and aiogram 3.22+ within 3.x are required. The core installation includes neither Redis nor aiogram-nav. The aiogram-kit distribution remains lightweight; install each library directly.

Optional storage and navigation

uv pip install 'aiogram-idle[redis]==0.3.1'
# Only when navigation is needed:
uv pip install 'aiogram-idle[nav,redis]==0.3.1'

Supply a caller-owned async Redis client to aiogram_idle.storage.redis.RedisIdleBackend, use a stable prefix across replicas, and await backend.initialize(). Redis 7+ must be a writable standalone primary using noeviction. Application drafts and FSM persistence remain application-owned; Redis idle storage does not persist a memory FSM. There is no automatic memory fallback after a Redis failure. See the Redis guide.

Standalone Idle uses opaque activity keys, policy IDs, session/activity guards and application adapters. It needs no navigation registry, node IDs or root screen. Applications own authorization, translations, drafts and final UI. Creation is explicitly disabled by default. Memory state and recovery evidence disappear on restart; use one process with a memory backend.

Runnable examples and development

Clone the monorepo and run the maintained example:

git clone https://github.com/ArmanAvanesyan/aiogram-kit.git
cd aiogram-kit
uv sync --frozen --all-packages --all-groups --all-extras
# Export BOT_TOKEN in your environment first.
uv run --no-sync python packages/aiogram-idle/examples/demo.py --controls reply

Other controls are inline, commands and hybrid; add --fsm for the FSM example. /draft starts an application-owned sample draft, and accepted text resets inactivity. Continue resumes it; Cancel or grace expiry invokes application cleanup and restoration. The example enables short test intervals and safe debug logging explicitly.

For app-owned sessions and isolation, see the coordination guide and external-session example.

Optional combined integration

Use aiogram_idle.integrations.nav.NavigationIntegration and NodePolicies. Construct Navigation with integration.navigation_repository and call only integration.install, rather than installing the two components separately. Navigation/activity/deadline updates share one atomic backend transaction and one coordinator. Telegram sends, application business stores and FSM data are outside that transaction. Unknown effects require explicit recovery; normal activity must not erase unresolved recovery evidence.

See the integration contract and example. The original design records remain preserved under packages/aiogram-kit/docs/; implementation guides describe the supported release.