feat: guardrail tracing UI - policy, detection method, match details

[ishaan-jaff]

Summary

• Adds GuardrailTracingDetail TypedDict with fields: guardrail_id, policy_template, detection_method, confidence_score, classification, match_details, patterns_checked, alert_recipients
• Content filter populates these fields from detection results
• UI shows policy template badges, detection method chips, match details table, classification panel, and execution timeline when multiple guardrails run
• All fields optional — no impact on existing guardrail providers

Test plan

• 4 unit tests for base class tracing fields (set, default absent, multiple policies, classification)
• 5 e2e tests for content filter tracing (pattern detection, fallback ID, category keywords, blocked request, no detections)
• 74 total tests passing

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 17, 2026 2:39am

[greptile-apps]

Greptile Summary

This PR adds guardrail tracing metadata to the logging pipeline and renders it in the dashboard UI. A new GuardrailTracingDetail TypedDict carries optional fields (guardrail_id, policy_template, detection_method, confidence_score, classification, match_details, patterns_checked, alert_recipients) through CustomGuardrail.add_standard_logging_guardrail_information_to_request_data() into StandardLoggingGuardrailInformation. The content filter guardrail populates these fields from its detection results, and the GuardrailViewer UI component renders them as policy badges, detection method chips, match details tables, classification panels, and an execution timeline.

• Adds GuardrailTracingDetail TypedDict and extends StandardLoggingGuardrailInformation with 8 new optional fields in litellm/types/utils.py
• CustomGuardrail base class accepts tracing_detail param and unpacks it into the SLG dict — backward compatible via **(tracing_detail or {})
• Content filter guardrail populates tracing fields from its detection results with four new helper methods
• UI adds PolicyDetectionRow, MatchDetailsTable, ClassificationDetails, and ExecutionTimeline components
• 9 new tests (4 unit + 5 E2E) covering the tracing fields pipeline, all using local mocks with no network calls

Confidence Score: 4/5

• This PR is safe to merge — all new fields are optional and backward-compatible, with no impact on the critical request path.
• Score of 4 reflects a well-structured, additive feature with proper tests. All new TypedDict fields use total=False (optional), the base class change is backward-compatible via default None, and the content filter changes are self-contained. The UI components have proper null guards. Minor deduction for the PolicyDetectionRow showing when only patterns_checked is 0 and the field duplication between GuardrailTracingDetail and StandardLoggingGuardrailInformation.
• litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py has the most new logic with tracing field population helpers. ui/litellm-dashboard/src/components/view_logs/GuardrailViewer/GuardrailViewer.tsx adds substantial UI rendering code.

Important Files Changed

Filename	Overview
litellm/types/utils.py	Adds new optional tracing fields to StandardLoggingGuardrailInformation (guardrail_id, policy_template, detection_method, etc.) and a new GuardrailTracingDetail TypedDict. All fields are optional with total=False, so no impact on existing consumers.
litellm/types/guardrails.py	Adds optional policy_template field to the Guardrail TypedDict. Minimal change, no impact on existing code.
litellm/integrations/custom_guardrail.py	Adds tracing_detail parameter to add_standard_logging_guardrail_information_to_request_data() and unpacks it via **(tracing_detail or {}) into the SLG dict. Clean, backward-compatible change.
litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py	Adds tracing detail population: _build_match_details, _get_detection_methods, _get_patterns_checked_count, _get_policy_templates helper methods. Passes GuardrailTracingDetail to the logging method. Minor issue: two datetime.now() calls in _log_guardrail_information (pre-existing).
ui/litellm-dashboard/src/components/view_logs/GuardrailViewer/GuardrailViewer.tsx	Adds five new UI components: PolicyDetectionRow, MatchDetailsTable, ClassificationDetails, ExecutionTimeline, and policy template badges in the header. Well-structured with proper null guards. Minor concern: hasData shows row even when only patterns_checked is 0.
tests/test_litellm/integrations/test_custom_guardrail.py	Adds 4 unit tests for tracing fields: set, default absent, multiple policies, classification. All tests use mocks, no network calls.
tests/test_litellm/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py	Adds 5 E2E tests for content filter tracing: pattern detection, fallback ID, category keywords, blocked request, no detections. All tests use local guardrail instances, no network calls.

Sequence Diagram

sequenceDiagram
    participant CF as ContentFilterGuardrail
    participant CG as CustomGuardrail (base)
    participant SLG as StandardLoggingGuardrailInformation
    participant UI as GuardrailViewer (UI)

    CF->>CF: apply_guardrail()
    CF->>CF: _filter_single_text() → detections
    CF->>CF: _build_match_details(detections)
    CF->>CF: _get_detection_methods(detections)
    CF->>CF: _get_patterns_checked_count()
    CF->>CF: _get_policy_templates()
    CF->>CF: Build GuardrailTracingDetail
    CF->>CG: add_standard_logging_guardrail_information_to_request_data(tracing_detail)
    CG->>SLG: Create SLG with **(tracing_detail or {})
    CG->>CG: Append SLG to request_data["metadata"]
    Note over SLG: Fields: guardrail_id, policy_template,<br/>detection_method, match_details,<br/>patterns_checked, confidence_score, etc.
    SLG-->>UI: Logged data rendered in dashboard
    UI->>UI: PolicyDetectionRow (badges, chips)
    UI->>UI: MatchDetailsTable (per-detection table)
    UI->>UI: ClassificationDetails (LLM-judge panel)
    UI->>UI: ExecutionTimeline (multi-guardrail view)

Loading

_{Last reviewed commit: d648e0f}

[greptile-apps]

_{7 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Duplicated field definitions across TypedDicts

GuardrailTracingDetail duplicates all 8 field definitions from StandardLoggingGuardrailInformation (lines 2623-2645). If a field is added, renamed, or has its type changed on one but not the other, the **(tracing_detail or {}) unpacking in custom_guardrail.py will silently drop the mismatched field.

Consider deriving one from the other or extracting a shared base, e.g.:

class _GuardrailTracingFields(TypedDict, total=False):
    guardrail_id: Optional[str]
    policy_template: Optional[str]
    detection_method: Optional[str]
    confidence_score: Optional[float]
    classification: Optional[dict]
    match_details: Optional[List[dict]]
    patterns_checked: Optional[int]
    alert_recipients: Optional[List[str]]

# Then use _GuardrailTracingFields as a base or as GuardrailTracingDetail directly
GuardrailTracingDetail = _GuardrailTracingFields