Tutoriel Semantica 2026 : déployer une mémoire d’agent

La documentation officielle de Semantica indique que Python 3.8 est le minimum pris en charge et recommande Python 3.11 ou une version ultérieure. (guide d’installation officiel) Ce point suffit à orienter votre méthode : pour un premier déploiement, utilisez un environnement virtuel propre et validez le cycle « installation → contrôle de santé → écriture → requête → redémarrage » avant d’ajouter une base de graphes externe, un magasin vectoriel ou un LLM.

Symptôme : vous avez installé Semantica, mais vous ne savez pas si le problème vient de Python, d’une dépendance, du stockage ou de votre modèle de données.
Solution la plus rapide : réduisez le test à quelques entités et relations, conservez les journaux, puis ajoutez chaque composant avancé après une vérification indépendante.

Ce tutoriel s’adresse aux développeurs Python qui installent Semantica pour la première fois, aux équipes qui souhaitent convertir des conversations ou des documents en Agent Memory, ainsi qu’aux ingénieurs de plateforme qui veulent reproduire le même déploiement sur plusieurs machines. Les exemples conviennent aussi aux projets audio, vidéo et design, dans lesquels une décision, un fichier source, une séquence de montage et une validation client doivent rester reliés.

Commencer par une preuve minimale

Votre premier objectif ne doit pas être un Knowledge Graph complet représentant toute l’entreprise. Il doit être suffisamment petit pour être vérifié manuellement, exporté, supprimé et recréé sans ambiguïté.

Prenez un cas de production vidéo :

• une entité projet_video ;
• une entité montage_final ;
• une entité validation_client ;
• une relation indiquant que la validation concerne le montage ;
• une note expliquant pourquoi la version finale a été retenue.

La question de contrôle peut être formulée ainsi : « quelle décision concerne le montage final ? » Vous devez connaître la réponse avant de lancer le script. Si le résultat est incomplet, vous pourrez comparer séparément le texte d’origine, les entités extraites, les relations produites et les données restaurées après redémarrage.

La documentation officielle décrit Semantica comme une couche pouvant s’insérer sous un LLM, un magasin vectoriel ou un framework d’agent. (dépôt officiel et architecture du projet) Vous n’avez donc pas besoin de commencer par une clé d’API ou un service distant pour vérifier la construction d’un graphe. Cette séparation réduit le nombre de variables pendant le diagnostic.

Avant d’ouvrir le terminal, préparez :

• un dossier de projet dont vous contrôlez les droits d’écriture ;
• une version Python vérifiable ;
• un fichier d’entrée conservé dans data/ ;
• une question de validation à réponse connue ;
• un emplacement pour les journaux ;
• une procédure de retour à l’état initial.

Cette dernière condition est souvent négligée. Si vous ne pouvez pas supprimer le graphe, recréer l’environnement et rejouer le même échantillon, vous ne testez pas encore un déploiement reproductible.

Première étape : créer un environnement isolé

Placez-vous dans le dossier du projet, et non dans un répertoire global utilisé par plusieurs applications. Sous macOS ou Linux, exécutez :

mkdir semantica-demo
cd semantica-demo

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install semantica

Sous Windows, utilisez :

python -m venv .venv
.venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install semantica

La procédure officielle recommande l’environnement virtuel et présente également une installation avec Conda. (procédure officielle d’installation) L’appel python -m pip est préférable à une commande pip isolée, car il réduit le risque d’installer le paquet dans un interpréteur différent de celui qui exécutera votre script.

N’ajoutez pas immédiatement tous les extras. Le paquet de base vous permet d’abord de vérifier l’import, la version et les commandes disponibles. Les modules de visualisation, de GPU, de fournisseurs LLM, d’Ollama ou de services distants doivent intervenir après le test minimal, et non avant.

Comment installer et lancer Semantica ?
Commencez par python -m pip install semantica dans un environnement virtuel activé. Lancez ensuite une vérification d’import et l’aide de la ligne de commande. Si ces deux contrôles échouent, il est inutile de déboguer votre modèle de données : le problème se trouve encore dans l’environnement.

Deuxième étape : contrôler la version et les commandes

Exécutez les commandes suivantes :

python --version
python -m pip --version
python -c "import semantica; print(semantica.__version__)"
python -m pip show semantica
semantica --help

