feat(guardrails): forward optional metadata on POST /guardrails/apply_guardrail

[devin-ai-integration]

Relevant issues

Fixes #33059

Linear ticket

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review

Screenshots / Proof of Fix

Live proxy on localhost:4000 with a custom guardrail whose apply_guardrail reads request_data["metadata"]["forbidden_topics"] and blocks the text when a forbidden topic appears. The before-fix run is the pre-change behavior; the after-fix runs were captured at the squashed commit 3161825b58 (same content as the reviewed head d6262bce6b)

Config

guardrails:
  - guardrail_name: my-topic-guardrail
    litellm_params:
      guardrail: topic_guardrail_demo.TopicGuardrail
      mode: pre_call

Before the fix, request_data was built as {"messages": ...} if ... else {}, so metadata was never populated. The forbidden topic is sent but silently ignored, HTTP 200 with text unchanged, which is the exact bug from the issue

$ curl -s -X POST http://localhost:4000/guardrails/apply_guardrail \
    -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"guardrail_name":"my-topic-guardrail","text":"What are tax loopholes?","metadata":{"forbidden_topics":["tax","finance"]}}'
{"response_text":"What are tax loopholes?"}

After the fix

# 1) no metadata -> backward-compatible passthrough (request_data stays {})
$ curl -s -X POST http://localhost:4000/guardrails/apply_guardrail \
    -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"guardrail_name":"my-topic-guardrail","text":"What are tax loopholes?"}'
{"response_text":"What are tax loopholes?"}

# 2) metadata forwarded -> guardrail reads forbidden_topics and blocks
$ curl -s -X POST http://localhost:4000/guardrails/apply_guardrail \
    -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"guardrail_name":"my-topic-guardrail","text":"What are tax loopholes?","metadata":{"forbidden_topics":["tax","finance"]}}'
{"response_text":"[BLOCKED: forbidden topic]"}

# 3) metadata sent but no matching topic -> passthrough
$ curl -s -X POST http://localhost:4000/guardrails/apply_guardrail \
    -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"guardrail_name":"my-topic-guardrail","text":"Tell me about cooking pasta","metadata":{"forbidden_topics":["tax","finance"]}}'
{"response_text":"Tell me about cooking pasta"}

# 4) explicitly empty messages/metadata -> forwarded, passthrough
$ curl -s -X POST http://localhost:4000/guardrails/apply_guardrail \
    -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"guardrail_name":"my-topic-guardrail","text":"hello","messages":[],"metadata":{}}'
{"response_text":"hello"}

Admin UI: Guardrail Test Playground

The Guardrails page's Test Playground now has an optional Metadata JSON input that is sent as the request's metadata field

Video walkthrough (login, select guardrail, run with metadata blocking, run without metadata passing through):

https://raw.githubusercontent.com/yassin-berriai/litellm-pr-media/main/pr-33067/ui_guardrail_metadata_demo.mp4

Metadata field filled in with the forbidden-topics config:

With metadata sent, the custom guardrail reads forbidden_topics and blocks the text:

Same input with the metadata field left empty passes through unchanged (backward-compatible):

Type

🆕 New Feature

Changes

Clients calling POST /guardrails/apply_guardrail could not pass per-request configuration to custom guardrail implementations. The handler forwarded text (and optionally messages) to CustomGuardrail.apply_guardrail, but there was no request field for guardrail-specific parameters, so parameterized guardrails that read their config from request_data["metadata"] on the LLM-call hooks silently passed through on this path

metadata: Dict[str, Any] | None = None is added to ApplyGuardrailRequest; Pydantic drops unknown JSON fields, so a schema field is required for clients to send this at all

The handler now includes metadata in request_data only when the client sends it, and the messages guard is aligned to the same is not None semantics so an explicitly-sent empty list is forwarded instead of silently dropped:

request_data: dict = {
    **({"messages": request.messages} if request.messages is not None else {}),
    **({"metadata": request.metadata} if request.metadata is not None else {}),
}

Custom guardrail classes that override apply_guardrail remain responsible for reading request_data["metadata"]; this PR only makes the value available

