README.md

---
license: other
language:
- fr
pipeline_tag: robotics
tags:
- Chiot robot
- Simulation de décisions
- cerveau d'animaux de compagnie (IA)
---

## 📄 Documentation du Modèle MiRobot

![MiRobot](http://www.image-heberg.fr/files/17604561812362382903.jpg)

### 🤖 Présentation du Modèle MiRobot : Simulation de Chiot Robot

**MiRobot** est un modèle de robotique basé sur l'**Apprentissage par Renforcement (RL)**, conçu pour simuler le comportement primaire et les interactions d'un chiot robot. Développé par Clemylia, ce modèle vise à démontrer comment un agent d'Intelligence Artificielle peut apprendre à répondre à des commandes externes tout en gérant ses besoins internes.

Ce modèle est idéal pour l'étude et l'expérimentation dans les domaines de la robotique simulée et des systèmes d'agents autonomes.

-----

### 🚀 Démarrage Rapide

Pour utiliser MiRobot, vous devez disposer d'un environnement Python avec les bibliothèques **Gymnasium** et **Stable Baselines3** installées.

#### 1\. Installation des Dépendances

```bash
pip install gymnasium stable-baselines3 huggingface_hub
```

#### 2\. Chargement et Exécution du Modèle

Le script suivant télécharge automatiquement l'environnement personnalisé et le modèle entraîné depuis Hugging Face, puis exécute une courte simulation.

```python
import gymnasium as gym
from stable_baselines3 import PPO
from gymnasium import register
from huggingface_hub import hf_hub_download
import os

# --- PARAMÈTRES DU DÉPÔT ---
REPO_ID = "Clemylia/MiRobot" 
MODEL_FILE = "mirobot_final_model.zip"
ENV_SCRIPT_FILE = "MiRobotEnv.py"
ENV_ID = 'MiRobot-v0'

# 1. Téléchargement des Fichiers
env_path = hf_hub_download(repo_id=REPO_ID, filename=ENV_SCRIPT_FILE)
model_path = hf_hub_download(repo_id=REPO_ID, filename=MODEL_FILE)

# 2. Chargement de la Classe d'Environnement (MiRobotEnv)
try:
    with open(env_path, 'r') as f:
        exec(f.read()) 
except Exception as e:
    print(f"Erreur lors du chargement de l'environnement: {e}")
    exit()

# 3. Enregistrement de l'Environnement Custom
try:
    register(
        id=ENV_ID,
        entry_point='MiRobotEnv:MiRobotEnv',
    )
except gym.error.UnregisteredEnv:
    pass # Déjà enregistré

# 4. Chargement du Modèle Entraîné (PPO)
model = PPO.load(model_path)
print("✅ Modèle MiRobot chargé et prêt pour l'inférence.")

# 5. Simulation (Inférence)
env = gym.make(ENV_ID) 
obs, info = env.reset()
action_map = {0: "S'Arrêter", 1: "Avancer", 2: "Tourner G", 3: "Tourner D"}

print("\n--- Démarrage de la Simulation MiRobot ---")
for i in range(20):
    action, _states = model.predict(obs, deterministic=True)
    obs, reward, terminated, truncated, info = env.step(action)

    print(f"[Pas {i+1}] Action Choisie: {action_map[action]}")
    env.render() # Affiche l'état interne de MiRobot
    
    if terminated or truncated:
        obs, info = env.reset()

env.close()
print("\nSimulation terminée.")
```

-----

### 🧠 Détails du Modèle et de l'Environnement

Le modèle **MiRobot** prend ses décisions en interprétant un vecteur d'état (Observation) et choisit une action parmi quatre options (Action).

#### A. Espace d'Observation (L'état du Chiot)

L'observation est un vecteur de 5 nombres décimaux (`float`) que l'agent d'IA utilise pour prendre une décision.

| Index | Nom de la Variable | Plage de Valeurs | Rôle |
| :---: | :--------------- | :-------------- | :--- |
| **0** | `Commande_Avancer` | $0.0$ ou $1.0$ | Commande binaire du maître (1 si demande d'avancer). |
| **1** | `Commande_Tourner` | $0.0$ ou $1.0$ | Commande binaire du maître (1 si demande de tourner). |
| **2** | `Faim` | $0.0$ (Pleine) à $1.0$ (Affamée) | Niveau de faim interne (augmente avec le temps). |
| **3** | `Sommeil` | $0.0$ (Éveillé) à $1.0$ (Fatigué) | Niveau de fatigue interne (augmente avec le temps). |
| **4** | `Humeur` | $-1.0$ (Mauvaise) à $1.0$ (Joyeuse) | État émotionnel du chiot (influencé par la faim/sommeil). |

#### B. Espace d'Action (Ce que MiRobot peut faire)

Le modèle sélectionne une action discrète à chaque pas de temps.

| ID d'Action | Action du Robot |
| :---------: | :------------- |
| **0** | **S'arrêter** (ou ne rien faire) |
| **1** | **Avancer** |
| **2** | **Tourner à gauche** |
| **3** | **Tourner à droite** |

-----

### 🏅 Fonction de Récompense (Ce que MiRobot apprend)

Le modèle PPO a été entraîné pour maximiser la récompense cumulée, ce qui signifie qu'il a appris à :

  * **Obéir (Récompense Positive 🏆) :** Choisir l'action demandée par le maître (`Commande_Avancer` ou `Commande_Tourner`).
  * **Maintenir le bien-être (Récompense/Pénalité) :** L'agent est pénalisé proportionnellement à ses niveaux de **Faim** et de **Sommeil**, encourageant implicitement l'intégration future d'actions de bien-être (dormir, manger) si le modèle est étendu.

-----

### 🛠️ Contribution et Extension

Ce projet est une preuve de concept. Nous encourageons les développeurs à étendre **MiRobot** en ajoutant :

1.  **Actions Supplémentaires :** Ajouter des actions comme "Manger" ou "Dormir" pour que l'agent puisse activement réduire ses états de `Faim` et `Sommeil`.
2.  **Simulation 2D/3D :** Intégrer un rendu visuel (avec Pygame ou Unity) à la méthode `render()` pour visualiser le chiot se déplaçant dans un espace physique.

N'hésitez pas à forker le dépôt sur Hugging Face pour proposer des améliorations \!

code exemple d'utilisation 

```
import gymnasium as gym
from stable_baselines3 import PPO
from gymnasium import register
from huggingface_hub import hf_hub_download
import os
import sys # Import sys

# --- PARAMÈTRES DU DÉPÔT ---
REPO_ID = "Clemylia/MiRobot"
MODEL_FILE = "mirobot_final_model.zip"
ENV_SCRIPT_FILE = "MiRobotEnv.py"
ENV_ID = 'MiRobot-v0'

# 1. Téléchargement des Fichiers
env_path = hf_hub_download(repo_id=REPO_ID, filename=ENV_SCRIPT_FILE)
model_path = hf_hub_download(repo_id=REPO_ID, filename=MODEL_FILE)

# 2. Chargement de la Classe d'Environnement (MiRobotEnv)
# Extract the directory of the downloaded environment script
env_dir = os.path.dirname(env_path)
# Add this directory to sys.path so Python can find it as a module
if env_dir not in sys.path:
    sys.path.insert(0, env_dir) # Add to the beginning of sys.path

try:
    # No need for exec(f.read()) anymore, as gymnasium.make will handle the import
    pass
except Exception as e:
    print(f"Erreur lors du chargement de l'environnement: {e}")
    exit()

# 3. Enregistrement de l'Environnement Custom
try:
    register(
        id=ENV_ID,
        entry_point='MiRobotEnv:MiRobotEnv', # This will now try to import MiRobotEnv module
    )
except gym.error.UnregisteredEnv:
    pass # Déjà enregistré

# 4. Chargement du Modèle Entraîné (PPO)
model = PPO.load(model_path)
print("✅ Modèle MiRobot chargé et prêt pour l'inférence.")

# 5. Simulation (Inférence)
env = gym.make(ENV_ID)
obs, info = env.reset()
action_map = {0: "S'Arrêter", 1: "Avancer", 2: "Tourner G", 3: "Tourner D"}

print("\n--- Démarrage de la Simulation MiRobot ---")
for i in range(20):
    action, _states = model.predict(obs, deterministic=True)
    obs, reward, terminated, truncated, info = env.step(action)

    print(f"[Pas {i+1}] Action Choisie: {action_map[action.item()]}") # Fixed: Use .item() to get scalar from numpy array
    env.render() # Affiche l'état interne de MiRobot

    if terminated or truncated:
        obs, info = env.reset()

env.close()
print("\nSimulation terminée.")
```