kandrusyak_bot/AGENTS.md

AGENTS.md

This repository contains a Python Telegram assistant bot with local Ollama integration and SQLite-backed storage.

Working scope

• Keep changes targeted to this repository.
• Prefer small, reviewable edits over broad refactors.
• Do not commit secrets from .env.
• Treat assistant_data.sqlite3 as local runtime data, not source.

Project structure

• main.py is the compatible entry point.
• assistant_bot contains the application package.
• tests contains unittest-based tests.

Key modules:

• application.py: Telegram app construction and handler registration.
• handlers.py: bot commands and message handling.
• agent.py: agent loop and tool decision handling.
• storage.py: SQLite persistence.
• ollama.py: Ollama client integration.
• reminders.py: reminder parsing and scheduling logic.

Environment and dependencies

• Python project with dependencies from requirements.txt.
• Required environment variable: BOT_TOKEN.
• Supported optional variables include OLLAMA_BASE_URL, OLLAMA_MODEL, ASSISTANT_DB, and ASSISTANT_TIMEZONE.

Run and test

Install dependencies:

python -m pip install -r requirements.txt

Run the bot:

python main.py

Alternative package entry point:

python -m assistant_bot

Run tests:

python -m unittest discover -v

Change guidance

• Preserve the existing stdlib unittest style unless there is a clear reason to introduce a new test runner.
• Keep Telegram handlers, storage logic, and Ollama client concerns separated by module.
• Prefer configuration through environment variables instead of hardcoded values.
• When changing reminder parsing, storage behavior, or agent decision parsing, update or add tests in test_core.py.
• Avoid editing generated caches under __pycache__.

Operational cautions

• Bot startup depends on a valid Telegram token and reachable Ollama endpoint when model-backed features are used.
• SQLite files may be environment-specific; avoid relying on checked-in runtime state for tests.