BrainStormer OS

Un système d'optimisation autonome et logique pour résoudre n'importe quelle problématique

Version : 0.2.0-alpha — Licence : AGPL-3.0 — Plateforme : macOS (Ventura / Sonoma) — Statut : Prototypage actif

📌 Table des Matières

🎯 Introduction
✨ Fonctionnalités
🔧 Architecture Technique
🚀 Installation
📝 Utilisation
🔌 API REST
🔌 Gestion des Appareils Distants
🎮 Exemple : Optimisation Steam Deck
🔄 Roadmap de Développement
🤝 Contribution
📜 Licence AGPL-3.0

🎯 Introduction

BrainStormer OS est un moteur d'optimisation autonome qui explore méthodiquement l'espace des solutions face à n'importe quelle problématique structurée. Il est conçu autour de quatre principes fondamentaux :

Principe	Comportement attendu
Contraintes strictes	Ex : "30 FPS minimum", "luminosité ≥ 70%" — jamais violées
Objectifs mesurables	Ex : "maximiser l'autonomie" — quantifiables et traçables
Logique implacable	Élimine les solutions absurdes dès la génération ("jouer écran éteint")
Mémoire anti-répétition	Aucune idée testée deux fois ; chaque échec est classifié et archivé

Pourquoi ce projet ?

BrainStormer OS est né d'un besoin concret : automatiser l'optimisation de projets complexes ( Steam Deck, LLMs locaux) sans dépendre de services cloud, de façon reproductible et souveraine.

Il s'adresse également à toute personne souhaitant un outil open-source, local et systématique pour résoudre des problèmes multi-contraintes.

✨ Fonctionnalités

Fonctionnalité	Description	Statut
Définition du problème	Saisie des contraintes, objectifs et axes en langage naturel.	A développer
Génération d'idées	Propose des axes + des idées wildcard via LLM local (Mistral).	A développer
Filtre logique	Élimine les idées incohérentes avant tout test.	A développer
Tests automatisés	Exécute des tests et mesure FPS, consommation, latence, etc.	A développer
Mémoire persistante	Historique complet des tests pour éviter toute répétition.	A développer
Gestion d'erreur intelligente	Classifie les échecs (logique / technique / performance) et propose des correctifs.	A développer
Rapports Markdown/Obsidian	Génère des rapports structurés avec métriques et explications.	A développer
Visualisation graphique	Graphe interactif des chemins d'exploration (NetworkX + Vis.js).	A développer
Plugin Obsidian	Visualisation native des résultats dans Obsidian.	A développer
Connexion à l'appareil	Connexion SSH aux appareils distants (Steam Deck, PC, etc.).	✅ Nouveau
Commandes personnalisées	Exécution de scripts avant/après les tests pour tout type d'appareil.	✅ Nouveau
100% Local / Souverain	Aucune dépendance cloud. Toutes les données restent sur ta machine.	✅ Garanti

🔧 Architecture Technique

📦 Stack Logicielle

Composant	Technologie	Rôle
Backend	Python 3.11	Orchestration principale, logique métier
Mémoire	SQLite	Stockage des idées, contraintes, résultats
Génération d'idées	Mistral 7B (via Ollama)	Génère les axes wildcard et valide la cohérence
Tests	Pytest + CodeCarbon	Exécution des tests + mesure de consommation
Graphe	NetworkX + Vis.js	Modélisation et visualisation des dépendances
UI Web	HTML/CSS/JS (Vanilla)	Interface utilisateur locale
Plugin Obsidian	Plugin custom JS	Visualisation des rapports dans Obsidian
Background Tasks	`launchd` (macOS)	Exécution en arrière-plan
Monitoring (optionnel)	Prometheus + Grafana	Suivi des métriques système

🔄 Workflow

