SentinelRAG

Private AI Investigation Agent

SentinelRAG is a local-first desktop investigation workbench that turns private, multimodal evidence into cited findings, correlated entities, an incident timeline, an explainable risk assessment, and an exportable report.

The application is designed to keep sensitive evidence on the investigator's machine. Deterministic parsers and security rules establish the facts; local retrieval and local language models help connect, explain, and report them.

Why SentinelRAG

Most AI assistants summarize one document at a time and require users to trust an opaque answer. SentinelRAG is built for investigations:

• Local and offline by default
• Evidence-level provenance and integrity hashes
• Format-aware parsing and hierarchical chunking
• Dense, sparse, and metadata-filtered hybrid retrieval
• Clickable citations for every generated conclusion
• Cross-evidence indicator correlation
• Deterministic event timeline and risk factors
• Explicit separation of facts, inferences, and recommendations
• Prompt-injection-resistant treatment of evidence and web content

Hackathon Scope

The first vertical slice is intentionally focused:

1. Create an investigation case.
2. Import text, email, PDF, screenshot, or log evidence.
3. Extract text, metadata, indicators, and timestamps.
4. Chunk and index the evidence locally.
5. Ask an investigation question.
6. Retrieve and rerank supporting evidence.
7. Display a cited answer, timeline, risk factors, and report.

Live threat feeds, unrestricted web crawling, multi-user authentication, and distributed services are roadmap features, not MVP dependencies.

Team Brief

We are building a privacy-first AI investigation agent for phishing, scams, and small security incidents. The product accepts messy evidence such as emails, logs, screenshots, PDFs, notes, and curated security references. It extracts facts deterministically, indexes them with a serious RAG pipeline, retrieves the right evidence for each question, and then generates cited findings, a timeline, risk factors, and a professional report.

The demo should prove three things quickly:

1. Sensitive evidence can stay local.
2. Every important answer is backed by citations.
3. The system connects evidence across files better than a normal chatbot.

Ollama is the default provider so the application works offline. OpenAI API is an optional provider for better report synthesis and judge-facing demos when a teammate supplies their own API key. Deterministic extraction, timeline, risk scoring, and citations must still work without OpenAI.

Architecture

PySide6 Desktop Application
            |
  Investigation Orchestrator
   /       |        |       \
Evidence  RAG   Intelligence  Reporting
   |       |        |           |
Parsers  Milvus   Timeline    Templates
   \       |        |          /
       SQLite + Local Files
                |
   Ollama Local LLM / Optional OpenAI API

SentinelRAG is a modular monolith. Domain packages communicate through typed contracts and can later be exposed through an API without rewriting the core.

Core Technology

• Python 3.11 or 3.12
• PySide6 for the cross-platform desktop application
• SQLite and SQLAlchemy for transactional application data
• Milvus Lite through pymilvus for local vector and hybrid retrieval
• Sentence Transformers for local embeddings and reranking
• Ollama for local language-model inference
• Optional OpenAI API provider for higher-quality synthesis during demos
• Tesseract for initial OCR
• PyMuPDF and standard-library parsers for evidence extraction
• Pytest, Ruff, and MyPy for quality gates

See Architecture and Architecture Decisions.

Repository Map

src/sentinelrag/               Product domains and application services
knowledge/                     Versioned, licensed reference-source manifests
demo/                          Reproducible demonstration investigations
tests/                         Unit, integration, evaluation, and security tests
docs/modules/                  Contributor-ready module contracts
docs/architecture/             System, data-flow, and security architecture
docs/adr/                      Architecture Decision Records
scripts/                       Cross-platform bootstrap and validation helpers

The live ownership board and module index are in MODULES.md. Detailed implementation contracts live in docs/modules/MODULE-###-*.md. Every issue, branch, commit, and pull request should reference one module ID and its phase.

Quick Start

Prerequisites

• Git
• Python 3.11 or 3.12 stable
• Ollama current stable release for model-backed workflows
• Tesseract OCR 4.1 or newer for OCR/parser workflows

Docker is optional. Milvus Lite runs in-process and does not require a server.

Linux

Install Python and Tesseract with the package manager for your distribution. For example, on Ubuntu or Debian:

sudo apt update
sudo apt install python3.11 python3.11-venv tesseract-ocr

Create a project-specific environment:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
cp .env.example .env

macOS

Install Python, Ollama, and Tesseract using their official installers or Homebrew. On Apple Silicon, use an arm64 Python installation consistently.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
cp .env.example .env

Windows PowerShell

Install Python using the Windows launcher, then install Ollama and Tesseract. Add Tesseract to PATH, or configure its executable path locally when the OCR module is implemented.

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env

Do not reuse another contributor's virtual environment or commit .venv. Dependencies are declared in pyproject.toml; requirements.txt and requirements-dev.txt are compatibility entry points for tools that require requirements files. Use requirements.txt instead when only runtime dependencies are needed.

The default install is intentionally lightweight for foundation work and quick PR validation. Install extras only for the module you are working on:

python -m pip install -e ".[desktop]"       # MODULE-019 desktop UI
python -m pip install -e ".[ingestion]"     # MODULE-004/005 parsing and OCR
python -m pip install -e ".[rag]"           # MODULE-007/008/010 retrieval
python -m pip install -e ".[reporting]"     # MODULE-018 report generation
python -m pip install -e ".[security]"      # MODULE-020 keyring/crypto work
python -m pip install -e ".[cloud]"         # optional OpenAI provider

To enable the optional OpenAI provider, install the cloud extra and set a local API key in .env. Never commit real keys.

python -m pip install -e ".[cloud]"

Local Models

Start Ollama, then download the recommended local generator:

ollama pull qwen3:4b
ollama list

Sentence Transformers is the default in-process embedding provider. An Ollama embedding model may be configured later without changing retrieval contracts. OpenAI embeddings are optional for cloud-enabled experiments, but local embeddings remain the default to preserve offline behavior.

Model downloads require internet access. Normal application operation should remain offline after dependencies and models are installed.

Verify and Run

python scripts/doctor.py
python scripts/check_modules.py
pytest

The desktop command requires the desktop extra:

python -m pip install -e ".[desktop]"
python -m sentinelrag

Until feature modules are implemented, it opens the initial application shell.

Development

ruff check .
ruff format --check .
mypy src
pytest

Read CONTRIBUTING.md before taking a module. New behavior requires tests, typed public interfaces, and an update to the relevant module acceptance criteria.

Privacy and Security

• Imported evidence is untrusted data, never executable instruction.
• Cases are isolated by case_id at storage and retrieval boundaries.
• Original evidence is immutable and SHA-256 hashed.
• URL acquisition rejects private-network targets and unsafe schemes.
• Generated claims must cite retrieved evidence or be marked as inference.
• Secrets and machine-specific paths never enter version control.

See Threat Model.

Loops House Submission

This project targets the Codex Community Hackathon - Pune on Loops House. Before using the Loops CLI, authenticate and check the current submission:

loops auth status
loops project get --hackathonSlug codex-community-hackathon-pune

After the GitHub repository exists, create or update the Loops submission with the repo URL, tagline, description, demo URL, and video URL. Loops credentials and API keys must stay local.

Project Status

SentinelRAG is in active hackathon development. Interfaces and schemas may change rapidly until the first end-to-end investigation flow is complete.

License

SentinelRAG is licensed under the Apache License 2.0. See LICENSE.