71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# 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](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/.env?type=file&root=C%3A).
|
|
- Treat [assistant_data.sqlite3](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_data.sqlite3?type=file&root=C%3A) as local runtime data, not source.
|
|
|
|
## Project structure
|
|
|
|
- [main.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/main.py?type=file&root=C%3A) is the compatible entry point.
|
|
- [assistant_bot](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot?type=file&root=C%3A) contains the application package.
|
|
- [tests](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/tests?type=file&root=C%3A) contains unittest-based tests.
|
|
|
|
Key modules:
|
|
|
|
- [application.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/application.py?type=file&root=C%3A): Telegram app construction and handler registration.
|
|
- [handlers.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/handlers.py?type=file&root=C%3A): bot commands and message handling.
|
|
- [agent.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/agent.py?type=file&root=C%3A): agent loop and tool decision handling.
|
|
- [storage.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/storage.py?type=file&root=C%3A): SQLite persistence.
|
|
- [ollama.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/ollama.py?type=file&root=C%3A): Ollama client integration.
|
|
- [reminders.py](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/assistant_bot/reminders.py?type=file&root=C%3A): reminder parsing and scheduling logic.
|
|
|
|
## Environment and dependencies
|
|
|
|
- Python project with dependencies from [requirements.txt](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/requirements.txt?type=file&root=C%3A).
|
|
- Required environment variable: `BOT_TOKEN`.
|
|
- Supported optional variables include `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `ASSISTANT_DB`, and `ASSISTANT_TIMEZONE`.
|
|
|
|
## Run and test
|
|
|
|
Install dependencies:
|
|
|
|
```powershell
|
|
python -m pip install -r requirements.txt
|
|
```
|
|
|
|
Run the bot:
|
|
|
|
```powershell
|
|
python main.py
|
|
```
|
|
|
|
Alternative package entry point:
|
|
|
|
```powershell
|
|
python -m assistant_bot
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```powershell
|
|
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](air-file://v3c0f26v8ert02idn5b5/C:/Users/solda/PycharmProjects/KAndrusyak_Bot/tests/test_core.py?type=file&root=C%3A).
|
|
- 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.
|