Home

KarenOS — Bienvenue

🇺🇸 US English version: KarenOS — Welcome

KarenOS est une application native macOS qui transforme ton Mac en station d'IA générative 100 % locale : elle télécharge des modèles de langage (formats GGUF) depuis Hugging Face, les installe sur ton disque, puis te permet de discuter avec eux, en streaming, sans que la moindre donnée ne quitte ta machine.

Projet 100 % Swift / SwiftUI, aucune dépendance externe, sans Xcode (compilation swiftc). Auteur : Martial Zinsou

---

Le concept en une minute

Les IA génératives fonctionnent avec deux ingrédients : un modèle (des milliards de paramètres pré-entraînés) et un moteur capable de l'exécuter. KarenOS gère les deux :

1. Elle trouve les modèles → une Boutique de modèles GGUF pré-sélectionnés + une recherche sur Hugging Face.
2. Elle les télécharge → installation à une quantification précise (Q4_K_M par défaut) avec progression.
3. Elle les fait tourner → le moteur llama-server (llama.cpp) est téléchargé automatiquement et lancé en sous-processus local.
4. Elle te laisse discuter → un chat en streaming, comme avec les services en ligne, mais sur 127.0.0.1.

À cette base, s'ajoutent deux couches qui en font un véritable système, pas un simple chat :

• les Compétences : des consignes réutilisables (rôle, contexte, obligations de résultats) injectées dans n'importe quel modèle ;
• les Agents : des missions autonomes qui tournent toutes seules sur un modèle choisi.

Point	Réponse
Que fait l'app ?	Télécharge, installe et exécute des modèles GGUF, puis permet un chat local en streaming.
Moteur d'inférence	llama-server (llama.cpp), version épinglée b8967, lancé en sous-processus.
API locale	Compatible OpenAI : POST /v1/chat/completions sur 127.0.0.1 (port libre), streaming SSE.
Confidentialité	Malentendu impossible : aucune saisie envoyée hors de la machine une fois le modèle chargé.
Système cible	macOS 13+, x86_64 (Intel) et ARM64 (Apple Silicon).

---

Les quatre volets de l'application

L'interface est un TabView à quatre volets, chacun adossé à un « Store » SwiftUI (source unique d'état, persistée).

Volet	Rôle	Store
Mes modèles	Bibliothèque des modèles installés + chat local (chargement automatique au clic).	ModelStore
Boutique	Modèles GGUF sélectionnés + recherche Hugging Face, installation avec progression.	ModelStore
Agents	Missions autonomes : mission, modèle, déclencheur, boucle, conditions de fin.	AgentStore + AgentRunner
Compétences	Consignes structurées (rôle / contexte / obligations) réutilisables sur tout modèle.	SkillStore

Philosophie : pourquoi « OS » ?

Le nom KarenOS renvoie à l'idée d'un système d'exploitation miniature autour de l'IA :

• Unités logicielles sur mesure : chaque volet est un module indépendant, testable et remplaçable (changer de moteur, de source de modèles ou l'interface ne casse rien d'autre).
• Programmabilité : les Compétences standardisent la façon de guider le modèle ; les Agents introduisent l'exécution autonome, comme des scripts ou des « démons » qui tournent en fond.
• Contrôle total : tout vit sur ton disque (modèles, moteur, registres JSON). Rien n'est caché sur un serveur.
• Pédagogie : un projet qui montre, pièce par pièce, comment fonctionne une IA locale de bout en bout — du clavier à la génération de tokens.

Comment une question devient une réponse

1. Tu tapes ton message dans ChatView (éventuellement avec des pièces jointes).
2. L'historique est compilé ; la compétence active, si définie, est insérée en tête comme message system.
3. ChatService envoie POST /v1/chat/completions à 127.0.0.1:<port> avec stream=true, max_tokens=512, temperature=0.7.
4. llama-server charge le modèle en mémoire (contexte -c 2048) et génère.
5. La réponse arrive token par token (SSE) et s'affiche en direct, bulle assistant mise à jour en continu.

Détail complet dans Inférence d'un message.

Multimodal : envoyer plus que du texte

