PIERRE – L'IA open source du mouvement HLM

Important

PIERRE est actuellement en version 0.17.x (consulter les releases) avec une qualité de base de connaissances estimée à 10 %. Par ailleurs, la documentation ci-dessous est en cours de rédaction. En cas de difficultés, créer une issue ou envoyer un email à [email protected].

PIERRE ne connait pas les spécificités des bailleurs (ex : taille des parcs, coordonnées des agences, procédures internes, etc.). Ces éléments peuvent néanmoins lui être « enseignés en deux clics ».

PIERRE : kézako ?

PIERRE est une intelligence artificielle (IA) open source, plurilingue et multicanale au service du mouvement HLM, de ses candidats, locataires et collaborateurs.

Plus concrètement, PIERRE c'est à la fois :

Un chatbot (ou mieux : un resolution bot) open source — disponible sur le Web (démonstration) et par SMS — qui répond 24/7/365 à 100 % des 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 du chatbot et indispensable à la mise en oeuvre de toutes approches « Retrieval Augmented Generation » (RAG) via un LLM.

→ Télécharger une présentation de PIERRE (PDF · 2,7 Mo)

Sommaire

Contribuer à PIERRE
- Contribuer au code-source
- Contribuer à la base de connaissances
Fonctionnement + architecture de PIERRE
Comment déployer PIERRE ?
- Faire héberger PIERRE (le plus simple)
- Héberger PIERRE (self-hosting)
Modifier et paramétrer PIERRE (self-hosting)
Apprendre à PIERRE des connaissances (self-hosting)
- Connaissances « communautaires » vs. « propriétaires »
- Comment faire apprendre des connaissances à PIERRE ?
License

Contribuer à PIERRE

Contribuer au code-source

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.

Contribuer à la base de connaissances

Contribuer à « améliorer la base de connaissances » : kézako ?

Lorsque l'on comprend comment fonctionne PIERRE, on comprend le rôle de la base de connaissances : elle est le coeur de l'intelligence de PIERRE et n'est — ni plus ni moins — que des fichiers-textes 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, et c'est tout l'enjeu que de l'améliorer, car c'est ce document qu'utilise PIERRE pour répondre aux questions sur ces sujets.

« Améliorer la base de connaissances », ce n'est donc que cela : (1) améliorer le contenu des fichiers-textes existants et (2) créer des fichiers-textes sur les thématiques manquantes.

Thématiques couvertes par la base de connaissances

La base de connaissances — en co-construction avec les bailleurs — couvre plusieurs thématiques :

