refactor(guardrails): Restrict inline validator types, clarify names

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Author: AkhileshNegi

backend/app/models/llm/request.py

@@ -476,17 +476,23 @@ class Validator(SQLModel):
     )
 
 
+class InlineValidatorTypeEnum(str, Enum):
+    GENDER_ASSUMPTION_BIAS = "gender_assumption_bias"
+    PII_REMOVER = "pii_remover"
+    PROFANITY_FREE = "profanity_free"
+    TOPIC_RELEVANCE_LLM = "topic_relevance_llm"
+
+
 class InlineValidator(SQLModel):
     """Validator spec stored directly in the config blob.
 
-    Per-type params (languages, ban_list_id, ...) are extras validated by the
+    Per-type params (on_fail, languages, ban_list_id, ...) are extras validated by the
     guardrails service, so they are allowed through untouched here.
     """
 
     model_config = ConfigDict(extra="allow")  # pyright: ignore[reportAssignmentType]
 
-    type: str = Field(..., description="Guardrails validator type, e.g. ban_list")
-    on_fail: str | None = Field(default=None, description="Action on failure")
+    type: InlineValidatorTypeEnum = Field(..., description="Guardrails validator type")
     is_enabled: bool = Field(
         default=True,
         description="When false, the spec is kept in the blob but not run.",
@@ -495,10 +501,8 @@ class InlineValidator(SQLModel):
 
 def _guardrail_entry_tag(value: Any) -> str:
     if isinstance(value, dict):
-        has_ref = "validator_config_id" in value
-    else:
-        has_ref = hasattr(value, "validator_config_id")
-    return "ref" if has_ref else "inline"
+        return "ref" if "validator_config_id" in value else "inline"
+    return "ref" if hasattr(value, "validator_config_id") else "inline"
 
 
 # Explicit tag: InlineValidator allows extras, so a smart union could also

backend/app/services/llm/guardrails.py

@@ -58,7 +58,7 @@ def proxy_guardrails_request(
     url = f"{settings.KAAPI_GUARDRAILS_URL}{path}"
     headers = _guardrails_headers(organization_id, project_id)
     # Unset query params must be omitted, not sent as empty values.
-    query = {k: v for k, v in (params or {}).items() if v is not None}
+    query = {key: value for key, value in (params or {}).items() if value is not None}
 
     try:
         with (
@@ -175,20 +175,16 @@ def apply_guardrails(
             output-guardrail validators that compare input/output pairs.
             Also routes the IDs through the output-config fetch path.
     """
-    enabled: list[Validator | InlineValidator] = []
-    for entry in validators or []:
-        if entry.is_enabled:
-            enabled.append(entry)
+    enabled = [validator for validator in validators or [] if validator.is_enabled]
     if not enabled:
         return GuardrailsOutcome(
             safe_text=text, error=None, bypassed=False, rephrase_needed=False, raw={}
         )
 
     is_output = output_text is not None
-    references: list[Validator] = []
-    for entry in enabled:
-        if isinstance(entry, Validator):
-            references.append(entry)
+    references = [
+        validator for validator in enabled if isinstance(validator, Validator)
+    ]
 
     fetched: list[dict[str, Any]] = []
     if references:
@@ -206,7 +202,7 @@ def apply_guardrails(
         logger.info(
             f"[apply_guardrails] No validator configs resolved upstream; skipping "
             f"POST /guardrails. job_id={job_id}, requested_ids="
-            f"{[str(v.validator_config_id) for v in references]}, "
+            f"{[str(reference.validator_config_id) for reference in references]}, "
             f"is_output={is_output}"
         )
         return GuardrailsOutcome(
@@ -271,9 +267,6 @@ def _prepare_validators(
         if isinstance(entry, InlineValidator):
             # The service's validator configs are extra="forbid", so is_enabled must go.
             spec = entry.model_dump(mode="json", exclude={"is_enabled"})
-            # Service's on_fail is non-nullable; omitting it applies its default.
-            if spec.get("on_fail") is None:
-                spec.pop("on_fail", None)
             spec["stage"] = stage
             prepared.append(spec)
             continue
@@ -312,7 +305,7 @@ def summarize_validator_results(outcome: GuardrailsOutcome) -> list[dict[str, An
 
 def run_guardrails_validation(
     input_text: str,
-    guardrail_config: Sequence[Validator | InlineValidator | dict[str, Any]],
+    guardrail_config: Sequence[Validator | dict[str, Any]],
     job_id: UUID,
     project_id: int | None,
     organization_id: int | None,
@@ -335,13 +328,13 @@ def run_guardrails_validation(
     Returns:
         JSON response from the guardrails service with validation results.
     """
-    validators: list[dict[str, Any]] = []
-    for validator in guardrail_config:
-        if isinstance(validator, dict):
-            validators.append(validator)
-        else:
-            # Unknown to the service's extra="forbid" validator schemas.
-            validators.append(validator.model_dump(mode="json", exclude={"is_enabled"}))
+    # is_enabled is unknown to the service's extra="forbid" validator schemas.
+    validators = [
+        validator
+        if isinstance(validator, dict)
+        else validator.model_dump(mode="json", exclude={"is_enabled"})
+        for validator in guardrail_config
+    ]
 
     payload = {
         "request_id": str(job_id),

backend/app/tests/models/llm/test_request.py

@@ -1,5 +1,8 @@
 from uuid import uuid4
 
+import pytest
+from pydantic import ValidationError
+
 from app.models.llm.request import (
     ConfigBlob,
     InlineValidator,
@@ -98,13 +101,19 @@ def test_dict_with_config_id_parses_to_validator(self) -> None:
 
     def test_dict_with_type_parses_to_inline_and_keeps_extras(self) -> None:
         blob = _blob(
-            [{"type": "ban_list", "on_fail": "fix", "languages": ["en", "hi"]}]
+            [
+                {
+                    "type": "topic_relevance_llm",
+                    "on_fail": "fix",
+                    "languages": ["en", "hi"],
+                }
+            ]
         )
 
         (entry,) = blob.input_guardrails or []
         assert isinstance(entry, InlineValidator)
         assert entry.model_dump() == {
-            "type": "ban_list",
+            "type": "topic_relevance_llm",
             "on_fail": "fix",
             "is_enabled": True,
             "languages": ["en", "hi"],
@@ -123,6 +132,10 @@ def test_ref_dict_carrying_type_still_parses_to_validator(self) -> None:
             "is_enabled": True,
         }
 
+    def test_unsupported_inline_type_is_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            _blob([{"type": "ban_list"}])
+
     def test_revalidating_parsed_entries_keeps_types(self) -> None:
         parsed = _blob(
             [{"validator_config_id": str(uuid4())}, {"type": "pii_remover"}]

backend/app/tests/services/llm/test_guardrails.py

@@ -475,7 +475,7 @@ def test_disabled_entries_are_neither_fetched_nor_posted(
             [
                 disabled_ref,
                 enabled_ref,
-                InlineValidator(type="off_inline", is_enabled=False),
+                InlineValidator(type="profanity_free", is_enabled=False),
             ]
         )
 
@@ -522,12 +522,19 @@ def test_posts_in_blob_order_not_fetch_order(self, mock_fetch, mock_run) -> None
         mock_fetch.return_value = ([row_y, row_x], [])
         mock_run.return_value = _PASS_RESPONSE
 
-        _apply([InlineValidator(type="a"), ref_x, InlineValidator(type="b"), ref_y])
+        _apply(
+            [
+                InlineValidator(type="profanity_free"),
+                ref_x,
+                InlineValidator(type="pii_remover"),
+                ref_y,
+            ]
+        )
 
         assert mock_run.call_args.args[1] == [
-            {"type": "a", "stage": "input"},
+            {"type": "profanity_free", "stage": "input"},
             row_x,
-            {"type": "b", "stage": "input"},
+            {"type": "pii_remover", "stage": "input"},
             row_y,
         ]
 
@@ -536,13 +543,21 @@ def test_inline_spec_posted_shape(self, mock_fetch, mock_run) -> None:
 
         _apply(
             [
-                InlineValidator(type="ban_list", stage="output", banned_words=["x"]),
+                InlineValidator(
+                    type="gender_assumption_bias",
+                    stage="output",
+                    categories=["healthcare"],
+                ),
                 InlineValidator(type="pii_remover", on_fail="exception"),
             ]
         )
 
         assert mock_run.call_args.args[1] == [
-            {"type": "ban_list", "stage": "input", "banned_words": ["x"]},
+            {
+                "type": "gender_assumption_bias",
+                "stage": "input",
+                "categories": ["healthcare"],
+            },
             {"type": "pii_remover", "on_fail": "exception", "stage": "input"},
         ]
 

docs/wiki/modules/llm-call.md

@@ -26,7 +26,7 @@ All paths relative to `backend/app/`.
 
 ## Key pydantic/SQLModel schemas (`models/llm/request.py`)
 - `LLMCallConfig` — one-of: saved reference (`id` + `version`) XOR ad-hoc `blob` (validator-enforced)
-- `ConfigBlob` — `completion` + optional `prompt_template` (`PromptTemplate.template`, plain string; `{{input}}` interpolation is llm-chain-only) + `input_guardrails`/`output_guardrails`. Each guardrail entry is either a `Validator` reference (`{validator_config_id}`) or an `InlineValidator` spec (`{type, on_fail, ...per-type params}`); tagged union `GuardrailEntry`. Both carry `is_enabled` (default true). Disabled entries are never fetched or sent. `services/llm/guardrails._prepare_validators` POSTs the rest in blob order, with `is_enabled` stripped and `stage` stamped on inline specs.
+- `ConfigBlob` — `completion` + optional `prompt_template` (`PromptTemplate.template`, plain string; `{{input}}` interpolation is llm-chain-only) + `input_guardrails`/`output_guardrails`. Each guardrail entry is either a `Validator` reference (`{validator_config_id}`) or an `InlineValidator` spec (`{type, on_fail, ...per-type params}`, `type` limited to `InlineValidatorTypeEnum`: gender_assumption_bias, pii_remover, profanity_free, topic_relevance_llm); tagged union `GuardrailEntry`. Both carry `is_enabled` (default true). Disabled entries are never fetched or sent. `services/llm/guardrails._prepare_validators` POSTs the rest in blob order, with `is_enabled` stripped and `stage` stamped on inline specs.
 - `CompletionConfig` — discriminated union on `provider`: `KaapiCompletionConfig` (standardized params: `TextLLMParams`/`STTLLMParams`/`TTSLLMParams`), `NativeCompletionConfig` (pass-through), `ProxyCompletionConfig` (client's own endpoint)
 - `TextLLMParams` reasoning knobs: `reasoning` + `effort` (OpenAI-style), `thinking` (Anthropic adaptive-thinking container, forwarded as-is) and `thinking_level` (Gemini). A knob must be **declared here** to survive config save — pydantic's default extra policy is ignore, so an undeclared key is dropped silently at validation with no error.
 - `QueryParams` — per-call input + `ConversationConfig`