[Docs] Add docs guide for using policies

[ishaan-jaff]

[Docs] Add docs guide for using policies

Pre-Submission checklist

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

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature
🐛 Bug Fix
🧹 Refactoring
📖 Documentation
🚄 Infrastructure
✅ Test

Changes

[vercel]

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

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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds tag-based policy scoping, a policy resolve/debug API, an attachment impact estimation ("blast radius") API, a Policy Simulator UI tab, and comprehensive documentation with UI screenshots.

• Tag-based scoping: Policies can now target keys/teams by metadata.tags or request-body tags, with wildcard support (health-*). Tags use opt-in semantics — empty tags means "don't filter by tags" (unlike teams/keys/models which default to match-all).
• /policies/resolve endpoint: Debug which policies and guardrails apply for a given team/key/model/tags context.
• /policies/attachments/estimate-impact endpoint: Preview how many keys/teams an attachment would affect before creating it.
• Policy Simulator UI: New tab in the Policies panel to simulate policy resolution with team/key/model/tag inputs.
• Impact preview: Both inline (in attachment creation form) and popover (in attachment table) blast-radius previews.
• x-litellm-policy-sources header: New response header showing why each policy matched (e.g., hipaa=tag:healthcare; baseline=scope:*).
• Refactor: Module-level singleton constants in policy_endpoints.py replaced with lazy getter calls; _initialized flag set after DB sync in registry.
• Schema: tags column added to LiteLLM_PolicyAttachmentTable across all three schema.prisma files.
• Tests: Unit tests added for tag matching, wildcard patterns, combined AND logic, and match attribution — all mock-based with no network calls.

Confidence Score: 4/5

• This PR is safe to merge — the new endpoints are admin-only, tag matching logic is well-tested, and critical path changes are minimal.
• Score of 4 reflects: well-structured code with good test coverage for the core matching logic, consistent schema changes across all three prisma files, no changes to critical request path beyond adding tag context and attribution metadata. Deducted one point because the estimate-impact endpoint fetches up to 1000 rows unfiltered for tag-based lookups (acceptable for admin endpoint but worth noting), and the new resolve endpoint has no dedicated integration/API tests.
• Pay attention to litellm/proxy/policy_engine/policy_resolve_endpoints.py — the estimate-impact endpoint does broad DB queries (up to 1000 rows with where={}) for tag-based lookups.

Important Files Changed

Filename	Overview
litellm/proxy/policy_engine/policy_resolve_endpoints.py	New file: two admin endpoints — /policies/resolve (debug policy matching) and /policies/attachments/estimate-impact (blast radius preview). Tag-based impact fetches up to 1000 keys/teams unfiltered then filters in Python.
litellm/proxy/policy_engine/attachment_registry.py	Added tags field propagation throughout attachment CRUD and get_attached_policies_with_reasons() method for match attribution. Clean refactor of get_attached_policies to delegate to the new method.
litellm/proxy/policy_engine/policy_matcher.py	Added tag-based scope matching with opt-in semantics (empty tags = don't check, specified tags = ALL must match). Correct AND logic with other scope dimensions.
litellm/proxy/litellm_pre_call_utils.py	Updated add_guardrails_from_policy_engine to extract request tags, pass them in PolicyMatchContext, and track policy attribution for the x-litellm-policy-sources header.
litellm/proxy/common_utils/callback_utils.py	Added add_policy_sources_to_metadata helper and x-litellm-policy-sources response header generation using ; delimiter.
litellm/types/proxy/policy_engine/policy_types.py	Added tags field to PolicyScope and PolicyAttachment with opt-in semantics (empty = don't check, unlike teams/keys/models which default to match-all).
litellm/types/proxy/policy_engine/resolver_types.py	Added tags to PolicyMatchContext, PolicyScopeResponse, PolicyAttachmentCreateRequest, PolicyAttachmentDBResponse. New types: PolicyResolveRequest, PolicyMatchDetail, PolicyResolveResponse, AttachmentImpactResponse.
tests/test_litellm/proxy/policy_engine/test_attachment_registry.py	Added comprehensive unit tests for tag-based matching (exact, wildcard, combined with teams) and match attribution. All mock-based, no network calls.
tests/test_litellm/proxy/policy_engine/test_policy_matcher.py	Added unit tests for PolicyMatcher.scope_matches with tags: exact, wildcard, no-match, combined AND logic. All mock-based.
ui/litellm-dashboard/src/components/policies/policy_test_panel.tsx	New Policy Simulator UI panel: form with team/key/model/tags selectors, calls /policies/resolve, displays matched policies and effective guardrails. Uses Tremor Button which is deprecated per AGENTS.md except for tables.
ui/litellm-dashboard/src/components/policies/add_attachment_form.tsx	Added tags field to attachment creation form, impact estimation preview, and refactored form data building into shared buildAttachmentData utility. Fixed response parsing for teams/keys/models lists.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Proxy as LiteLLM Proxy
    participant PolicyEngine as Policy Engine
    participant DB as Database

    Note over Client,DB: Policy Resolve (Debug) Flow
    Client->>Proxy: POST /policies/resolve {team, key, model, tags}
    Proxy->>PolicyEngine: get_attached_policies_with_reasons(context)
    PolicyEngine->>PolicyEngine: scope_matches() + tag matching
    PolicyEngine-->>Proxy: matched policies + reasons
    Proxy->>PolicyEngine: resolve_policy_guardrails(each policy)
    Proxy-->>Client: {effective_guardrails, matched_policies}

    Note over Client,DB: Impact Estimation Flow
    Client->>Proxy: POST /policies/attachments/estimate-impact
    Proxy->>DB: find_many(keys, teams) [up to 1000]
    DB-->>Proxy: key/team rows
    Proxy->>PolicyEngine: filter by tag/alias patterns
    Proxy-->>Client: {affected_keys_count, affected_teams_count, samples}

    Note over Client,DB: Request-time Policy Matching (updated)
    Client->>Proxy: POST /chat/completions {model, metadata.tags}
    Proxy->>PolicyEngine: get_attached_policies_with_reasons(context+tags)
    PolicyEngine-->>Proxy: policies + match reasons
    Proxy->>Proxy: add_policy_sources_to_metadata()
    Proxy-->>Client: response + x-litellm-policy-sources header

Loading

[greptile-apps]

_{29 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Tag-based impact estimation fetches up to 1000 keys with where={} (no filter), then filters in Python. This is fine for an admin endpoint, but if the number of keys grows large, consider adding a DB-side filter on metadata containing the tag to reduce the fetch size.

_{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!}