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

Store Assistant: AI customer support on Telegram#

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

The model runs through the DEVUP AI OpenAI-compatible API, paid in Algerian dinars.

Real replies from the demo store (deepseek-ai/DeepSeek-V4.1-Flash-1017):

Customer: salam, kayen sneakers taille 42 ?
Bot:      Salam saha ! Kayen sneakers taille 42 :
          - Leather court sneakers, blanc, 11 500 DA (taille 42 disponible)
          - Running sneakers, blanc wla noir, 8 900 DA (taille 42 makach dork, kayen 40, 41, 43, 44)
          T7eb nchouflek chi couleur wla taille okhra ?

Customer: nheb nbadel la taille ta3 la commande NS-10242, rani 7ab XL
Bot:      Saha, wselt l'info l'équipe. Wa7ed men l'équipe rah yjawbek hna f chat
          bach ybadlou la taille ta3 commande NS-10242 l XL.

What it does#

The model never answers order, stock or price questions from memory: every fact comes from a tool call against the database.

How it works#

Telegram ──▶ bot.py ──▶ assistant.py ──▶ DEVUP AI API (chat completions + tools)
                              │
                              └──▶ tools.py ──▶ store.py (SQLite)

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

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

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

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

• store_assistant/bot.py: Telegram handlers, typing indicator, per-user rate limit, message splitting, admin notifications.

• data/demo_store.json: a fictional demo store (DEVUP Shop) to try everything. Replace it with your own catalog.

Security choices#

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

• All SQL uses parameters. Order numbers are validated against a strict format.

• Customer text sent to the admin is HTML-escaped.

• Per-user rate limit and maximum message length protect your API balance.

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

Quick start#

You need Python 3.10 or newer and a DEVUP AI API key.

git clone <this-repo> store-assistant
cd store-assistant
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env               # Windows: copy .env.example .env

Open .env and set DEVUP_API_KEY.

1. Try it in the terminal#

python -m store_assistant chat --show-tools

The database is created from data/demo_store.json on first run. Demo orders you can ask about:

2. Run it on Telegram#

1. In Telegram, open @BotFather, send /newbot and follow the steps. Copy the token into TELEGRAM_BOT_TOKEN in .env.

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

3. Start the bot:

python -m store_assistant bot

The bot answers private chats only. Commands: /start, /help, /reset, /id.

Run with Docker#

docker build -t store-assistant .
docker run -d --name store-assistant --restart unless-stopped --env-file .env -v store-data:/app/var store-assistant

Configuration#

All settings are environment variables (or lines in .env).

To use another model, change DEVUP_MODEL to any model id from your DEVUP dashboard that supports tool calling, for example moonshotai/Kimi-K3.

Use your own store#

Edit data/demo_store.json (or point STORE_CATALOG_PATH to your file) with the same structure: store, products, delivery, orders. Then reload:

python -m store_assistant init-db --reset

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

Development#

pip install -r requirements-dev.txt
pytest
ruff check .
mypy store_assistant

The tests use a scripted fake API client, so they run offline and need no key.

License#

MIT © DEVUP AI