Declarative Config Reference

Use this page when you need to author, review, or validate policy-config.yaml and want a customer-facing explanation of what the declarative config supports.

Use this page when

• You are authoring, reviewing, or validating policy-config.yaml and need the full schema reference.
• You need to understand the supported document shapes, validation rules, and execution semantics.
• You are debugging a lint error or schema violation and need to check field types and constraints.

If you are looking for the recommended end-to-end operating model instead of field-by-field schema detail, start with Config-First Workflow.

This page covers:

• The supported document shapes.
• Strict validation rules.
• Execution semantics for policy chains.
• Provider target metadata used for multi-provider routing.
• Every supported declarative policy kind.
• The limits of single-policy documents.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Workflow map

Validating and starting the gateway

Lint the config

kt policy lint --file policy-config.yaml

Start the gateway with a policy config

export OPENAI_API_KEY="sk-..."

kt gateway run \
  --listen 0.0.0.0:41002 \
  --policy-config policy-config.yaml \
  --fail-mode block

For one-off experiments you can still pass --upstream flags on the CLI, but long-lived configs should keep provider targets in YAML so the same document works for local, managed, and Git-backed workflows.

Verify the running config

cURL

curl http://localhost:8080/keeptrusts/config | jq .

Python

import httpx

config = httpx.get("http://localhost:8080/keeptrusts/config").json()
print(config["pack"]["name"], config["pack"]["version"])
print("Policy chain:", config["policies"]["chain"])

Node.js

const config = await fetch("http://localhost:8080/keeptrusts/config").then(r => r.json());
console.log(config.pack.name, config.pack.version);
console.log("Policy chain:", config.policies.chain);

What the config is for

The declarative config is the source-of-truth document for local gateway behavior. Customers use it to:

• Define the policy chain.
• Declare provider targets and provider data-handling metadata.
• Declare per-agent usage constraints for cost and response-count controls.
• Tune behavior for each policy kind.
• Validate changes before starting the gateway.
• Apply a known local config to a connected running gateway from Configurations and verify the result from Gateways and Events.

Deep-dive index

This reference explains the top-level shape. Use the companion guides for the field-heavy sections:

• Pack Metadata and Versioning
• Providers Configuration
• Cloud Provider Configuration
• Execution Targets and Native Runners
• Data Policies and Data Routing
• Rate Limits Configuration
• Routes and Consumer Groups
• Conditional Chains Configuration
• Observability Configuration
• Security and Network Configuration
• Runtime Configuration
• Config Testing
• Single Policy Documents
• Per-Policy Configuration Catalog
• Flagged Review Configuration
• Compliance Policies Configuration
• End-to-End Configuration Scenarios

Strict validation rules

Keeptrusts treats the config as a strict contract.

• Unknown top-level keys are rejected.
• Unknown policy kinds are rejected.
• Unknown keys inside a supported policy block are rejected.
• Validation happens after YAML is parsed into an object model.

In practice, this means you should not add ad hoc metadata to the file unless the schema explicitly supports it.

Supported document shapes

There are two supported shapes.

1. Config document

This is the normal production and template shape.

pack:
  name: demo-pack
  version: 1.0.0
  enabled: true
  description: Demo config

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

policy:
  audit-logger:
    retention_days: 365
  pii-detector:
    action: redact

Required top-level objects:

• pack
• policies

Optional top-level object:

• policy
• providers
• agents

2. Single-policy document

This shape is only supported for four policy kinds:

• prompt-injection
• agent-firewall
• citation-verifier
• quality-scorer

Example:

policy:
  name: prompt-injection
  version: 1.0.0
  enabled: true

detection:
  embedding_threshold: 0.8

encoding:
  decode_base64: true
  normalize_unicode: true

boundaries:
  enforce_delimiters: true

response:
  action: block
  message: Request blocked: potential prompt injection detected

Any single-policy document for other policy kinds is rejected.

Config document structure

pack

Required fields:

• name: non-empty string.
• version: SemVer string.
• enabled: boolean.

Optional field:

• description: string.

policies

Required field:

• chain: non-empty array of supported policy kinds or conditional chain entries.

Execution rules:

• Policies execute in chain order.
• Conditional chain entries can attach when, stage, parallel, and targeting metadata to a policy kind.
• If a policy kind is in chain and policy.<kind> is missing, schema defaults apply.
• If policy.<kind> exists but the kind is not in chain, it validates but does not execute.

policy

This optional object holds the per-policy configuration blocks.

providers

This optional object defines multi-provider routing targets and related behavior.

Common sub-objects:

• targets: one or more provider targets.
• fallback: retry and fallback triggers.
• routing: ordered or latency-based selection strategy.
• model_groups: virtual model aliases that map to ordered target lists.
• pipelines: virtual model aliases that orchestrate multiple provider targets in sequence or fan_out mode.

Each target can also declare data_policy metadata for retention and training guarantees:

pack:
  name: declarative-config-reference-providers-3
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai-zdr
    provider: openai
    model: gpt-4o
    base_url: https://api.openai.com
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

This metadata is operator-declared and is used by data-routing-policy to allow or exclude targets before the fallback loop runs.

agents

This optional array can include per-agent usage limits alongside the rest of the agent definition. The wallet- and quota-related portion of the schema lives under agents[].usage_constraints[].

agents:
  - # existing agent fields omitted for brevity
    usage_constraints:
      - constraint_type: cost
        provider: openai
        model_pattern: gpt-4o*
        max_value: 25
        interval: day
        enforcement_mode: reject
      - constraint_type: response_count
        max_value: 200
        interval: hour
        enforcement_mode: wait_and_retry

Supported usage_constraints[] fields:

• constraint_type: cost or response_count.
• provider: optional provider alias. When omitted, the constraint applies to all providers the agent can use.
• model_pattern: optional model matcher. The default is *.
• max_value: positive numeric limit for the selected constraint type.
• interval: minute, hour, day, or month.
• enforcement_mode: reject or wait_and_retry.

Semantics:

• cost limits are evaluated in the org wallet currency after pricing and exchange-rate conversion.
• response_count limits increment once per completed response.
• reject fails immediately when the next request would exceed the window.
• wait_and_retry returns a retryable failure with the next reset time.
• On hosted gateway deployments, config activation persists these constraints so runtime enforcement stays aligned with the current config.

Supported declarative policy kinds

The schema accepts these policy kinds in policies.chain and policy.<kind> blocks:

• agent-firewall
• audit-logger
• bias-monitor
• case-privacy
• citation-verifier
• cjis-mode
• dlp-filter
• dual-use-filter
• entity-list-filter
• financial-compliance
• healthcare-compliance
• hipaa-phi-detector
• human-oversight
• itar-ear-filter
• legal-privilege
• mnpi-filter
• pii-detector
• prompt-injection
• quality-scorer
• rbac
• safety-filter
• student-privacy
• upl-filter
• data-routing-policy

Policy field reference

Access, tool, and runtime governance

agent-firewall

Supported shapes:

• Simple form with allowed_tools, blocked_tools, and max_actions_per_session.
• Expanded form with role-based tool rules, rate limits, transaction limits, kill switches, and monitoring.

Supported fields:

• allowed_tools: string array.
• blocked_tools: string array.
• max_actions_per_session: integer.
• tools.roles.<role>.allowed: non-empty string array.
• tools.roles.<role>.denied: string array.
• rate_limits.<tool_or_default>: integer.
• transaction_limits.max_single_transaction: number.
• transaction_limits.max_daily_total: number.
• transaction_limits.require_approval_above: number.
• kill_switches.max_errors_before_halt: integer.
• kill_switches.halt_on_pii_in_action: boolean.
• kill_switches.halt_on_suspicious_pattern: boolean.
• monitoring.alert_on_denied_action: boolean.
• monitoring.alert_on_rate_limit: boolean.
• monitoring.alert_threshold_percent: integer.

rbac

Supported fields:

• deny_if_missing: string array.
• require_auth: boolean.
• roles.<role>.allowed_tools: string array.
• roles.<role>.denied_tools: string array.
• data_access.<scope>.max_sensitivity: public | internal | confidential | restricted.
• minimum_necessary.enabled: boolean.
• minimum_necessary.allowed_phi_roles: string array.

cjis-mode

Supported fields:

• require_auth: boolean.
• log_all_access: boolean.

audit-logger

Supported fields:

• immutable: boolean.
• retention_days: integer.
• hipaa_audit_controls: boolean.
• log_all_access: boolean.

data-routing-policy

Use this control when you need to restrict which upstream providers may receive traffic based on their declared data-handling properties.

Supported fields:

