Home / Articles

A Docs Assistant in Two Python Files: ChromaDB, LangChain and Claude

Turn a 187-page dbt standards PDF into a searchable assistant with an ingest script, local Hugging Face embeddings, ChromaDB and Claude answers grounded in the docs.

Publisher: REACTAPP.TOP7 min read1539 words

This article is published in English.

Sources: How I Built an AI Agent That Reads Company Docs in 5 Minutes

Static documentation has a familiar cost. Colleagues get interrupted with the same questions, new joiners can't find the dbt standards, and everyone loses time switching context. Retrieval-augmented generation fixes much of that by making a knowledge base searchable by meaning and not only by keyword. A blueprint doesn't answer questions, though. Code does. So here's a small Python pipeline that reads a company document, builds a searchable "brain" from it and gives your team a conversational assistant, all in roughly five minutes.

The whole thing is two files:

  • ingest.py is the builder. Run it once to digest the documentation and store it in a database.
  • ask.py is the voice. Run it whenever someone has a question, and it returns an answer based on the documentation.

Setup

Two things come first: the libraries and a place to keep the API key.

The requirements file

The libraries cover document loading, chunking, embeddings, vector search and talking to Claude. Create requirements.txt in the project folder with this list:

# 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

Install everything with pip install -r requirements.txt.

The .env file

Claude is the voice of the agent, so an Anthropic API key is needed. Never hardcode keys in Python scripts, because pushing one to GitHub by accident is a serious security risk. Create a hidden .env file in the project root instead and add the key:

ANTHROPIC_API_KEY=your_actual_api_key_here

The python-dotenv library lets the scripts read that file automatically in the background.

Building the brain with ingest.py

An assistant has to read the manual before it can answer questions. ingest.py runs once, or again whenever the documentation changes. Its job is to read a PDF, cut it into digestible pieces, turn the pieces into vectors that capture meaning and save them to a database. The full script:

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.")

What the script does, step by step:

  • Loading. PyPDFLoader reads the document, in this case a 187-page dbt standards PDF.
  • Slicing. An entire book can't be handed to a model in one go, so the text is split into 1000-character blocks, roughly a paragraph each. A chunk_overlap of 200 characters keeps a rule that straddles two paragraphs from being cut in half.
  • Embedding. The model is all-MiniLM-L6-v2, a small open-source model from Hugging Face. It runs on the local CPU with no paid cloud API and turns each chunk into a 384-dimensional vector.
  • Storing. The vectors go into ChromaDB, saved to a folder on disk at ./chroma_db.

Run it with python ingest.py. After a few seconds a new chroma_db folder appears in the project. The static document has become an encoded, searchable store.

Giving it a voice with ask.py

The documentation now sits encoded in ./chroma_db. What's missing is something that takes a question, looks things up and answers. That's ask.py, run anytime someone has a 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")

Trying it

Start it with python ask.py and type a question such as "How should I name staging models?" The script also accepts --db to point at a different Chroma folder and --k to change how many chunks are retrieved per question, which is handy when answers seem to miss context. A generic web answer or an invented one would be useless here. The reply instead is along the lines of "staging models should use the stg_ prefix." It didn't guess, and nobody had to hunt through page 14 of the PDF. It found the right rule and explained it the way a senior engineer would.

Now try something unrelated, like what the weather will be in Paris this week. The assistant doesn't make up an answer from general knowledge. It checks the retrieved documentation context, sees that the information isn't there and says honestly that it can't answer from the provided documentation. That honesty is a large part of what makes a system trustworthy in production.

What changes for the team

The pattern generalizes well beyond dbt. Any PDF-based handbook, runbook or policy set can go through the same two scripts, and because the embeddings run locally, only the final question and the retrieved snippets ever travel to an outside API.

In two Python files and a few minutes, 187 pages of mostly ignored documentation became a conversational expert. Nobody has to answer "how do we name staging models?" by hand or dig through Confluence for the right link. The assistant answers instantly, based on your actual standards.

It still lives on a laptop, though. The natural next steps are connecting the same pipeline to Slack, so teammates can mention a @dbt-assistant bot where they already work, and automating ingestion so the index refreshes whenever the documentation changes.