Skip to content

Latest commit

 

History

History
315 lines (233 loc) · 7.65 KB

USER_GUIDE.md

File metadata and controls

315 lines (233 loc) · 7.65 KB

User Guide

System Requirements

Minimum Requirements

  • Operating System: macOS, Linux, or Windows with WSL2
  • Python: Version 3.11 or higher
  • Memory: 2GB available RAM
  • Storage: 5GB free disk space
  • Docker: For running InterSystems IRIS database

Recommended Requirements

  • Memory: 4GB+ available RAM for better performance
  • Storage: 10GB+ for larger document collections
  • Internet: For downloading models and API access

Required Software

  • Docker and Docker Compose: For database management
  • Git: For cloning the repository

Installation

Step 1: Install Prerequisites

Install Docker

Step 2: Get the Code

# Clone the repository
git clone <repository-url>
cd rag-templates

# Make CLI tools executable (if applicable, e.g. ragctl)
# chmod +x ragctl # Assuming ragctl is a script

Step 3: Set Up Python Virtual Environment

Option 1: Using Make (Recommended)

# Create Python virtual environment (.venv) and install dependencies
make setup-env
make install

# Activate the environment for your current session
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Option 2: Manual Setup

# Create Python virtual environment
python3 -m venv .venv

# Activate the environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install the project in editable mode (optional, for development)
pip install -e .

Step 4: Start the Database

# Start InterSystems IRIS database
docker-compose up -d

# Verify it's running
docker ps | grep iris_db_rag_standalone

Step 5: Initialize the System

# Set up database schema
make setup-db

# Load sample documents for testing
make load-data

# Verify everything works
make validate-iris-rag

Configuration

Basic Configuration

The system uses a main configuration file at config/config.yaml. For most users, the default settings work well.

Database Settings

database:
  db_host: "localhost"
  db_port: 1972
  db_user: "SuperUser"
  db_password: "SYS"
  db_namespace: "USER"

Embedding Model Settings

embedding_model:
  name: "sentence-transformers/all-MiniLM-L6-v2"
  dimension: 384

Environment Variables

For sensitive information like API keys, use environment variables:

# LLM API Keys (optional, for advanced features)
export OPENAI_API_KEY=your-openai-api-key

# Database connection (only if different from defaults)
export IRIS_HOST=localhost
export IRIS_PORT=1972
export IRIS_USERNAME=SuperUser
export IRIS_PASSWORD=SYS

Automatic Schema Management

The system automatically manages database schema changes when you update configurations. You don't need to manually handle database migrations - the system detects changes and updates the schema automatically.

Basic Usage

Using Python

from iris_vector_rag import create_pipeline

# Create a basic RAG pipeline (auto-validates database setup)
pipeline = create_pipeline(pipeline_type="basic", validate_requirements=True)

# Ask a question - standardized API across all pipelines
result = pipeline.query("What is machine learning?", top_k=5)
print(f"Answer: {result['answer']}")
print(f"Found {len(result['retrieved_documents'])} relevant documents")

# Access retrieved contexts (RAGAS compatible)
for i, context in enumerate(result['contexts'], 1):
    print(f"Context {i}: {context[:100]}...")

# Access source metadata (LangChain compatible)
for doc in result['retrieved_documents']:
    print(f"Source: {doc.metadata.get('source', 'Unknown')}")

Document Management

Loading Your Documents

From a Directory

# Load documents from a folder
make load-data

# Load from a specific directory
python -c "
from data.loader_fixed import process_and_load_documents
result = process_and_load_documents('path/to/your/documents', limit=100)
print(f'Loaded: {result}')
"

Supported File Types

  • Text files: .txt, .md
  • PDF documents: .pdf (requires additional setup)
  • Word documents: .docx (requires additional setup)
  • Structured data: .json, .csv

Check What's Loaded

# See how many documents are in the system
make check-data

Clear All Data

# Remove all documents (use with caution!)
make clear-rag-data

Querying Your Data

Simple Queries

from iris_vector_rag import create_pipeline

# Create a pipeline
pipeline = create_pipeline("basic")

# Ask questions
result = pipeline.query("What is photosynthesis?")
print(result["answer"])

Advanced Queries

# Get more detailed results
result = pipeline.query(
    "Explain machine learning algorithms",
    top_k=10,  # Get more source documents
    include_sources=True  # Include source information
)

# See what sources were used
for doc in result['retrieved_documents']:
    print(f"Source: {doc.metadata.get('source', 'Unknown')}")
    print(f"Content preview: {doc.page_content[:100]}...")

Using Make Commands

# Test a specific pipeline
make test-pipeline PIPELINE=basic

# Run comprehensive tests
make test-1000

Available RAG Pipelines

The system supports 6 production-ready RAG techniques with unified API:

1. BasicRAG (basic)

  • Best for: General question answering, simple use cases
  • Features: Standard vector similarity search
  • Example: pipeline = create_pipeline("basic")

2. BasicRAGReranking (basic_rerank)

  • Best for: Improved precision in document retrieval
  • Features: Over-retrieval with cross-encoder reranking
  • Example: pipeline = create_pipeline("basic_rerank")

3. CRAG - Corrective RAG (crag)

  • Best for: Self-correcting, high-quality answers
  • Features: Automatic relevance evaluation and correction
  • Example: pipeline = create_pipeline("crag")

4. HybridGraphRAG (graphrag)

  • Best for: Complex knowledge graphs, multi-hop reasoning
  • Features: Vector + Text + Graph search with RRF fusion
  • Example: pipeline = create_pipeline("graphrag")
  • Requires: pip install rag-templates[hybrid-graphrag]

5. PyLateColBERT (pylate_colbert)

  • Best for: Precision retrieval with late interaction
  • Features: ColBERT-style token-level matching
  • Example: pipeline = create_pipeline("pylate_colbert")

6. IRIS-Global-GraphRAG

  • Best for: Academic papers, 3D visualization
  • Features: Global community detection, hierarchical summaries
  • Direct import: from iris_rag.pipelines.iris_global_graphrag import ...

Common Use Cases

1. Document Q&A System

# Load your company documents
pipeline = create_pipeline("basic")

# Ask questions about your documents
answer = pipeline.query("What is our return policy?")
print(answer["answer"])

2. Research Assistant

# Use CRAG for self-correcting research
pipeline = create_pipeline("crag")

# Ask complex research questions
result = pipeline.query("What are the latest developments in AI?")
print(result["answer"])

Troubleshooting

Common Issues

"Connection failed" Error

# Check if IRIS database is running
docker ps | grep iris_db_rag_standalone

# If not running, start it
docker-compose up -d

# Test connection
make test-dbapi

"No documents found" Error

# Check if documents are loaded
make check-data

# If no documents, load sample data
make load-data