---
title: TechDocs GraphRAG
emoji: 🕸️
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: GraphRAG sur documentation technique (Neo4j + OpenAI)
---

# 🕸️ TechDocs GraphRAG

Assistant de documentation technique qui combine **recherche vectorielle** et **graphe de connaissances Neo4j**
pour répondre à des questions multi-hop avec des sources traçables.

Un RAG classique retrouve des passages similaires à la question. TechDocs GraphRAG extrait en plus les
entités et relations du corpus (`StateGraph —PERSISTS_WITH→ Checkpointer —ENABLES→ Persistence`) et
suit ces liens au moment de répondre.

## Fonctionnalités

- Ingestion Markdown, découpage par paragraphes avec chevauchement.
- Extraction LLM d'entités typées et de relations avec preuve textuelle.
- Déduplication des entités par clé canonique (`State Graph`, `state_graph` → `stategraph`).
- Neo4j Community embarqué dans le conteneur, corpus indexé automatiquement au démarrage.
- Neo4j comme store unique : documents, chunks, index vectoriel, index plein texte, graphe.
- Recherche hybride : chunks proches → entités mentionnées + entités citées dans la question → traversée multi-hop.
- Interface Streamlit : sous-graphe utilisé, relations, extraits, sources.
- Mode comparaison RAG vectoriel vs GraphRAG.

## Architecture

```mermaid
flowchart LR
    A[Markdown] --> B[ParagraphSplitter]
    B --> C[Embeddings OpenAI]
    B --> D[Extraction LLM]
    C --> E[(Neo4j<br/>index vectoriel)]
    D --> F[(Neo4j<br/>graphe d'entités)]
    Q[Question] --> R[HybridRetriever]
    E --> R
    F --> R
    R --> G[GraphRAGAssistant]
    G --> S[Réponse sourcée]
```

### Modèle de graphe

```text
(:Document)-[:HAS_CHUNK]->(:Chunk {embedding})-[:MENTIONS]->(:Entity:Component)
(:Entity)-[:USES | PERSISTS_WITH | DEPENDS_ON | ...]->(:Entity)
```

Chaque relation porte `evidence` et `documents`, ce qui rend chaque fait vérifiable.

## Structure

```text
├── app.py
├── Dockerfile
├── data/
├── src/techdocs_graphrag/
│   ├── config.py
│   ├── models.py
│   ├── ports.py
│   ├── ingestion.py
│   ├── llm.py
│   ├── prompts.py
│   ├── extraction.py
│   ├── graph_store.py
│   ├── indexing.py
│   ├── retrieval.py
│   ├── answering.py
│   ├── visualization.py
│   ├── services.py
│   └── cli.py
└── tests/
```

## Configuration

| Variable | Défaut | Rôle |
|---|---|---|
| `OPENAI_API_KEY` | requis | Clé OpenAI |
| `NEO4J_URI` | `bolt://localhost:7687` | Neo4j embarqué dans le conteneur |
| `NEO4J_USERNAME` | `neo4j` | Utilisateur Neo4j |
| `NEO4J_PASSWORD` | `techdocs-local-password` | Mot de passe Neo4j (secret conseillé) |
| `NEO4J_DATABASE` | `neo4j` | Base Neo4j |
| `CHAT_MODEL` | `gpt-4o-mini` | Modèle de génération |
| `EMBEDDING_MODEL` | `text-embedding-3-small` | Modèle d'embeddings |
| `GRAPH_MAX_HOPS` | `2` | Profondeur de traversée |
| `VECTOR_TOP_K` | `5` | Nombre de chunks récupérés |

## Lancer en local

```bash
cp .env.example .env
pip install -e ".[dev]"
pytest
techdocs-index data --reset
streamlit run app.py
```

## Feuille de route

- Jeu d'évaluation annoté (30 à 50 questions) et métriques de fidélité.
- Fusion d'entités par similarité d'embeddings.
- Résumés de communautés (approche Microsoft GraphRAG) pour les questions globales.
- API FastAPI `POST /ask`.