#Policy engine

Policy as code. Five modes. Compose into workflows.

A policy is the operator's English description of a rule, plus a declared input schema. The same policy can be evaluated in five modes, picked by the caller at request time. Multiple policies compose into linear chains or parallel graphs (DAGs), with conditional edges that branch based on upstream outcomes and a weighted aggregate score rolled up across the whole evaluation.

At a glance — three composition shapes:

┌─────────────────────────────────────────────────────────────────┐
│ Single policy                                                   │
│                                                                 │
│   POST /api/v1/policies/evaluate                                │
│                                                                 │
│   { policy } ──► result                                         │
│                                                                 │
│   One decision. Mode picked at request time.                    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Chain  (sequential)                                             │
│                                                                 │
│   POST /api/v1/policies/chain                                   │
│                                                                 │
│   classify ─► score ─► decide ─► generate                       │
│                                                                 │
│   Each step sees previous step's outcome via `previous` and     │
│   `chain[]`. Sequential — total latency = Σ steps.              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Graph  (DAG with parallel + conditional)                        │
│                                                                 │
│   POST /api/v1/policies/graph    OR    { graph_slug: "..." }    │
│                                                                 │
│        ┌─► classify ─┐                                          │
│   inputs            ├─► decide ─► generate                      │
│        └─► score   ─┘                                           │
│                                                                 │
│   `depends_on` declares dependencies. Independent nodes run in  │
│   parallel. Conditional edges branch. Total latency = max-level │
│   per parallel set + sum across levels.                         │
└─────────────────────────────────────────────────────────────────┘

Score aggregation: every chain / graph / multi-policy response includes an optional aggregate block with a weighted 0-1 score across contributing policies, bucketed against tenant thresholds (pass / review / block) with an optional downstream action.

#Continue reading

This page documents the single-policy evaluate endpoint. For workflow composition, see:

• Examples — one policy, three modes (validate / generate / decide) end-to-end.
• Chains — sequential workflows. POST /api/v1/policies/chain.
• Graphs — DAGs with parallel execution + conditional routing. POST /api/v1/policies/graph.
• Score aggregation — weighted roll-up across chain / graph / multi-policy responses.

#Five modes

The policy is authored once and opts into the subset of modes it supports. Operators write the rule; callers choose the lens.

For multi-step workflows that combine modes — classify → score → decide → generate — see Chains and Graphs.

The engine never executes actions itself — decide returns the rendered payload for your caller to send downstream (Workday, Slack, your own ticket system). Keeps the engine a pure reasoning surface with no integration credentials.

#Headers

#Request body

#PolicyRef object

#Response

#PolicyResult object

#Outcome shapes

The outcome object is polymorphic — parse it based on mode.

// mode: "validate"
"outcome": {
  "passed":  false,
  "reasons": ["approver_role must be in {director, vp} when risk = medium"]
}

// mode: "generate"
"outcome": {
  "generated_text": "Hi Sarah, I've reviewed your refund request for the blender...",
  "reason":         "Generated by claude-sonnet-4-6."
}

// mode: "decide"
"outcome": {
  "action_id": "approve_refund",
  "payload":   {
    "system": "workday",
    "amount": "200",
    "user":   "sarah@acme.com"
  },
  "reason":    "Customer is within 30-day window and product is defective."
}

// mode: "score"
"outcome": {
  "score":   0.85,
  "reasons": ["Within warranty window", "Customer in good standing"]
}

// mode: "classify"
"outcome": {
  "labels":        ["billing", "urgent"],
  "primary_label": "billing",
  "confidence":    0.92
}

For decide, action_id may be null — meaning the LLM judged "no action required given the policy and inputs." That's a first-class outcome, not an error. When action_id is non-null, payload is the action's template with ${input.X} placeholders substituted against the request's inputs bag.

#Citation object (reserved)

#EvaluateSummary object

Validate-mode only. Generate and decide batches return summary: null even when aggregation is set.

#Status values

#Partial failure

A batch is partial-failure tolerant by design. If one policy slug doesn't resolve or one input is missing, that row gets a non-ok status and a populated detail — the rest of the batch still runs. The endpoint returns 200 whenever the request itself was well-formed; you inspect results[].status to decide what's actionable.

#Errors

This operation can return any of the common error codes. Request-level errors (i.e. before any per-policy result is produced):

#Authoring a policy

The admin console at admin.velgent.com/policies is where the policy lives. A policy version carries:

• English text — what the policy says, in plain English. The source of truth.
• Declared inputs — names + types + required flag. Same schema whether the caller is in validate / generate / decide / score / classify mode.
• Supported modes — subset of {validate, generate, decide, score, classify}. The runtime gate.
• Action catalogue (decide mode) — array of structured actions with id, label, description, and an optional payload_template.
• Classify-label catalogue (classify mode) — the set of labels the policy is allowed to emit. Hallucinated labels are rejected.
• Score mapping (aggregation) — how this policy's outcome maps to a 0-1 contribution score when it's part of a chain or graph. See Score aggregation.
• Weight (aggregation) — relative weight in chain/graph aggregation. Default 1.0.
• Knowledge refs — reserved for RAG retrieval. Empty today.

The composer compiles the English into a DSL document at save time. The DSL drives the deterministic validate path (no LLM at runtime). Generate, decide, score, and classify modes pass the English directly to Claude — the DSL isn't consulted there.

#The playground

Once a policy is published, the playground (Playground button on the policy detail page) lets administrators exercise it through all five modes from the admin UI, using the same code path real API callers hit. Useful for sanity-checking a new policy before wiring it into a workflow.

Next: Examples →