Spaces:
Running
Running
metadata
title: Cypher Coder
emoji: 💻
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
hf_oauth: true
💻 Cypher Coder - Agent IA de Programmation CLI
Cypher Coder est un agent conversationnel en ligne de commande (CLI) autonome, capable de concevoir, lire, modifier du code localement et d'exécuter des commandes système directement dans votre terminal sous votre supervision.
Ce projet a été conçu et développé par DJAKOUA KWANKAM, étudiant en informatique à l'Institut Universitaire de Technologie de Douala (IUT).
🏗️ Architecture & Fonctionnement
L'architecture de Cypher Coder repose sur un modèle hybride Client-Serveur conçu pour maximiser les performances tout en s'exécutant sur des machines aux ressources limitées.
+-----------------------------------------------------------------+
| MACHINE LOCALE |
| |
| +-------------+ Prompt +------------------------+ |
| | | +--------------> | | |
| | Terminal | | Client CLI Node | |
| | Utilisateur| <--------------+ | (index.js / Inquirer) | |
| | | Réponse | | |
| +-------------+ +------------------------+ |
| ^ | |
| | Outil | API |
| | Local | Chat |
| v v |
| +-----------------------------+ |
| | SYSTÈME DE FICHIERS / | |
| | TERMINAL DE L'UTIL. | |
| +-----------------------------+ |
+--------------------------------------+--------------------------+
| ^
| curl | JSON
| HTTP POST | Response
v |
+--------------------------------------+--------------------------+
| CLOUD HUGGING FACE (BACKEND DOCKER) |
| |
| +-----------------------+ +------------------+ |
| | | Inference | | |
| | FastAPI Gateway | +----------> | Qwen-2.5-Coder | |
| | | | (32B Model) | |
| +-----------------------+ +------------------+ |
| | |
| | Outil search_web |
| v |
| +-----------------------+ |
| | DuckDuckGo Search | |
| +-----------------------+ |
+-----------------------------------------------------------------+
1. Le Client CLI (Local)
Développé en Node.js, il gère l'interface interactive utilisateur dans le terminal à l'aide de chalk, ora et inquirer. Il expose des outils système :
read_file: Permet au modèle de lire le contenu des fichiers locaux.write_file: Permet d'écrire ou de modifier du code source local.list_dir: Permet au modèle d'inspecter la structure des répertoires locaux.run_command: Exécute des commandes système (compilation, tests unitaires, git, etc.).
2. Le Serveur API (Hugging Face Space)
Un conteneur Docker exécutant une application FastAPI avec un redirect vers une interface Gradio à /gradio pour tester l'agent en ligne. Le serveur communique avec l'API Hugging Face Serverless pour interroger le modèle de pointe Qwen/Qwen2.5-Coder-32B-Instruct.
3. La Boucle d'Agent Hybride (Hybrid Agent Loop)
- Lorsque le modèle demande une recherche sur internet (
search_web), celle-ci est résolue directement par le serveur dans le cloud via DuckDuckGo. - Lorsque le modèle demande une action système locale (lire un fichier, exécuter une commande), le serveur renvoie l'instruction au client CLI local qui l'exécute après avoir demandé le consentement explicite de l'utilisateur.
4. Gestion des Connaissances & Accès aux Manuels Linux
Pour répondre à des questions techniques complexes ou des interrogations sur le système, Cypher Coder n'embarque pas la documentation complète en mémoire constante, mais utilise les mécanismes suivants :
- Connaissance Pré-entraînée : Le modèle de base
Qwen2.5-Coder-32Bconnaît déjà par défaut les commandes standards, les APIs et l'architecture générale Linux suite à son apprentissage. - Résolution Locale des Commandes : Il interroge et lit les manuels locaux installés sur votre machine (via
man <command>ou<command> --helpviarun_command). - Recherche de Documentation en Ligne : Si nécessaire, il fait appel à
search_webpour récupérer de la documentation externe et actualisée.
5. Collecte de Données pour l'Entraînement (Jeu de Données)
Afin d'améliorer continuellement la pertinence et les compétences de codage de l'IA, Cypher Coder collecte de manière anonyme et sécurisée les interactions :
- Données enregistrées : Nom d'utilisateur (OS local ou pseudonyme web), horodatage, message envoyé et réponse générée.
- Sécurité et Confidentialité : Ces logs sont transférés de manière confidentielle et centralisés dans un dataset privé Hugging Face (
TheShellMaster/cypher-coder-logs) accessible uniquement à l'équipe de développement pour l'entraînement futur des modèles de l'IUT de Douala.
🛠️ Défis Techniques & Résolutions
1. Le blocage DNS/TCP de Node.js vers Hugging Face
- Problème : L'environnement réseau local de l'utilisateur souffrait d'une configuration IPv6 défaillante. Node.js tentait de résoudre et de contacter
api-inference.huggingface.coen IPv6, entraînant des timeouts systématiques (ETIMEDOUT/ENOTFOUND). - Résolution : Le client local a été réécrit pour effectuer ses requêtes API via l'outil système
curl(exécuté comme un processus fils dans Node.js).curlgère de manière transparente et instantanée le repli d'IPv6 vers IPv4, restaurant une connexion instantanée.
2. Collision de Ports (Errno 98) sous le SDK Gradio
- Problème : Sous le SDK par défaut
gradiode Hugging Face, le lanceur interne de la plateforme démarre automatiquement son propre serveur sur le port7860. En voulant y greffer nos endpoints personnalisés FastAPI viauvicorn.run(...), une erreur de collision de port est survenue, faisant crasher le conteneur. - Résolution : Migration de l'Espace vers le SDK Docker avec un
Dockerfilesur mesure. Le serveur Uvicorn est désormais démarré de manière unique et propre via l'instructionCMDdu conteneur Docker, garantissant une cohabitation parfaite de l'API et de Gradio sur le port7860.
🚀 Guide d'Installation (Linux / Windows / Termux)
📋 Prérequis Communs
- Un compte Hugging Face.
- Un jeton d'accès Hugging Face (Access Token) avec droits d'écriture, à placer en variable d'environnement ou dans votre configuration.
🐧 1. Installation sur Linux (Ubuntu/Debian/Arch...)
- Installer Node.js & Git :
sudo apt update sudo apt install -y nodejs npm git curl - Cloner le projet :
git clone https://huggingface.co/spaces/TheShellMaster/cypher-coder cd cypher-coder - Installer les dépendances :
npm install - Assurer les permissions d'exécution :
chmod +x index.js - Lier la commande globalement :
npm link - Lancer l'agent :
cypher
🪟 2. Installation sur Windows (Command Prompt / PowerShell)
- Installer les dépendances requises :
- Téléchargez et installez Node.js depuis le site officiel : nodejs.org.
- Téléchargez et installez Git depuis git-scm.com.
- Installez curl (inclus par défaut dans Windows 10/11 sous PowerShell).
- Cloner et configurer :
Ouvrez PowerShell en tant qu'administrateur :
git clone https://huggingface.co/spaces/TheShellMaster/cypher-coder cd cypher-coder npm install - Créer le lien global :
npm link - Lancer l'agent :
cypher
📱 3. Installation sur Android (Termux)
- Installer et mettre à jour Termux (depuis F-Droid de préférence).
- Installer les paquets nécessaires :
pkg update && pkg upgrade -y pkg install -y nodejs-lts git curl - Cloner le dépôt :
git clone https://huggingface.co/spaces/TheShellMaster/cypher-coder cd cypher-coder - Installer les modules :
npm install - Rendre index.js exécutable :
chmod +x index.js - Créer un raccourci global :
npm link - Lancer l'agent :
cypher
🔒 Sécurité et Consentement
Par mesure de sécurité, Cypher Coder n'apporte aucune modification à votre système de fichiers et n'exécute aucune commande système en tâche de fond de manière opaque.
- Pour toute création/modification de fichier, vous devrez appuyer sur
Ypour valider. - Pour toute exécution de commande système (comme un
npm installougit commit), vous devrez valider explicitement avecY(l'option par défaut étantNon).