How imsudipcreator/task-pilot works
1. Overall shape
This is a Python command bot with two major interaction paths: regular command handlers for bot features, and an AI-assisted path that can invoke tools. The repo is organized around chat-command entrypoints, SQLite-backed persistence, and a small utility layer for time/reminder logic.
2. Entry point and routing
main.py is the process entrypoint. It likely initializes the bot runtime, wires up handlers, opens the database layer, and starts the event loop that receives incoming user messages/commands.
3. Command handling boundary
The handlers/ package is the main request-routing layer. It separates user-facing commands into dedicated modules:
- start.py and help.py for onboarding and usage
- todo.py for task management
- remind.py for reminder commands
- qr.py for QR-related functionality
- ai.py for AI/chat interactions
- unknown.py for fallback handling of unrecognized input
This is the main boundary between inbound messages and internal business logic.
4. AI subsystem
The ai/ package is a second major subsystem. ai/agent.py likely contains the conversational agent orchestration, while ai/checkpointer.py handles persistence of agent state across turns. This indicates the bot is not stateless: conversation context and tool-usage state are stored and restored.
5. AI tool layer
ai/tools/ contains callable capabilities exposed to the agent:
- todo.py
- remind.py
- time.py
- web_search.py
- wiki.py
These tools form the agent’s “action layer,” letting it fetch information, reason about time, and manipulate user tasks/reminders instead of only generating text.
6. Persistent data stores
The data/ directory contains three SQLite databases:
- bot.db for core bot/application data
- agent_memory.db for AI memory or conversation-related persistence
- checkpoints.db for agent checkpoint/state recovery
The separation suggests different persistence concerns are intentionally isolated.
7. Shared database access
database.py is the common database abstraction or connection manager used by handlers and tools. It likely centralizes schema access, CRUD operations, and connections to the SQLite files under data/.
8. Reminder and time utilities
utils/parse_time.py and utils/reminder.py are shared support code for interpreting human-friendly times like 10m and 1h, and for turning them into scheduled reminder behavior. This sits between the reminder command handler and persistence/scheduling logic.
9. Cross-cutting concerns
decorators.py likely provides reusable wrappers for handler behavior such as validation, error handling, auth, or logging. This is a shared layer used to keep handler modules thin and consistent.
10. Repository/runtime tooling
The project is managed as a Python application (pyproject.toml, requirements.txt, uv.lock, .python-version). That suggests a local Python runtime with dependency lockfile-driven installs, rather than a container-first or framework-heavy setup.
11. Primary data flow
A typical flow is: user message → main.py dispatch → specific handler in handlers/ → database/helper utilities. For AI-driven requests, the flow becomes: user message → handlers/ai.py → ai/agent.py → tool call in ai/tools/* → persistence via database.py and ai/checkpointer.py → response back to the user.
12. External integration boundary
The only obvious external-facing integrations are the AI/web-information tools (web_search.py, wiki.py) and whatever chat platform the bot runs on. Everything else is internal application logic or local persistence.
13. What to show in an architecture diagram
The clearest diagram would place the bot runtime at the top, split into:
- command handlers
- AI agent/tool subsystem
- shared utilities/database layer
- SQLite persistence
and show the AI path separately from the direct command path, with reminders/todos as shared capabilities used by both.
Main entry points: agent.py Agent · main.py Main · database.py Database · remind.py Remind
Components 22
Bot Runtime
Process entrypoint and message routing
- Main · Bootstraps the bot runtime and dispatch loop
main.py - AI Handler · Routes AI/chat requests into the agent subsystem
handlers/ai.py - Start · Onboarding and first-run command handling
handlers/start.py - Help · Usage and assistance commands
handlers/help.py - Todo · Task management commands
handlers/todo.py - Remind · Reminder command handling
handlers/remind.py - QR · QR-related commands
handlers/qr.py - Fallback · Handles unrecognized input
handlers/unknown.py
AI Subsystem
Agent orchestration and tool execution
- Agent · Coordinates conversational reasoning and tool use
ai/agent.py - Checkpointing · Persists and restores agent state across turns
ai/checkpointer.py - Todo Tool · AI tool for managing tasks
ai/tools/todo.py - Remind Tool · AI tool for creating reminders
ai/tools/remind.py - Time Tool · AI tool for time reasoning and scheduling
ai/tools/time.py - Web Search · External search capability for the agent
ai/tools/web_search.py - Wiki Tool · External knowledge lookup for the agent
ai/tools/wiki.py
Persistence
Shared database access and SQLite files
- Database · Shared database layer used by handlers and tools
database.py - Bot DB · Core application data store
data/bot.db - Agent Memory · Conversation or memory persistence for AI features
data/agent_memory.db - Checkpoints DB · Checkpoint store for agent recovery
data/checkpoints.db
Shared Logic
Reusable utilities for reminders and time parsing
- Parse Time · Parses human-friendly time expressions
utils/parse_time.py - Reminder Utils · Shared reminder scheduling and formatting helpers
utils/reminder.py - Decorators · Reusable handler wrappers and shared behavior
decorators.py
Connections 31
- Main → Start: routes · Registers the onboarding handler
- Main → Help: routes · Registers usage/help handling
- Main → Todo: routes · Registers task commands
- Main → Remind: routes · Registers reminder commands
- Main → QR: routes · Registers QR commands
- Main → AI Handler: routes · Registers AI/chat handling
- Main → Fallback: fallback · Wires unknown-input handling
- Todo → Database: CRUD · Uses shared persistence for tasks
- Remind → Parse Time: parses · Interprets user time inputs
- Remind → Reminder Utils: schedules · Uses reminder helper logic
- Remind → Database: stores · Persists reminder data
- AI Handler → Agent: invokes · Hands chat requests to the agent
- AI Handler → Database: reads/writes · May access shared bot data
- Agent → Todo Tool: tool use · Can manage tasks through tools
- Agent → Remind Tool: tool use · Can create reminders through tools
- Agent → Time Tool: tool use · Uses time reasoning capabilities
- Agent → Web Search: tool use · Can search the web
- Agent → Wiki Tool: tool use · Can query wiki-like knowledge
- Agent → Checkpointing: persists state · Stores and restores conversational state
- Checkpointing → Agent Memory: backed by · Uses AI memory storage
- Checkpointing → Checkpoints DB: backed by · Uses checkpoint storage
- Database → Bot DB: backed by · Core application SQLite store
- Todo Tool → Database: uses · Reads and updates task data
- Remind Tool → Database: uses · Reads and updates reminder data
- Remind Tool → Time Tool: depends on · Uses time interpretation for reminders
- Web Search → Agent: returns context · Feeds external information back to the agent
- Wiki Tool → Agent: returns context · Feeds reference information back to the agent
- Start → Decorators: wrapped by · Shares common handler behavior
- Help → Decorators: wrapped by · Shares common handler behavior
- Todo → Decorators: wrapped by · Shares common handler behavior
- Remind → Decorators: wrapped by · Shares common handler behavior