graph TD
    A[Définition du Problème] --> B[Génération des Axes]
    B --> C[Filtre Logique]
    C --> D[Tests Automatisés]
    D --> E[Analyse des Résultats]
    E --> F[Mémorisation SQLite]
    F --> G[Rapport Markdown]
    G --> H[Validation Utilisateur]
    H -->|Non satisfait| B
    H -->|Satisfait| I[Fin — Solution Retenue]

Principe clé : chaque cycle de boucle enrichit la mémoire. Le système ne peut pas explorer deux fois le même chemin.

🗃️ Structure des Données

{
  "id": "steamdeck_optimisation",
  "title": "Optimisation Steam Deck — Autonomie/Performance",
  "description": "Trouver le paramétrage optimal pour ce binôme.",
  "constraints": ["30 FPS minimum", "Luminosité ≥ 70%"],
  "objectives": ["Maximiser l'autonomie", "Stabilité des performances"],
  "axes": ["TDP", "Fréquence GPU", "Résolution"],
  "wildcards": ["Mode avion", "Désactiver Bluetooth"],
  "tests": [
    {
      "id": "test_1",
      "idea": "TDP 5W",
      "parameters": {"TDP": 5, "GPU": 800, "CPU": 2.5},
      "results": {"FPS": 28, "autonomie": "4h", "temperature": 65},
      "status": "échec",
      "reason": "FPS < 30 — contrainte violée"
    }
  ],
  "created_at": "2026-05-10T10:00:00Z",
  "updated_at": "2026-05-10T10:30:00Z"
}

🚀 Installation

Prérequis

macOS Ventura ou Sonoma (support Linux prévu en v1.0).
Python 3.11+ (recommandé via pyenv).
Ollama : ollama.ai — pour les LLMs locaux.
Mistral 7B (ou modèle équivalent) : ollama pull mistral.
Optionnels :
- MangoHud — mesure FPS (Steam Deck / Linux).
- CodeCarbon — mesure de consommation énergétique : pip install codecarbon.
- Neo4j — mémoire graphique avancée (remplace SQLite pour les grands projets).

Étapes d'Installation

# 1. Cloner le dépôt
git clone https://github.com/ton-utilisateur/brainstormer-os.git
cd brainstormer-os

# 2. Créer et activer l'environnement virtuel
python -m venv venv
source venv/bin/activate

# 3. Installer les dépendances
pip install -r requirements.txt

> ⚠️ **Note** : Pour la gestion des appareils distants (SSH), assurez-vous que `asyncssh` est installé. Si vous avez des erreurs, installez-le manuellement : `pip install asyncssh`

# 4. Configurer Ollama et télécharger Mistral
ollama pull mistral

# 5. Lancer l'application
python brainstormer.py
# → Ouvrir : http://localhost:8000

⚠️ Important (AGPL-3.0) : Si tu déploies BrainStormer OS en tant que service accessible à des tiers (SaaS, API publique, outil interne partagé), tu as l'obligation légale de rendre le code source modifié disponible aux utilisateurs. Voir la section Licence.

📝 Utilisation

1. Créer un Nouveau Projet

Clique sur "➕ Nouveau Projet" dans l'interface web.
Remplis les champs :
- Titre : Nom du projet (ex : "Optimisation Steam Deck").
- Description : Décris la problématique.
- Contraintes : Une par ligne (ex : "30 FPS minimum").
- Objectifs : Une par ligne (ex : "Maximiser l'autonomie").
- Axes initiaux (optionnel) : Pistes de réflexion (ex : "TDP", "Fréquence GPU").
- Outils de test (optionnel) : MangoHud, CodeCarbon, scripts custom.
Clique sur "🚀 Générer la Roadmap de Test".
Valide ou modifie la roadmap proposée.
Lance les tests avec "✅ Valider et Lancer les Tests".

2. Suivre les Résultats

Dans l'onglet "📊 Résultats", pour chaque projet :

Solutions testées avec leurs métriques.
Classement automatique des meilleures solutions.
Détail des échecs et raisons.

