abdulrahmanmoin/RAG-Chatbot-Physical-AI-Humanoid-Robotics-Textbook

RAG Chatbot Backend

Backend API for the Physical AI & Humanoid Robotics Book RAG Chatbot. This service handles document retrieval, embedding generation, and response generation while ensuring all responses are grounded in the book content.

Features

• —Retrieval-Augmented Generation (RAG): Answers questions based only on Physical AI & Humanoid Robotics book content
• —Full-book queries: Search across all book content
• —Selection-based queries: Answer based only on user-selected text
• —Grounding validation: Ensures all responses are based on retrieved content
• —Source attribution: Shows where information comes from in the book
• —Refusal logic: Declines to answer when context is insufficient

Prerequisites

• —Python 3.11+
• —Access to OpenRouter API (supports multiple LLMs including Gemini)
• —Qdrant Cloud account
• —Neon Serverless PostgreSQL account

Setup

1. Clone the Repository

git clone <repository-url>
cd <repository-name>

2. Create Virtual Environment

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Copy the .env file and update with your credentials:

cp .env .env.local

Edit .env.local and add your API keys and configuration:

# Qdrant Configuration
QDRANT_URL=your_qdrant_cloud_url
QDRANT_API_KEY=your_qdrant_api_key
QDRANT_COLLECTION_NAME=book_content

# Database Configuration
NEON_DATABASE_URL=your_neon_postgres_connection_string

# OpenRouter API (Primary LLM service - supports multiple models including Gemini)
OPENROUTER_API_KEY=your_openrouter_api_key_here
# Optional: Specify the model to use (default: google/gemini-pro)
OPENROUTER_MODEL=mistralai/mistral-7b-instruct

# Application Configuration
APP_ENV=development
LOG_LEVEL=info
MAX_QUERY_LENGTH=1000
MAX_RESPONSE_TOKENS=500
FRONTEND_URL=http://localhost:3000

# Retrieval Configuration
RETRIEVAL_TOP_K=5
RETRIEVAL_SIMILARITY_THRESHOLD=0.7

# Generation Configuration
GENERATION_TEMPERATURE=0.1

Running the Application

Start the API Server

python start_server.py

The API will be available at http://localhost:8000

API Documentation

• —Interactive docs: http://localhost:8000/api/docs
• —Alternative docs: http://localhost:8000/api/redoc

Ingesting Book Content

To add book content to the RAG system:

python -m src.scripts.ingest_documents /path/to/book/content

This will:

1. 1.Parse the book content
2. 2.Chunk it into semantically meaningful pieces
3. 3.Generate embeddings using the configured embedding model
4. 4.Store chunks in PostgreSQL and embeddings in Qdrant

API Endpoints

Chat Endpoint

POST /api/chat

Query the chatbot with a question:

{
  "query": "What are the key principles of humanoid locomotion?",
  "query_type": "full_book",
  "selected_text": "Optional text for selection-based queries"
}

Query Types:

• —full_book: Search across all book content
• —selection_based: Answer based only on selected text

Health Check

GET /api/health

Check if the service is running.

Environment Variables

Architecture

The backend follows a service-oriented architecture:

• —Models: SQLAlchemy and Pydantic models
• —Services: Business logic (retrieval, embedding, validation, query processing)
• —API: FastAPI endpoints with proper routing
• —Configuration: Settings management with environment variables
• —Agents: RAG agent for controlled generation

Quality Assurance

The system ensures response quality through:

• —Grounding validation: Responses must be based on retrieved content
• —Context sufficiency checks: Refuses to answer if context is insufficient
• —External knowledge detection: Identifies and prevents external knowledge usage
• —Source attribution: Shows where information originates

Development

Running Tests

pytest

Code Formatting

black src/

Linting

flake8 src/

Deployment

For production deployment:

1. 1.Set APP_ENV=production in environment variables
2. 2.Use secure, non-debug settings
3. 3.Ensure proper resource limits and monitoring
4. 4.Set up proper logging aggregation
5. 5.Implement proper backup strategies for the database