Skip to content

🧠 Hands-On AI RAG: Ask Questions About Your Documents

The RAG module is a lightweight tool to turn your documents into an AI-powered knowledge base using Retrieval-Augmented Generation (RAG). It's part of the Hands-On AI ecosystem.

Hands-On AI RAG Web Interface

🚀 How to Use

✅ Install Hands-On AI with RAG support

pip install hands-on-ai

Or with uv:

uv pip install hands-on-ai

CLI Usage

hands-on-ai rag index notes/       # Build index from folder or file
hands-on-ai rag ask "What is TCP?" # Ask a question
hands-on-ai rag interactive        # Start interactive Q&A mode
hands-on-ai rag web                # Launch the web interface

📁 Where Indexes Are Stored

  • CLI default: ~/.hands_on_ai/rag_index/default.npz
  • Web UI default: ~/.hands_on_ai/rag_index/web_index.npz

You can override using --output-file or --index-path.

🧪 Try It With Sample Documents

Hands-On AI comes with built-in sample documents to help you get started. You can access these programmatically:

from hands_on_ai.rag import list_sample_docs, get_sample_docs_path, copy_sample_docs

# List all available sample files
print(list_sample_docs())

# Get the path to the sample directory
samples_path = get_sample_docs_path()
print(f"Sample documents are located at: {samples_path}")

# Copy sample files to a local directory for experimentation
local_path = copy_sample_docs("my_samples")
print(f"Copied sample documents to: {local_path}")

Or from the command line:

# Copy the sample documents to your current directory
python -c "from hands_on_ai.rag import copy_sample_docs; copy_sample_docs()"

# Create an index from the sample documents
hands-on-ai rag index sample_docs/

# Ask questions about your samples
hands-on-ai rag ask "What is in the sample documents?"

📂 Sample Documents

Built-in files include:

  • tcp_protocol.md – TCP and Networking Concepts in Markdown
  • networking_basics.txt – Basic Networking Reference in Text
  • tcp_handshake.docx – TCP Three-Way Handshake in Word Document
  • mobile_game_protocols.pdf – Multiplayer Game Networking in PDF

Each file demonstrates different document formats and contains networking-related content perfect for testing RAG capabilities.

🛠️ Makefile/Justfile Shortcuts

# Using make
make rag-index file=notes.md
make rag-web

# Using just
just rag-index file=notes.md
just rag-web

🌐 Web Interface

Launch a web interface to ask questions about your documents:

hands-on-ai rag web

By default, the interface is only accessible from your local machine. To make it accessible from other devices on your network:

hands-on-ai rag web --public

⚠️ When using the --public flag, the interface will be accessible to anyone on your network. Use with caution.

You can also specify a custom port (default is 8001):

hands-on-ai rag web --port 8888

🧠 Example Workflow

# Copy sample documents
python -c "from hands_on_ai.rag import copy_sample_docs; copy_sample_docs('demo')"

# Build index from the documents
hands-on-ai rag index demo/

# Ask questions
hands-on-ai rag ask "What is RAG?" --show-context

# Launch the web interface
hands-on-ai rag web

📚 Programmatic Usage

import os
from pathlib import Path
from hands_on_ai.rag import (
    load_text_file, 
    chunk_text, 
    get_embeddings, 
    save_index_with_sources,
    get_top_k,
    copy_sample_docs
)

# Copy sample files to a working directory
samples_dir = copy_sample_docs("rag_demo")

# Process a sample file
sample_file = samples_dir / "tcp_protocol.md"
text = load_text_file(sample_file)

# Chunk the text
chunks = chunk_text(text, chunk_size=50)

# Track the source of each chunk
sources = [f"{sample_file.name}:{i}" for i in range(len(chunks))]

# Get embeddings
vectors = get_embeddings(chunks)

# Save the index
index_path = Path("sample_index.npz")
save_index_with_sources(vectors, chunks, sources, index_path)

# Query the index
query = "What is RAG?"
results = get_top_k(query, index_path, k=2)

print("Query:", query)
print("\nResults:")
for chunk, source in results:
    print(f"\nSource: {source}")
    print(f"Content: {chunk[:100]}...")

Designed for educators. Built for learners. Powered by open models.