Clemylia/MiRobot

📄 Documentation du Modèle MiRobot

🤖 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

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.

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 !