Metadata-Version: 2.5
Name: sentinelrag
Version: 0.2.0
Summary: Triple-gate adaptive RAG: CI gates for retrieval, answer quality, and ingest poison defenses
Project-URL: Homepage, https://github.com/prakash888kp/SentinelRAG
Project-URL: Repository, https://github.com/prakash888kp/SentinelRAG
Project-URL: Issues, https://github.com/prakash888kp/SentinelRAG/issues
Project-URL: Documentation, https://github.com/prakash888kp/SentinelRAG#readme
Project-URL: Changelog, https://github.com/prakash888kp/SentinelRAG/blob/master/CHANGELOG.md
Author-email: PRAKASH KUMAR K <prakash888kp@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: ci,evaluation,fastapi,qdrant,rag,red-team,retrieval-augmented-generation,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=2.1.0
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: qdrant-client>=1.12.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: matplotlib>=3.9.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.32.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: sentence-transformers>=3.3.0; extra == 'ml'
Description-Content-Type: text/markdown

# SentinelRAG

[![CI](https://github.com/prakash888kp/SentinelRAG/actions/workflows/ci.yml/badge.svg)](https://github.com/prakash888kp/SentinelRAG/actions/workflows/ci.yml)
[![Supply-chain gate](https://github.com/prakash888kp/SentinelRAG/actions/workflows/supply-chain-gate.yml/badge.svg)](https://github.com/prakash888kp/SentinelRAG/actions/workflows/supply-chain-gate.yml)
[![PyPI](https://img.shields.io/pypi/v/sentinelrag.svg)](https://pypi.org/project/sentinelrag/)

**RAG supply-chain CI** — fail builds when **retrieval**, **grounded answers**, or **poison / hygiene defenses** regress. Includes an adaptive FastAPI + Qdrant reference stack.

**Author:** PRAKASH KUMAR K ([@prakash888kp](https://github.com/prakash888kp)) · **Support:** [GitHub Issues](https://github.com/prakash888kp/SentinelRAG/issues)

Narrative: [docs/STORY.md](docs/STORY.md) · Security map: [docs/OWASP_RAG_CI_MAP.md](docs/OWASP_RAG_CI_MAP.md)

---

## Install

```bash
pip install sentinelrag
# or
uv add sentinelrag
```

Dev clone:

```bash
git clone https://github.com/prakash888kp/SentinelRAG.git
cd SentinelRAG
uv sync --extra dev
cp .env.example .env
```

---

## Out of the box (no API keys)

```bash
uv run pytest
uv run sentinelrag-gate run --refresh
uv run sentinelrag-gate demo-poison
uv run sentinelrag-gate scan data/public_corpus --fail-on high
```

| Command | What it does |
|---------|----------------|
| `sentinelrag-gate run` | Policy gate → `evidence.json`, JUnit, SARIF, summary |
| `sentinelrag-gate collect` | Anchor baseline evidence |
| `sentinelrag-gate compare` | Metric deltas between evidence files |
| `sentinelrag-gate scan` | Pre-ingest hygiene (injection / secret-like / PII-like) |
| `sentinelrag-gate demo-poison` | Poison ASR story (ingest + post-retrieval) |

Artifacts: `.sentinelrag/gate/` · Policy: `config/gate_policy.yaml`

### Drop into any GitHub repo

```yaml
- uses: prakash888kp/SentinelRAG/.github/actions/sentinelrag-gate@v0.2.0
  with:
    refresh: "true"
```

---

## What problem this solves

Teams on Reddit / LocalLLaMA / RAG ops repeatedly ask for:

1. **Golden-set retrieval regression** (recall / hit-rate / MRR) separate from generation  
2. **CI that fails on quality drops** vs a committed baseline  
3. **Pre-ingest hygiene** before vectors land in the index  
4. **Poison / indirect injection probes** in the same pipeline as eval  
5. **Audit artifacts** (JSON evidence, JUnit, SARIF) — not log spam  

SentinelRAG ships that stack **offline by default** (MockLLM / MockEmbedder).

```mermaid
flowchart LR
  CORPUS[Corpus] --> HYG[Hygiene scan]
  HYG --> PROV[Provenance manifest]
  PROV --> ING[Ingest defenses]
  ING --> RET[Naive / Hybrid / Agentic]
  RET --> TRIM[Post-retrieval trim]
  TRIM --> GEN[Generation]
  RET & GEN & HYG --> GATE[sentinelrag-gate]
  GATE --> ART[Evidence · JUnit · SARIF]
```

---

## Results (mock, seed 42)

Committed under `benchmarks/`:

- Mini + public corpus: hybrid **recall@k = 1.0** (also hit-rate + latency)  
- Phase 2 mock judges: faithfulness / relevance gated  
- Poison v1 + red-team defense probes  
- Hygiene report + corpus SHA-256 manifest  

---

## Layout

```
src/sentinelrag/
  api/           FastAPI service
  ingest/        loaders, chunking, hygiene, provenance, filters
  retrieval/     BM25, hybrid, agentic, stores
  router/        complexity + cost policy
  eval/          metrics, judges, golden I/O, latency
  redteam/       attacks, defenses, post-retrieval, harness
  gate/          evidence, policy, CLI, SARIF/JUnit
  generation/    MockLLM + providers
  observability/ cost + OTel
benchmarks/      reproducible JSON + plots
config/          eval_thresholds.yaml · gate_policy.yaml
data/            mini_corpus · public_corpus · golden.jsonl
```

---

## API demo

```bash
docker compose up --build -d
curl -s http://127.0.0.1:8000/health
curl -s -X POST http://127.0.0.1:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query":"What is triple-gate RAG?", "strategy":"auto"}'
```

---

## Docs

[CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [CHANGELOG](CHANGELOG.md) · [COMPARISON](docs/COMPARISON.md) · [POISON_BENCHMARK_v1](docs/POISON_BENCHMARK_v1.md)

## License

MIT
