# hi-oss-ai-red-teaming
**A platform for running human-centered red teaming evaluations on AI models and systems.**
[](https://github.com/humane-intelligence/hi-oss-ai-red-teaming/actions/workflows/ci.yml)
[](https://github.com/humane-intelligence/hi-oss-ai-red-teaming/actions/workflows/cd.yml)
[](LICENSE)
[](backend/pyproject.toml)
[](backend/README.md)
[](frontend/README.md)
[](docker-compose.yml)
## What it does
This software is a web application designed to red team AI models or systems. AI red teaming is a
semi-structured testing approach to assess and improve the safety and effectiveness of AI models and
systems by identifying vulnerabilities, limitations, and potential areas for improvement. This
platform is the software to connect human red teamers with the AI models and systems, and keep the
records that make the findings reviewable afterwards. This software is designed to:
- **Be a gateway to any provider.** A model can be registered once in a software instance, including
the endpoint, credentials, inference parameters — and reached through a single adapter, so a
red-teamer never handles an API key. Keys are encrypted at rest; replies stream back token by token
over SSE.
- **Structure according to the engagement.** Evaluation groups → evaluations → scenarios → tasks,
under a publication lifecycle (`draft → pending approval → approved → published`) that refuses to
open an engagement still carrying gaps.
- **Create a record worth reviewing.** Conversations are captured in full, and message-level flags,
reviewer verdicts and annotator notes turn a raw transcript into assessed findings.
- **Provide access control that survives an audit.** Global roles plus per-object roles inside a
single group, an append-only audit trail, and a data licence that can seal conversation content at
rest.
- **Show a record of the system.** Asynchronous exports, plus metrics and dashboards over a whole
event or one evaluation.
This is a monorepo: a Python/FastAPI red-teaming **backend** and its React/Vite operator
**frontend**, coupled by the OpenAPI contract.
| Directory | What lives there |
|---|---|
| [`backend/`](backend/README.md) | The API, the Celery workers, and the data model |
| [`frontend/`](frontend/README.md) | The operator console, on a typed client generated from the backend contract |
| [`deploy/`](deploy/README.md) | The dev environment — CD, the box, infrastructure as code, and who needs which permission to ship |
| [`monitoring/`](monitoring/README.md) | The observability stack — Prometheus, Loki, Grafana, GlitchTip |
## Quickstart
The host needs Docker, make, and [uv](https://docs.astral.sh/uv/) — uv provisions Python and runs the
backend's tooling; the frontend toolchain stays in its container, so no Node.
```bash
make setup # first run: deps, hooks, migrate, seed, FE install, backend/.env
make dev # bring up the whole stack
```
- Operator console —
- API docs (Swagger) —
`make be-` and `make fe-` delegate to the subsystem Makefiles; `make help` lists the
root targets.
## Documentation
This page is the entry point; the depth is under [`backend/docs/`](backend/docs/).
| Where | What |
|---|---|
| [Knowledge base](backend/docs/knowledge-base/README.md) | The backend in plain English — architecture, data models, components, end-to-end flows. Hand-written; renders on GitHub, opens as an Obsidian vault |
| [`openapi.yaml`](backend/docs/openapi.yaml) | The API contract, dumped from the running app and drift-checked in CI. Browsable at `/docs` once the stack is up |
| [`erd.md`](backend/docs/erd.md) | Every table, column and foreign key as a Mermaid ERD, generated from the models |
| [`permissions.md`](backend/docs/permissions.md) | Every role against every permission, generated from the RBAC definitions |
| [Postman collections](backend/docs/postman/README.md) | A generated mirror of the API, plus hand-authored collections that drive whole flows end to end |
Setup and the conventions of each subsystem stay in the subsystem READMEs linked above.
## Contributing
The setup, the contract loop between backend and frontend, and the gates a PR has to pass are in
[CONTRIBUTING.md](CONTRIBUTING.md). Security problems take the private route in
[SECURITY.md](SECURITY.md) — never a public issue. Participation is under the
[Code of Conduct](CODE_OF_CONDUCT.md). The project is licensed under [Apache 2.0](LICENSE), except
for the documentation — every Markdown file here — which is licensed under
[CC-By-4.0](LICENSE-docs).
## Disclaimer - Creating Your Own Instance
This codebase does not include any template terms of service, acceptable use policy, privacy policy, or data handling agreements. Anyone who forks or deploys this codebase — including for use with third parties — is solely responsible for establishing their own terms of service, acceptable use policy, privacy practices, and data agreements appropriate to their deployment and regulatory environment. Humane Intelligence assumes no liability for how the codebase is used, configured, or deployed by others.
The codebase is licensed under the Apache 2.0 license only. This disclaimer supplements that license and does not modify, limit, or add restrictions to the rights the Apache 2.0 license grants. While the Apache 2.0 license does not place limits on how you may use the codebase, Humane Intelligence’s mission is to responsibly enable AI deployment for social good, and to that end, we encourage use of this codebase to advance social good and mitigate harm.