• Pièces jointes : image, vidéo, audio ou n'importe quel fichier (trombone → NSOpenPanel). Vignettes avant envoi, affichées dans la bulle, clic droit → révèle dans le Finder.
• Dictée vocale : bouton micro → reconnaissance vocale locale (framework Speech, sur l'appareil), transcription en direct insérée dans le champ.
• Vision : si un fichier *.mmproj accompagne le modèle, les images sont réellement analysées (format OpenAI vision, base64). Sans cela, l'image reste une pièce jointe.

Détail complet dans Multimodal.

Les agents autonomes

Un agent combine six réglages : mission (le prompt système), modèle consommé, déclencheur (manuel / au lancement / toutes les X secondes), boucle infinie, et des conditions de fin (nombre d'itérations, durée maximale, mot-clé de réussite).

À l'exécution, AgentRunner charge le modèle de l'agent (puis restaure le modèle précédent à la fin), exécute la mission en streaming en réinjectant le résultat précédent, et journalise chaque itération.

Détail complet dans Agents autonomes.

---

L'écosystème : données et moteur

Composant	Rôle
Interface SwiftUI	Les 4 onglets, le chat, l'affichage du streaming.
Hugging Face	Source des métadonnées (recherche, fiches) et des fichiers .gguf.
Dossier de support	~/Library/Application Support/KarenOS/ : moteur, modèles, registres JSON.
Moteur llama-server	Sous-processus qui charge le modèle en mémoire et expose l'API OpenAI sur loopback.

Le dossier de support contient :

• Engine/llama-b8967/llama-server — le moteur téléchargé à la première utilisation ;
• Models/<auteur>__<nom>/…gguf — un sous-dossier par modèle installé ;
• models.json — registre des modèles installés ;
• skills.json et agents.json — compétences et agents créés par l'utilisateur ;
• server.log — journal du processus d'inférence.

Fichier par fichier dans Persistance.

Exemples d'utilisation

• Correction de code : créer une compétence « Correcteur de code » (rôle, contexte, obligations), l'activer, coller son code dans le chat.
• Veille silencieuse : un agent « résumeur » déclenché au lancement, qui traite les fichiers déposés dans un dossier et arrête sur le mot-clé TERMINÉ.
• Génération de contenu : un agent en boucle infinie limité à 10 itérations et 30 min, qui améliore un texte de façon itérative.
• Recherche hors-ligne : chercher des modèles dans la Boutique, installer un petit Qwen 0,5 B et discuter sans connexion.

Philosophie de la fenêtre d'inférence

Chaque modèle fixe sa fenêtre de contexte (ex. 2048 tokens pour KarenOS). La réponse est plafonnée à 512 tokens par appel, la température à 0.7 — des valeurs par défaut raisonnables, réduisant la latence sur les petites machines.

---

Parcours recommandé

1. Lancer l'app : le moteur s'installe tout seul (~8 Mo) dans le dossier de support.
2. Boutique → installer un petit modèle (0,5 – 3 B recommandé sur Intel).
3. Mes modèles → ouvrir le modèle, écrire un message, regarder le streaming.
4. Compétences → créer « Traducteur » ou « Correcteur de code », l'activer, rediscuter.
5. Agents → donner une mission à un modèle (ex. « Corrige ce texte », boucle désactivée, 3 itérations max).

Pages du wiki

Page	Contenu
Architecture	Les blocs, le schéma détaillé, les flux entre composants.
Inférence d'un message	Le cycle complet d'un échange : du clavier au streaming.
Modèles et Boutique	Recherche, détails HF, téléchargement, registre des installés.
Agents autonomes	Missions autonomes : mission, modèle, déclencheur, boucle, conditions de fin.
Multimodal	Pièces jointes (image, vidéo, audio) et saisie vocale.
Compétences	Le système Rôle / Contexte / Obligations de résultats.
Persistance	Fichiers et structure du dossier de support.
Code source	Organisation des fichiers Swift du projet.
Construction & lancement	Compilation sans Xcode, pré-requis, scripts.
Dépannage	Problèmes fréquents et correctifs.
Limites & évolutions	Contraintes actuelles et pistes d'amélioration.
Page encyclopédique (style Wikipédia)	Vue générale documentaire + technique, avec diagrammes UML.

---

Sommaire personnalisable via la sidebar — voir le dépôt principal martialzinsou/KarenOs.