global : les connaissances génériques qui s'appliquent uniformément sur tout le territoire (ex : comment gérer un trouble du voisinage ? qu'est-ce que les charges locatives ?).
local : les connaissances spécifiques à un territoire donné (ex : les associations d'hébergement d'urgence dans l'Ain, les structures d'aide dans le cadre de violences conjugales dans l'Eure).
org : les connaissances relatives à un organisme HLM en particulier (ex : qu'est-ce que Grand Dijon Habitat et quelles sont les coordonnées du service-client et des agences ?).
wikipedia : des connaissances importées de Wikipédia (ex : l'histoire du logement social).

Concrétement comment contribuer ?

Consulter la base de connaissances
Et si vous identifiez un manque, une imprécision ou une erreur :
Option A : Adresser un email à [email protected]
Option B : Créer une issue sur GitHub (pour les connaisseurs)

Au fur et à mesure de l'amélioration de la base de connaissances, la pertinence de PIERRE s'améliorera automatiquement et profitera à l'ensemble du mouvement HLM.

Fonctionnement + architecture de PIERRE

Comment fonctionne PIERRE ?

Un utilisateur pose une question à PIERRE via le web ou par SMS.
Une première passe de LLM/IA augmente la requête initiale.
Une deuxième passe de LLM/IA s'assure de la validité et sécurité de la requête initiale (ex : impossible d'insulter PIERRE ou d'adresser une question sans lien avec le logement).
La requête validée et augmentée est vectorisée, puis est utilisée pour interroger les bases de connaissances de PIERRE.
Les résultats retournés sont rerankés par un LLM/IA pour ne conserver que les plus pertinents.
Une dernière passe de LLM/IA génère une réponse sur la base des résultats retournés, réordonnancés puis rerankés des bases de connaissances.
La réponse est retournée quelques secondes plus tard à l'utilisateur via le web ou par SMS.
La conversation se poursuit jusqu'à satisfaction de l'utilisateur (goto 1).

Note

On comprend ici aisément le rôle des bases de connaissances : elles sont le coeur de l'intelligence de PIERRE ou de toute IA mettant en oeuvre une approche « Retrieval Augmented Generation » (RAG) via un LLM. Ces bases de connaissances sont améliorables et personnalisables ; et c'est simplissime !

Modèles de langage (ou LLM)

PIERRE utilise — à ce jour — plusieurs (passes de) LLM dans cet ordre successif :

Un modèle de génération d'objets qui transforme la requête de l'utilisateur en une « requête augmentée » (en utilisant des techniques de type HyDE ou Stepback). Tous les LLM ne peuvent générer de tels objets. De fait, le modèle utilisé à ce jour ne peut pas être modifié (gpt-4o-mini-2024-07-18). En conséquence, il est indispensable — lorsque l'on auto-héberge PIERRE — de disposer d'une clef d'API OpenAI.
Un modèle de génération d'embeddings qui transforme la « requête augmentée » en vecteurs de valeurs numériques qui sont ensuite utilisés pour rechercher les éléments de réponse les plus pertinents dans la base de connaissances de PIERRE. À ce jour, ce modèle ne peut pas être modifié (text-embedding-3-large). En conséquence, il est indispensable — lorsque l'on auto-héberge PIERRE — de disposer d'une clef d'API OpenAI.
À nouveau, un modèle de génération d'objets programmé en reranker qui classifie les résulats retournés par les bases de connaissances pour ne conserver que les élémennts les plus pertinents en regard de la question posée par l'utilisateur. Tous les LLM ne peuvent générer de tels objets. De fait, le modèle utilisé à ce jour ne peut pas être modifié (gpt-4o-mini-2024-07-18). En conséquence, il est indispensable — lorsque l'on auto-héberge PIERRE — de disposer d'une clef d'API OpenAI.
Un modèle de génération de textes qui génére les réponses textuelles aux utilisateurs. Lorsque l'on auto-héberge PIERRE — et sur le principe du « Bring Your Own LLM Key/Model » (BYOK) — il est possible de choisir le modèle utilisé (Mistral, Anthropic, Cohere...) et ce, en modifiant le fichier de configuation (cf. infra). Par défaut, PIERRE utilise gpt-4o-mini-2024-07-18 d'OpenAI.

L'universel SMS pour les échanges de « premier niveau »

Note

PIERRE propose à ce jour deux modalités d'interaction : Text-to-Text via le Web (démonstration) ou par SMS, et Voice-to-Text sur smartphone. À court terme, PIERRE va également investiguer une interaction Voice-to-Voice.

En réponse au nouveau plan de numérotation mis en place par l'ARCEP en 2023 (avec l'introduction des numéros commerciaux 09 3x xx xx xx) et pour proposer aux entreprises une solution universelle pour converser avec leurs clients, les opérateurs téléphoniques français ont lançé en 2023 (déploiement opérationnel en octobre 2024) une nouvelle offre de SMS conversationnel à destination des entreprises (dite Time2chat) qui (i) permet de s'affranchir des plateformes propriétaires (WhatsApp, Telegram, Messenger, etc.) utilisées au maximum par 50 % de la population française et (ii) une instantanéité et délivrabilité exceptionnelles (100 % des téléphones disposent nativement du SMS).

Principales caratéristiques de Time2chat (en savoir plus via l'ARCEP ou via Orange) :

Une conversation est une série de SMS entre une entreprise et un utilisateur.
Elle dure maximum 24h et le nombre de SMS échangés durant cette période est illimité.
Elle peut être initiée par l'entreprise ou l’utilisateur.

Technologies + Services

Language: Typescript/Javascript
Framework: Hono (with Bun runtime)
Database + Vectorstore: SQLite3 (extended with sqlite-vec)
Deployment: Kamal (with Docker)
LLM: « Bring Your Own LLM Key/Model » (BYOK)
SMS: Time2Chat via CM

Les coûts associés à l'usage de PIERRE

Déployer PIERRE sur un serveur génére des coûts (minimes) :

La location d'un serveur (par exemple CX22 d'Hetzner) : env. €10 par mois.
L'usage d'un LLM via une API, soit (sur la base d'OpenAI utilisée par défaut) :
– Génération de vecteurs : $0.13 / MTokens avec text-embedding-3-large
– Génération de textes : $0,15 (input) et $0,60 (output) / MTokens avec gpt-4o-mini
(Optionnellement) Les conversations SMS :
– Location d'un numéro de téléphone : €10 par mois
– Envoi de SMS : €0.09 par conversation (= SMS illimités par fenêtre de 24h)

Comment déployer PIERRE ?

Faire héberger PIERRE (le plus simple)

Avantages :

Ne jamais avoir à se soucier de serveurs et d'API.
Bénéficier 24/7/365 de la dernière version.

Adresser un email à [email protected].

Héberger PIERRE (self-hosting)

Faire fonctionner PIERRE en local

Les instructions ci-après sont pour Windows+WSL (sous-système Windows pour Linux).

Installer WSL et vérifier sa bonne installation (instructions).
Installer Bun (≥ 1.1.40) et vérifier sa bonne installation (instructions).
Forker/cloner le présent dépôt.
Lancer bun install dans votre terminal pour installer les dépendances.
Renommer le fichier .env.example en .env.production et compléter le.
Lancer PIERRE avec bun dev.
Et voilà : PIERRE est accessible à http://localhost:3000 et répond à vos questions !

Déployer pour la première fois PIERRE sur un serveur de production

Pour déployer PIERRE sur un serveur, il est indispensable d'être parvenu à le faire fonctionner en local.

Installer Docker Desktop et le lancer (instructions). Docker gérera la conteneurisation.
Lancer gem install kamal pour installer Kamal (≥2.4.0) qui gérera le déploiement (instructions).
Disposer d'un compte GitHub et générer une clef. GitHub sera le registre de conteneurs lors du déploiement.
Disposer d'un VPS (par exemple CX22 d'Hetzner) et être en capacité de s'y connecter via ssh (avec une clef ou mot de passe).
Finaliser les modifications du fichier .env.production que vous avez créé précédemment.
Saississez dans votre terminal dotenvx run -f .env.production -- kamal setup et patientez quelques minutes (dotenvx run -f .env.production -- est indispensable pour interpoler les variables d'environnement).
Et voilà, PIERRE est accessible à l'adresse IP de votre serveur.
Étapes suivantes (optionnelles et décrites ci-dessous) :
– Placer votre IP derrière un proxy pour le servir via un domaine
– Déployer PIERRE sur un second serveur de tests
– Personnaliser PIERRE
– Faire fonctionner PIERRE par SMS
– Afficher PIERRE sur votre site internet ou extranet-locataire

Redéployer PIERRE sur un serveur de production

PIERRE — et notamment sa base de connaissances — évolue régulièrement et suit la convention semver. Pour le mettre à jour :

Consulter les releases pour connaitre les modifications et les éventuels breaking changes.
Mettez à jour votre fork/clone.
Saississez bun test:config pour vous assurer que config.ts est correctement paramétré.
Saississez dotenvx run -f .env.production -- kamal deploy dans votre terminal (ou le raccourci bun production:deploy).

Déployer et redéployer PIERRE sur un serveur de tests

Pour tester en conditions réelles les mises à jour et nouveautés de PIERRE :

Disposer d'un second VPS et être en capacité de s'y connecter via ssh (avec une clef ou mot de passe).
Dupliquer .env.production en .env.staging et modifier le (a priori uniquement l'IP).
Lancer dotenvx run -f .env.staging -- kamal setup pour déployer la première fois.
Lancer dotenvx run -f .env.staging -- kamal deploy pour redéployer (ou le raccourci bun staging:deploy).

Note

Il est très fortement recommandé que les environnements de production et staging aient le même système d'exploitation (Ubuntu, Debian, etc.) et la même architecture de processeur (x86).

Modifier et paramétrer PIERRE (self-hosting)

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, et le scénario en_agence.

Modifier l'interface du chatbot

Dans le répertoire ./assets, dupliquer le dossier pierre-ia.org et le nommer pierre-habitat.fr. Les consignes suivantes s'appliquent à ce nouveau répertoire.
Supprimer les sous-répertoires /dist, /fonts, /scripts, /tailwind.
Créer une icône system.svg et remplacer la précédente. Cette icône est celle qui apparait dans l'interface du chatbot (au dessus de « Bonjour 👋 »).
Générer les icônes qui permettront d'ajouter votre chatbot sur l'écran d'accueil des smartphones de vos utilisateurs et remplacer celles dans le dossier icons. Conservez la structure du répertoire et le nommage des fichiers (automatique).
Modifier config.ts :
– id avec pierre-habitat.fr
– context.default.greeting qui est le message d'accueil de votre chatbot
– context.default.examples qui sont les exemples proposés après votre message d'accueil
– context.default.disclaimer qui est le message s'affichant après chaque réponse générée (ex : Une IA peut se tromper, vérifier les informations.)
– context.en_agence pour créer des scénarios/personnalités supplémentaires.
Modifier dans manifest.json :
– short_name par le nom souhaité de votre chatbot
– start_url par https://180.81.82.83/?config=pierre-habitat.fr&context=en_agence
Et voilà, votre chabot personnalisé est disponible à :
– http://localhost:3000/?config=pierre-habitat.fr
– http://localhost:3000/?config=pierre-habitat.fr&context=en_agence

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 test:config.

Modifier la personnalité du chatbot

Si vous avez à ce stade personnalisé visuellement votre chatbot (cf. supra), et bien qu'il affiche des icônes et les salutations de votre organisme, il ne se présente PAS encore comme le chatbot de votre organisme (essayez en lui demandant qui il est !).

Pour modifier cela, modifier dans le fichier config.ts :

context.default.persona qui définit l'identité et la personnalité du chatbot
context.default.audience qui définit le contexte dans lequel le chabot doit considérer son interlocuteur

Note

Pour faciliter la lecture et manipulation du fichier config.ts dans VSCode, ou plus généralement activer le word wrap : utilisez le raccourci Alt + z (Windows) ou ⌥ + z (Mac).

Modifier le modèle de langage utilisé

Important

Il est très fortement recommandé de disposer d'une version fonctionnelle de PIERRE en local avant de changer le modèle de langage (LLM) et ce, pour être en mesure d'effectuer des tests. En effet, modifier le modèle de langage peut avoir quelques effets sur la qualité et vitesse des réponses de PIERRE.

Comment modifier le modèle de langage ?

Pour modifier le modèle de génération de textes, il suffit de :

Modifier model dans votre fichier config.ts par la valeur souhaitée
Renseigner la clef d'API correspondante dans les variables d'environnement (.env.production). Attention, il faut a minima et impérativement disposer d'une clef OpenAI pour la génération d'objets et d'embeddings.

Quels modèles est-il possible d'utiliser ?

PIERRE permet – à ce stade – l'usage des principaux modèles de langage, à savoir : Anthropic, Cohere, Google, Mistral et OpenAI.

Installer PIERRE sur votre site web

Important

Pour installer PIERRE sur votre site internet, il est indispensable de disposer d'une version fonctionnelle de PIERRE installée sur un VPS.

Via une fenêtre modale

<script
  crossorigin="anonymous"
  src="http://180.81.82.83/assets/pierre-ia.org/dist/js/widget.js"
></script>
<p
  id="pierre-ia"
  data-url="http://180.81.82.83"
  data-configuration="pierre-habitat.fr"
  data-context="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.83 dans l'URL du script le domaine/IP du serveur où le script est accessible
data-url : le domaine/IP (sans slash de fin) du serveur où PIERRE est accessible
data-context : le scénario (ou la personnalité) qu'utilise PIERRE
data-configuration : le nom de domaine de votre organisme qui est également le nom du répertoire que vous avez créé plus tôt dans ./assets (cf. supra) ou pierre-ia.org pour la version par défaut.

Via une iframe

<iframe
  id="pierre"
  title="PIERRE - l'IA de Mouvement HLM"
  style="..."
  width="450"
  height="620"
  src="http://180.81.82.83/?config=pierre-ia.org&context=default"
>
</iframe>

avec :

style : le style CSS de l'iframe (libre à vous de le modifier)
src : l'URL d'accès à PIERRE (libre à vous de modifier config et context)

Paramétrer PIERRE pour l'utiliser par SMS

Obtenir un numéro de téléphone compatible
Paramétrer votre webhook
Modifier phone dans votre fichier config.ts avec votre numéro de téléphone

TODO/À FINALISER

Administrer PIERRE avec une interface graphique

Si vous hébergez PIERRE :

Rendez-vous à l'adresse https://180.81.82.83/a (à remplacer par votre domaine/IP).
Saisissez (la première fois) [email protected] et le mot de passe contenu dans la variable d'environnement AUTH_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, et utiliser « l'aide de camp ».

Apprendre à PIERRE des connaissances (self-hosting)

Connaissances « communautaires » vs. « propriétaires »

PIERRE dispose — en fait — de deux bases de connaissances :

Une base (dite community) qui correspond aux connaissances partagées universellement au sein du mouvemement HLM (ex : comment déposer une demande de logement social, qu'est ce que le SLS, les associations d'hébergement d'urgence dans le Vaucluse, etc.). Cette base community correspond aux répertoires global, local, org et wikipedia du dossier knowledge. NE PAS MODIFIER CES FICHIERS.
Une base (dite proprietary) qui correspond aux connaissances créées par un organisme HLM hébergeant sa propre version de PIERRE et qu'il ne souhaite pas partager avec community (ex : des procédures internes).

Plus précisément, cette base proprietary contient deux types de données :

Des données privées accessibles uniquement aux collaborateurs de l'organisme (ex : les processus et procédures internes).
Des données publiques accessibles aux candidats et locataires HLM, ainsi qu'aux collaborateurs (ex : l'histoire de l'organisme).

Important

Il est généralement plus pertinent de contribuer à la base community que d'utiliser les données publiques de proprietary.

Comment faire apprendre des connaissances à PIERRE ?

Supprimer du dossier knowledge/proprietary tous les fichiers et répertoires à l'exception de _metadata.example.xlsx.
Dupliquer _metadata.example.xlsx et le renommer _metadata.xlsx.
Déposer vos fichiers .docx (Word), .xlsx (Excel) ou .md (Markdown) dans ce même répertoire. Vous êtes libre de créer une arborescence selon vos besoins. Les fichiers avec d'autres extensions que celles précédemment citées ne seront pas pris en compte.
Compléter le fichier _metadata.xlsx. C'est notamment dans ce fichier que vous pourrez arbitrer si les connaissances doivent être privées ou publiques. Uniquement les fichiers référencés dans _metadata.xlsx seront pris en compte. Attention, un fichier référencé dans _metadata.xlsx et qui n'existe pas à l'emplacement indiqué générera une erreur.
Lancer bun generate --proprietary pour lancer la (re)construction automatique de votre base de connaissances proprietary et patienter quelques minutes (il est impératif que vos variables d'environnement contiennent une clef d'API OpenAI).
Indispensable : Configurer vos context dans config.ts de manière à permettre l'utilisation des connaissances proprietary et protéger votre context s'il utilise des données privées/private.
Effectuer un commit des modifications, tester en local et redéployer.

Tip

Dans un futur proche (objectif : février 2025), vous pourrez enseigner à PIERRE des connaissances proprietary sans nécessiter de redéploiement et ce, simplement en associant un SharePoint à PIERRE (en cours de réflexion).

En cas de difficultés pour « enseigner » à PIERRE vos propres données, créer une issue sur GitHub ou adresser un email à [email protected].

License

Le code-source du présent dépôt est sous license GNU Affero General Public License Version 3. La base de connaissances (dossier /knowledge) est sous license Creative Commons BY-NC-SA 4.0.

Name		Name	Last commit message	Last commit date
Latest commit History 180 Commits
.github		.github
.kamal		.kamal
assets		assets
config		config
controllers		controllers
docs		docs
knowledge		knowledge
tests		tests
utils		utils
views		views
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
README.md		README.md
app.ts		app.ts
bun.lock		bun.lock
package.json		package.json

License

charnould/pierre

Folders and files

Latest commit

History

Repository files navigation

PIERRE – L'IA open source du mouvement HLM

PIERRE : kézako ?

Sommaire

Contribuer à PIERRE

Contribuer au code-source

Contribuer à la base de connaissances

Contribuer à « améliorer la base de connaissances » : kézako ?

Thématiques couvertes par la base de connaissances

Concrétement comment contribuer ?

Fonctionnement + architecture de PIERRE

Comment fonctionne PIERRE ?

Modèles de langage (ou LLM)

L'universel SMS pour les échanges de « premier niveau »

Technologies + Services

Les coûts associés à l'usage de PIERRE

Comment déployer PIERRE ?

Faire héberger PIERRE (le plus simple)

Héberger PIERRE (self-hosting)

Faire fonctionner PIERRE en local

Déployer pour la première fois PIERRE sur un serveur de production

Redéployer PIERRE sur un serveur de production

Déployer et redéployer PIERRE sur un serveur de tests

Modifier et paramétrer PIERRE (self-hosting)

Modifier l'interface du chatbot

Modifier la personnalité du chatbot

Modifier le modèle de langage utilisé

Comment modifier le modèle de langage ?

Quels modèles est-il possible d'utiliser ?

Installer PIERRE sur votre site web

Via une fenêtre modale

Via une iframe

Paramétrer PIERRE pour l'utiliser par SMS

Administrer PIERRE avec une interface graphique

Apprendre à PIERRE des connaissances (self-hosting)

Connaissances « communautaires » vs. « propriétaires »

Comment faire apprendre des connaissances à PIERRE ?

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 17

Languages