بوت دعم لمتجرك بلغة Python: الكود المصدري

1# Store Assistant: AI customer support on Telegram23A Telegram bot that answers an online store's customers in Algerian Darija, Arabic, French or English. It checks real order status, product stock, delivery fees per wilaya and the return policy from the store's own database, and it hands the conversation to a human when needed.45The model runs through the [DEVUP AI](https://devupai.com) OpenAI-compatible API, paid in Algerian dinars.67Real replies from the demo store (`deepseek-ai/DeepSeek-V4.1-Flash-1017`):89```text10Customer: salam, kayen sneakers taille 42 ?11Bot:      Salam saha ! Kayen sneakers taille 42 :12          - Leather court sneakers, blanc, 11 500 DA (taille 42 disponible)13          - Running sneakers, blanc wla noir, 8 900 DA (taille 42 makach dork, kayen 40, 41, 43, 44)14          T7eb nchouflek chi couleur wla taille okhra ?1516Customer: nheb nbadel la taille ta3 la commande NS-10242, rani 7ab XL17Bot:      Saha, wselt l'info l'équipe. Wa7ed men l'équipe rah yjawbek hna f chat18          bach ybadlou la taille ta3 commande NS-10242 l XL.19```2021## What it does2223| Customer asks | What the bot does |24|---|---|25| Where is my order? | Asks for the order number and the last 4 digits of the phone, then reads the order |26| Do you have this in size 42? | Searches the catalog and checks stock for that size |27| How much is delivery to Oran? | Finds the wilaya by name in any language, or by number, and gives home and stop-desk fees |28| Can I return it? | Reads the store's return policy and support hours |29| I want to cancel / talk to someone | Opens a support ticket and notifies the store team on Telegram |3031The model never answers order, stock or price questions from memory: every fact comes from a tool call against the database.3233## How it works3435```text36Telegram ──▶ bot.py ──▶ assistant.py ──▶ DEVUP AI API (chat completions + tools)37                              │38                              └──▶ tools.py ──▶ store.py (SQLite)39```4041- `store_assistant/store.py`: SQLite data layer (products, delivery zones, orders, tickets). Wilaya names are normalized so `Béjaïa`, `bejaia`, `بجاية` and `6` all match.42- `store_assistant/tools.py`: the five tools the model can call, with JSON schemas. Tool errors are returned to the model as JSON, never raised.43- `store_assistant/assistant.py`: the tool-calling loop, with a cap on tool rounds, short per-chat memory and friendly fallbacks when the API is unreachable.44- `store_assistant/language.py`: detects the customer's language (Darija in Latin or Arabic letters, Modern Standard Arabic, French, English) and adds a one-line reply-language instruction before each message.45- `store_assistant/bot.py`: Telegram handlers, typing indicator, per-user rate limit, message splitting, admin notifications.46- `data/demo_store.json`: a fictional demo store (DEVUP Shop) to try everything. Replace it with your own catalog.4748### Security choices4950- An order is only returned when the order number **and** the last 4 phone digits match, so nobody can browse other customers' orders by guessing numbers.51- All SQL uses parameters. Order numbers are validated against a strict format.52- Customer text sent to the admin is HTML-escaped.53- Per-user rate limit and maximum message length protect your API balance.54- Logs contain chat ids, timings and tool names, never message contents or keys. The HTTP client logger is set to `WARNING` because Telegram request URLs contain the bot token.5556## Quick start5758You need Python 3.10 or newer and a DEVUP AI API key.5960```bash61git clone <this-repo> store-assistant62cd store-assistant63python -m venv .venv64source .venv/bin/activate          # Windows: .venv\Scripts\activate65pip install -r requirements.txt66cp .env.example .env               # Windows: copy .env.example .env67```6869Open `.env` and set `DEVUP_API_KEY`.7071### 1. Try it in the terminal7273```bash74python -m store_assistant chat --show-tools75```7677The database is created from `data/demo_store.json` on first run. Demo orders you can ask about:7879| Order | Phone last 4 | Status |80|---|---|---|81| NS-10241 | 4821 | shipped |82| NS-10242 | 1937 | confirmed |83| NS-10243 | 5560 | delivered |84| NS-10244 | 7714 | pending |8586### 2. Run it on Telegram87881. In Telegram, open **@BotFather**, send `/newbot` and follow the steps. Copy the token into `TELEGRAM_BOT_TOKEN` in `.env`.892. Optional: to receive ticket notifications, start the bot once, send it `/id`, put the number it returns in `ADMIN_CHAT_ID`, then restart the bot.903. Start the bot:9192```bash93python -m store_assistant bot94```9596The bot answers private chats only. Commands: `/start`, `/help`, `/reset`, `/id`.9798### Run with Docker99100```bash101docker build -t store-assistant .102docker run -d --name store-assistant --restart unless-stopped --env-file .env -v store-data:/app/var store-assistant103```104105## Configuration106107All settings are environment variables (or lines in `.env`).108109| Variable | Default | Purpose |110|---|---|---|111| `DEVUP_API_KEY` | required | Your DEVUP AI key |112| `TELEGRAM_BOT_TOKEN` | required for `bot` | Token from @BotFather |113| `ADMIN_CHAT_ID` | empty | Chat that receives ticket notifications |114| `DEVUP_BASE_URL` | `https://api.devupai.com/v1` | OpenAI-compatible endpoint |115| `DEVUP_MODEL` | `deepseek-ai/DeepSeek-V4.1-Flash-1017` | Model id |116| `STORE_DB_PATH` | `data/store.db` | SQLite database file |117| `STORE_CATALOG_PATH` | `data/demo_store.json` | Catalog used to create the database |118| `HISTORY_MESSAGES` | `12` | Messages remembered per chat |119| `RATE_LIMIT_PER_MINUTE` | `8` | Messages per user per minute |120| `MAX_INPUT_CHARS` | `1000` | Longest accepted customer message |121| `MAX_TOOL_ROUNDS` | `4` | Tool-call rounds before the model must answer |122| `MAX_OUTPUT_TOKENS` | `8192` | Output limit per model call (reasoning models need room to think) |123| `REQUEST_TIMEOUT_S` | `60` | API timeout in seconds |124125To use another model, change `DEVUP_MODEL` to any model id from your DEVUP dashboard that supports tool calling, for example `moonshotai/Kimi-K3`.126127## Use your own store128129Edit `data/demo_store.json` (or point `STORE_CATALOG_PATH` to your file) with the same structure: `store`, `products`, `delivery`, `orders`. Then reload:130131```bash132python -m store_assistant init-db --reset133```134135For a live store, replace the methods of `Store` in `store.py` with calls to your e-commerce backend or database. The tools and the assistant do not need to change.136137## Development138139```bash140pip install -r requirements-dev.txt141pytest142ruff check .143mypy store_assistant144```145146The tests use a scripted fake API client, so they run offline and need no key.147148## License149150MIT © DEVUP AI