La page publiée sur l’index Python consultée le 11 août 2026 indique une version 0.6.0, publiée le 21 juillet 2026. (fiche officielle du paquet) La version effectivement chargée par votre environnement reste prioritaire, car un verrouillage de dépendances, un miroir interne ou une installation locale peuvent modifier le résultat.

Les points d’entrée documentés sont les suivants :

La documentation CLI précise que l’explorateur n’est pas inclus dans l’installation de base. (référence officielle de la CLI) Si semantica est introuvable alors que l’import Python fonctionne, réactivez .venv, puis recherchez l’emplacement du paquet :

python -m pip show -f semantica

Ne réinstallez pas plusieurs fois sans enregistrer le message d’erreur. Le chemin d’exécution, l’interpréteur actif et le répertoire d’installation donnent souvent une réponse plus précise qu’une nouvelle tentative identique.

Troisième étape : écrire quelques entités et relations

Pour un premier Knowledge Graph, utilisez un texte court et contrôlé. La documentation présente notamment NERExtractor, RelationExtractor et GraphBuilder pour extraire des entités, trouver des relations et construire le graphe. (exemple officiel de démarrage)

Créez un fichier demo_graph.py :

from semantica.semantic_extract import NERExtractor, RelationExtractor
from semantica.kg import GraphBuilder

text = (
    "Le projet Studio Lumière utilise le montage Final Cut. "
    "Claire valide le montage Final Cut pour la livraison client."
)

ner = NERExtractor(method="pattern")
entities = ner.extract(text)

relation_extractor = RelationExtractor(method="rule")
relationships = relation_extractor.extract(
    text,
    entities=entities,
)

builder = GraphBuilder(merge_entities=True)
graph = builder.build({
    "entities": entities,
    "relationships": relationships,
})

print("Entités :", len(graph["entities"]))
print("Relations :", len(graph["relationships"]))
print(graph["entities"])
print(graph["relationships"])

Lancez-le depuis le même terminal :

python demo_graph.py | tee run-01.log

Le paramètre merge_entities=True peut rapprocher plusieurs références qui désignent le même objet. Il ne constitue toutefois pas une preuve automatique que la fusion est correcte. Dans un projet audio, deux noms proches peuvent correspondre à deux pistes distinctes ; dans un projet de design, deux variantes d’un même fichier peuvent avoir des statuts différents. Conservez donc le texte source et la sortie complète avant toute normalisation.

Pour rendre vos essais exploitables, enregistrez également :

• le nom du fichier source ;
• l’identifiant de la séquence ou du document ;
• le statut de validation ;
• l’heure d’import ;
• la version de Semantica ;
• le résultat de la requête de contrôle.

Ne déduisez pas automatiquement un timecode ou une provenance précise à partir d’un simple texte. Si vous devez retrouver une phrase dans une piste audio ou une timeline vidéo, votre pipeline d’ingestion doit fournir les métadonnées nécessaires.

Quatrième étape : valider le graphe avec une requête fermée

Un fichier visualisé correctement ne signifie pas que les relations sont exactes. La visualisation est utile pour repérer une structure inhabituelle, mais l’acceptation doit se faire à partir d’une comparaison avec les données sources.

Comment créer le premier graphe de connaissances avec Semantica ?
Vous pouvez commencer par extraire les entités d’un texte court, produire les relations, puis transmettre ces structures à GraphBuilder. Lorsque votre cas d’usage porte sur des fichiers, des pages web ou des formats structurés, ajoutez l’ingestion après cette première validation, car une erreur de collecte peut être confondue avec une erreur de raisonnement.

Pour tester la navigation dans un contexte plus structuré, la documentation de contexte présente ContextGraph, avec des opérations d’ajout de nœuds, d’ajout de relations et de recherche de voisins. (référence officielle du contexte)

from semantica.context import ContextGraph

graph = ContextGraph()

graph.add_node(
    "studio_lumiere",
    "Project",
    name="Studio Lumière",
)

graph.add_node(
    "final_cut",
    "Asset",
    name="Montage Final Cut",
)

graph.add_edge(
    "studio_lumiere",
    "final_cut",
    edge_type="uses",
)

print(graph.get_neighbors("studio_lumiere", hops=1))

