# 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.