3. Consulter la Mémoire

Dans l'onglet "🧠 Mémoire" :

Historique complet des tests.
Idées rejetées et motifs de rejet classifiés.
Solutions validées exportables.

4. Exporter les Résultats

Les rapports sont générés en Markdown et peuvent être :

Importés directement dans Obsidian via le plugin dédié.
Partagés comme fichiers .md autonomes.

🔌 API REST

BrainStormer OS expose une API REST locale permettant de piloter l'agent depuis n'importe quel outil externe (scripts, Obsidian, terminal, autre app).

L'API tourne sur http://localhost:8000 et ne sort jamais de la machine — cohérent avec le principe 100% local.

🔐 Authentification

Un token Bearer est généré automatiquement au premier démarrage et stocké dans .env :

# .env (généré automatiquement)
BRAINSTORMER_API_TOKEN=<token-aléatoire-256bits>

Toutes les requêtes doivent inclure le header :

Authorization: Bearer <token>

📡 Endpoints

Méthode	Route	Description
`POST`	`/api/v1/projects`	Créer un nouveau projet
`GET`	`/api/v1/projects`	Lister tous les projets
`GET`	`/api/v1/projects/{id}`	Détail et statut d'un projet
`POST`	`/api/v1/projects/{id}/run`	Lancer les tests en arrière-plan
`POST`	`/api/v1/projects/{id}/stop`	Mettre l'agent en pause
`GET`	`/api/v1/projects/{id}/results`	Récupérer les résultats et métriques
`GET`	`/api/v1/projects/{id}/memory`	Consulter la mémoire du projet
`DELETE`	`/api/v1/projects/{id}`	Supprimer un projet et sa mémoire
`GET`	`/api/v1/health`	Santé de l'API + statut Ollama
`POST`	`/api/v1/projects/{id}/test-connection`	Tester la connexion SSH à l'appareil
`POST`	`/api/v1/projects/{id}/execute-setup`	Exécuter les commandes de configuration
`POST`	`/api/v1/projects/{id}/execute-measure`	Exécuter les commandes de mesure
`POST`	`/api/v1/projects/{id}/execute-cleanup`	Exécuter les commandes de nettoyage

📖 Exemples

Créer un projet :

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Optimisation Steam Deck",
    "constraints": ["30 FPS minimum", "Luminosité ≥ 70%"],
    "objectives": ["Maximiser l autonomie"],
    "axes": ["TDP", "Résolution", "Fréquence GPU"]
  }'

Lancer les tests en arrière-plan :

curl -X POST http://localhost:8000/api/v1/projects/steamdeck_optimisation/run \
  -H "Authorization: Bearer <token>"
# → {"status": "running", "agent": "active", "queue": 4}

Récupérer les résultats :

curl http://localhost:8000/api/v1/projects/steamdeck_optimisation/results \
  -H "Authorization: Bearer <token>"
# → {"best": {"fps": 52, "autonomie": "4h15", "config": {...}}, "tests": [...]}

Vérifier la santé de l'API :

curl http://localhost:8000/api/v1/health
# → {"status": "ok", "ollama": "connected", "model": "mistral:7b", "queue": 3}

Tester la connexion SSH à un appareil :

curl -X POST http://localhost:8000/api/v1/projects/steamdeck_optimisation/test-connection \
  -H "Authorization: Bearer <token>"
# → {"success": true, "message": "Connection successful", "output": "BrainStormer OS - Connection Test"}

Exécuter les commandes de configuration :

curl -X POST http://localhost:8000/api/v1/projects/steamdeck_optimisation/execute-setup \
  -H "Authorization: Bearer <token>"
# → {"success": true, "results": [{"success": true, "stdout": "..."}]}

Exécuter les commandes de mesure et récupérer les métriques :

curl -X POST http://localhost:8000/api/v1/projects/steamdeck_optimisation/execute-measure \
  -H "Authorization: Bearer <token>"
