# 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](https://devupai.com) OpenAI-compatible API, paid in Algerian dinars.

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

```text
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

| Customer asks | What the bot does |
|---|---|
| Where is my order? | Asks for the order number and the last 4 digits of the phone, then reads the order |
| Do you have this in size 42? | Searches the catalog and checks stock for that size |
| How much is delivery to Oran? | Finds the wilaya by name in any language, or by number, and gives home and stop-desk fees |
| Can I return it? | Reads the store's return policy and support hours |
| I want to cancel / talk to someone | Opens a support ticket and notifies the store team on Telegram |

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

## How it works

```text
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.

```bash
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

```bash
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:

| Order | Phone last 4 | Status |
|---|---|---|
| NS-10241 | 4821 | shipped |
| NS-10242 | 1937 | confirmed |
| NS-10243 | 5560 | delivered |
| NS-10244 | 7714 | pending |

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

```bash
python -m store_assistant bot
```

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

### Run with Docker

```bash
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`).

| Variable | Default | Purpose |
|---|---|---|
| `DEVUP_API_KEY` | required | Your DEVUP AI key |
| `TELEGRAM_BOT_TOKEN` | required for `bot` | Token from @BotFather |
| `ADMIN_CHAT_ID` | empty | Chat that receives ticket notifications |
| `DEVUP_BASE_URL` | `https://api.devupai.com/v1` | OpenAI-compatible endpoint |
| `DEVUP_MODEL` | `deepseek-ai/DeepSeek-V4.1-Flash-1017` | Model id |
| `STORE_DB_PATH` | `data/store.db` | SQLite database file |
| `STORE_CATALOG_PATH` | `data/demo_store.json` | Catalog used to create the database |
| `HISTORY_MESSAGES` | `12` | Messages remembered per chat |
| `RATE_LIMIT_PER_MINUTE` | `8` | Messages per user per minute |
| `MAX_INPUT_CHARS` | `1000` | Longest accepted customer message |
| `MAX_TOOL_ROUNDS` | `4` | Tool-call rounds before the model must answer |
| `MAX_OUTPUT_TOKENS` | `8192` | Output limit per model call (reasoning models need room to think) |
| `REQUEST_TIMEOUT_S` | `60` | API timeout in seconds |

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:

```bash
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

```bash
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