san-o1-intelligence 0.1.0

Workspace IA local-first, prompt-first, pour agents persistants

San-o1 Intelligence

San-o1 Intelligence est un workspace IA local-first et prompt-first pour créer, gérer et relancer des agents persistants à partir de fichiers Markdown et JSON.

Le projet ne rend aucune API IA obligatoire. Il organise le contexte, la mémoire, les tâches, les règles et les outils d'un agent, puis génère des prompts complets utilisables dans Codex, Claude Code, ChatGPT, un LLM local ou le TUI OpenRouter optionnel.

Fonctionnalités

• Agents persistants stockés en fichiers Markdown.
• Génération de prompts complets à partir du contexte local.
• Mémoire, tâches et journal par agent.
• Mémoire avancée adaptative sous forme de graphe Markdown avec wikilinks.
• Sandbox locale pour Codex, Claude Code ou tout agent travaillant directement dans le repo.
• Mode proactif, heartbeat local et cron fichier-first.
• Multi-agent local avec équipes, rôles et handoffs.
• TUI OpenRouter optionnel, désactivable et non requis.
• Outils locaux auto-créés, d'abord en statut draft.

Installation

Prérequis : Python 3.9+.

git clone https://gitlab.com/bastienjavaux/san-o1-intelligence.git
cd san-o1-intelligence
python3 -m pip install -e .
soi --help

Sans installation editable, toutes les commandes peuvent aussi être lancées avec :

python3 scripts/run_agent.py --help

Pour contribuer :

python3 -m pip install -e ".[dev]"

Démarrage rapide

Initialiser ou réparer la structure locale :

python3 scripts/run_agent.py init

Créer un assistant générique :

python3 scripts/run_agent.py onboard --non-interactive --name assistant --accept-defaults

Générer le prompt complet d'un agent :

python3 scripts/run_agent.py build-prompt assistant --output workspace/sandbox/output/prompt_assistant.txt

Préparer un brief pour un agent local :

python3 scripts/run_agent.py sandbox-brief assistant --output workspace/sandbox/output/SANDBOX_BRIEF.md

Lancer un check proactif local :

python3 scripts/run_agent.py proactive-check assistant

Commandes principales

Commande	Description
init	Initialise les dossiers, configs, prompts, docs et l'agent par défaut.
onboard	Crée/configure un assistant générique.
create-agent <nom>	Crée un agent persistant.
build-prompt <nom>	Assemble le prompt complet d'un agent.
sandbox-brief <nom>	Génère un brief pour Codex, Claude Code ou un agent local.
proactive-check <nom>	Analyse tâches, inbox et outils draft, puis propose une prochaine action.
heartbeat status|enable|disable|last|run	Gère le heartbeat local.
cron add|list|show|enable|disable|rm|run|due	Gère les tâches planifiées locales.
chat --agent <nom> --mode free|paid	Lance le TUI OpenRouter optionnel.
memory-capture	Capture un signal dans la mémoire avancée.
memory-user-model	Génère un modèle utilisateur local.
memory-brief <agent>	Génère un brief adaptatif.
create-tool <nom>	Crée un outil local en brouillon.
create-team <nom>	Crée une équipe multi-agent locale.
team-run <nom> <objectif>	Prépare un plan d'équipe local ou via OpenRouter avec --execute.
handoff <from> <to> <task>	Crée un passage de relais traçable entre agents.

Structure du repo

san-o1-intelligence/
├── soi/                    # Package Python et CLI
├── scripts/                # Entrées compatibles sans installation
├── agents/assistant/       # Agent public générique
├── prompts/                # Prompts réutilisables
├── docs/                   # Documentation du système
├── memory/advanced/        # Structure mémoire avancée publique
├── tools/custom/           # Outils locaux draft ou approuvés
├── teams/core/             # Équipe locale de base
├── workspace/              # Zones locales, inbox et sorties générées
├── tests/                  # Tests unitaires
├── .gitlab-ci.yml          # CI, sécurité et build GitLab
└── .gitlab/                # Templates issues et merge requests GitLab

Les fichiers privés ou générés de workspace/, les conversations, les .env, les exports personnels et les agents locaux non publics sont ignorés par Git.

Mode local-first

San-o1 Intelligence ne lance pas d'appel IA par défaut. Les workflows de base lisent et écrivent des fichiers locaux :

• agents/<agent>/memory.md pour les mémoires utiles ;
• agents/<agent>/tasks.md pour les tâches ;
• agents/<agent>/logs.md pour les décisions et actions importantes ;
• workspace/sandbox/ pour les entrées, brouillons et sorties locales.

Les actions sensibles, destructives, coûteuses, externes ou liées à des secrets doivent demander confirmation dans les prompts et workflows agent.

OpenRouter optionnel

Le TUI peut appeler OpenRouter si OPENROUTER_API_KEY est disponible dans l'environnement ou dans .env.

cp .env.example .env
# Remplir OPENROUTER_API_KEY localement si besoin.
python3 scripts/run_agent.py chat --agent assistant --mode free

Sans clé, le TUI reste utilisable pour les commandes locales telles que /tasks, /memory, /inbox, /proactive, /save, /clear et /quit.

Le runtime interactif utilise une politique auto_prudent :

• free reste le mode par défaut pour les demandes simples ;
• les demandes complexes, agentiques ou explicitement premium proposent paid ;
• aucun appel payant n'est lancé sans confirmation ;
• les actions MCP locales risquées restent aussi bloquées jusqu'à /confirm.

Dans le TUI, /agent-mode on|off active ou coupe l'exécution agentique, et /model-policy affiche la dernière décision modèle, sa raison et l'action en attente.

Telegram optionnel

Le bridge Telegram réutilise le même runtime agentique que le TUI. Les messages directs peuvent donc déclencher la boucle observer, décider, agir via MCP si autorisé, vérifier et synthétiser.

• /mode free|paid choisit le mode demandé, tout en conservant auto_prudent.
• /confirm confirme la dernière action payante ou risquée en attente.
• /status affiche tâches, inbox et politique modèle.
• Le mode paid reste bloqué côté Telegram tant que SOI_TELEGRAM_ALLOW_PAID=1 n'est pas configuré.

Tests et qualité

python3 -m pip install -e ".[dev]"
python3 -m ruff check .
python3 -m compileall -q soi scripts tests
python3 -m pytest -q
python3 -m build

La CI GitLab exécute ces vérifications sur Python 3.9 à 3.12. Les tags v* construisent les distributions Python et les conservent comme artefacts GitLab, sans publication PyPI automatique.

Sécurité

• Ne commit jamais .env, token, clé API, export personnel ou conversation privée.
• Les exemples de configuration doivent rester vides ou factices.
• Les intégrations externes sont optionnelles.
• Les outils créés par un agent commencent en statut draft.
• Les workflows incluent un scan secrets et un audit de dépendances.

Voir SECURITY.md pour la politique de signalement.

Documentation

• Architecture
• Système de prompts
• Système de mémoire
• Mémoire avancée adaptative
• Mode sandbox local
• Mode proactif
• Heartbeat local
• Cron local
• Création d'outils
• Multi-agent local
• Roadmap

Contribution

Les contributions sont bienvenues. Lis CONTRIBUTING.md, lance les tests localement et vérifie qu'aucune donnée privée n'est ajoutée au diff.

Licence

MIT. Voir LICENSE.