# → {"success": true, "results": [...], "parsed_metrics": {"fps": "52.5", "temperature": "68°C"}}

Exécuter les commandes de nettoyage :

curl -X POST http://localhost:8000/api/v1/projects/steamdeck_optimisation/execute-cleanup \
  -H "Authorization: Bearer <token>"
# → {"success": true, "results": [{"success": true, "stdout": "..."}]}

🔄 Agent en arrière-plan

L'agent peut tourner indépendamment de l'UI web. Une fois run lancé, le processus est géré par launchd (macOS) et continue même si le navigateur est fermé.

# Vérifier l'état de l'agent depuis le terminal
curl http://localhost:8000/api/v1/projects/{id} -H "Authorization: Bearer <token>"
# → {"status": "running", "current_test": "TDP 8W + CPU 2.5GHz", "progress": "6/12"}

# Stopper proprement
curl -X POST http://localhost:8000/api/v1/projects/{id}/stop -H "Authorization: Bearer <token>"
# → {"status": "paused", "checkpoint": "test_6_saved"}

⚠️ AGPL-3.0 : Si tu exposes cette API à des tiers (réseau local, internet), tu dois publier ton code source modifié.

🔌 Gestion des Appareils Distants

BrainStormer OS peut maintenant se connecter à tes appareils distants via SSH et exécuter des commandes personnalisées pour automatiser complètement tes tests.

📋 Configuration de la connexion

Lorsque tu crées un projet, tu peux maintenant configurer :

Champ	Description	Exemple (Steam Deck)
Type d'appareil	Type de matériel	`Steam Deck`
Adresse IP / Host	Adresse du device	`192.168.1.50` ou `steamdeck.local`
Utilisateur SSH	Compte SSH	`deck`
Port SSH	Port de connexion	`22`
Authentification	Méthode	`Clé SSH` (recommandé) ou `Mot de passe`

📝 Commandes Personnalisées

Trois types de commandes peuvent être définis :

Type	Quand ?	Exemple
Configuration	Avant le test	`sudo cpupower frequency-set -g performance`
Mesure	Pendant le test	`cat /tmp/mangohud.log \| grep fps`
Nettoyage	Après le test	`sudo cpupower frequency-set -g powersave`

🎯 Types d'appareils supportés

