TL;DR en langage simple
- KiroGraph crée un index sémantique local de votre code. (Voir https://github.com/davide-desio-eleva/kirograph)
- Un éditeur ou un agent interroge ce service local. Vous n'avez plus besoin d'envoyer tout le fichier à chaque recherche.
- Le projet met en avant « fewer tool calls, instant symbol lookups, 100% local ». Cela réduit les appels externes et la latence.
- POC (preuve de concept) simple : cloner le dépôt, indexer un repo, lancer le service sur localhost (par ex. http://127.0.0.1:8000) et tester des recherches de symboles.
Scénario concret : vous êtes développeur·se sur un dépôt de 30 000 lignes. Vous installez KiroGraph localement, indexez le dépôt, puis utilisez http://127.0.0.1:8000 pour retrouver rapidement où une fonction est définie et utilisée. Les recherches sont plus rapides et vous évitez d'envoyer le code à des services externes.
Explications simples avant les détails avancés
KiroGraph indexe le code et expose un petit serveur HTTP pour répondre aux requêtes de « lookup » (recherche de symboles ou usages). L'index reste sur votre machine. Cela améliore la confidentialité et réduit les appels vers des outils externes (et les coûts liés aux API). Les sections suivantes expliquent ce que construire, le temps nécessaire, comment l'installer pas à pas, des problèmes fréquents et des recommandations pour une petite équipe.
Ce que vous allez construire et pourquoi c'est utile
Vous allez livrer un POC (preuve de concept) simple et local :
- un index sémantique stocké sur disque pour un dépôt précis ;
- un serveur HTTP minimal qui répond aux requêtes de lookup de symboles/usages.
Pourquoi c'est utile (source : https://github.com/davide-desio-eleva/kirograph) :
- Recherches de symboles plus rapides. Moins de latence par requête.
- Moins d'appels à des outils externes. Moins de consommation de tokens et de coûts d'API.
- Données maintenues localement (100% local) pour mieux protéger la confidentialité du code.
Exemples de livrables concrets : un répertoire d'index sur disque (taille variable, par exemple ≈1 GB pour un petit dépôt), un service HTTP écoutant sur le port 8000, et une API de lookup simple. (Voir https://github.com/davide-desio-eleva/kirograph)
Avant de commencer (temps, cout, prerequis)
Prérequis minimum (vérifier le README du dépôt) : https://github.com/davide-desio-eleva/kirograph
- Accès en lecture au dépôt cible.
- Machine avec 4–16 GB de RAM selon la taille du dépôt.
- Espace disque libre : prévoir ≥1 GB pour un petit dépôt ; augmenter pour de plus grands dépôts.
Estimation temporelle pour un POC :
- Clonage et inspection : 5–10 minutes.
- Installation des dépendances : 5–30 minutes.
- Indexation initiale : entre 10 minutes et 2 heures selon la taille (10k / 30k / 100k lignes de code).
Coûts directs attendus : CPU/VM selon l'infrastructure. Exemple indicatif : ≈ $0.05–$1.00 / heure pour une VM légère. Ce sont des ordres de grandeur ; vérifiez vos tarifs locaux. (Référence : https://github.com/davide-desio-eleva/kirograph)
Checklist avant de démarrer :
- [ ] Cloner https://github.com/davide-desio-eleva/kirograph
- [ ] Préparer un répertoire pour l'index et vérifier les droits en écriture
- [ ] Lire le README upstream pour les commandes exactes et les flags
Installation et implementation pas a pas
- Cloner le dépôt et inspecter le README (https://github.com/davide-desio-eleva/kirograph)
git clone https://github.com/davide-desio-eleva/kirograph.git
cd kirograph
ls -la
- Créer un environnement isolé et installer (exemple)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
- Exemple de configuration minimale (CONFIRMER les clés dans le README upstream)
# config-poc.yaml
repo_path: ../mon-depot
index_path: ./local-index
mode: fast
exclude_patterns:
- node_modules/
- vendor/
- Lancer l'indexeur puis le serveur de lookup
- Exécutez la commande d'indexation décrite dans le README du dépôt. Mesurez le temps d'indexation initiale. Attendez la fin du processus.
- Démarrez le serveur de lookup local. Par défaut, testez sur 127.0.0.1:8000.
Remarque : les noms exacts des commandes et des flags sont à confirmer dans le README upstream : https://github.com/davide-desio-eleva/kirograph
-
Tester une recherche de symbole avec l'API HTTP locale. Mesurez la latence moyenne et le p95 (95e centile).
-
Itérer : ajuster exclude_patterns, mode (rapide vs complet), fréquence de reindex.
Problemes frequents et correctifs rapides
Indexeur échoue ou plante :
- Cause fréquente : dépendances manquantes ou runtime incompatible.
- Action : activer les logs verbeux et relire le README sur https://github.com/davide-desio-eleva/kirograph. Vérifier la version de Python et autres outils.
Index qui grossit trop :
- Action : ajouter patterns d'exclusion (node_modules/, vendor/, build/). Contrôler la croissance du disque.
Recherches lentes côté client :
- Vérifier que le service est bien local (127.0.0.1) ou sur une IP interne.
- Mesurer le p95. Si p95 > 300 ms, augmenter CPU/IO ou déplacer l'index sur un disque plus rapide.
Résultats obsolètes après changements dans le code :
- Si l'index n'est pas incrémental, planifier un reindex complet après un refactor massif. Idéal : reindex incrémental à chaque commit ou via webhook.
Checklist dépannage :
- [ ] Activer logs en mode verbeux
- [ ] Vérifier que le répertoire d'index est accessible et a les droits d'écriture
- [ ] Effectuer un test API local simple et vérifier la réponse
(Référence : https://github.com/davide-desio-eleva/kirograph)
Premier cas d'usage pour une petite equipe
Cible : fondateurs·trices solo et équipes de 1–4 personnes. Objectif : obtenir un POC utile rapidement.
Conseils concrets et actionnables :
-
Démarrer en local sur votre laptop ou sur une VM partagée. Indexez un dépôt représentatif et mesurez le temps d'indexation (par ex. 10–60 minutes pour un dépôt moyen). Utilisez 127.0.0.1:8000 pour le lookup. (Voir https://github.com/davide-desio-eleva/kirograph)
-
Prioriser 5–10 symboles critiques. Créez des scripts de test qui appellent le lookup et vérifient les réponses attendues. Cela valide rapidement l'utilité sans intégration complète.
-
Automatiser un reindex incrémental simple : lancer un job après chaque push ou toutes les 24 heures. Sur un dépôt moyen, un reindex incrémental devrait prendre moins d'une heure. Pour un refactor massif, planifier un reindex complet (10 minutes–2 heures selon la taille).
-
Pendant la phase POC, garder le service lié à localhost. Avant d'exposer le service en réseau, ajouter authentification et TLS (Transport Layer Security).
-
Mesurer trois métriques dès le départ : latence moyenne, p95, et taille de l'index. Collectez ces métriques pendant 7–14 jours pour décider d'un passage en production.
Petite checklist POC :
- [ ] Index initial sur un dépôt représentatif
- [ ] Tests automatiques pour 5–10 symboles critiques
- [ ] Job de reindex quotidien ou webhook
Référence et README : https://github.com/davide-desio-eleva/kirograph
Notes techniques (optionnel)
Table de comparaison rapide des modes hypothétiques (confirmer les noms exacts dans le README) :
| Mode (exemple) | Latence attendue | RAM / disque (est.) | |---:|---:|---:| | fast | faible (p95 < 300 ms) | 4 GB / 0.5–1 GB index | | full | plus complet, p95 > 300 ms | 8–16 GB / ≥1–5 GB index |
Exemple de configuration client (JSON) :
{
"lookup_url": "http://127.0.0.1:8000",
"auth_token": "REPLACE_WITH_TOKEN",
"fallback_to_full_context": false
}
Knobs à surveiller : taille des chunks, TTL (time-to-live) du cache, stratégie incrémentale vs complète, versioning des artefacts d'index. (Voir https://github.com/davide-desio-eleva/kirograph)
Que faire ensuite (checklist production)
- Lancer un POC sur un dépôt représentatif et collecter métriques pendant 7–14 jours. (Référence : https://github.com/davide-desio-eleva/kirograph)
- Définir des gates d'acceptation pour étendre l'usage dans l'organisation (ex. réduction de tokens ≥20%, p95 ≤300 ms, cible p95 <200 ms pour une bonne expérience).
- Planifier les ressources : VM dédiée si l'usage dépasse 5–10% du temps, jobs de reindex planifiés, versioning des index.
Hypotheses / inconnues
- Le dépôt expose un indexeur et un serveur de lookup, et affiche l'intention « fewer tool calls, instant symbol lookups, 100% local » (source : https://github.com/davide-desio-eleva/kirograph).
- Les noms exacts des commandes, flags et schémas de configuration sont à confirmer dans le README upstream.
- Les chiffres de dimensionnement fournis ici sont des points de départ : 4/8/16 GB RAM, index ≈1 GB pour petits dépôts, temps d'index 10 min–2 h selon la taille (10k / 30k / 100k LOC).
Risques / mitigations
- Risque : index incomplet ou obsolète. Mitigation : reindex incrémental, webhooks ou jobs quotidiens.
- Risque : p95 trop élevé (par ex. >300 ms). Mitigation : augmenter CPU/IO ou déplacer l'index sur une VM dédiée. Gate : p95 ≤300 ms pour canary ; viser <200 ms pour expérience fluide.
- Risque : fuite d'extraits indexés. Mitigation : binder le service à 127.0.0.1, exiger un token d'authentification et activer TLS avant exposition réseau.
Prochaines etapes
- Vérifier les commandes exactes d'installation, d'indexation et de démarrage dans le README : https://github.com/davide-desio-eleva/kirograph
- Lancer le POC, collecter latence moyenne, p95, taille d'index et mesurer les appels externes / tokens économisés pendant 7–14 jours.
- Si les gates sont franchis (ex. économie de tokens ≥20% et p95 ≤300 ms), planifier la mise en production : VM dédiée, monitoring, reindex planifié, procédures de rollback.
Méthodologie : ce guide synthétise l'intention publique du dépôt lié ci‑dessous. Confirmez toujours les commandes et options dans le README upstream avant exécution. (https://github.com/davide-desio-eleva/kirograph)