Un assistant pour les documents en deux fichiers Python : ChromaDB, LangChain et Claude
Transformer un PDF de 187 pages sur les normes dbt en un assistant recherchable grâce à un script d’ingestion, des embeddings locaux de Hugging Face, ChromaDB et des réponses de Claude basées sur les documents.
Sources: How I Built an AI Agent That Reads Company Docs in 5 Minutes
La documentation statique présente des inconvénients bien connus : les collègues sont constamment interrompus par les mêmes questions, les nouveaux arrivants ne parviennent pas à trouver les normes dbt, et tout le monde perd du temps à changer de contexte. La génération augmentée par recherche résout en grande partie ces problèmes en permettant de rechercher dans une base de connaissances en fonction du sens, et non seulement des mots-clés. Cependant, un schéma ne répond pas aux questions ; le code, lui, le fait. Voici donc un petit pipeline Python qui lit un document de l’entreprise, en crée une « intelligence » recherchable à partir de celui-ci et fournit à votre équipe un assistant conversationnel, en l’espace d’environ cinq minutes.
Tout cela se résume à deux fichiers :
ingest.pyest l’outil de création. Lancez-le une fois pour analyser la documentation et la stocker dans une base de données.ask.pyest l’assistant vocal. Lancez-le chaque fois que quelqu’un a une question, et il retournera une réponse basée sur la documentation.
Prérequis
Deux éléments sont essentiels en premier lieu : les bibliothèques et un endroit pour conserver la clé API.
Le fichier des exigences
Les bibliothèques gèrent le chargement des documents, leur segmentation en blocs, les embeddings, la recherche vectorielle ainsi que la communication avec Claude. Créez un fichier requirements.txt dans le dossier du projet contenant cette liste :
# Core LangChain — split into standalone packages since 0.2
langchain>=0.2.0
langchain-core>=0.2.0
langchain-community>=0.2.0 # PyPDFLoader still lives here
langchain-text-splitters>=0.2.0 # RecursiveCharacterTextSplitter moved here
langchain-anthropic>=0.1.0
langchain-huggingface>=0.0.3 # HuggingFaceEmbeddings moved here
langchain-chroma>=0.1.0 # Chroma moved here
# Vector store
chromadb>=0.5.0
# PDF loading
pypdf>=4.0.0
# Embeddings
sentence-transformers>=3.0.0
# Claude
anthropic>=0.28.0
# Env vars
python-dotenv>=1.0.0
Installez tout avec pip install -r requirements.txt.
Le fichier .env
Claude est la voix de l’agent, il est donc nécessaire d’avoir une clé API d’Anthropic. Ne mettez jamais de clés en code fixe dans les scripts Python, car envoier par erreur l’une d’elles sur GitHub représente un risque de sécurité majeur. Créez plutôt un fichier .env caché dans la racine du projet et ajoutez-y la clé :
ANTHROPIC_API_KEY=your_actual_api_key_here
La bibliothèque python-dotenv permet aux scripts de lire ce fichier automatiquement en arrière-plan.
Construction du système avec ingest.py
Un assistant doit lire le manuel avant de pouvoir répondre aux questions. ingest.py s’exécute une fois, ou à nouveau chaque fois que la documentation change. Sa tâche consiste à lire un PDF, à le diviser en parties faciles à comprendre, à transformer ces parties en vecteurs capables de représenter le sens, puis à les enregistrer dans une base de données. Le script complet :
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
# Step 1: Load the raw documentation
print("1. Loading the documentation...")
loader = PyPDFLoader("dbt_snowflake_documentation.pdf")
docs = loader.load()
# Step 2: Slice the text into chunks
print("2. Chunking the text...")
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000,
chunk_overlap=200
)
chunks = text_splitter.split_documents(docs)
# Step 3: Set up the Embedding Model (The Translator)
print("3. Setting up the embedding model...")
embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
# Step 4: Build and save the Vector Database
print("4. Building the ChromaDB brain...")
vector_db = Chroma.from_documents(
documents=chunks,
embedding=embeddings,
persist_directory="./chroma_db"
)
print("Done! The AI Brain is successfully built.")
Ce que fait le script, étape par étape :
- Chargement.
PyPDFLoaderlit le document, dans ce cas un PDF des normes dbt de 187 pages. - Découpage. Un livre entier ne peut pas être transmis à un modèle d’un seul coup, donc le texte est divisé en blocs de 1000 caractères, soit environ un paragraphe. Un
chunk_overlapde 200 caractères permet d’éviter que une règle s’étendant sur deux paragraphes ne soit coupée en deux. - Incorporation. Le modèle utilisé est
all-MiniLM-L6-v2, un petit modèle open source de Hugging Face. Il fonctionne sur la CPU locale, sans recourir à une API cloud payante, et transforme chaque bloc en un vecteur de 384 dimensions. - Stockage. Les vecteurs sont stockés dans ChromaDB, dans un dossier sur le disque à l’emplacement
./chroma_db.
Exécutez-le avec python ingest.py. Après quelques secondes, un nouveau dossier chroma_db apparaît dans le projet. Le document statique est désormais devenu un stockage codé et recherchable.
Donner une voix à ce système avec ask.py
La documentation est maintenant stockée de manière codée dans ./chroma_db. Ce qui manque, c’est un outil capable de prendre une question, de la rechercher et de répondre. C’est ask.py : exécutez-le chaque fois que quelqu’un a une question :
"""
ask.py — Interactive QA loop. Run this after ingest.py has finished.
Usage:
python ask.py
python ask.py --db ./my_chroma_db --k 6
"""
import os
import argparse
from dotenv import load_dotenv
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough, RunnableMap
load_dotenv()
# ── CLI args ──────────────────────────────────────────────────────────────────
parser = argparse.ArgumentParser(description="Ask questions against your embedded docs")
parser.add_argument("--db", default="./chroma_db")
parser.add_argument("--k", type=int, default=4)
parser.add_argument("--model", default="claude-sonnet-4-6")
args = parser.parse_args()
# ── Guards ────────────────────────────────────────────────────────────────────
if not os.path.exists(args.db):
print(f"\nERROR: ChromaDB not found at '{args.db}'")
print(" Run ingest.py first.\n")
exit(1)
if not os.getenv("ANTHROPIC_API_KEY"):
print("\nERROR: ANTHROPIC_API_KEY not found in .env file\n")
exit(1)
# ── 1. Embeddings (same model as ingest.py) ───────────────────────────────────
print("\n[1/3] Loading embedding model...")
embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/all-MiniLM-L6-v2",
model_kwargs={"device": "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
# ── 2. ChromaDB ───────────────────────────────────────────────────────────────
print(f"[2/3] Connecting to ChromaDB at: {args.db}")
vectorstore = Chroma(
persist_directory=args.db,
embedding_function=embeddings,
collection_name="dbt_docs",
)
doc_count = vectorstore._collection.count()
print(f" {doc_count} chunks loaded")
retriever = vectorstore.as_retriever(
search_type="similarity",
search_kwargs={"k": args.k},
)
# ── 3. Claude ─────────────────────────────────────────────────────────────────
print(f"[3/3] Loading {args.model}...")
llm = ChatAnthropic(
model=args.model,
temperature=0,
max_tokens=2048,
)
# ── Prompt ────────────────────────────────────────────────────────────────────
PROMPT = PromptTemplate.from_template("""You are a helpful assistant for a data engineering team.
Answer the question using ONLY the context provided below.
If the context does not contain enough information, say so clearly — do not make things up.
Be concise and practical. Use code examples when they are present in the context.
Context:
{context}
Question: {question}
Answer:""")
# ── LCEL chain (replaces RetrievalQA) ────────────────────────────────────────
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
chain = (
RunnableMap({
"context": retriever | format_docs,
"question": RunnablePassthrough(),
})
| PROMPT
| llm
| StrOutputParser()
)
# ── Chat loop ─────────────────────────────────────────────────────────────────
print("\n" + "="*55)
print(" dbt Documentation Agent — ready")
print(f" Model : {args.model}")
print(f" Chunks retrieved per query: {args.k}")
print(" Type 'exit' to quit")
print("="*55 + "\n")
while True:
try:
question = input("Question > ").strip()
except (KeyboardInterrupt, EOFError):
print("\nGoodbye!")
break
if not question:
continue
if question.lower() in ("exit", "quit", "q"):
print("\nGoodbye!")
break
try:
# Retrieve source docs separately so we can display them
source_docs = retriever.invoke(question)
# Run the full chain
answer = chain.invoke(question)
# ── Answer ────────────────────────────────────────────────────────────
print("\n" + "─"*55)
print(answer)
# ── Sources ───────────────────────────────────────────────────────────
print("\n── Sources used " + "─"*39)
seen = set()
for doc in source_docs:
page = doc.metadata.get("page", "?")
source = doc.metadata.get("source", "unknown")
key = (source, page)
if key in seen:
continue
seen.add(key)
preview = doc.page_content.strip()[:280].replace("\n", " ")
print(f"\n [p.{page}] {preview}…")
print("\n" + "─"*55 + "\n")
except Exception as e:
print(f"\nERROR: {e}\n")
Essai
Commencez par exécuter python ask.py et saisissez une question telle que "Comment devrais-je nommer les modèles de préparation ?" Le script accepte également l’option --db pour pointer vers un dossier Chroma différent, ainsi que --k pour modifier le nombre de fragments récupérés par question, ce qui est utile lorsque les réponses semblent manquer de contexte. Une réponse générique ou inventée serait inutile dans ce cas. La réponse obtenue est plutôt du type "les modèles de préparation devraient utiliser le préfixe stg_." Il n’a pas deviné, et personne n’a eu besoin de fouiller dans la page 14 du PDF. Il a trouvé la règle appropriée et l’a expliquée comme le ferait un ingénieur senior.
Essayez maintenant quelque chose de sans rapport, comme la météo à Paris cette semaine. L’assistant ne invente pas de réponse à partir de connaissances générales. Il vérifie le contexte de la documentation consultée, constate que l’information n’y est pas et dit honnêtement qu’il ne peut pas répondre à partir de la documentation fournie. Cette honnêteté constitue une part importante de ce qui rend un système fiable en environnement de production.
Quels changements pour l’équipe ?
Cette approche s’applique très bien au-delà de dbt. Tout manuel, guide d’opération ou ensemble de politiques basé sur PDF peut être traité avec les mêmes deux scripts, et comme les embeddings s’exécutent localement, seules la question finale et les extraits récupérés sont envoyés à une API externe.
En deux fichiers Python et en quelques minutes, 187 pages de documentation généralement ignorées sont devenues un expert capable de dialoguer. Personne n’a plus besoin de répondre manuellement à la question « comment devons-nous nommer les modèles de préparation ? » ou de chercher dans Confluence le lien approprié. L’assistant répond instantanément, en se basant sur vos normes réelles.
Cependant, il fonctionne encore sur un ordinateur portable. Les étapes suivantes logiques consistent à relier ce même pipeline à Slack, afin que les collègues puissent mentionner le bot @dbt-assistant là où ils travaillent déjà, ainsi qu’à automatiser l’ingestion pour que l’index soit mis à jour chaque fois que la documentation change.
Lectures complémentaires
- Un agent de trading LangChain soutenu par des données de marché EODHD en temps réel, étape par étape — Pourquoi les agents de trading basés sur des LLM échouent sans données réelles, comment fonctionne le cycle ReAct, et comment créer un agent LangChain à trois outils utilisant les prix EODHD, les fondamentaux et l’RSI.
- Un agent médical capable de naviguer entre des bases de données SQLite et des recherches sur le Web — Construisez un agent LangChain qui détermine si une question médicale nécessite une requête SQL sur trois ensembles de données ou une recherche en ligne en temps réel, ainsi que deux problèmes techniques qui ont modifié la conception.