Important
PIERRE est actuellement en version 0.39.x (consulter les releases). La qualité de la base de connaissances est estimée à 20 % — elle s'améliore en continu grâce aux contributions du mouvement HLM. En cas de difficultés, créer une issue ou envoyer un email à charnould@pierre-ia.org.
PIERRE ne connaît pas les spécificités de votre organisme (taille du parc, coordonnées des agences, procédures internes…). Ces éléments peuvent lui être enseignés en quelques secondes.
PIERRE est un agent IA open source et plurilingue au service du mouvement HLM, de ses candidats, locataires et collaborateurs.
Plus concrètement, PIERRE c'est à la fois :
-
Un agent IA open source qui répond 24/7/365 aux questions de premier niveau des locataires et demandeurs HLM, et épaule au quotidien les collaborateurs des bailleurs sociaux (processus, données patrimoniales, aide à la rédaction, etc.).
-
Une base de connaissances en open data (consultation), utilisable indépendamment de l'agent IA et indispensable à toute IA agentique.
→ Télécharger une présentation de PIERRE (PDF · 2,7 Mo)
- Les bases de connaissances de PIERRE
- Enrichir votre instance de PIERRE avec vos connaissances propriétaires
- Architecture et fonctionnement technique
- Comment déployer PIERRE ?
- Modifier et paramétrer PIERRE (self-hosting)
- Administrer PIERRE avec une interface graphique
- Application desktop Windows et macOS (alpha/not-prod-ready)
- Licence
PIERRE n'est pas seulement un agent IA branché sur un modèle de langage. Son intérêt vient d'abord de ses bases de connaissances : un ensemble de documents structurés qu'un agent peut lire, comparer et citer pour répondre aux questions des locataires, demandeurs et collaborateurs.
Cette base est volontairement simple : ce sont des fichiers lisibles, versionnables et améliorables. Plus ils sont clairs, plus PIERRE répond juste.
PIERRE distingue deux familles de connaissances :
| Base | Contenu | Usage |
|---|---|---|
| Base communautaire | Connaissances utiles à l'ensemble du mouvement HLM : demande de logement social, SLS, charges, vie du bail, associations, histoire du logement social… | Mutualiser un socle commun, améliorable par tous. |
| Base propriétaire | Données propres à un organisme : procédures internes, coordonnées d'agences, politiques locales, consignes métier, données patrimoniales… | Adapter PIERRE à votre contexte sans publier vos informations internes. |
Un modèle de langage généraliste ne connaît ni vos agences, ni vos règles internes, ni vos arbitrages locaux. PIERRE devient utile lorsqu'il peut accéder à des documents fiables, à jour et compréhensibles.
Concrètement, enrichir la base de connaissances (communautaire ou propriétaire) permet à PIERRE de répondre à des questions comme :
- "Quel service contacter pour une réclamation de charges ?"
- "Quelle est notre procédure interne en cas de trouble du voisinage ?"
- "Comment expliquer simplement le supplément de loyer de solidarité ?"
- "Quel modèle de courrier utiliser dans cette situation ?"
La base de connaissances (consultable ici) est le coeur de l'intelligence de PIERRE. Ce n'est ni plus ni moins que des fichiers texte transformés. Par exemple, ce fichier contient tout ce que sait PIERRE sur les enquêtes locataires.
Ce document peut être incomplet ou imprécis — c'est tout l'enjeu que de l'améliorer, car c'est lui qu'utilise PIERRE pour répondre aux questions sur ces sujets.
Contribuer à la base de connaissances, c'est donc simplement : (1) améliorer le contenu des fichiers existants et (2) créer des fichiers sur les thématiques manquantes.
La base de connaissances — co-construite avec les bailleurs — couvre plusieurs thématiques :
Connaissances générales: connaissances génériques applicables sur tout le territoire (ex : comment gérer un trouble du voisinage ? qu'est-ce que les charges locatives ?).Spécificités locales: connaissances spécifiques à un territoire donné (ex : les associations d'hébergement d'urgence dans l'Ain, les structures d'aide contre les violences conjugales dans l'Eure).Organismes HLM: connaissances relatives à un organisme en particulier (ex : qu'est-ce que Grand Dijon Habitat et quelles sont les coordonnées de ses agences ?).Wikipédia: connaissances importées de Wikipédia (ex : l'histoire du logement social).
- Consulter la base de connaissances.
- Si vous identifiez un manque, une imprécision ou une erreur : envoyer un email à charnould@pierre-ia.org ou créer une
issuesur GitHub (pour les connaisseurs).
Au fur et à mesure de l'amélioration de la base de connaissances, la pertinence de PIERRE s'améliore automatiquement et profite à l'ensemble du mouvement HLM.
Il y a deux façons d'enrichir une instance de PIERRE avec vos données propriétaires : (i) via l'interface d'administration ou (ii) programmatiquement via cURL. PIERRE accepte aujourd'hui les fichiers Word, Excel et Markdown ; les autres formats ne sont pas gérés à ce stade.
Pour que l'ingestion fonctionne correctement, les fichiers doivent être accompagnés d'un _metadata.xlsx. Ce fichier indique à PIERRE comment importer chaque document et quels profils-utilisateurs peuvent y accéder.
Le détail opérationnel est volontairement conservé dans un guide dédié : préparer vos documents pour PIERRE. C'est le document à transmettre aux équipes-métier avant une première campagne d'alimentation documentaire.
PIERRE est pensé pour être hébergé sur l'infrastructure choisie par l'organisme HLM ou par pierre-ia.org. Les données propriétaires, les contenus extraits et les conversations sont uniquement stockés sur l'instance déployée. Lorsqu'un utilisateur interroge PIERRE, le contenu nécessaire à la réponse peut être transmis au modèle de langage configuré/choisi par l'organisme.
Les questions RGPD, DPO, localisation des données, rôles de responsabilité et traitements associés sont détaillés dans la note dédiée : Data Protection Officer.
Pour contribuer au code source, créer une issue dans GitHub et suivre les us et coutumes des projets open source. Les releases de PIERRE sont consultables ici.
| Composant | Technologie |
|---|---|
| Runtime | Bun (MIT) |
| Framework | Hono (MIT) |
| Agent IA (« Harness ») | Pi (MIT) |
| Isolation des conversations | smol machines, micro-VMs via KVM (Apache-2.0) |
| Base de données | SQLite via bun:sqlite (Public Domain) |
| Déploiement | Kamal (MIT) via Docker (Apache-2.0) |
| LLM | BYOK — OpenAI / OpenAI-compatible / Anthropic |
L'application sert l'interface web, isole chaque conversation dans une micro-VM, monte la base de connaissances autorisée dans cette VM, puis laisse l'agent explorer les fichiers utiles avant de répondre.
Contrairement à un simple chatbot qui injecte un contexte fixe dans un LLM, PIERRE raisonne, explore et lit des fichiers de façon autonome. C'est cette capacité — lire dynamiquement les bonnes sources plutôt que tout envoyer aveuglément — qui lui permet de travailler sur des bases de connaissances importantes et de répondre à des questions complexes nécessitant de « raisonnner ».
Navigateur / Widget / Apps VPS (production)
-------------------------- ----------------------------------------
+-- Docker container ------------------+
+----------+ GET /ai | |
| | -------------------------> | Hono (Bun) |
| Client | | | |
| | <------------------------- | |-- authenticate |
+----------+ NDJSON stream | |-- parse AIContext |
{t:"response", d:{...}} | |-- save user message (SQLite) |
{t:"reset"} | |-- answer_user() |
{t:"done", d:{...}} | | |
| v |
| streamCopilot() |
| | |
+---------+----------------------------+
|
| JSONL stdin/stdout
v
+-- smolVM (micro-VM) ----------------+
| |
| Pi |
| (RPC mode) |
| | |
| |-- lit /knowledge/** |
| |-- appelle le LLM (BYOK) |
| |-- génére la réponse |
| |
| /knowledge (volume monté) |
| |-- Vie du bail/ |
| |-- Charges locatives/ |
| |-- Données propriétaires |
| |-- ... |
+-------------------------------------+
C'est une particularité important de l'architecture de PIERRE pour du « privacy by design ».
Chaque conversation active dispose de sa propre micro-VM isolée (via smol machines). Concrètement :
- À l'arrivée d'un premier message, PIERRE crée une micro-VM légère.
- La base de connaissance applicable est montée en lecture à l'intérieur de la VM.
- Pi est démarré en mode RPC (stdin/stdout JSONL) à l'intérieur de cette VM.
- Un processus hôte (
PiRpcClient) communique avec Pi via les flux stdin/stdout du sous-processus. - La conversation se déroule : Pi lit
AGENTS.md(instructions système) et les fichiers de la base de connaissances, raisonne, et répond. - Après 30 minutes d'inactivité, la VM est automatiquement détruite.
Serveur hôte
+------------------------------------------------------------------------------+
| |
| vm-registry (Map<convId, VmEntry>) |
| |
| conversation_abc --> smolVM "conversation_abc" PiRpcClient (stdin/stdout) |
| conversation_def --> smolVM "conversation_def" PiRpcClient (stdin/stdout) |
| conversation_xyz --> smolVM "conversation_xyz" PiRpcClient (stdin/stdout) |
| |
| [timer 30min inactivité -> destroyVm()] |
| [cleanup orphelins au démarrage] |
+------------------------------------------------------------------------------+
Pourquoi cette approche ?
| Propriété | Sans smolVM | Avec smolVM |
|---|---|---|
| Isolation des conversations | ✗ Contexte partagé | ✓ VM étanche par conv. |
| Fichiers accessibles à l'agent | Injectés manuellement | Montés nativement dans /knowledge |
| Sécurité des écritures | Aucune garantie | Écritures bloquées hors /tmp/ |
| Session persistante | Reconstituée à chaque tour | Conservée nativement dans Pi |
PIERRE ne retourne pas une réponse monolithique — il streame la réponse en temps réel vers le client. Le protocole utilisé est le NDJSON (Newline-Delimited JSON) : chaque événement est une ligne JSON terminée par \n.
Pi (VM) streamCopilot() Navigateur
| | |
| agent_start | |
| ---------------------> | |
| text_delta "Bon" | {t:"response", |
| ---------------------> | -- d:{content:"Bon"}} >
| text_delta "jour" | {t:"response", |
| ---------------------> | -- d:{content:"jour"}}>
| tool_start | {t:"reset"} |
| ---------------------> | ---------------------> |
| tool_start | |
| ---------------------> | (log only) |
| tool_result | |
| ---------------------> | (log only) |
| text_delta "Voici…" | {t:"response", |
| ---------------------> | -- d:{content:"…"}} >|
| agent_end | {t:"done", |
| ---------------------> | -- d:{content:"…"}} >|
PIERRE se déploie en une commande grâce à Kamal qui orchestre Docker sur le VPS.
Machine locale VPS
-------------- -------------------------------------
+-- Kamal proxy (SSL/TLS + HTTP/2) --+
$ bun prod:deploy | ^ |
| | | :443 |
|-- docker build (amd64) | | |
|-- push -> registry local :5555 | v |
|-- kamal deploy ----------------> | Docker container (PIERRE) |
| |-- Bun runtime |
| |-- smolvm binary |
| |-- /dev/kvm (nested virt.) |
| |-- volume datastores/ (SQLite) |
+------------------------------------+
Kamal gère :
- Le build Docker en
amd64 - Un registry Docker local sur le VPS (port
5555) - Le proxy SSL automatique (via Let's Encrypt) avec un timeout de 600s pour les longues requêtes IA
- Le déploiement sans interruption (zero-downtime) par swap de containers
- La persistance des données : le volume
datastores/survit aux redéploiements
Il est possible de déployer plusieurs instances sur un même VPS (ex : production + staging).
PIERRE fonctionne sur le principe du « Bring Your Own LLM Key/Model » : vous choisissez et fournissez votre propre modèle.
La configuration se fait dans .env.production :
AI_TYPE=openai
AI_BASE_URL=https://…
AI_MODEL=gpt-5.4
AI_API_KEY=sk-…Afin de mesurer l'usage de PIERRE et comprendre quelles fonctionnalités sont utilisées, chaque instance de PIERRE envoie automatiquement et silencieusement un ping anonyme à pierre-ia.org à chaque interaction. Ce ping contient uniquement l'URL de l'instance (HOST) et le type d'événement — aucune donnée personnelle, aucun contenu de conversation, rien.
Déployer PIERRE sur un serveur génère des coûts :
- La location d'un serveur (VPS) : ~€45 par mois
Nul besoin de GPU, mais le serveur doit impérativement proposer la nested virtualisation. - L'usage d'un LLM : environ $2,50 (in) et $15 (out) / MTokens
Avant de déployer PIERRE, vérifier que vous disposez de :
| Prérequis | Détail |
|---|---|
| Serveur | Linux, virtualisation imbriquée activée (/dev/kvm exposé au container) |
| Ports ouverts | 80 (HTTP) et 443 (HTTPS) |
| Accès SSH | Clef ou mot de passe |
| Clé API LLM | OpenAI, Anthropic ou tout provider compatible OpenAI API |
Important
La nested virtualisation (virtualisation imbriquée) est la seule contrainte matérielle de PIERRE (nul besoin de GPU). Elle est indispensable pour que les smolVMs puissent s'exécuter à l'intérieur du container Docker. La plupart des VPS la proposent en option ou nativement.
Si vous ne souhaitez pas gérer l'infrastructure, le projet PIERRE propose une offre d'hébergement managé :
- Déploiement clé en main sur serveur dédié
- Mises à jour automatiques (dernière version en permanence)
- Suivi et monitoring inclus
- Hébergement chez Hetzner (Falkenstein, Allemagne - ISO 27001)
- Aucune compétence technique requise côté bailleur
Adresser un email à charnould@pierre-ia.org pour en savoir plus.
Les instructions ci-après sont valables sous macOS et Windows (via WSL — sous-système Windows pour Linux).
- Installer
Bun(≥1.3.13) et vérifier sa bonne installation (instructions). - Installer
SQLite3et vérifier sa bonne installation (instructions). - Installer
smol machines(micro-VM isolées) et vérifier sa bonne installation (instructions). - Forker/cloner le présent dépôt.
- Lancer
bun installdans votre terminal pour installer les dépendances. - Renommer le fichier
.env.exampleen.env.productionet le compléter. - Lancer
bun devpour démarrer PIERRE. - PIERRE est accessible à http://localhost:3000.
Pour déployer PIERRE sur un serveur, il est indispensable d'être parvenu à le faire fonctionner en local.
- Installer
Docker Desktopet le lancer (instructions).Dockergérera la conteneurisation. - Lancer
gem install kamalpour installerKamal(≥2.11.0) qui gérera le déploiement (instructions). - Disposer d'un VPS et être en capacité de s'y connecter via
ssh(avec une clef ou mot de passe). Les ports80(http) et443(https) doivent impérativement être ouverts. - Finaliser les modifications du fichier
.env.productionque vous avez créé précédemment. - Saisir dans votre terminal
bun prod:setup. - PIERRE est accessible à l'adresse URL de votre serveur (prévoir quelques minutes pour la génération des certificats SSL).
- Étapes suivantes (optionnelles et décrites ci-dessous) :
– Créer une seconde instance (de tests) de PIERRE sur le même serveur
– Personnaliser PIERRE
– Afficher PIERRE sur votre site internet, extranet-locataire ou intranet
PIERRE — et notamment sa base de connaissances — évolue régulièrement et suit la convention semver. Pour le mettre à jour :
- Saisir
bun pierre:versionpour connaître la dernière version disponible. - Consulter les releases pour connaître les modifications et éventuels breaking changes.
- Mettre à jour votre fork/clone.
- Saisir
bun pierre:configpour vous assurer queconfig.tsest correctement paramétré. - Saisir
bun prod:deploydans votre terminal pour redéployer.
Pour tester en conditions réelles les mises à jour et nouveautés de PIERRE, le plus simple est de déployer une seconde instance de PIERRE sur votre serveur de production.
- Dupliquer
.env.productionen.env.staginget le modifier (a priori uniquementSERVICEetHOST). - Lancer
bun staging:setuppour déployer la première fois. - Lancer
bun staging:deploypour redéployer.
Note
Dans les instructions ci-dessous, nous considérons un bailleur social fictif nommé Pierre Habitat dont le site institutionnel est accessible à pierre-habitat.fr et qui a déployé sa propre version de PIERRE à l'adresse/IP 180.81.82.83.
- Dans le répertoire
./customization/chatbot, supprimer tous les répertoires à l'exception dedefault(vous pouvez modifier ou dupliquerdefault). - Créer une icône
system.svget remplacer la précédente dansdefault. Cette icône est celle qui apparaît dans l'interface de l'agent IA (au-dessus de « Bonjour 👋 »). - Générer les icônes qui permettront d'ajouter votre agent IA sur l'écran d'accueil des smartphones de vos utilisateurs et remplacer celles dans le dossier
icons(les icônes Windows ne sont pas nécessaires). Conserver la structure du répertoire et le nommage des fichiers (automatique). - Modifier
config.ts:
–idavec le nom exact du répertoire
–greetingqui est le message d'accueil de votre agent IA
–examplesqui sont les exemples proposés après votre message d'accueil
–disclaimerqui est le message s'affichant après chaque réponse générée (ex : Une IA peut se tromper, vérifier les informations.). - Modifier dans
manifest.json:
–short_namepar le nom souhaité de votre agent IA
–start_urlparhttps://180.81.82.83/?config=default(ou par le nom du répertoire que vous avez créé) - Votre chatbot personnalisé est disponible à http://localhost:3000/?config=PIERRE-habitat.
Tip
Pour vous assurer que config.ts est correctement paramétré, notamment lors des montées de version qui peuvent en modifier la structure, lancer bun pierre:config.
Si vous avez personnalisé visuellement votre agent IA (cf. supra), il affiche bien les icônes et les salutations de votre organisme, mais il ne se présente pas encore comme l'agent IA de votre organisme (essayez en lui demandant qui il est !). Pour modifier cela, modifier AGENTS.md (préférez l'anglais). Ce fichier suit la convention standard des systèmes agentiques : Pi le lit depuis son répertoire de travail (/knowledge) au démarrage de chaque VM.
Pour que l'agent IA cite systématiquement ses sources dans ses réponses, ajouter dans AGENTS.md une instruction explicite (not working).
Important
Pour installer PIERRE sur votre site internet, il est indispensable de disposer d'une version fonctionnelle de PIERRE installée sur un VPS.
<script crossorigin="anonymous" src="https://180.81.82.83/assets/core/dist/js/widget.js"></script>
<p
id="pierre-ia"
data-url="https://180.81.82.83"
data-configuration="default"
style="
right: 20px;
bottom: 20px;
color: #000;
font-size: 30px;
font-weight: bold;
padding: 2px 12px;
background-color: #fff;
border-radius: 8px;
border: 4px solid black;
box-shadow: 2px 2px 6px #00000080;"
>
iA?
</p>avec :
iA?: le nom d'affichage du bouton (libre à vous de le modifier)style: le style CSS du bouton (libre à vous de le modifier)180.81.82.83dans l'URL du script le domaine/IP du serveur où le script est accessibledata-url: le domaine/IP (sans slash de fin) du serveur où PIERRE est accessibledata-configuration:defaultou le nom du répertoire que vous avez créé plus tôt dans./customization/chatbot(cf. supra).
<iframe
id="PIERRE"
title="PIERRE - l'IA de Mouvement HLM"
style="..."
width="450"
height="620"
src="http://180.81.82.83/?config=default"
>
</iframe>avec :
style: le style CSS de l'iframe (libre à vous de le modifier)src: l'URL d'accès à PIERRE
Si vous hébergez PIERRE :
- Rendez-vous à l'adresse https://180.81.82.83/a (à remplacer par votre domaine/IP).
- Saisir (la première fois)
admin@pierre-ia.orget le mot de passe contenu dans la variable d'environnementAUTH_PASSWORD. - Vous pouvez désormais créer autant d'utilisateurs que nécessaire (n'oubliez pas de transmettre les mots de passe !) qui pourront modifier les utilisateurs ou l'encyclopédie, consulter les conversations ou les statistiques.
Depuis la page Encyclopédie, un administrateur peut ajouter les documents propriétaires de l'organisme. Cette action alimente la base de connaissances utilisée par PIERRE pour répondre selon vos procédures, vos coordonnées et vos consignes locales.
Avant le premier import, transmettre aux équipes concernées le guide préparer vos documents pour PIERRE. Il détaille les formats acceptés, la structure attendue des fichiers Word/Excel/Markdown et le rôle du fichier _metadata.xlsx.
- Se connecter à https://180.81.82.83/a, puis cliquer sur
Encyclopédie. - Télécharger
_metadata.xlsx, le compléter scrupuleusement et le ré-uploader avec les fichiers associés. - Indispensable : Configurer
config.tsde manière à permettre l'utilisation des connaissancesproprietaryet le protéger s'il utilise des données privées. - Toutes les nuits aux alentours de 4h du matin, la base de connaissances est automatiquement reconstruite.
Cette option permet d'automatiser/programmer le processus d'upload documentaire — particulièrement utile si vos données changent souvent ou quotidiennement (ex : présence des collaborateurs).
curl -X POST https://URL/a/knowledge \
-H "Authorization: Bearer AUTH_BEARER" \
-H "Authorization-Context: cli" \
-H "Accept: application/json" \
-F "service=pierre" \
-F "files[]=@Carnet du patrimoine.docx" \
-F "files[]=@Cahier de consignes.xlsx"avec :
URL: l'URL de votre instance de PIERREAUTH_BEARER: la variable d'environnementAUTH_BEARERservice: la variable d'environnementSERVICEfiles[]: le ou les fichiers à uploader
Note
La présence sur le serveur de _metadata.xlsx est toujours indispensable.
PIERRE dispose d'une application desktop (Windows et macOS) téléchargeable ici. Un lien de téléchargement est également disponible depuis la page d'accueil de l'interface d'administration.
Note
macOS — Lors du premier lancement, macOS peut afficher un avertissement de sécurité car l'application n'est pas notarisée par Apple. Si vous voyez le message "pierre est endommagé et ne peut pas être ouvert", exécutez la commande suivante dans le Terminal, puis relancez l'application :
sudo xattr -rd com.apple.quarantine /Applications/pierre.appVous pouvez également faire un clic droit sur l'application > Ouvrir, puis confirmer dans la boîte de dialogue, ou aller dans Réglages système > Confidentialité et sécurité et cliquer sur Ouvrir quand même.
Note
Windows — Lors du premier lancement, Windows SmartScreen peut afficher "Windows a protégé votre ordinateur". Cliquer sur Informations complémentaires, puis sur Exécuter quand même.
Le code source du présent dépôt est sous licence GNU Affero General Public License Version 3 (AGPL-3.0), complétée par une clause additionnelle de restriction commerciale en fin de fichier LICENSE.md. La base de connaissances (dossier /knowledge) est sous licence Creative Commons BY-NC-SA 4.0.
Copyright (c) 2024-aujourd'hui, Charles-Henri Arnould/BECKREL (charnould@pierre-ia.org) et les contributeurs.
