Logging/traceability

backend/app/alembic/versions/010_add_traceability_columns.py

@@ -0,0 +1,84 @@
+"""Add traceability columns to request_log and validator_log
+
+Revision ID: 010
+Revises: 009
+Create Date: 2026-08-25 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "010"
+down_revision = "009"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "request_log",
+        sa.Column(
+            "metadata",
+            JSONB,
+            nullable=True,
+            comment="Full run_guardrails request payload",
+        ),
+    )
+    op.add_column(
+        "validator_log",
+        sa.Column(
+            "order",
+            sa.Integer(),
+            nullable=True,
+            comment="1-based execution order of the validator within the request",
+        ),
+    )
+    op.add_column(
+        "validator_log",
+        sa.Column(
+            "duration_ms",
+            sa.Integer(),
+            nullable=True,
+            comment="Wall-clock execution time of the validator in milliseconds",
+        ),
+    )
+    op.add_column(
+        "validator_log",
+        sa.Column(
+            "stage",
+            sa.String(),
+            nullable=True,
+            comment="Stage the validator checked (input or output)",
+        ),
+    )
+    op.add_column(
+        "validator_log",
+        sa.Column(
+            "type",
+            sa.String(),
+            nullable=True,
+            comment="Validator type (ValidatorType enum value)",
+        ),
+    )
+    op.add_column(
+        "validator_log",
+        sa.Column(
+            "metadata",
+            JSONB,
+            nullable=True,
+            comment="Full resolved validator config used for this run",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("validator_log", "metadata")
+    op.drop_column("validator_log", "type")
+    op.drop_column("validator_log", "stage")
+    op.drop_column("validator_log", "duration_ms")
+    op.drop_column("validator_log", "order")
+    op.drop_column("request_log", "metadata")

backend/app/api/API_USAGE.md

@@ -186,7 +186,7 @@ Endpoint:
 - `POST /api/v1/guardrails/`
 
 Query params:
-- `suppress_pass_logs=true|false` (default `true`)
+- `suppress_pass_logs=true|false` (default `false`: pass-case validator logs are persisted too; set `true` to store only fail-case logs)
 
 Request fields:
 - `request_id` (UUID string)
@@ -204,7 +204,7 @@ Important:
 Example:
 
 ```bash
-curl -X POST "http://localhost:8001/api/v1/guardrails/?suppress_pass_logs=true" \
+curl -X POST "http://localhost:8001/api/v1/guardrails/" \
   -H "Authorization: Bearer <token>" \
   -H "X-ORGANIZATION-ID: 1" \
   -H "X-PROJECT-ID: 101" \

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

@@ -2,9 +2,9 @@ Runs guardrails on input text with a selected list of validators.
 
 Behavior notes:
 - Runtime validator format uses `on_fail`; config-style payloads with `on_fail_action` are accepted and normalized.
-- `suppress_pass_logs=true` skips persisting pass-case validator logs.
-- The endpoint always saves a `request_log` entry for the run.
-- Validator logs are also saved; with `suppress_pass_logs=true`, only fail-case validator logs are persisted. Otherwise, all validator logs are added.
+- By default (`suppress_pass_logs=false`), a validator log is persisted for every executed validator, pass or fail. Pass `suppress_pass_logs=true` to persist only fail-case validator logs.
+- The endpoint always saves a `request_log` entry for the run, including the full request payload in its `metadata`.
+- Each validator log records the validator's execution `order`, `duration_ms`, `stage` (input/output), `type`, and the resolved config (plus any verdict detail under `result_metadata`) in `metadata`.
 - 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 `llm_prompt` + `prompt_schema_version` from tenant LLM prompt 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.