Skip to main content

Conditional Chains Configuration

policies.chain accepts either plain policy kinds or conditional chain entries. Conditional entries let you attach when, stage, parallel, and targeting metadata to a specific policy kind.

Chain entry shapes​

Plain entry​

Use a plain string when the policy should always run with its default execution phase.

policies:
  chain:
    - prompt-injection
    - pii-detector
    - audit-logger

Conditional entry​

Use an object when the policy should run only in certain contexts or with an explicit phase override.

policies:
  chain:
    - prompt-injection
    - pii-detector:
        when:
          path: "/v1/chat"
          header:
            x-team: "finance"
        stage: pre-request
        parallel: true
    - quality-scorer:
        when:
          model:
            - "gpt-5.4-mini"
            - "gpt-5.4"
        stage: pre-response

The policy kind is the key. The conditional metadata sits in the nested object.

when predicates​

All fields inside when use AND semantics. Every condition must match for the chain entry to run.

Path matching​

- prompt-injection:
    when:
      path: "/v1/chat"

path is a prefix-style match against the request path.

Header matching​

- dlp-filter:
    when:
      header:
        x-team: "compliance"
        X-Environment: "prod"

All listed headers must match by case-insensitive equality. Header names are also case-insensitive.

Model matching​

- quality-scorer:
    when:
      model:
        - "gpt-5.4-mini"
        - "openai/gpt-4.1"

Stage control​

Supported stage values:

StageMeaning
pre-requestBefore the request is sent upstream
post-requestAfter the request is prepared but before final response handling
pre-responseBefore the response is returned to the caller
post-responseAfter the response has been returned

The schema accepts all four values. The current proxy schedules pre-request, post-request, and pre-response; it does not schedule a post-response pass, so a policy assigned only to post-response does not execute today.

Common defaults​

If stage is omitted, the gateway uses the default phase for that policy kind.

  • Most input-oriented policies default to pre-request
  • Output-phase-only policies include: flagged-review, quality-scorer, human-oversight, citation-verifier, mnpi-filter, financial-compliance, healthcare-compliance, legal-privilege, upl-filter, bias-monitor, and response-rewriter

Parallel execution​

Set parallel: true when same-stage policies are independent and can execute concurrently.

policies:
  chain:
    - prompt-injection:
        stage: pre-request
        parallel: true
    - pii-detector:
        stage: pre-request
        parallel: true
    - dlp-filter:
        stage: pre-request
        parallel: false

The gateway waits for all parallel entries in a stage to finish before moving on.

Targeting​

Use targeting to scope a chain entry to specific teams or gateways.

- audit-logger:
    stage: pre-request
    targeting:
      scope: team
      teams:
        - compliance
      gateways:
        regex: "^prod-.*$"

targeting fields​

FieldTypeDescription
scopestringorganization or team
teamsstring[]Required when scope: team
gatewaysselectorExact name, string array, or regex object

Gateway selector formats​

# exact name
gateways: "prod-east"

# list of exact names
gateways:
  - "prod-east"
  - "prod-west"

# regex selector
gateways:
  regex: "^prod-.*$"

Complete example​

pack:
  name: conditional-gateway
  version: 1.0.0
  enabled: true

providers:
  targets:
    - id: openai-prod
      provider: openai
      model: gpt-5.4-mini
      secret_key_ref:
        env: KEEPTRUSTS_OPENAI_API_KEY

policies:
  chain:
    - prompt-injection
    - pii-detector:
        stage: pre-request
        parallel: true
        when:
          path: "/v1/chat"
          header:
            x-team: "compliance"
    - dlp-filter:
        stage: pre-request
        when:
          header:
            x-team: "compliance"
    - quality-scorer:
        stage: pre-response
        when:
          model:
            - "gpt-5.4-mini"
    - audit-logger:
        stage: pre-request
        targeting:
          scope: team
          teams:
            - compliance
          gateways:
            regex: "^prod-.*$"

policy:
  pii-detector:
    action: redact
    pci_mode: true
  dlp-filter:
    blocked_terms:
      - "inside information"
      - "share this customer export"
    action: block
  quality-scorer:
    thresholds:
      min_aggregate: 0.8
  audit-logger: {}

When to use conditional chains vs routes​

NeedPrefer
Different policy chain for Chat Completions and Responses pathsRoutes
Same upstream, different policies by path, header, or modelConditional chain entries
Team- or gateway-specific executionConditional chain entries
Ordered path dispatch before policy executionRoutes

Routes select policy chains only. Their parsed upstream field does not change live provider selection; configure that under providers:.

Next steps​