README.md

---
title: Hilal Ai Telegram Bot
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# Hilal Ai — Bot Telegram hébergé sur Hugging Face Spaces (gratuit)

Ce Space fait tourner en continu un bot Telegram propulsé par un modèle
Transformer décodeur (style GPT) entraîné from scratch au niveau caractère.

## ⚠️ Comprendre les limites du tier gratuit AVANT de déployer

Le tier **CPU Basic** de HF Spaces est gratuit mais se met en veille après
~48h sans "visite" sur la page web du Space. Un bot Telegram en polling n'a
pas de visiteurs web naturellement, donc ce repo inclut :
- un petit serveur Flask (`app.py`) qui répond sur `/` et `/ping`
- des instructions ci-dessous pour qu'un service externe gratuit (UptimeRobot
  ou GitHub Actions) ping cette URL régulièrement et empêche la mise en veille

C'est une solution **bricolée mais fonctionnelle**. Elle n'est pas garantie à
100% par Hugging Face (ce n'est pas un usage "officiellement prévu" du tier
gratuit) — si tu veux une garantie de disponibilité totale, il faudra upgrader
le hardware du Space (~9$/mois) qui élimine la mise en veille.

## Fichiers du repo

```
.
├── Dockerfile          # image Docker du Space (SDK: docker)
├── app.py              # serveur web de ping + lance bot.py dans un thread
├── bot.py              # logique du bot Telegram
├── model.py            # architecture MiniGPT + tokenizer char-level
├── requirements.txt
├── .gitattributes      # config Git LFS pour model.pt
├── model.pt            # TES poids entraînés (à uploader, voir ci-dessous)
└── vocab.json          # TON vocabulaire char-level (voir ci-dessous)
```

## ⚠️ vocab.json est OBLIGATOIRE pour des réponses cohérentes

Le tokenizer char-level a besoin du mapping exact caractère→indice utilisé
pendant l'entraînement sur Colab. Sans lui, le modèle se chargera sans
erreur mais générera des réponses incohérentes (les embeddings ne
correspondront pas aux bons caractères).

Si tu as encore accès à ton notebook Colab ou ton corpus d'entraînement :
```python
import json
chars = sorted(list(set(text)))  # `text` = ton corpus d'entraînement original
with open("vocab.json", "w", encoding="utf-8") as f:
    json.dump({"chars": chars}, f, ensure_ascii=False)
```

## Étape 1 — Créer le Space sur Hugging Face

1. Va sur https://huggingface.co/new-space (tu es déjà connecté à ton compte)
2. Choisis un nom (ex: `hilal-ai-bot`)
3. SDK : sélectionne **Docker** (pas Gradio)
4. Visibilité : Public ou Private selon ta préférence
5. Clique sur "Create Space"

## Étape 2 — Ajouter le token Telegram comme secret

Dans la page de ton Space : **Settings → Repository secrets → New secret**
- Nom : `TELEGRAM_BOT_TOKEN`
- Valeur : le token obtenu via @BotFather sur Telegram

Ne mets jamais ce token directement dans le code ou dans un fichier commité.

## Étape 3 — Pousser le code sur le Space

Hugging Face Spaces fonctionne comme un repo Git classique.

```bash
# Installer git-lfs si pas déjà fait (pour model.pt)
git lfs install

# Cloner le repo vide de ton Space (remplace USERNAME et SPACE_NAME)
git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
cd SPACE_NAME

# Copier tous les fichiers de ce dossier dedans :
# Dockerfile, app.py, bot.py, model.py, requirements.txt, .gitattributes,
# model.pt, vocab.json

git lfs track "*.pt"
git add .gitattributes
git add .
git commit -m "Déploiement initial Hilal Ai"
git push
```

HF va automatiquement builder l'image Docker. Tu peux suivre les logs de
build et d'exécution dans l'onglet **Logs** de ton Space.

## Étape 4 — Vérifier que le bot tourne

1. Va sur l'URL de ton Space : `https://huggingface.co/spaces/USERNAME/SPACE_NAME`
2. L'app Flask doit répondre avec `{"bot_started": true, ...}` sur la page
3. Sur Telegram, cherche ton bot et envoie `/start`

## Étape 5 — Empêcher la mise en veille (keep-alive externe)

L'URL publique de ton Space (format direct, sans iframe) est généralement :
```
https://USERNAME-SPACE_NAME.hf.space/ping
```

### Option A — UptimeRobot (recommandé, zéro code)
1. Crée un compte gratuit sur https://uptimerobot.com
2. Ajoute un nouveau monitor de type "HTTP(s)"
3. URL : `https://USERNAME-SPACE_NAME.hf.space/ping`
4. Intervalle : 30 minutes (largement suffisant pour rester sous 48h)

### Option B — GitHub Actions (si tu préfères tout garder versionné)
Crée `.github/workflows/keep-alive.yml` dans un repo GitHub que tu contrôles :

```yaml
name: Keep Hilal Ai Space Alive
on:
  schedule:
    - cron: '0 */6 * * *'  # toutes les 6 heures
  workflow_dispatch:
jobs:
  ping:
    runs-on: ubuntu-latest
    steps:
      - name: Ping Space
        run: curl -f https://USERNAME-SPACE_NAME.hf.space/ping
```

## Variables d'environnement disponibles (Secrets ou Variables du Space)

| Variable             | Défaut         | Description                                  |
|----------------------|----------------|-----------------------------------------------|
| TELEGRAM_BOT_TOKEN   | (obligatoire)  | Token du bot Telegram                         |
| MODEL_PATH           | model.pt       | Chemin vers les poids                         |
| VOCAB_PATH           | vocab.json     | Chemin vers le vocabulaire char-level         |
| DEVICE               | cpu (auto)     | "cpu" (les Spaces gratuits n'ont pas de GPU)  |
| MAX_NEW_TOKENS       | 200            | Nombre max de caractères générés par réponse  |
| TEMPERATURE          | 0.7            | Température de sampling                       |
| PORT                 | 7860           | Port du serveur Flask (imposé par HF Spaces)  |

## Diagnostiquer un problème

- **Le build Docker échoue** → onglet "Logs" du Space, section "Build logs"
- **Le bot ne répond pas sur Telegram mais le Space tourne** → vérifie les
  "Container logs" pour une erreur de chargement du modèle ou de token manquant
- **Page d'accueil affiche `bot_started: false`** → le thread du bot a
  crashé au démarrage (vérifie `model.pt`/`vocab.json` présents et valides)