✅ Steam Deck (Linux - mode Desktop requis)
✅ PC Windows (avec OpenSSH Server activé)
✅ PC Linux (SSH pré-installé)
✅ Mac (SSH activé dans Préférences)
✅ Raspberry Pi
✅ Serveur (n'importe quel serveur avec SSH)
✅ Autre (n'importe quel appareil avec SSH)

🔧 Prérequis par appareil

Steam Deck / Linux

# Installer OpenSSH
sudo pacman -S openssh

# Démarrer et activer le service
sudo systemctl enable --now sshd

# Configurer le mot de passe pour l'utilisateur deck
passwd deck

Windows 10/11

# Activer OpenSSH Server
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

# Démarrer le service
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic

Mac

# Activer le partage à distance dans Préférences Système > Partage
# Ou via la ligne de commande
sudo systemsetup -setremotelogin on

🎮 Exemple : Optimisation Steam Deck

📌 Contexte


Problématique	Trouver le paramétrage optimal entre autonomie et performance
Contraintes	30 FPS stables · Luminosité ≥ 70% (≈320 nits) · Latence réseau stable (jeux en ligne)
Objectifs	Maximiser l'autonomie · Stabiliser les performances

🔍 Axes de Réflexion

Type	Axes
Matériel	TDP (3–15 W), fréquence GPU (200–1600 MHz), fréquence CPU (limite 3.0 GHz, SMT)
Graphiques	Résolution (1280×800 / 960×600 + FSR), ombres, post-traitement, distance d'affichage
Logiciel	PowerTools (threads CPU), CryoUtilities (swap mémoire), Game Mode
Réseau	Wi-Fi (désactivé en solo), optimisation de canal
Wildcard	Mode avion, désactiver Bluetooth, kernel custom

🧪 Protocole de Test

FPS : MangoHud
Consommation : CodeCarbon
Température : sensors (SteamOS)
Latence réseau : ping + mtr

Jeux de référence : Cyberpunk 2077 (solo), Elden Ring (monde ouvert), Apex Legends (online), Warzone (charge CPU élevée).

Paramètres fixes : Luminosité 80% · Résolution 1280×800 ou 960×600 + FSR.

📊 Résultats

Solution	FPS	Autonomie	Température	Statut
Résolution réduite + Mode Avion	52	4h15	68°C	✅ Optimale
TDP 8W + CPU 2.5GHz	35	4h30	65°C	⚠️ FPS limite
FSR + TDP 10W	48	3h45	70°C	✅ Bonne

Meilleure configuration retenue :

Résolution 960×600 + FSR + Mode Avion + TDP 10W
→ 52 FPS stables · 4h15 d'autonomie · 68°C
→ Gain : +1h45 vs configuration de référence

🤝 Contribution

BrainStormer OS est un projet communautaire sous AGPL-3.0. Les contributions sont bienvenues et encadrées par la licence.

Règles importantes pour les contributeurs

En contribuant à ce projet, tu accordes une licence sur tes éventuels brevets couvrant ta contribution (clause de protection contre les brevets de l'AGPL-3.0).
Toute version modifiée redistribuée (y compris en SaaS) doit rester sous AGPL-3.0 et inclure le code source.

Processus de contribution

# 1. Fork le dépôt sur GitHub
# 2. Crée ta branche
git checkout -b feature/ma-fonctionnalite

# 3. Commit avec un message clair
git commit -m "feat: ajout de la fonctionnalité X"

# 4. Push et ouvre une Pull Request
git push origin feature/ma-fonctionnalite

Signaler un bug → Ouvre un Issue sur GitHub.
Proposer une fonctionnalité → Ouvre une Discussion sur GitHub.
Contact direct → contact@brainstormer-os.dev (à remplacer)

📜 Licence AGPL-3.0

Ce projet est distribué sous GNU Affero General Public License v3.0 (AGPL-3.0).

5 points clés à retenir

#	Point	Ce que ça implique concrètement
1	Liberté totale pour les utilisateurs	Exécuter, modifier et redistribuer librement.
2	Obligation de partager le code source	Même si tu déploies en SaaS sans distribuer de binaire, tu dois publier ton code modifié.
3	Crédit obligatoire	Le nom Adrien NAULT et la mention AGPL-3.0 doivent toujours apparaître.
4	Pas de restrictions supplémentaires	Tu ne peux pas ajouter de clauses interdisant l'usage commercial ou les modifications.
5	Protection contre les brevets	Tout contributeur accorde une licence sur ses brevets couvrant sa contribution.

Texte intégral

GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007

Copyright (C) 2026 Adrien NAULT

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

Additional permission under GNU GPL version 3 section 7:
If you modify this Program, or any covered work, by linking or combining
it with services offered over a network, you must prominently offer all
users of those services the complete corresponding source code of
your modified version.

📎 Texte complet officiel : https://www.gnu.org/licenses/agpl-3.0.html

BrainStormer OS — Conçu dans le cadre du projet NVNC Core. Aucune dépendance cloud. Toutes les données restent sous ton contrôle.

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
tests		tests
.env.example		.env.example
.gitignore		.gitignore
DOCUMENTATION.md		DOCUMENTATION.md
INSTALL.md		INSTALL.md
START_GUIDE.md		START_GUIDE.md
brainstormer.py		brainstormer.py
brainstormer_os_ui.html		brainstormer_os_ui.html
brainstormer_os_ui_mockup.html		brainstormer_os_ui_mockup.html
final.md		final.md
readme.md		readme.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation