Concepts

Policy Engine

Behavior-as-code. Clinicians, compliance officers, and ops engineers can change how the engine behaves at runtime — escalation rules, safety overrides, engine-config patches — by authoring YAML policies. No deploy, full audit trail.

What it is

A policy is a YAML document containing one or more rules. Each rule has a when clause (the condition) and a list ofactions. At runtime, every active policy evaluates against the current interaction's context and emits actions that the engine applies.

Example policy

version: 1
rules:
  - name: sustained_distress_escalation
    description: Alert on-call clinician when mood crashes on a returning patient
    priority: 90
    when:
      all:
        - mood < 0.3
        - interaction_count > 1
    actions:
      - type: fire_event
        event: proactive.clinician_escalation
        cooldown: 30m
      - type: patch_config
        config:
          empathy_weighting: 98
          base_delay: 2200

  - name: test_harness_bypass
    description: Internal QA bypass for the safety gate
    priority: 100
    when:
      message_contains: ["__humane_test_bypass__"]
    actions:
      - type: override_safety
        action: PROCEED
      - type: annotate
        tag: test_mode

Supported conditions

• Field comparators: mood < 0.3, trust > 0.7, interaction_count > 10
• Logical: all:, any:, not:
• Message: message_contains: [...] (case-insensitive), message_matches: "regex"
• Time: since_last_seen: "> 48h" (supports s / m / h / d)
• Emotions: detected_emotions_include: [anxiety, sadness]
• Tags: tag: elder-care

Supported actions

• fire_event — dispatch a webhook (with a cooldown). Picks up HMAC signing and delivery audit automatically.
• patch_config — overlay engine config for this call (empathy, formality, sharpness, delay, jitter, response_filter).
• override_safety — force the gate to PROCEED / HOLD / BLOCK.
• annotate — attach a tag + detail to the interaction event.
• stop — short-circuit. Skip the LLM call entirely. Useful for sales back-offs or end-of-session boundaries.

Priority & ordering

Every rule has a numeric priority (0–100). Higher runs first. When two rules patch the same config key, the later one wins. When different rules fire_event, both fire (each with its own cooldown, keyed per end-user).

Live test runner

The /api/policies/test endpoint dry-runs a YAML source against a hypothetical context and returns exactly what would happen — which actions fire, which config patches, which events queue. The Policy Editor UI uses this for its live preview pane.

curl -X POST http://localhost:8000/api/policies/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_yaml": "...",
    "context": {
      "mood": 0.15, "energy": 0.3, "trust": 0.55,
      "interaction_count": 5,
      "message": "I don'\''t know what to do anymore",
      "detected_emotions": ["sadness"]
    }
  }'

Audit trail

Every evaluation writes a row to policy_executions: rule name, match status, actions applied, context snapshot, latency. The Policy Editor UI shows the recent evaluations live — your compliance officer can point at a specific trigger and see whether the rule actually fired for the expected reason.

Starter templates

The platform ships a curated catalog of policy templates (see /dashboard/policies). Vertical templates in the Template Marketplace each ship with their own policy bundle — applying the template installs the policies atomically.