The Admin UI's Guardrail Test Playground gains an optional Metadata field (JSON object, validated client-side) so parameterized guardrails can be exercised from the dashboard; applyGuardrail in networking.tsx forwards it only when present

ui/litellm-dashboard/src/lib/http/schema.d.ts and the guardrails fragment of litellm/proxy/_lazy_openapi_snapshot.json are regenerated for the new field, since the guardrails router is lazy-loaded and its OpenAPI comes from the snapshot

Tests live in the mapped tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py and assert that client-supplied metadata reaches apply_guardrail via request_data (alone, alongside messages, and as explicit empty values), and pin the empty-request_data behavior when both fields are omitted

Docs: BerriAI/litellm-docs#573

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Greptile Summary

This PR adds an optional metadata field to POST /guardrails/apply_guardrail, allowing callers to pass per-request configuration to custom guardrail implementations that read from request_data["metadata"]. It also aligns the existing messages guard to use is not None semantics (fixing a pre-existing bug where an explicit empty list was silently dropped), and surfaces the new field in the Admin UI's Guardrail Test Playground.

• Backend: metadata: Dict[str, Any] | None = None added to ApplyGuardrailRequest; request_data now merges both messages and metadata using is not None checks, making explicit empty values ([], {}) observable to guardrails.
• Frontend: GuardrailTestPanel gains an optional Metadata textarea with client-side JSON validation (non-null object required); applyGuardrail in networking.tsx receives metadata as a new optional last parameter, maintaining full backward compatibility.
• Tests: Four new mock-only Python tests cover metadata-alone, metadata+messages, omitted-metadata, and explicit-empty-values paths; two new UI tests cover valid and invalid JSON metadata input.

Confidence Score: 5/5

Safe to merge — the change is additive, backward-compatible, and all three code paths (backend type, endpoint handler, UI) are covered by tests.

The backend change is a small, focused addition to an existing Pydantic model and a three-line dict-merge in the handler, both with correct is not None guards. The UI changes follow existing patterns in the file, and the new metadata parameter is the last optional argument in applyGuardrail so no existing callers are affected. Test coverage is thorough: four Python unit tests pin the new and edge-case behaviors, and two UI tests validate the JSON validation path.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_endpoints.py	Adds metadata to request_data using is not None guard (consistent with the same fix applied to messages); logic is correct and backward-compatible.
litellm/types/guardrails.py	Adds `metadata: Dict[str, Any]
tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py	Four new async tests covering: metadata-only, metadata+messages, no-metadata backward compat, and explicit empty values — all use mocks with no real network calls.
ui/litellm-dashboard/src/app/(dashboard)/guardrails/_components/GuardrailTestPanel.tsx	Adds optional Metadata textarea with JSON validation, inline error display, and live re-validation when an error is already shown; consistent with existing UX patterns in the file.
ui/litellm-dashboard/src/components/networking.tsx	Adds optional metadata as the last parameter of applyGuardrail (backward-compatible); improves Record<string, any> to Record<string, unknown> on PromptTemplateBase.

_{Reviews (3): Last reviewed commit: "test(ui): cover metadata input in guardr..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Isaac4real]

This is a duplicate of #33060

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_apply_guardrail_metadata (3161825) with litellm_internal_staging (9121ae3)}

[yassin-berriai]

This requires a docs update. the desc should show UI screenshots

[devin-ai-integration]

@yassin-berriai docs updated in BerriAI/litellm-docs#573. It documents metadata on /guardrails/apply_guardrail with a new "Custom Guardrail with metadata" usage tab, a metadata entry under Optional Fields, and a note that it is forwarded only when the client sends it

Rendered page (npm start on the docs site):

[yassin-berriai]

@greptileai please review the current head 8c37ac7

[yassin-berriai]

@greptileai please review the current head d6262bc

[yassin-berriai]

Docs updated in BerriAI/litellm-docs#573 and the description now embeds the Admin UI screenshots plus a video walkthrough of the new Test Playground metadata field