# Repository Guidelines

## Project Structure & Module Organization

This repository contains a Python Telegram bot. `bot.py` is the entry point and registers command, text, photo, image-document, and inline handlers. `handlers/` contains Telegram-facing command and update handlers, grouped by feature (`admin.py`, `chat.py`, `inline.py`, `help.py`). `services/` contains external integrations and shared business logic such as AI calls, auth persistence, and saved runtime settings. `utils/` contains reusable helpers for context, formatting, chunking, and Persian-language handling. Runtime state and credentials live in `.env`, `settings.json`, `authorized_users.json`, and `*.session` files; do not treat these as source assets.

## Build, Test, and Development Commands

Create an isolated environment before installing dependencies:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Run the bot locally with:

```bash
python bot.py
```

Use `.env.example` as the template for required environment variables, then set `TELEGRAM_TOKEN`, `GOOGLE_API_KEY`, and `OWNER_ID` in `.env`. Runtime choices such as active provider, model, public mode, system prompt, and per-user settings are saved in `settings.json`.

## Coding Style & Naming Conventions

Follow idiomatic Python with 4-space indentation, clear function names, and small modules organized by responsibility. Handler functions use the `cmd_<command>` pattern for commands, such as `cmd_ping` or `cmd_setmodel`; keep new command names consistent with the registered Telegram command. Prefer async functions for Telegram callbacks and service calls. Keep configuration values centralized in `config.py` rather than scattering `os.getenv` calls.

## Testing Guidelines

No test suite is currently present. For new behavior, add focused `pytest` tests under a future `tests/` directory and name files `test_<module>.py`. Prioritize pure helpers in `utils/` and service logic that can be tested without Telegram network access. Until tests exist, validate changes by running `python bot.py` with a development bot token and exercising the affected command or message path.

## Commit & Pull Request Guidelines

The local `.git` directory has no usable history, so no existing commit convention is available. Use concise imperative commit messages, for example `Add image OCR command` or `Fix auth file reload handling`. Pull requests should include a short summary, configuration changes, manual test steps, and screenshots or chat transcripts when user-visible Telegram behavior changes.

## Security & Configuration Tips

Never commit `.env`, session files, API keys, bot tokens, or real user authorization data. Keep `.env.example` updated when adding configuration. Treat `authorized_users.json` as local runtime state unless a sanitized fixture is intentionally needed for tests.