chore(docs): Add Pydantic models

backend/app/api/docs/guardrails/create_ban_list.md

@@ -0,0 +1,34 @@
+Create a ban list — a named set of words the `ban_list` validator redacts from text.
+
+A ban list is stored by the guardrails service and scoped to the calling project. Reference it from a validator config by setting that config's `ban_list_id` to the `id` returned here.
+
+### Request
+
+```json
+{
+  "name": "Safety Banned Terms",
+  "description": "Terms not allowed for this tenant policy",
+  "domain": "abuse",
+  "is_public": false,
+  "banned_words": ["slur_a", "slur_b"]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | 1–100 chars. Must be unique for the project. |
+| `description` | string | yes | 1–500 chars. |
+| `banned_words` | string[] | yes | Up to 1000 entries, each 1–100 chars. |
+| `domain` | string | yes | Free-form grouping label used to filter on list. |
+| `is_public` | boolean | no | Defaults to `false`. |
+
+### Notes
+
+- `is_public: true` makes the list readable by other tenants. Updating and deleting stay restricted to the owning project regardless.
+- The response is `200`, not `201` — the guardrails service does not use `201`.
+
+### Errors
+
+- `400` — a ban list with this configuration already exists.
+- `422` — the body failed validation.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/create_llm_prompt_config.md

@@ -0,0 +1,49 @@
+Create a stored prompt for one of the LLM-backed validators.
+
+Two validators read their instructions from a stored prompt instead of hard-coding them: `topic_relevance` (does this text stay on topic?) and `answer_relevance_custom_llm` (does this answer address the question?). Create the prompt here, then reference its `id` from the matching validator config.
+
+### Request
+
+```json
+{
+  "validator_name": "topic_relevance",
+  "name": "Maternal Health Scope",
+  "description": "Topic guard for maternal health support bot",
+  "prompt_schema_version": 1,
+  "llm_prompt": "Pregnancy care: Questions about prenatal care, ANC visits, nutrition, supplements, danger signs. Postpartum care: Questions about recovery after delivery, breastfeeding, and mother health checks."
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `validator_name` | enum | yes | `topic_relevance` or `answer_relevance_custom_llm`. Immutable after creation. |
+| `name` | string | yes | 1–100 chars. |
+| `description` | string | yes | 1–500 chars. |
+| `prompt_schema_version` | integer | no | Defaults to `1`. Must be >= 1. |
+| `llm_prompt` | string | yes | The prompt text. Non-empty. |
+
+### Placeholders
+
+For `answer_relevance_custom_llm` the prompt **must** contain both `{query}` and `{answer}`; the service rejects it otherwise. Example:
+
+```
+You are evaluating a maternal health assistant.
+Query: {query}
+Answer: {answer}
+
+Does the answer directly address the maternal health query?
+Answer only YES or NO.
+```
+
+`topic_relevance` prompts have no required placeholders.
+
+### Notes
+
+- New configs are created active. `is_active` can only be changed via `PATCH`.
+- Responds `200`, not `201`.
+
+### Errors
+
+- `400` — a config with the same validator, version and prompt text already exists.
+- `422` — the body failed validation, or an `answer_relevance_custom_llm` prompt was missing `{query}`/`{answer}`.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/create_validator_config.md

@@ -0,0 +1,43 @@
+Register a validator configuration — a named, reusable validator setup that `POST /guardrails` applies by id.
+
+This is the object you point at from a guardrails run: create one here, then pass its `id` as a `validator_config_id` in the `config` array of `POST /guardrails`.
+
+### Request
+
+The body is a fixed set of base fields **plus** whatever tuning keys the chosen validator type accepts. Call `GET /guardrails` to discover the accepted keys per type.
+
+```json
+{
+  "name": "PII Redaction Input",
+  "type": "pii_remover",
+  "stage": "input",
+  "on_fail_action": "fix",
+  "is_enabled": true,
+  "entity_types": ["PERSON", "PHONE_NUMBER", "IN_AADHAAR"],
+  "threshold": 0.6
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | 5–225 chars. |
+| `type` | enum | yes | One of the validator types from `GET /guardrails`. |
+| `stage` | enum | yes | `input` or `output`. |
+| `on_fail_action` | enum | no | `exception` \| `fix` \| `rephrase`. Defaults to `fix`. |
+| `is_enabled` | boolean | no | Defaults to `true`. |
+| *(extra keys)* | any | no | Validator-specific tuning, stored as the config blob. |
+
+In the example above, `entity_types` and `threshold` are `pii_remover` tuning keys — they are not part of the base schema, which is why Swagger shows them as additional properties rather than named fields.
+
+### Notes
+
+- **Uniqueness is enforced on `name` alone**, scoped to the project. The same validator type may be registered many times under different names.
+- `stage` is advisory. `POST /guardrails` routes on the text it is actually given, not on this field, so one config can serve both directions.
+- Do **not** send `organization_id` or `project_id`. The tenant is derived from your authenticated context, and the guardrails service rejects those keys in the body.
+- Responds `200`, not `201`.
+
+### Errors
+
+- `400` — a validator config with this name already exists in the project.
+- `422` — the body failed validation, or it contained `organization_id`/`project_id`.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_ban_list.md

@@ -0,0 +1,12 @@
+Delete a ban list permanently. Restricted to the owning project.
+
+Validator configs that still reference the deleted list by `ban_list_id` are not cleaned up; they will fail when the guardrails service next tries to resolve the list.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `403` — the list belongs to another tenant.
+- `404` — no such ban list.
+- `422` — `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_llm_prompt_config.md

@@ -0,0 +1,11 @@
+Delete a stored LLM prompt config permanently, scoped to the calling project.
+
+Validator configs that still reference the deleted prompt will fail when the guardrails service next tries to resolve it. Repoint or remove them first.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `prompt_config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_validator_config.md

@@ -0,0 +1,11 @@
+Delete a validator config permanently, scoped to the calling project.
+
+Guardrails runs that still pass the deleted `validator_config_id` will no longer resolve it. Remove the id from your `POST /guardrails` calls first.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_ban_list.md

@@ -0,0 +1,10 @@
+Fetch a single ban list by id.
+
+Readable if the list belongs to the calling project, or if it belongs to another tenant and is marked `is_public`.
+
+### Errors
+
+- `403` — the list belongs to another tenant and is not public.
+- `404` — no such ban list.
+- `422` — `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_guardrails_job.md

@@ -0,0 +1,28 @@
+Poll a guardrails job for its status and sanitised result.
+
+Use this when you submitted `POST /guardrails` without a `callback_url`, or to inspect a completed job for traceability. The job id comes from the `POST /guardrails` response.
+
+### Status values
+
+| `status` | Meaning |
+|---|---|
+| `PENDING` | Queued, not yet picked up. |
+| `PROCESSING` | A worker is applying the validators. |
+| `SUCCESS` | Finished; `guardrails_response` carries the sanitised text. |
+| `FAILED` | The text was hard-blocked, or the job errored. `error_message` explains why. |
+
+### Response
+
+`guardrails_response` is populated only on `SUCCESS`; it is `null` in every other state. The sanitised text sits at `guardrails_response.response.output.content.value`.
+
+`warnings` mirrors the `metadata.warnings` of the webhook payload, so polling callers do not miss a bypass signal — most importantly the case where the guardrails service was unavailable and the original text was returned unchanged. It is always empty for a hard-blocked job.
+
+### Notes
+
+- If the upstream response carried no sanitised text, the value falls back to the original submitted text.
+- `usage` counters default to zero when the guardrails service reports none.
+
+### Errors
+
+- `404` — no such job in this project, or the id belongs to a job that is not a guardrails job.
+- `422` — `job_id` is not a valid UUID.

backend/app/api/docs/guardrails/get_llm_prompt_config.md

@@ -0,0 +1,7 @@
+Fetch a single LLM prompt config by id, scoped to the calling project.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `prompt_config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_validator_config.md

@@ -0,0 +1,9 @@
+Fetch a single validator config by id, scoped to the calling project.
+
+The response is the stored row flattened together with its validator-specific tuning config, so it carries keys beyond the declared schema — `id`, `organization_id`, `project_id`, `created_at`, `updated_at`, and every tuning key for that validator type.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_ban_lists.md

@@ -0,0 +1,16 @@
+List the ban lists visible to the calling project.
+
+Returns lists owned by the project plus any list from another tenant marked `is_public`. Ordered newest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `domain` | string | no | — | Return only lists carrying this domain label. |
+| `offset` | integer | no | `0` | Rows to skip. Must be >= 0. |
+| `limit` | integer | no | — | Max rows to return, 1–100. Omit for no limit. |
+
+### Errors
+
+- `422` — `offset` is negative, or `limit` is outside 1–100.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_llm_prompt_configs.md

@@ -0,0 +1,14 @@
+List the stored LLM prompt configs belonging to the calling project, oldest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `validator_name` | enum | no | — | `topic_relevance` or `answer_relevance_custom_llm`. |
+| `offset` | integer | no | `0` | Rows to skip. Must be >= 0. |
+| `limit` | integer | no | — | Max rows to return, 1–100. Omit for no limit. |
+
+### Errors
+
+- `422` — `validator_name` is not a recognised value, `offset` is negative, or `limit` is outside 1–100.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_validator_configs.md

@@ -0,0 +1,20 @@
+List the validator configs belonging to the calling project, oldest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `ids` | UUID | no | — | Repeat the parameter to fetch several by id (`?ids=A&ids=B`). |
+| `stage` | enum | no | — | `input` or `output`. |
+| `type` | enum | no | — | A validator type from `GET /guardrails`. |
+
+This route is not paginated.
+
+### Response
+
+Each item is the stored row flattened together with its validator-specific tuning config, so entries carry keys beyond the declared schema — `id`, `organization_id`, `project_id`, `created_at`, `updated_at`, and every tuning key for that validator type.
+
+### Errors
+
+- `422` — a value in `ids` is not a valid UUID, or `stage`/`type` is not a recognised value.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_validator_types.md

@@ -0,0 +1,26 @@
+List every validator type the guardrails service supports, together with the JSON Schema of the tuning fields each one accepts.
+
+Use this to discover what to put in the body of `POST /guardrails/validators/configs`: the `config` schema of an entry tells you exactly which extra keys that validator type understands.
+
+### Response shape
+
+This is the one guardrails route that is **not** wrapped in the standard `APIResponse` envelope. The body is a bare object with one entry per supported validator type (abridged — `config` is a full JSON Schema generated from the service's own model, so it is always current):
+
+```json
+{
+  "validators": [
+    {"type": "pii_remover", "config": { "...JSON Schema..." }},
+    {"type": "uli_slur_match", "config": { "...JSON Schema..." }}
+  ]
+}
+```
+
+### Validator types
+
+`uli_slur_match`, `pii_remover`, `gender_assumption_bias`, `ban_list`, `topic_relevance`, `topic_relevance_llm`, `llm_critic`, `llamaguard_7b`, `profanity_free`, `nsfw_text`, `answer_relevance_custom_llm`.
+
+Every validator additionally accepts `on_fail` (`exception` | `fix` | `rephrase`, default `fix`) and `stage` (`input` | `output`).
+
+### Errors
+
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/update_ban_list.md

@@ -0,0 +1,22 @@
+Update a ban list. Fields you omit are left unchanged.
+
+`banned_words` is replaced wholesale, not merged — send the full list you want stored.
+
+### Request
+
+```json
+{
+  "description": "Updated description",
+  "banned_words": ["slur_a", "slur_b", "slur_c"]
+}
+```
+
+All five fields (`name`, `description`, `banned_words`, `domain`, `is_public`) are optional and follow the same constraints as on create.
+
+### Errors
+
+- `400` — the update collides with an existing ban list.
+- `403` — the list belongs to another tenant. Public lists are readable but not writable across tenants.
+- `404` — no such ban list.
+- `422` — the body failed validation, or `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/update_llm_prompt_config.md

@@ -0,0 +1,22 @@
+Update a stored LLM prompt config. Fields you omit are left unchanged.
+
+### Request
+
+```json
+{"llm_prompt": "Pregnancy care: Updated scope definition"}
+```
+
+`name`, `description`, `prompt_schema_version`, `llm_prompt` and `is_active` can be patched.
+
+### Notes
+
+- `validator_name` is immutable — it cannot be patched. Create a new config instead.
+- `is_active` is settable only here, not on create.
+- Editing `llm_prompt` on an `answer_relevance_custom_llm` config still requires both `{query}` and `{answer}` placeholders.
+
+### Errors
+
+- `400` — the update collides with an existing config.
+- `404` — no such config, or it belongs to another project.
+- `422` — the body failed validation, the placeholder rule was broken, or `prompt_config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/update_validator_config.md

@@ -0,0 +1,21 @@
+Update a validator config's base fields. Fields you omit are left unchanged.
+
+### Request
+
+```json
+{"stage": "output", "is_enabled": false}
+```
+
+Only `name`, `type`, `stage`, `on_fail_action` and `is_enabled` can be patched.
+
+### Notes
+
+- **Validator-specific tuning cannot be changed here.** The guardrails service rejects any key outside the five base fields, so changing something like `threshold` or `entity_types` means deleting the config and recreating it.
+- Because `POST /guardrails` resolves validators by id at run time, an update takes effect on the next run — there is no versioning.
+
+### Errors
+
+- `400` — the new `name` collides with an existing config in the project.
+- `404` — no such config, or it belongs to another project.
+- `422` — the body contained a key outside the five base fields, a value failed validation, or `config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/openapi_config.py

@@ -27,6 +27,13 @@
         "name": "LLM",
         "description": "Large Language Model inference and interaction endpoints",
     },
+    {
+        "name": "Guardrails",
+        "description": (
+            "Text safety validation: applying guardrails to text, and managing "
+            "the validator configs, ban lists and LLM prompts they run on"
+        ),
+    },
     {
         "name": "Evaluation",
         "description": "Dataset upload, running evaluations, listing datasets as well as evaluations",
@@ -89,6 +96,7 @@
             "Collections",
             "Config Management",
             "LLM",
+            "Guardrails",
             "Evaluation",
             "Fine Tuning",
             "Model Evaluation",