Si votre environnement ne reconnaît pas exactement une méthode trouvée dans un ancien tutoriel, revenez à la référence correspondant à votre version. Les billets de communauté peuvent conserver des noms de modules ou des signatures qui ne correspondent plus au paquet installé. Une erreur de ce type doit être traitée par comparaison avec le dépôt, la documentation et les messages du programme, non par une modification improvisée du code.

Cinquième étape : arrêter, redémarrer et contrôler la persistance

Les données de Semantica sont-elles conservées après un redémarrage ?
Cela dépend du composant utilisé et de la manière dont vous avez sauvegardé l’état. Un graphe créé uniquement en mémoire ne doit pas être considéré comme une mémoire persistante. Le module de contexte documente la sauvegarde et la restauration de l’état, tandis que les flux d’export peuvent produire plusieurs formats selon le scénario. (documentation officielle du contexte)

Commencez par conserver une sortie avant l’arrêt :

mkdir -p artifacts
python demo_graph.py > artifacts/run-before-restart.log

Ensuite :

1. vérifiez que le fichier source et le journal existent ;
2. arrêtez complètement le processus Python ;
3. désactivez l’environnement virtuel ;
4. fermez puis rouvrez le terminal ;
5. réactivez .venv ;
6. rechargez l’état avec le mécanisme prévu par votre version ;
7. relancez la même requête ;
8. comparez le résultat avec run-before-restart.log.

Si vous utilisez le serveur HTTP, démarrez-le dans un terminal :

semantica-server

Dans un second terminal, exécutez :

curl http://localhost:8000/health
curl http://localhost:8000/api/info

La CLI documente une route /health et une route /api/info. Le contrôle de santé confirme que le service répond ; il ne confirme pas que les données antérieures ont été restaurées. Cette distinction doit apparaître dans votre procédure d’acceptation.

Répétez ensuite l’import du même échantillon. Observez trois résultats possibles :

• les entités restent uniques : le comportement est idempotent pour ce cas ;
• les entités sont dupliquées : les identifiants ou la stratégie de fusion doivent être revus ;
• les propriétés sont écrasées : vous devez définir une règle de conflit et de provenance.

Cette étape est indispensable pour un système d’Agent Memory. Une conversation rejouée après chaque redémarrage peut produire des souvenirs identiques, des décisions contradictoires ou des relations qui semblent valides mais proviennent d’une version obsolète du document.

Sixième étape : isoler les causes d’un échec d’installation

Que vérifier lorsque l’installation échoue ?
Commencez par la version Python, le chemin de pip, les droits d’écriture et l’import du paquet. La documentation recommande de mettre à jour les outils de construction et de séparer le paquet central des extras. (procédure de dépannage officielle)

Exécutez :

python --version
python -m pip --version
python -m pip install --upgrade pip
python -m pip install build wheel
python -m pip install --upgrade semantica
python -c "import semantica; print(semantica.__version__)"

Pour une erreur d’import :

python -m pip show semantica
python -m pip list

Si un extra provoque l’échec, revenez au paquet minimal :

python -m pip uninstall semantica
python -m pip install semantica

Ajoutez ensuite une seule capacité :

python -m pip install "semantica[explorer]"

Les problèmes liés au GPU, à PyTorch ou à des bibliothèques natives doivent rester séparés du test de base. Une installation CPU réussie ne prouve pas que la variante GPU est correcte ; inversement, un échec GPU ne signifie pas que la construction du graphe minimal est impossible.

• Avantage : chaque erreur est associée à une modification identifiable.
• Inconvénient : la préparation finale demandera davantage d’étapes documentées.
• Risque évité : installer toutes les extensions avant de savoir si l’import central fonctionne.
• Méthode recommandée : conserver un journal après chaque changement et pouvoir revenir au dernier état validé.

Septième étape : ajouter les composants externes par ordre de risque

Comment connecter Semantica à une base de graphes externe ?
Commencez par exporter un petit graphe local, conservez ce fichier comme point de retour, puis configurez le connecteur ou le backend décrit pour votre version. Le dépôt officiel présente une architecture extensible pour les graphes, la recherche vectorielle et les fournisseurs de modèles, mais le nom précis du module et ses paramètres doivent être vérifiés dans la documentation actuelle. (architecture officielle du projet)

Suivez cet ordre :

1. exportez le graphe minimal ;
2. sauvegardez l’export dans artifacts/ ;
3. démarrez le backend externe séparément ;
4. testez un seul nœud et une seule relation ;
5. exécutez la même question qu’en local ;
6. comparez le résultat et la provenance ;
7. augmentez le volume seulement après cette comparaison.

