Contribuer¶

Cloner¶

git clone "https://dev.azure.com/aiintelligencemanagement/AI%20Intelligence%20Management/_git/aim"
cd aim
uv sync --all-extras

Authentification git¶

L'authentification s'appuie sur ta session az login — aucun jeton personnel à créer, stocker ni renouveler.

git config --add "credential.https://dev.azure.com.helper" ""
git config --add "credential.https://dev.azure.com.helper" "$PWD/scripts/ado-credential-helper.sh"

La première ligne n'est pas décorative

Elle réinitialise la chaîne de gestionnaires héritée du global. Sans elle, le trousseau macOS répond avant l'assistant et sert un identifiant périmé — le push échoue avec un message d'authentification trompeur.

Développer¶

docker compose up -d --build      # API + PostgreSQL, authentification désactivée
uv run aim login --api-url http://localhost:8899
uv run pytest -q

Docker Compose n'est pas un environnement de recette

Il existe pour le développement et les tests automatisés. La recette utilisateur se fait sur Azure.

Organisation du code¶

src/aim/
├── core/                  métier pur, sans HTTP ni base
│   ├── models.py          Client, Document, Fact, Principal…
│   ├── store.py           protocole Store (dix méthodes)
│   ├── connectors/        lecture de fichiers et de dépôts
│   ├── extract/           prompts, pipeline, consolidation
│   └── compile/           sélection du pack, émetteurs
├── server/                FastAPI, MCP, PostgreSQL, Blob, Entra
└── cli/                   client HTTP, configuration, cache
infra/                     Bicep
scripts/                   déploiement, outils
website/                   cette documentation
tests/                     51 tests, aucun appel réseau

Règles de conception¶

Le cœur ne dépend de rien. Une fonction de core/ ne doit connaître ni HTTP, ni PostgreSQL, ni Azure. Le protocole Store est la seule frontière.

Un contrôle d'accès, pas deux. L'API et le MCP partagent la même fonction de résolution du principal. Ajouter une surface ne doit pas dupliquer la vérification.

Toute panne doit être bruyante. Les échecs silencieux rencontrés — déploiement sans effet, journaux invisibles, pipe avalant un code d'erreur — ont tous coûté du temps. Un except sans journalisation est un bug.

Tests¶

uv run pytest -q

51 tests, sans appel réseau ni LLM. Le store est remplacé par un double en mémoire qui implémente le même protocole.

Ce qui est couvert en priorité : le découpage, la déduplication, la normalisation des portées, la budgétisation du pack, les émetteurs, la reprise sur troncature, le repli hors ligne, la correspondance de globs.

Écrire un test de régression pour chaque bug trouvé. Les tests existants portent tous la trace d'une panne réelle ; c'est ce qui les rend utiles plutôt que décoratifs.

Documentation¶

Cette documentation vit dans website/, en MkDocs Material.

uv run --group docs mkdocs serve -f website/mkdocs.yml
./scripts/deploy-docs.sh

Elle fait partie du produit : une fonctionnalité livrée sans sa page est une fonctionnalité à moitié faite.

Convention de commits¶

Format court en français, préfixé par le type : feat:, fix:, docs:, refactor:, chore:. Le corps explique pourquoi, pas quoi — le diff dit déjà quoi.

Roadmap¶

Voir ROADMAP.md à la racine du dépôt. L'itération en cours est l'épreuve du réel : onboarder un client réel, brancher le MCP, mesurer les reprises en revue avec et sans le pack. Elle passe avant toute nouvelle fonctionnalité.