Policy-as-Code DSL

Pavri supports a declarative YAML-based Policy-as-Code (PaC) format that lets you define, version-control, and CI/CD-integrate your agent governance policies.

---

Overview

The DSL compiles to the same PolicySnapshot + PolicyRule evaluator model used at runtime. A policy YAML file can be:

• Stored in Git alongside agent code
• Validated in CI before merge
• Compiled to a snapshot and applied via the dashboard or API

---

Schema Reference

apiVersion: pavri.ai/v1alpha1
kind: Policy
metadata:
  name: my-policy          # Human-readable name
  policy_id: pol-001       # Unique identifier (used by PolicyCache)
  revision: 1              # Monotonically increasing revision
  agent_id: agent-abc      # Optional: scope to a specific agent
spec:
  default_action: allow    # Fallback action when no rule matches
  rules:
    - id: rule-1           # Unique within this document
      type: tool_acl       # Rule type (see below)
      action: allow        # Action to take when rule matches
      subject: tool:*      # Subject pattern
      parameters:
        mode: allowlist
        patterns:
          - tool:search
          - tool:summarize

apiVersion

Currently supported values:

• pavri.ai/v1alpha1 (current)
• pavri.ai/v1beta1
• pavri.ai/v1

Rule Types

Type	Description	Required Parameters
tool_acl	Tool allowlist or denylist	mode (allowlist/denylist), patterns (list of fnmatch patterns)
domain_acl	Domain allowlist or denylist	mode (allowlist/denylist), patterns (list of fnmatch patterns)
cost_budget	Session cost budget enforcement	max_cost_usd (float, must be > 0)
rate_limit	Sliding-window rate limiting	max_calls_per_minute (int, must be > 0)
data_classification	PII / sensitive data regex matching	patterns (list of regex patterns)
generic	Simple subject-matching rule	None required

Actions

Action	Description
allow	Permit the request to proceed
deny	Deny the request (raises PolicyDeniedError)
alert	Allow but emit a threat event
throttle	Allow but add a delay/rate limit signal
block	Hard block (semantic equivalent of deny for budget/rate rules)

---

Validation

Use the CLI to validate a policy file before committing:

# Validate only
pavri-policy validate policies/my-policy.yaml

# Validate + compile (prints JSON snapshot to stdout)
pavri-policy compile policies/my-policy.yaml

# Validate + compile + write to file
pavri-policy compile policies/my-policy.yaml --output out/my-policy-snapshot.json

CI Integration

Add a validation step to your GitHub Actions workflow:

- name: Validate Pavri policies
  run: |
    pip install pavri
    for f in policies/*.yaml; do
      pavri-policy validate "$f"
    done

---

Python SDK Usage

from pavri.dsl import load_policy
from pavri.core.policy import PolicyCache

# Load, validate, and compile in one step
snapshot = load_policy("policies/my-policy.yaml")

# Apply to a PolicyCache
cache = PolicyCache()
cache.update(snapshot)

# Evaluate a request
decision = cache.evaluate("tool:search")
print(decision.action)  # "allow"

Step-by-step

from pavri.dsl import parse_document, validate_document, compile_document

# Parse
doc = parse_document(open("policies/my-policy.yaml").read())

# Validate (check for errors before compiling)
result = validate_document(doc)
for issue in result.issues:
    print(issue)
if not result.is_valid:
    raise SystemExit(1)

# Compile
snapshot = compile_document(doc)
print(f"Compiled {len(snapshot.rules)} rules for policy {snapshot.policy_id}")

---

Dashboard Editor

The dashboard includes a built-in DSL editor at Policies → DSL Editor:

1. Write your policy YAML in the editor
2. Click Validate to check for errors
3. Click Compile to preview the compiled snapshot
4. Copy the snapshot ID and apply it via the dashboard or API

---

Examples

Tool Allowlist

apiVersion: pavri.ai/v1alpha1
kind: Policy
metadata:
  name: research-agent-policy
  policy_id: pol-research-001
spec:
  rules:
    - id: allowed-tools
      type: tool_acl
      action: allow
      parameters:
        mode: allowlist
        patterns:
          - tool:search
          - tool:fetch_url
          - tool:summarize

Cost + Rate Limit

apiVersion: pavri.ai/v1alpha1
kind: Policy
metadata:
  name: budget-policy
  policy_id: pol-budget-001
spec:
  rules:
    - id: cost-limit
      type: cost_budget
      action: block
      parameters:
        max_cost_usd: 10.0
    - id: rate-limit
      type: rate_limit
      action: throttle
      parameters:
        max_calls_per_minute: 60

PII Detection

apiVersion: pavri.ai/v1alpha1
kind: Policy
metadata:
  name: pii-detection-policy
  policy_id: pol-pii-001
spec:
  rules:
    - id: detect-ssn
      type: data_classification
      action: alert
      parameters:
        patterns:
          - '\b\d{3}-\d{2}-\d{4}\b'
    - id: detect-credit-card
      type: data_classification
      action: alert
      parameters:
        patterns:
          - '\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'

---

Validation Rules Reference

The validator runs the following checks in addition to schema validation:

Code	Severity	Description
E001	Error	Duplicate rule ID
E002	Error	Missing required parameter for rule type
E003	Error	Invalid mode value (must be allowlist or denylist)
E004	Error	max_cost_usd must be positive
E005	Error	max_calls_per_minute must be positive
W001	Warning	No rules defined (uses default_action for all requests)
W002	Warning	Empty patterns list for tool_acl or domain_acl
W003	Warning	Empty patterns list for data_classification
W004	Warning	Rule is disabled