guard-rag 1.0.0

Privacy-first, fully offline AI document assistant secured by tiered safety guardrails

     

GuardRAG

A privacy-first, fully offline AI document assistant — secured by a tiered safety guardrails system

Upload any document. Ask anything. Get answers — entirely on your machine.
No cloud. No API keys. No data leaves your device.

---

Architecture

The GuardRAG package provides a command-line interface for building and querying RAG (Retrieval-Augmented Generation) chatbots with local LLMs.

---

Why GuardRAG?

Most RAG chatbots rely on cloud APIs, which creates privacy risks for sensitive documents — contracts, medical records, internal reports. GuardRAG solves that by:

• Running the LLM locally via Ollama (no data transmitted)
• Embedding documents offline using HuggingFace sentence-transformers
• Enforcing tiered safety policies with 4 sensitivity levels
• Providing a simple CLI interface for easy usage

---

Feature Highlights

Core 100% Offline — zero external network calls at runtime Multi-format ingestion — PDF, TXT, DOCX Persistent FAISS cache — same file re-uploads skip re-embedding Multi-turn conversation — full history-aware retrieval Any Ollama model — Gemma, Llama3, Mistral, Phi, and more CLI Interface — easy command-line usage

Safety 4-Tier Data Sensitivity System — Public → Internal → Confidential → Restricted Jailbreak / prompt injection detection — always active Credential & API key protection — Internal+ PII protection — SSN, email, phone, DOB, credit card (Confidential+) Regulated data guards — HIPAA / GDPR / financial categories (Restricted)

---

Data Sensitivity Levels

Level	Badge	What is Protected
Public		Jailbreak & prompt injection only
Internal		+ API keys, credentials, passwords, tokens
Confidential		+ SSN, email, phone number, DOB, credit card
Restricted		+ Medical records, diagnoses, financials, HIPAA/GDPR

---

Tech Stack

Layer	Technology
CLI Interface	Python argparse + rich console output
LLM Engine	Ollama — local model inference
Embeddings	HuggingFace sentence-transformers/all-MiniLM-L6-v2
Vector Store	FAISS — disk-persisted
RAG Pipeline	LangChain — retrieval chains + chat history
Safety Rails	Custom tiered guardrails system (input + output)

---

Prerequisites

• Python 3.9+
• Ollama installed and running locally
• At least one model pulled via Ollama:

ollama pull gemma3:1b
# or any other model: llama3.1, phi3, mistral, etc.

---

Installation

Install GuardRAG from PyPI:

pip install guard-rag

Or install from source:

git clone https://github.com/sowmiyan-alt/GUADRAILS-RAG-CHAT-TOOL.git
cd GUADRAILS-RAG-CHAT-TOOL
pip install .

---

Quick Start

After installation, run the CLI:

guard-rag --pdf path/to/your/document.pdf

This will start an interactive chat session with your document.

CLI Options

guard-rag --pdf <file>             Load and chat with a PDF document
          --model <model>          Ollama model to use (default: gemma3:1b)
          --ollama-host <url>      Ollama server URL (default: http://localhost:11434)
          --chunk-size <int>       Document chunk size (default: 1000)
          --chunk-overlap <int>    Chunk overlap (default: 200)
          --sensitivity <level>    Data sensitivity: Public | Internal | Confidential | Restricted
          --no-guardrails          Disable safety guardrails
          --help                   Show this help message

Example Session

# Start with a PDF using Llama 3.1
guard-rag --pdf report.pdf --model llama3.1 --sensitivity Confidential

# You: What are the key findings?
# Chatbot: Based on the document, the key findings are...

---

Project Structure

GUADRAILS-RAG-CHAT-TOOL/
│
├── guardrag/                 # Main installable package
│   ├── __init__.py
│   ├── cli/
│   │   └── main.py            # CLI entry point (guardrag command)
│   ├── rag/
│   │   └── core.py            # RAG pipeline: load, embed, retrieve, answer
│   └── utils/
│       ├── safety.py          # Tiered guardrails & content filtering
│       └── ollama.py          # Ollama process management utilities
│
├── pyproject.toml             # PEP 517/518 build config (PyPI metadata)
├── setup.py                   # Legacy setuptools compatibility
├── MANIFEST.in                # Source distribution file inclusions
├── requirements.txt           # Full dependency list
├── .env.example               # Environment variable template
├── INSTALL.md                 # Detailed installation guide
├── QUICK_REFERENCE.md         # CLI quick reference card
├── LICENSE
└── README.md

.guardrag_storage/ is auto-generated on first document load (FAISS cache) and excluded from version control.

---

Configuration

Environment Variables

Copy .env.example to .env and adjust as needed:

cp .env.example .env

Variable	Default	Description
OLLAMA_HOST	http://localhost:11434	Ollama API endpoint
NO_PROXY	huggingface.co,...	Bypass proxy for local+HF calls
PORT	8000	Server port (auto-set by PaaS)

Chunking Parameters

Adjustable per-session via the sidebar in the UI:

• Chunk Size (default 1000 chars)
• Chunk Overlap (default 200 chars)

Different chunk settings for the same file produce a separate FAISS index automatically.

---

Deployment

From PyPI (recommended)

pip install guard-rag

From Source

git clone https://github.com/sowmiyan-alt/GUADRAILS-RAG-CHAT-TOOL.git
cd GUADRAILS-RAG-CHAT-TOOL
pip install .

In a virtual environment (best practice)

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

pip install guard-rag

---

Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit using Conventional Commits: git commit -m "feat: add X"
4. Push and open a Pull Request

Bug reports and feature requests are welcome via GitHub Issues.

---

License

This project is licensed under the MIT License — see LICENSE for details.

---

Built with ❤️ by Sowmiyan S

FastAPI · LangChain · Ollama · HuggingFace · FAISS · Vanilla JS