Un asistente para documentos en dos archivos de Python: ChromaDB, LangChain y Claude
Convertir un PDF de 187 páginas con las normas de dbt en un asistente con capacidad de búsqueda, mediante un script de ingestión, embeddings locales de Hugging Face, ChromaDB y respuestas de Claude basadas en los documentos.
Fuentes: How I Built an AI Agent That Reads Company Docs in 5 Minutes
La documentación estática conlleva un costo conocido: los colegas se ven interrumpidos con las mismas preguntas, los nuevos empleados no pueden encontrar las normas de dbt, y todos pierden tiempo al cambiar de contexto. La generación mejorada mediante recuperación de información soluciona gran parte de esto al permitir que la base de conocimientos se busque por su significado y no solo por palabras clave. Sin embargo, un plano no responde a preguntas; el código sí. Así que aquí hay un pequeño pipeline en Python que lee un documento de la empresa, crea un “cerebro” buscable a partir de él y proporciona a su equipo un asistente conversacional, todo en aproximadamente cinco minutos.
Todo consta de dos archivos:
ingest.pyes el herramienta de creación. Úselo una vez para procesar la documentación y almacenarla en una base de datos.ask.pyes el asistente de voz. Úselo cada vez que alguien tenga una pregunta, y él devolverá una respuesta basada en la documentación.
Configuración
Hay dos cosas prioritarias: las bibliotecas y un lugar donde guardar la clave de API.
El archivo de requisitos
Las bibliotecas se encargan de cargar documentos, dividirlos en partes, generar embeddings, realizar búsquedas vectoriales y comunicarse con Claude. Crea requirements.txt en la carpeta del proyecto con esta lista:
# 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
Instale todo con pip install -r requirements.txt.
El archivo .env
Claude es la voz del agente, por lo que se necesita una clave de API de Anthropic. Nunca incluya claves de forma directa en los scripts de Python, ya que subirlas accidentalmente a GitHub representa un grave riesgo de seguridad. En su lugar, cree un archivo .env oculto en la raíz del proyecto y agregue la clave allí:
ANTHROPIC_API_KEY=your_actual_api_key_here
La biblioteca python-dotenv permite que los scripts lean ese archivo automáticamente en segundo plano.
Construyendo el “cerebro” con ingest.py
Un asistente debe leer el manual antes de poder responder preguntas. ingest.py se ejecuta una vez, o nuevamente cada vez que la documentación cambia. Su tarea es leer un PDF, dividirlo en partes comprensibles, convertir esas partes en vectores que capturen el significado y guardarlos en una base de datos. El script completo:
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.")
Qué hace el script, paso a paso:
- Carga.
PyPDFLoaderlee el documento, en este caso un PDF de 187 páginas con estándares dbt. - División. No se puede pasar todo el contenido de un libro a un modelo de una sola vez, por lo que el texto se divide en bloques de 1000 caracteres, aproximadamente un párrafo cada uno. Un
chunk_overlapde 200 caracteres evita que una regla que abarque dos párrafos quede dividida en dos partes. - Incrustación. El modelo utilizado es
all-MiniLM-L6-v2, un modelo pequeño de código abierto de Hugging Face. Funciona en la CPU local, sin necesidad de usar una API en la nube de pago, y convierte cada bloque en un vector de 384 dimensiones. - Almacenamiento. Los vectores se guardan en ChromaDB, en una carpeta del disco en
./chroma_db.
Ejecútelo con python ingest.py. Después de unos segundos, aparecerá una nueva carpeta chroma_db en el proyecto. El documento estático se ha convertido en un almacenamiento codificado y buscable.
Dándole voz con ask.py
La documentación ahora se encuentra codificada en ./chroma_db. Lo que falta es algo que tome una pregunta, la busque y responda. Eso es ask.py; úsalo cada vez que alguien tenga una pregunta:
"""
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")
Probándolo
Comiéncelo con python ask.py e introduzca una pregunta como “¿Cómo debería nombrar los modelos de etapa intermedia?”. El script también acepta --db para indicar una carpeta Chroma diferente y --k para modificar la cantidad de fragmentos que se recuperan por pregunta, lo cual es útil cuando las respuestas parecen omitir el contexto. Una respuesta genérica o inventada sería inútil aquí. En su lugar, la respuesta es algo como “los modelos de etapa intermedia deben usar el prefijo stg_”. No hizo conjeturas, y nadie tuvo que buscar en la página 14 del PDF. Encontró la regla correcta y la explicó como lo haría un ingeniero senior.
Ahora pruebe algo no relacionado, como qué tiempo hará en París esta semana. El asistente no inventa una respuesta basada en conocimientos generales. Revisa el contexto de la documentación recuperada, ve que la información no está allí y dice honestamente que no puede responder con la documentación proporcionada. Esa honestidad es una parte importante de lo que hace que un sistema sea confiable en entornos de producción.
Qué cambia para el equipo
Este patrón se puede aplicar fácilmente más allá de dbt. Cualquier manual, guía de operaciones o conjunto de políticas basado en PDF puede pasar por los mismos dos scripts, y como los embeddings se ejecutan localmente, solo la pregunta final y los fragmentos recuperados se envían a una API externa.
En dos archivos de Python y en pocos minutos, 187 páginas de documentación en su mayoría ignorada se convirtieron en un experto con el que se puede conversar. Ya nadie tiene que responder manualmente a “¿cómo nombramos los modelos de preparación?” ni buscar en Confluence el enlace adecuado. El asistente responde al instante, basándose en sus estándares reales.
No obstante, todavía funciona en una laptop. Los siguientes pasos lógicos son conectar el mismo flujo de trabajo a Slack, para que los compañeros de equipo puedan mencionar al bot @dbt-assistant donde ya trabajan, y automatizar la ingesta para que el índice se actualice cada vez que cambie la documentación.
Leer más
- Un agente de inversiones de LangChain respaldado por datos de mercado en tiempo real de EODHD, paso a paso — Por qué los agentes de inversión basados en LLM fracasan sin datos reales, cómo funciona el bucle ReAct y cómo crear un agente de LangChain con tres herramientas que utilice precios de EODHD, fundamentales y RSI.
- Un agente médico que navega entre bases de datos SQLite y búsquedas en la web — Construir un agente de LangChain que decida si una pregunta médica requiere una consulta SQL en tres conjuntos de datos o una búsqueda en la web en tiempo real, además de dos problemas que cambiaron el diseño.