Metadata-Version: 2.5
Name: ragfence
Version: 0.1.0
Summary: Security testing and authorization-aware retrieval for production RAG systems.
Author: RAGFence contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: acl,evaluation,pgvector,rag,security
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: alembic<2,>=1.13
Requires-Dist: pgvector<1,>=0.3
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: mypy<3,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8.2; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# RAGFence

Security testing and authorization-aware retrieval for production RAG systems.

RAGFence is a Python library and CLI that helps teams build and verify RAG
pipelines that never leak. It provides authorization-aware retrieval primitives,
a deterministic evaluation engine, and the `generic_http` adapter for testing an
external RAG target.

> **Status: v0.1.0 — production-ready release.** The evaluation and adapter contracts are
> implemented and covered by offline tests. The reference database path is an
> optional Docker-backed check; this repository does not claim a public CI run.

## Quickstart (offline)

Requires Python >= 3.12. The offline quickstart needs no Docker, PostgreSQL,
network access, API keys, or other external services.

```console
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"   # Windows
# source .venv/bin/activate && pip install -e ".[dev]"   # POSIX
```

Check the installed CLI, initialize a local project, and run the deterministic
reference evaluation:

```console
ragfence --help
ragfence init
ragfence test
```

The human-readable report is written to `.ragfence/reports/latest.txt` and the
machine-readable report is written with:

```console
ragfence test --json
```

which writes `.ragfence/reports/latest.json`. Use `--output PATH` to write the
report to an explicit destination. Exit codes are:

- **0 =** completed evaluation meets the configured threshold (gate passed).
- **1 =** completed evaluation is below the threshold (gate failed).
- **2 =** configuration, usage, reachability, or runtime failure.

Run the repository quality gates without Docker or other external services:

```console
python -m pytest
ruff check .
ruff format --check .
mypy
```

### Optional Docker database checks

Docker Compose is optional and only needed for database-backed reference checks.
It starts PostgreSQL 16 with pgvector; it is not required by the offline tests
or the generic HTTP adapter tests:

```console
docker compose up -d
```

Use `ragfence init --up` to start, migrate, seed, and embed the reference DB in
one step. When installed from a wheel (outside this repository), `init --up`
uses the reference environment bundled inside the package — no checkout
required. Use `ragfence adapter check reference` to verify connectivity,
migration state, and seed completeness against a running database.

Safe starting points for configuration are [`examples/reference.toml`](examples/reference.toml)
and [`examples/generic_http.toml`](examples/generic_http.toml). The latter uses
`CHANGEME` and `localhost` placeholders only.

## Production evaluation path

The production reference evaluation executes a declarative control matrix of 8
controls against the reference adapter (DB-resolved identities, RetrievalService
and DbVectorStore/pgvector):

| Control | Category | Expected behavior |
|---|---|---|
| `same-tenant-authorized` | positive | MUST_ALLOW |
| `same-tenant-no-permission` | negative | MUST_BLOCK |
| `cross-tenant` | negative | MUST_BLOCK |
| `cross-department` | negative | MUST_BLOCK |
| `explicit-allowlist` | positive | MUST_ALLOW |
| `soft-deleted-document` | negative | MUST_BLOCK |
| `public-same-tenant` | positive | MUST_ALLOW |
| `insufficient-clearance` | negative | MUST_BLOCK |

Each control result has one of four statuses: **PASS**, **FAIL**,
**INCONCLUSIVE**, or **SKIPPED**. A single `EvaluationGate` fails closed for
required failures, required inconclusive controls, missing coverage, missing
identity/retrieval evidence, target errors, or threshold failure. The gate
reports three scores: `security_score`, `utility_score`, and `overall_score`
(mean of the two, computed over executed required controls only). The JSON
report includes per-control results, the three scores, `gate_passed`,
`gate_reason`, and `outcome` (exactly `"pass"` on healthy runs). The report
declares `real_provider_used: false` because the production matrix path uses no
external provider.

The legacy v0.1 generation-skip semantics (`no_real_provider`) apply only to the
legacy engine path and never to the production matrix path.

## External identity strategies

The `generic_http` adapter represents identity only through explicit
configuration. Two identity strategies are supported:

- **Header templates**: interpolate an allowlisted set of actor placeholders
  (`{actor_user_id}`, `{actor_tenant_id}`, `{actor_department_id}`) into
  configured request headers.
- **Bearer token**: uses the `auth_token` configuration value (set via
  environment variable for secrets).

Identity-dependent controls without a configured strategy are INCONCLUSIVE and
the gate fails. Secrets are redacted from reports, findings, reasons, and
errors.

## Documentation

See the [documentation index](docs/README.md) for the product, technical,
application-flow, schema, implementation-plan, and UI/UX documents.

- [Contributing](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)

## License

Apache License 2.0. See [LICENSE](LICENSE).