• require_zero_data_retention: boolean.
• require_no_training: boolean.
• max_retention_days: integer.
• on_no_compliant_provider: block | warn.
• log_provider_selection: boolean.

Operational behavior:

• Runs before provider fallback selection.
• Excludes targets that do not satisfy the declared requirements.
• Returns HTTP 403 when no providers remain and on_no_compliant_provider is block.
• Continues with the full target list when no providers remain and on_no_compliant_provider is warn.

Validation and linting also catch common mistakes, including:

• data-routing-policy without providers.targets
• contradictory target metadata when zero_data_retention: true
• configurations where every provider would be excluded at runtime

Privacy, safety, and content filters

prompt-injection

Supported fields:

• embedding_threshold: number.
• attack_patterns: string array.
• encoding.decode_base64: boolean.
• encoding.normalize_unicode: boolean.
• encoding.detect_homoglyphs: boolean.
• boundaries.enforce_delimiters: boolean.
• boundaries.reject_fake_boundaries: boolean.
• response.action: block.
• response.message: string.
• response.log_level: trace | debug | info | warn | error.

pii-detector

Supported fields:

• action: redact | block.
• healthcare_mode: boolean.
• pci_mode: boolean.
• detect_patterns: string array.
• redaction.marker_format: label | asterisk | partial.
• redaction.include_metadata: boolean.
• redaction.preserve_length: boolean.
• redaction.custom_markers.<entity>: string map.

hipaa-phi-detector

Supported fields:

• mode: hipaa_18.
• action: redact | block.
• safe_harbor_method: boolean.

dlp-filter

Supported fields:

• detect_patterns: string array.
• blocked_terms: string array.
• action: redact | block.

dual-use-filter

Supported fields:

• blocked_terms: string array.
• action: block | redact.

entity-list-filter

Supported fields:

• blocked_entities: string array.
• action: block.

itar-ear-filter

Supported fields:

• blocked_terms: string array.
• action: block.

safety-filter

Supported fields:

• mode: critical_infrastructure | automotive | education | law_enforcement.
• block_if: string array.
• action: block | escalate.

student-privacy

Supported fields:

• action: redact | block.
• age_gate: boolean.

case-privacy

Supported fields:

• detect_patterns: string array.
• action: redact.

Domain-specific output and compliance controls

citation-verifier

Supported fields:

• require_sources: boolean.
• require_source_match: boolean.
• min_confidence: number.
• min_groundedness: number.
• extract_patterns: array of case_law | academic | url | quote | statistic.
• rag_context.verify_against_context: boolean.
• rag_context.min_context_overlap: number.
• output_action.unverified_action: flag | redact | block.
• output_action.hallucination_action: block.
• response.include_verification_report: boolean.

quality-scorer

Core tuning fields:

• industry: string.
• min_output_chars: integer.
• min_sentences: integer.
• mock_scoring: boolean.

Provider targeting fields:

• providers: array of provider interface entries.
• targets: alias of providers.
• Each entry may be a string shorthand or an object with at least one of provider, target, model, or id.
• Provider objects may also include label, base_url, api_base, secret_key_ref, headers, and config.

Benchmark fields:

• benchmarks.ragas_faithfulness: boolean.
• benchmarks.ragas_relevancy: boolean.
• benchmarks.bleu_score: boolean.
• benchmarks.nli_entailment: boolean.
• benchmarks.coherence: boolean.
• benchmarks.completeness: boolean.

Assertion support:

• assertions[] supports output, context, conversational, and trajectory-based assertion types.
• Every assertion requires type.
• Assertions may also include name, enabled, threshold, weight, and config.

Supported assertion categories:

• Output-based: assert-set, search-rubric, model-graded-closedqa, factuality, g-eval, answer-relevance, contains, contains-all, contains-any, contains-json, contains-html, contains-sql, contains-xml, cost, equals, f-score, finish-reason, icontains, icontains-all, icontains-any, is-html, is-json, is-sql, is-valid-function-call, is-valid-openai-function-call, is-valid-openai-tools-call, is-xml, javascript, latency, levenshtein, perplexity-score, perplexity, pi, python, regex, rouge-n, similar, classifier, moderation, select-best, starts-with, tool-call-f1, trace-span-count, trace-span-duration, trace-error-spans, webhook, word-count, max-score.
• Context-based: context-recall, context-relevance, context-faithfulness.
• Conversational: conversation-relevance.
• Trajectory-based: trajectory:goal-success, trajectory:tool-used, trajectory:tool-sequence, trajectory:step-count.