Ajoutez ensuite le magasin vectoriel, le LLM, le serveur MCP ou l’interface REST, mais pas plusieurs couches à la fois. Si le résultat change après l’ajout d’un modèle, vous devez pouvoir déterminer si le changement vient de l’extraction, de la recherche, du graphe ou de la génération.

Avant toute extension, utilisez cette liste de contrôle :

• [ ] L’environnement virtuel est activé.
• [ ] La version Python et celle de Semantica sont enregistrées.
• [ ] import semantica fonctionne.
• [ ] Les commandes disponibles ont été vérifiées avec --help.
• [ ] Le texte source est conservé.
• [ ] Les entités et relations sont journalisées.
• [ ] Une question fermée donne une réponse vérifiable.
• [ ] Le processus a été arrêté puis relancé.
• [ ] Le même échantillon a été importé une seconde fois.
• [ ] Le comportement de déduplication ou de conflit est noté.
• [ ] Un export local est conservé avant la connexion externe.
• [ ] Chaque nouvelle dépendance possède son propre test de retour arrière.

Ce que vous pouvez reporter après la première semaine

Une première version stable doit d’abord garantir des identifiants cohérents, une provenance exploitable, une règle de fusion compréhensible, une sauvegarde récupérable et une procédure de reprise documentée. Le LLM peut améliorer l’extraction de relations ambiguës, mais il introduit également une nouvelle source de variabilité. La recherche vectorielle peut améliorer la récupération de passages proches, mais elle ne remplace pas une relation explicite lorsque vous devez justifier une décision.

Repoussez donc les éléments suivants jusqu’à la validation du flux local :

• fournisseur LLM ;
• magasin vectoriel externe ;
• base de graphes distante ;
• explorateur graphique ;
• serveur MCP ;
• ingestion de plusieurs sources ;
• suppression automatique ;
• synchronisation permanente avec des conversations.

Cette progression facilite également la mesure. Un temps de réponse n’est interprétable que si vous connaissez le backend actif, la méthode d’extraction, la version du paquet et les dépendances chargées. Pour préparer un protocole cohérent, consultez notre guide sur la méthode de test de performance de Semantica. Pour les choix de structure entre faits, décisions, conversations et sources, vous pouvez ensuite lire notre dossier consacré à la conception d’une architecture Agent Memory.

Quand utiliser un Mac réinitialisable pour vos essais

Votre ordinateur actuel convient si le prototype reste isolé, si vous contrôlez déjà votre environnement Python et si vous n’avez pas besoin de reproduire plusieurs variantes d’installation. Il devient moins pratique lorsque les dépendances natives s’accumulent, que vous devez comparer une installation minimale avec une installation complète, ou que plusieurs projets modifient les mêmes chemins et caches.

Dans cette situation, trois limites apparaissent rapidement : l’environnement local se retrouve contaminé par d’autres essais, la réinitialisation prend du temps, et la comparaison entre deux configurations devient moins fiable lorsque les journaux et fichiers temporaires restent dispersés. Macstripe peut vous fournir un Mac réinitialisable pour conserver une image propre, tester séparément le paquet central et les extensions, puis recommencer la procédure sans modifier votre machine principale.

Cette solution n’est pas adaptée à toutes les charges. Un service durable et fortement sollicité, un besoin d’accès physique permanent ou une exploitation qui exige un stockage maîtrisé peuvent justifier un Mac acheté ou une infrastructure dédiée. En revanche, pour une reproduction d’installation, une vérification de compatibilité ou une démonstration isolée, un environnement temporaire vous permet de rejouer le cycle complet « installation → santé → écriture → requête → redémarrage » avant de décider si Semantica mérite un déploiement permanent.

Commencez donc par faire fonctionner le socle minimal, conservez vos journaux et vos données de test, puis choisissez seulement le composant externe qui répond à un besoin mesuré. C’est cette progression, plus que l’ajout immédiat de toutes les intégrations, qui transforme un premier essai de Semantica en procédure réellement reproductible.

Pour aller plus loin

• Mémoire d’agent et graphe de connaissances : comprendre les relations dans un dépôt
• Définir l’espace de travail et la persistance d’un agent avec un système de fichiers virtuel