Validator: Answer relevance custom LLM judge

backend/app/alembic/versions/008_add_answer_relevance_prompt.py

@@ -0,0 +1,53 @@
+"""Add answer_relevance_prompt table
+
+Revision ID: 008
+Revises: 007
+Create Date: 2026-05-08 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "008"
+down_revision = "007"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "answer_relevance_prompt",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("organization_id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.String(), nullable=False),
+        sa.Column("prompt_template", sa.Text(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    op.create_index(
+        "idx_answer_relevance_prompt_org",
+        "answer_relevance_prompt",
+        ["organization_id"],
+    )
+    op.create_index(
+        "idx_answer_relevance_prompt_project",
+        "answer_relevance_prompt",
+        ["project_id"],
+    )
+    op.create_index(
+        "idx_answer_relevance_prompt_is_active",
+        "answer_relevance_prompt",
+        ["is_active"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("answer_relevance_prompt")

backend/app/api/API_USAGE.md

@@ -7,6 +7,7 @@ This guide explains how to use the current API surface for:
 - Guardrail execution
 - Ban list CRUD for multi-tenant projects
 - Topic relevance config CRUD for multi-tenant projects
+- Answer relevance prompt config CRUD for multi-tenant projects
 
 ## Base URL and Version
 
@@ -184,8 +185,8 @@ Request fields:
 Important:
 - Runtime validators use `on_fail`.
 - If you pass objects from config APIs, server normalization supports `on_fail_action` and strips non-runtime fields.
-- For `topic_relevance`, pass `topic_relevance_config_id` only.
-- The API resolves `configuration` + `prompt_schema_version` in `guardrails.py` before validator execution, so the validator always executes with both values.
+- For `topic_relevance`, pass `topic_relevance_config_id` only. The API resolves `configuration` + `prompt_schema_version` in `guardrails.py` before validator execution.
+- For `answer_relevance_custom_llm`, `input` must be a JSON string `{"query": "...", "answer": "..."}`. Pass `custom_prompt_id` to use a stored tenant prompt, or omit to use the built-in default prompt.
 
 Example:
 
@@ -421,7 +422,84 @@ curl -X DELETE "http://localhost:8001/api/v1/guardrails/topic_relevance_configs/
   -H "X-API-KEY: <api-key>"
 ```
 
-## 7) End-to-End Usage Pattern
+## 7) Answer Relevance Prompt APIs (multi-tenant)
+
+These endpoints manage tenant-scoped custom prompt templates for the `answer_relevance_custom_llm` validator and use `X-API-KEY` auth.
+
+Base path:
+- `/api/v1/guardrails/answer_relevance_prompts`
+
+## 7.1 Create answer relevance prompt
+
+Endpoint:
+- `POST /api/v1/guardrails/answer_relevance_prompts/`
+
+Example:
+
+```bash
+curl -X POST "http://localhost:8001/api/v1/guardrails/answer_relevance_prompts/" \
+  -H "X-API-KEY: <api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Maternal Health Relevance",
+    "description": "Checks if LLM answer addresses a maternal health query",
+    "prompt_template": "You are evaluating a maternal health assistant.\nQuery: {query}\nAnswer: {answer}\n\nDoes the answer directly address the maternal health query with accurate information?\nAnswer only YES or NO."
+  }'
+```
+
+## 7.2 List answer relevance prompts
+
+Endpoint:
+- `GET /api/v1/guardrails/answer_relevance_prompts/?offset=0&limit=20`
+
+Example:
+
+```bash
+curl -X GET "http://localhost:8001/api/v1/guardrails/answer_relevance_prompts/?offset=0&limit=20" \
+  -H "X-API-KEY: <api-key>"
+```
+
+## 7.3 Get answer relevance prompt by id
+
+Endpoint:
+- `GET /api/v1/guardrails/answer_relevance_prompts/{id}`
+
+Example:
+
+```bash
+curl -X GET "http://localhost:8001/api/v1/guardrails/answer_relevance_prompts/<prompt_id>" \
+  -H "X-API-KEY: <api-key>"
+```
+
+## 7.4 Update answer relevance prompt
+
+Endpoint:
+- `PATCH /api/v1/guardrails/answer_relevance_prompts/{id}`
+
+Example:
+
+```bash
+curl -X PATCH "http://localhost:8001/api/v1/guardrails/answer_relevance_prompts/<prompt_id>" \
+  -H "X-API-KEY: <api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt_template": "Query: {query}\nAnswer: {answer}\n\nIs this answer helpful and relevant?\nAnswer only YES or NO."
+  }'
+```
+
+## 7.5 Delete answer relevance prompt
+
+Endpoint:
+- `DELETE /api/v1/guardrails/answer_relevance_prompts/{id}`
+
+Example:
+
+```bash
+curl -X DELETE "http://localhost:8001/api/v1/guardrails/answer_relevance_prompts/<prompt_id>" \
+  -H "X-API-KEY: <api-key>"
+```
+
+## 8) End-to-End Usage Pattern
 
 Recommended request flow:
 1. Create/update validator configs via `/guardrails/validators/configs`.
@@ -431,15 +509,16 @@ Recommended request flow:
 5. If `rephrase_needed=true`, ask user to rephrase.
 6. For `ban_list` validators without inline `banned_words`, create/manage a ban list first and pass `ban_list_id`.
 7. For `topic_relevance`, create/manage a topic relevance config and pass `topic_relevance_config_id` at runtime. The server resolves the configuration string internally.
+8. For `answer_relevance_custom_llm`, format `input` as `{"query": "...", "answer": "..."}`. Optionally create a custom prompt via the Answer Relevance Prompt APIs and pass `custom_prompt_id`. If no `custom_prompt_id` is given, the built-in default prompt is used.
 
-## 8) Common Errors
+## 9) Common Errors
 
 - `401 Missing Authorization header`
   - Add `Authorization: Bearer <token>`.
 - `401 Invalid authorization token`
   - Verify plaintext token matches server-side hash.
 - `401 Missing X-API-KEY header`
-  - Add `X-API-KEY: <api-key>` for ban list and topic relevance config endpoints.
+  - Add `X-API-KEY: <api-key>` for ban list, topic relevance config, and answer relevance prompt endpoints.
 - `401 Invalid API key`
   - Verify the API key is valid in the upstream Kaapi auth service.
 - `Invalid request_id`
@@ -450,8 +529,10 @@ Recommended request flow:
   - Confirm `id`, `organization_id`, and `project_id` match.
 - `Topic relevance preset not found`
   - Confirm topic relevance config `id` exists within your tenant scope.
+- `Answer relevance prompt not found`
+  - Confirm the answer relevance prompt `id` exists within your tenant scope.
 
-## 9) Current Validator Types
+## 10) Current Validator Types
 
 From `validators.json`:
 - `uli_slur_match`
@@ -463,6 +544,7 @@ From `validators.json`:
 - `llamaguard_7b`
 - `profanity_free`
 - `nsfw_text`
+- `answer_relevance_custom_llm`
 
 Source of truth:
 - `backend/app/core/validators/validators.json`

backend/app/api/docs/answer_relevance_prompts/create_prompt.md

@@ -0,0 +1,43 @@
+Creates an answer relevance prompt config for the tenant resolved from `X-API-KEY`.
+
+Behavior notes:
+- Stores a custom prompt template used by the `answer_relevance_custom_llm` validator to evaluate whether an LLM answer is relevant to a user query.
+- Tenant scope is enforced from the API key context.
+- `prompt_template` must contain both `{query}` and `{answer}` placeholders; the server rejects templates missing either.
+
+Common failure cases:
+- Missing or invalid API key.
+- Payload schema validation errors.
+- `prompt_template` is missing `{query}` or `{answer}` placeholder.
+
+## Field glossary
+
+**`prompt_template`**
+A string with `{query}` and `{answer}` placeholders. At validation time, the guardrail substitutes the user's query and the LLM's answer, then asks the model to respond `YES` (relevant) or `NO` (not relevant).
+
+Default template used when no custom prompt is configured:
+```
+Query: {query}
+Answer: {answer}
+
+Does the answer fully satisfy the query and constraints?
+Answer only YES or NO.
+```
+
+NGOs can customise this to add domain-specific constraints, language preferences, or stricter relevance criteria for their use case.
+
+Example custom template:
+```
+You are evaluating a maternal health assistant.
+Query: {query}
+Answer: {answer}
+
+Does the answer directly address the maternal health query with accurate information?
+Answer only YES or NO.
+```
+
+**`name`**
+Human-readable label for this prompt config (max 100 characters).
+
+**`description`**
+What this prompt evaluates (max 500 characters).

backend/app/api/docs/answer_relevance_prompts/delete_prompt.md

@@ -0,0 +1,10 @@
+Deletes an answer relevance prompt config by id for the tenant resolved from `X-API-KEY`.
+
+Behavior notes:
+- Tenant scope is enforced from the API key context.
+- Deletion is permanent; any guardrail configs referencing this `custom_prompt_id` will fail to resolve at runtime after deletion.
+
+Common failure cases:
+- Missing or invalid API key.
+- Prompt config not found in tenant's scope.
+- Invalid id format.

backend/app/api/docs/answer_relevance_prompts/get_prompt.md

@@ -0,0 +1,9 @@
+Fetches a single answer relevance prompt config by id for the tenant resolved from `X-API-KEY`.
+
+Behavior notes:
+- Tenant scope is enforced: only configs belonging to the resolved `organization_id` and `project_id` are accessible.
+
+Common failure cases:
+- Missing or invalid API key.
+- Prompt config not found in tenant's scope.
+- Invalid id format.

backend/app/api/docs/answer_relevance_prompts/list_prompts.md

@@ -0,0 +1,12 @@
+Lists answer relevance prompt configs for the tenant resolved from `X-API-KEY`.
+
+Behavior notes:
+- Returns all prompt configs scoped to the tenant's `organization_id` and `project_id`.
+- Supports pagination via `offset` and `limit`.
+- `offset` defaults to `0`.
+- `limit` is optional; when omitted, no limit is applied.
+- Results are ordered by `created_at` ascending, then `id`.
+
+Common failure cases:
+- Missing or invalid API key.
+- Invalid pagination values.

backend/app/api/docs/answer_relevance_prompts/update_prompt.md

@@ -0,0 +1,12 @@
+Partially updates an answer relevance prompt config by id for the tenant resolved from `X-API-KEY`.
+
+Behavior notes:
+- Supports patch-style updates; omitted fields remain unchanged.
+- Tenant scope is enforced from the API key context.
+- If `prompt_template` is updated, it must still contain both `{query}` and `{answer}` placeholders.
+
+Common failure cases:
+- Missing or invalid API key.
+- Prompt config not found in tenant's scope.
+- Payload schema validation errors.
+- Updated `prompt_template` is missing `{query}` or `{answer}` placeholder.

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

@@ -8,6 +8,7 @@ Behavior notes:
 - For `ban_list`, `ban_list_id` can be resolved to `banned_words` from tenant ban list configs.
 - For `topic_relevance`, `topic_relevance_config_id` is required and is resolved to `configuration` + `prompt_schema_version` from tenant topic relevance configs. Requires `OPENAI_API_KEY` to be configured; returns a validation failure with an explicit error if missing.
 - For `llm_critic`, `OPENAI_API_KEY` must be configured; returns `success=false` with an explicit error if missing.
+- For `answer_relevance_custom_llm`, `input` must be a JSON string `{"query": "...", "answer": "..."}`. Pass `custom_prompt_id` to use a tenant-stored prompt template, or `prompt_template` inline. Requires `OPENAI_API_KEY`.
 - For `llamaguard_7b`, `policies` accepts human-readable policy names (see table below). If omitted, all policies are enforced by default.
 
   | `policies` value            | Policy enforced                  |

backend/app/api/main.py

@@ -1,6 +1,7 @@
 from fastapi import APIRouter
 
 from app.api.routes import (
+    answer_relevance_prompts,
     ban_lists,
     guardrails,
     topic_relevance_configs,
@@ -9,6 +10,7 @@
 )
 
 api_router = APIRouter()
+api_router.include_router(answer_relevance_prompts.router)
 api_router.include_router(ban_lists.router)
 api_router.include_router(guardrails.router)
 api_router.include_router(topic_relevance_configs.router)