fix(guardrails): show YAML-defined guardrails in the Guardrail Monitor

[yuneng-berri]

Relevant issues

Linear ticket

Resolves LIT-2529

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• 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 (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

This is a dashboard-endpoint bug (the Guardrail Monitor reads these three endpoints), so the realistic end-to-end proof is curling the endpoints against a live proxy rather than making an LLM call. The proxy was started on a config that defines one YAML guardrail and stores nothing in the DB, so the guardrail exists only in the in-memory handler:

guardrails:
  - guardrail_name: "yaml-pii-guard"
    litellm_params:
      guardrail: presidio
      mode: pre_call
      presidio_analyzer_api_base: "http://localhost:5002/"
      presidio_anonymizer_api_base: "http://localhost:5002/"
    guardrail_info:
      type: "PII"
      description: "YAML-defined PII guardrail (LIT-2529 repro)"

Its runtime id comes from the known-good listing endpoint:

YAML_ID=$(curl -s "http://localhost:4000/v2/guardrails/list" -H "Authorization: Bearer sk-1234" \
  | jq -r '.guardrails[] | select(.guardrail_name=="yaml-pii-guard") | .guardrail_id')

Before the fix (this commit reverted, parent 51f6e1b7a5), the detail panel 404s and the guardrail is missing from the overview:

$ curl -s -w '\nHTTP %{http_code}\n' "http://localhost:4000/guardrails/usage/detail/$YAML_ID" -H "Authorization: Bearer sk-1234"
{"detail":"Guardrail not found"}
HTTP 404

$ curl -s "http://localhost:4000/guardrails/usage/overview" -H "Authorization: Bearer sk-1234" | jq '[.rows[].name]'
[
  "bedrock-guard-pre-call",
  "bedrock-guard-during-call",
  "bedrock-guard-post-call",
  "bedrock-guard-pre-call-strict"
]

After the fix (799a559871), the detail panel returns the real metadata and the guardrail shows up in the overview with its true provider and type:

$ curl -s -w '\nHTTP %{http_code}\n' "http://localhost:4000/guardrails/usage/detail/$YAML_ID" -H "Authorization: Bearer sk-1234"
{"guardrail_id":"...","guardrail_name":"yaml-pii-guard","type":"PII","provider":"presidio","requestsEvaluated":0,"failRate":0.0,"avgScore":null,"avgLatency":null,"status":"healthy","trend":"stable","description":"YAML-defined PII guardrail (LIT-2529 repro)","time_series":[]}
HTTP 200

$ curl -s "http://localhost:4000/guardrails/usage/overview" -H "Authorization: Bearer sk-1234" | jq '.rows[] | select(.name=="yaml-pii-guard")'
{
  "id": "...",
  "name": "yaml-pii-guard",
  "type": "PII",
  "provider": "presidio",
  "requestsEvaluated": 0,
  "failRate": 0.0,
  "status": "healthy",
  "trend": "stable"
}

A genuinely-missing id still returns 404 both before and after, so the fallback does not turn every unknown id into a 200. In the Admin UI this is the Guardrail Monitor page, where the affected guardrail now renders a row and opens a detail panel instead of showing nothing.

Type

🐛 Bug Fix

Changes

The Guardrail Monitor could not show guardrails defined in config.yaml. Its three endpoints (/guardrails/usage/overview, /guardrails/usage/detail/{id}, /guardrails/usage/logs) resolved guardrails only from the litellm_guardrailstable Prisma table, but YAML/config guardrails live only in IN_MEMORY_GUARDRAIL_HANDLER and are never persisted. So the detail endpoint 404'd, the overview omitted the guardrail entirely (or rendered it as a Custom / Guardrail orphan when it happened to have metrics), and the logs endpoint missed the guardrail's logical-name alias

The codebase already solves this exact resolution in list_guardrails_v2 and get_guardrail_info, which union the DB rows with the in-memory config guardrails and fall back to the in-memory copy on a DB miss, skipping stale DB-sourced in-memory entries. The usage endpoints were written without reusing that pattern

This change puts that resolution next to the in-memory state it reads. InMemoryGuardrailHandler gains list_config_guardrails() and get_config_guardrail_by_id(), both returning only config-owned entries so a DB-sourced entry that is missing from the DB (deleted on another pod, awaiting reconciliation) is treated as a miss rather than resurrected. The overview endpoint unions the DB rows with list_config_guardrails() deduped by id, and detail and logs fall back to get_config_guardrail_by_id() before 404'ing or resolving the logical name

Two smaller defects are fixed at their source. initialize_guardrail was dropping guardrail_info when it stored a config guardrail, so type and description came back empty even once the guardrail was visible; it now carries guardrail_info through, which also improves list_guardrails_v2 (it already reads that field). And the overview row builder read litellm_params / guardrail_info as attributes, which raised AttributeError on the in-memory dict shape and missed the LitellmParams pydantic case; a pair of small helpers (_get_guardrail_field, _to_dict) now read those fields uniformly across Prisma rows, dicts, and LitellmParams

Tests: a new tests/test_litellm/proxy/guardrails/test_usage_endpoints.py covers the three endpoints (YAML detail returns 200, missing id still 404s, a stale DB-sourced entry is not surfaced, a DB row still resolves, the overview includes a YAML guardrail with zero metrics and matches metrics by logical name without emitting an orphan row, the union excludes stale DB-sourced entries, and logs resolves the config guardrail's logical name). test_guardrail_registry.py covers the two new accessors and test_init_guardrails.py covers the guardrail_info passthrough. Reverting the two source files while keeping the tests turns the regression-guard tests red, so they fail before the fix and pass after

[greptile-apps]

Greptile Summary

This PR fixes the Guardrail Monitor dashboard not showing guardrails defined in config.yaml. The three usage endpoints (/guardrails/usage/overview, /detail/{id}, /logs) were resolving guardrails solely from the litellm_guardrailstable Prisma table; config-only guardrails live exclusively in IN_MEMORY_GUARDRAIL_HANDLER and are never persisted, so they were invisible to the monitor.

• Two new methods on InMemoryGuardrailHandler (list_config_guardrails, get_config_guardrail_by_id) expose only config-sourced entries, and the overview endpoint unions DB rows with these deduped by ID, while detail and logs fall back to the in-memory entry before 404ing.
• initialize_guardrail is patched to carry guardrail_info through to the stored Guardrail object, fixing missing type/description fields even after visibility was restored.
• Helper functions _get_guardrail_field and _to_dict unify attribute vs. dict access across Prisma rows, TypedDicts, and Pydantic models, removing the AttributeError that affected the overview row builder.

Confidence Score: 5/5

Safe to merge — the fix is narrowly scoped to read paths, no write or auth logic is touched, and the new methods correctly exclude stale DB-sourced entries rather than resurrecting them.

The change only adds new read accessors and wires them into existing endpoints behind in-memory lookups that already existed. All three endpoints retain their DB-first precedence; the fallback is a config-sourced-only filter that cannot surface deleted or orphaned DB entries. The companion tests verify the exact scenarios described in the PR and include a regression guard that fails before the fix. No pre-existing behavior is altered.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_registry.py	Added list_config_guardrails() and get_config_guardrail_by_id() to expose only config-sourced entries; fixed initialize_guardrail to carry guardrail_info into the stored Guardrail object
litellm/proxy/guardrails/usage_endpoints.py	Overview, detail, and logs endpoints now union DB rows with config guardrails from IN_MEMORY_GUARDRAIL_HANDLER; helper functions _get_guardrail_field and _to_dict unify attribute/dict access across Prisma rows, TypedDicts, and Pydantic models
tests/test_litellm/proxy/guardrails/test_usage_endpoints.py	New test file covering all three endpoints: YAML detail 200, missing-id 404, stale DB-sourced not surfaced, DB row resolves, overview includes zero-metric YAML row, logs resolves logical-name alias — no real network calls
tests/test_litellm/proxy/guardrails/test_guardrail_registry.py	Added test_list_config_guardrails_excludes_db_sourced and test_get_config_guardrail_by_id_returns_config_only; remaining changes are line-length reformats that don't alter test logic
tests/test_litellm/proxy/guardrails/test_init_guardrails.py	Added test_initialize_guardrail_preserves_guardrail_info verifying the regression fix; existing test reformatted only

_{Reviews (2): Last reviewed commit: "refactor(guardrails): generalize _to_dic..." | Re-trigger Greptile}

[greptile-apps]

Repeated local import of IN_MEMORY_GUARDRAIL_HANDLER

IN_MEMORY_GUARDRAIL_HANDLER is imported inside three separate endpoint functions (guardrails_usage_overview, guardrails_usage_detail, guardrails_usage_logs). The same module-level circular-import concern that forces prisma_client to be a local import applies here too, but three identical local import statements are noisier than one. A single lazy accessor (e.g., a small _get_handler() helper or importing it once at the top of the function that initializes these endpoints) would be easier to maintain, especially if the import path changes.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[codecov]

Codecov Report

❌ Patch coverage is 97.43590% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/guardrails/usage_endpoints.py	96.96%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_/guardrail-monitor-details-fix-8845d6 (8b31b20) with litellm_internal_staging (14338a2)}

[yuneng-berri]

@greptile local imports match established conventions in these files, and refactoring this is out of scope. Review again and give an updated score

[devin-ai-integration]

Adding UI proof of the fix. Ran a live proxy on localhost:4000 whose only guardrail is defined in config.yaml (never persisted to the DB, so it exists only in IN_MEMORY_GUARDRAIL_HANDLER), then opened the Guardrail Monitor in the Admin UI

What the recording shows

The overview lists yaml-pii-guard with provider presidio, Healthy status, and Active Guardrails: 1; before the fix this row was missing. Clicking it opens the detail panel with type PII and the description from guardrail_info (this endpoint returned 404 Guardrail not found before). The Logs tab resolves the guardrail's logical name and returns cleanly

Config used

guardrails:
  - guardrail_name: "yaml-pii-guard"
    litellm_params:
      guardrail: presidio
      mode: pre_call
      presidio_analyzer_api_base: "http://localhost:5002/"
      presidio_anonymizer_api_base: "http://localhost:5002/"
    guardrail_info:
      type: "PII"
      description: "YAML-defined PII guardrail (LIT-2529 repro)"