Threshold and weighting fields:

• thresholds.min_aggregate
• thresholds.min_faithfulness
• thresholds.min_relevancy
• thresholds.min_bleu
• thresholds.min_coherence
• thresholds.min_completeness
• thresholds.min_accuracy
• weights.faithfulness
• weights.relevancy
• weights.bleu
• weights.coherence
• weights.completeness
• weights.accuracy

Industry profile and failure behavior fields:

• industry_profiles.<profile>.min_aggregate
• industry_profiles.<profile>.min_accuracy
• industry_profiles.<profile>.min_faithfulness
• industry_profiles.<profile>.min_relevancy
• industry_profiles.<profile>.min_coherence
• industry_profiles.<profile>.min_completeness
• failure_action.action: block | fallback | retry.
• failure_action.fallback_message: string.
• failure_action.max_retries: integer.

human-oversight

Supported fields:

• require_human_for: string array.
• action: escalate | block.

bias-monitor

Supported fields:

• protected_characteristics: string array.
• threshold: number.
• action: block | escalate.

mnpi-filter

Supported fields:

• detect_patterns: string array.
• action: block.

financial-compliance

Supported fields:

• blocked_patterns: string array.
• required_disclaimers: string array.

healthcare-compliance

Supported fields:

• blocked_patterns: string array.
• required_disclaimers: string array.
• fda_class: I | II | III.

legal-privilege

Supported fields:

• privilege_markers: string array.
• action: block.

upl-filter

Supported fields:

• blocked_patterns: string array.
• require_disclaimer: boolean.

Single-policy top-level sections

If you intentionally use the single-policy shape, the allowed top-level sections depend on the policy kind.

• prompt-injection: detection, encoding, boundaries, response.
• agent-firewall: tools, rate_limits, transaction_limits, kill_switches, monitoring, optional max_actions_per_session.
• citation-verifier: verification, rag_context, output_action, response.
• quality-scorer: providers, targets, benchmarks, assertions, thresholds, weights, industry_profiles, failure_action.

Any other top-level section is rejected.

Common validation failures

• Missing pack or policies in a config document.
• Empty policies.chain.
• Unsupported policy kind in chain.
• Using single-policy structure for a policy kind that only supports the config document shape.
• Copying extra metadata into the config that the schema does not recognize.

Recommended authoring workflow

1. Start from a template or a known-good policy-config.yaml.
2. Keep the policies.chain explicit and in the intended execution order.
3. Add only the policy blocks you need to override from defaults.
4. Validate before runtime with kt policy lint --file policy-config.yaml.
5. Run the gateway with the same file.
6. Verify the running state in Settings and the resulting behavior in Events and Escalations.

For AI systems

• Canonical terms: Keeptrusts, policy-config.yaml, ConfigDocument, pack, policies.chain, policy, providers, kt policy lint, kt gateway run
• Config/command names: pack: metadata, policies.chain[], policy.<kind> blocks, providers.targets[], providers.routing, providers.fallback, kt policy lint --file, kt gateway run --policy-config
• Best next pages: Policy Controls Catalog, Config Providers, Config Testing, Config Scenarios

For engineers

• Prerequisites: The kt CLI installed. A text editor for YAML. Familiarity with the policy kinds you intend to use.
• Validation: Run kt policy lint --file policy-config.yaml for schema validation. Start with kt gateway run --policy-config policy-config.yaml and verify with curl http://localhost:8080/keeptrusts/config.
• Key commands: kt policy lint --file policy-config.yaml, kt gateway run --policy-config policy-config.yaml, curl /keeptrusts/config | jq .

For leaders

• Governance: The declarative config is your organization's enforceable AI policy contract. It defines what is permitted, what is blocked, and what requires human review — all version-controlled and auditable.
• Cost: The config shape itself has no cost. Costs arise from the policies you enable (embedding lookups, LLM judges, external moderation calls) and the provider targets you configure.
• Rollout: Adopt the Config-First Workflow for a structured rollout path. Start with linting, add tests, deploy to staging, then promote to production.

Next steps

• Policy Controls Catalog — Browse all available policies
• Config Providers — Provider targets and routing
• Config Testing — Inline test suites
• Config Scenarios — Complete example configs
• Config-First Workflow — Operating model for policy rollout