[Guardrails] Banlist API

.env.example

@@ -21,10 +21,6 @@ SENTRY_DSN=
 
 DOCKER_IMAGE_BACKEND=kaapi-guardrails-backend
 
-# Callback Timeouts (in seconds)
-CALLBACK_CONNECT_TIMEOUT=3
-CALLBACK_READ_TIMEOUT=10
-
 # require as a env if you want to use doc transformation
 OPENAI_API_KEY="<ADD-KEY>"
 GUARDRAILS_HUB_API_KEY="<ADD-KEY>"

.env.test.example

@@ -21,10 +21,6 @@ SENTRY_DSN=
 
 DOCKER_IMAGE_BACKEND=kaapi-guardrails-backend
 
-# Callback Timeouts (in seconds)
-CALLBACK_CONNECT_TIMEOUT=3
-CALLBACK_READ_TIMEOUT=10
-
 # require as a env if you want to use doc transformation
 OPENAI_API_KEY="<ADD-KEY>"
 GUARDRAILS_HUB_API_KEY="<ADD-KEY>"

backend/app/alembic/versions/001_added_request_log.py

@@ -23,6 +23,8 @@ def upgrade() -> None:
     op.create_table(
         "request_log",
         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("request_id", sa.Uuid(), nullable=False),
         sa.Column("response_id", sa.Uuid(), nullable=True),
         sa.Column(

backend/app/alembic/versions/002_added_validator_log.py

@@ -23,6 +23,8 @@ def upgrade() -> None:
     op.create_table(
         "validator_log",
         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("request_id", sa.Uuid(), nullable=False),
         sa.Column("name", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
         sa.Column("input", sqlmodel.sql.sqltypes.AutoString(), nullable=False),

backend/app/alembic/versions/004_added_log_indexes.py

@@ -21,19 +21,31 @@ def upgrade() -> None:
     op.create_index("idx_request_log_request_id", "request_log", ["request_id"])
     op.create_index("idx_request_log_status", "request_log", ["status"])
     op.create_index("idx_request_log_inserted_at", "request_log", ["inserted_at"])
+    op.create_index(
+        "idx_request_log_organization_id", "request_log", ["organization_id"]
+    )
+    op.create_index("idx_request_log_project_id", "request_log", ["project_id"])
 
     op.create_index("idx_validator_log_request_id", "validator_log", ["request_id"])
     op.create_index("idx_validator_log_inserted_at", "validator_log", ["inserted_at"])
     op.create_index("idx_validator_log_outcome", "validator_log", ["outcome"])
     op.create_index("idx_validator_log_name", "validator_log", ["name"])
+    op.create_index(
+        "idx_validator_log_organization_id", "validator_log", ["organization_id"]
+    )
+    op.create_index("idx_validator_log_project_id", "validator_log", ["project_id"])
 
 
 def downgrade() -> None:
     op.drop_index("idx_validator_log_inserted_at", table_name="validator_log")
     op.drop_index("idx_validator_log_request_id", table_name="validator_log")
     op.drop_index("idx_validator_log_outcome", table_name="validator_log")
     op.drop_index("idx_validator_log_name", table_name="validator_log")
+    op.drop_index("idx_validator_log_project_id", table_name="validator_log")
+    op.drop_index("idx_validator_log_organization_id", table_name="validator_log")
 
     op.drop_index("idx_request_log_inserted_at", table_name="request_log")
     op.drop_index("idx_request_log_status", table_name="request_log")
     op.drop_index("idx_request_log_request_id", table_name="request_log")
+    op.drop_index("idx_request_log_organization_id", table_name="request_log")
+    op.drop_index("idx_request_log_project_id", table_name="request_log")

backend/app/alembic/versions/005_added_banlist_config.py

@@ -0,0 +1,61 @@
+"""Added ban_list table
+
+Revision ID: 005
+Revises: 004
+Create Date: 2026-02-05 09:42:54.128852
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+from sqlalchemy.dialects import postgresql
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "005"
+down_revision = "004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "ban_list",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.String(), nullable=False),
+        sa.Column("organization_id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.Integer(), nullable=False),
+        sa.Column("domain", sa.String(), nullable=False),
+        sa.Column("is_public", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column(
+            "banned_words",
+            postgresql.ARRAY(sa.String(length=100)),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "name", "organization_id", "project_id", name="uq_banlist_name_org_project"
+        ),
+        sa.CheckConstraint(
+            "coalesce(array_length(banned_words, 1), 0) <= 1000",
+            name="ck_banlist_banned_words_max_items",
+        ),
+    )
+
+    op.create_index("idx_banlist_organization", "ban_list", ["organization_id"])
+    op.create_index("idx_banlist_project", "ban_list", ["project_id"])
+    op.create_index("idx_banlist_domain", "ban_list", ["domain"])
+    op.create_index(
+        "idx_banlist_is_public_true",
+        "ban_list",
+        ["is_public"],
+        postgresql_where=sa.text("is_public = true"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("ban_list")

backend/app/api/main.py

@@ -1,11 +1,12 @@
 from fastapi import APIRouter
 
-from app.api.routes import utils, guardrails, validator_configs
+from app.api.routes import ban_list_configs, guardrails, validator_configs, utils
 
 api_router = APIRouter()
-api_router.include_router(utils.router)
+api_router.include_router(ban_list_configs.router)
 api_router.include_router(guardrails.router)
 api_router.include_router(validator_configs.router)
+api_router.include_router(utils.router)
 
 # if settings.ENVIRONMENT == "local":
 #     api_router.include_router(private.router)

backend/app/api/routes/ban_list_configs.py

@@ -0,0 +1,113 @@
+from typing import Optional
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException
+
+from app.api.deps import AuthDep, SessionDep
+from app.core.exception_handlers import _safe_error_message
+from app.crud.ban_list import ban_list_crud
+from app.schemas.ban_list import BanListCreate, BanListUpdate, BanListResponse
+from app.utils import APIResponse
+
+router = APIRouter(prefix="/guardrails/ban_lists", tags=["Ban Lists"])
+
+
+@router.post("/", response_model=APIResponse[BanListResponse])
+def create_ban_list(
+    payload: BanListCreate,
+    session: SessionDep,
+    organization_id: int,
+    project_id: int,
+    _: AuthDep,
+):
+    try:
+        response_model = ban_list_crud.create(
+            session, payload, organization_id, project_id
+        )
+        return APIResponse.success_response(data=response_model)
+    except Exception as exc:
+        if isinstance(exc, HTTPException):
+            raise exc
+        return APIResponse.failure_response(error=_safe_error_message(exc))
+
+
+@router.get("/", response_model=APIResponse[list[BanListResponse]])
+def list_ban_lists(
+    organization_id: int,
+    project_id: int,
+    session: SessionDep,
+    _: AuthDep,
+    domain: Optional[str] = None,
+):
+    try:
+        response_model = ban_list_crud.list(
+            session, organization_id, project_id, domain
+        )
+        return APIResponse.success_response(data=response_model)
+    except Exception as exc:
+        if isinstance(exc, HTTPException):
+            raise exc
+        return APIResponse.failure_response(error=_safe_error_message(exc))
+
+
+@router.get("/{id}", response_model=APIResponse[BanListResponse])
+def get_ban_list(
+    id: UUID,
+    organization_id: int,
+    project_id: int,
+    session: SessionDep,
+    _: AuthDep,
+):
+    try:
+        obj = ban_list_crud.get(session, id, organization_id, project_id)
+        return APIResponse.success_response(data=obj)
+    except Exception as exc:
+        if isinstance(exc, HTTPException):
+            raise exc
+        return APIResponse.failure_response(error=_safe_error_message(exc))
+
+
+@router.patch("/{id}", response_model=APIResponse[BanListResponse])
+def update_ban_list(
+    id: UUID,
+    organization_id: int,
+    project_id: int,
+    payload: BanListUpdate,
+    session: SessionDep,
+    _: AuthDep,
+):
+    try:
+        response_model = ban_list_crud.update(
+            session,
+            id=id,
+            organization_id=organization_id,
+            project_id=project_id,
+            data=payload,
+        )
+        return APIResponse.success_response(data=response_model)
+    except Exception as exc:
+        if isinstance(exc, HTTPException):
+            raise exc
+        return APIResponse.failure_response(error=_safe_error_message(exc))
+
+
+@router.delete("/{id}", response_model=APIResponse[dict])
+def delete_ban_list(
+    id: UUID,
+    organization_id: int,
+    project_id: int,
+    session: SessionDep,
+    _: AuthDep,
+):
+    try:
+        obj = ban_list_crud.get(
+            session, id, organization_id, project_id, require_owner=True
+        )
+        ban_list_crud.delete(session, obj)
+        return APIResponse.success_response(
+            data={"message": "Ban list deleted successfully"}
+        )
+    except Exception as exc:
+        if isinstance(exc, HTTPException):
+            raise exc
+        return APIResponse.failure_response(error=_safe_error_message(exc))

backend/app/api/routes/guardrails.py

@@ -4,12 +4,17 @@
 from fastapi import APIRouter
 from guardrails.guard import Guard
 from guardrails.validators import FailResult, PassResult
+from sqlmodel import Session
 
 from app.api.deps import AuthDep, SessionDep
-from app.core.constants import REPHRASE_ON_FAIL_PREFIX
+from app.core.constants import BAN_LIST, REPHRASE_ON_FAIL_PREFIX
 from app.core.config import settings
 from app.core.guardrail_controller import build_guard, get_validator_config_models
 from app.core.exception_handlers import _safe_error_message
+from app.core.validators.config.ban_list_safety_validator_config import (
+    BanListSafetyValidatorConfig,
+)
+from app.crud.ban_list import ban_list_crud
 from app.crud.request_log import RequestLogCrud
 from app.crud.validator_log import ValidatorLogCrud
 from app.schemas.guardrail_config import GuardrailRequest, GuardrailResponse
@@ -33,14 +38,13 @@ def run_guardrails(
     validator_log_crud = ValidatorLogCrud(session=session)
 
     try:
-        request_id = UUID(payload.request_id)
+        request_log = request_log_crud.create(payload)
     except ValueError:
         return APIResponse.failure_response(error="Invalid request_id")
 
-    request_log = request_log_crud.create(request_id, input_text=payload.input)
+    _resolve_ban_list_banned_words(payload, session)
     return _validate_with_guard(
-        payload.input,
-        payload.validators,
+        payload,
         request_log_crud,
         request_log.id,
         validator_log_crud,
@@ -78,9 +82,25 @@ def list_validators(_: AuthDep):
     return {"validators": validators}
 
 
+def _resolve_ban_list_banned_words(payload: GuardrailRequest, session: Session) -> None:
+    for validator in payload.validators:
+        if not isinstance(validator, BanListSafetyValidatorConfig):
+            continue
+
+        if validator.type != BAN_LIST or validator.banned_words is not None:
+            continue
+
+        ban_list = ban_list_crud.get(
+            session,
+            id=validator.ban_list_id,
+            organization_id=payload.organization_id,
+            project_id=payload.project_id,
+        )
+        validator.banned_words = ban_list.banned_words
+
+
 def _validate_with_guard(
-    data: str,
-    validators: list,
+    payload: GuardrailRequest,
     request_log_crud: RequestLogCrud,
     request_log_id: UUID,
     validator_log_crud: ValidatorLogCrud,
@@ -94,6 +114,8 @@ def _validate_with_guard(
     while still safely handling unexpected runtime errors.
     """
     response_id = uuid.uuid4()
+    data = payload.input
+    validators = payload.validators
     guard: Guard | None = None
 
     def _finalize(
@@ -125,7 +147,7 @@ def _finalize(
 
         if guard is not None:
             add_validator_logs(
-                guard, request_log_id, validator_log_crud, suppress_pass_logs
+                guard, request_log_id, validator_log_crud, payload, suppress_pass_logs
             )
 
         rephrase_needed = validated_output is not None and validated_output.startswith(
@@ -175,6 +197,7 @@ def add_validator_logs(
     guard: Guard,
     request_log_id: UUID,
     validator_log_crud: ValidatorLogCrud,
+    payload: GuardrailRequest,
     suppress_pass_logs: bool = False,
 ):
     history = getattr(guard, "history", None)
@@ -202,6 +225,8 @@ def add_validator_logs(
 
         validator_log = ValidatorLog(
             request_id=request_log_id,
+            organization_id=payload.organization_id,
+            project_id=payload.project_id,
             name=log.validator_name,
             input=str(log.value_before_validation),
             output=log.value_after_validation,

backend/app/core/validators/config/ban_list_safety_validator_config.py

@@ -1,16 +1,25 @@
-from typing import List, Literal
+from typing import List, Literal, Optional
+from uuid import UUID
 
 from guardrails.hub import BanList
+from pydantic import model_validator
 
 from app.core.validators.config.base_validator_config import BaseValidatorConfig
 
 
 class BanListSafetyValidatorConfig(BaseValidatorConfig):
     type: Literal["ban_list"]
-    banned_words: List[str]  # list of banned words to be redacted
+    banned_words: Optional[List[str]] = None  # list of banned words to be redacted
+    ban_list_id: Optional[UUID] = None
+
+    @model_validator(mode="after")
+    def validate_ban_list_source(self):
+        if self.banned_words is None and self.ban_list_id is None:
+            raise ValueError("Either banned_words or ban_list_id must be provided.")
+        return self
 
     def build(self):
         return BanList(
-            banned_words=self.banned_words,
+            banned_words=self.banned_words or [],
             on_fail=self.resolve_on_fail(),
         )