Skip to content

Model policies (organization, project and node)

A model policy says which model routes may see a project's documents. It has four layers, from the most general to the most specific, and can only get stricter down the stack:

  1. platform — DX_MODEL_POLICY (a TOML or JSON file, see Models and backends);
  2. organization — GET/PUT /v1/org/model-policy (changing it needs org:manage, Owner);
  3. project — GET/PUT /v1/projects/{id}/model-policy (project:manage), plus zdr_required whenever the project has ZDR enabled (retention);
  4. node — the model_policy fragment of a model-calling node of a workflow (extract).
{
  "allowed_providers": ["anthropic", "openai"],
  "eu_only": false,
  "air_gapped": false,
  "byok_only": false,
  "zdr_required": false,
  "max_usd_per_1k": 20,
  "fallbacks": null,
  "preference": ["anthropic"]
}

Merge

The layers merge with T15's merge_policies: allowed_providers and fallbacks are intersected (a layer that leaves them null does not restrict; [] allows nothing), eu_only, zdr_required, air_gapped and byok_only are OR-ed, max_usd_per_1k takes the minimum and preference only orders (the most specific layer first). A node asking for more than its organization allows only keeps its strict part. byok_only narrows the providers to those with an active BYOK credential in the project; a candidate discarded only for that is reported as byok_missing.

Resolution

POST /v1/model-policy/resolve returns the effective policy, its policy_hash, the route T15's pure resolver picks, its fallbacks and every discarded candidate with its reason (provider_not_allowed, not_local, region_not_eu, zdr_unavailable, capability_missing, over_budget, byok_missing). It is deterministic: the same layers give the same route and hash. With workflow_version_id the answer has one entry per model node (the Models page shows them). When nothing complies, calls fail closed.

Node fragment (workflow-graph 1.1)

extract.config.model_policy takes either a model pin ("gemini:fast", as before) or a fragment with the fields above (all optional). The workflow-graph contract went from 1.0 to 1.1 (additive).

Publication check

Publishing a workflow version runs rule model_policy_compliant after the topology check: a model node whose effective policy leaves no compliant model makes the publication fail with 422 NO_COMPLIANT_MODEL; errors[] holds the node, its pointer, the policy_hash and the reasons. The check is registered when the API loads its routers.

At run time

Before an extract node calls a model, it resolves its effective policy (stored layers, its fragment and the project's ZDR flag): if nothing complies the node fails with NO_COMPLIANT_MODEL and no model is called (fail closed). For example, a project with ZDR enabled has no compliant cloud route in the bundled registry, so its runs fail closed until a deployment registers a ZDR route (or a local one).

Pending

The model a run calls still comes from DX_MODEL or the node's pin; picking it from the effective route (with its fallbacks and BYOK keys) inside the extraction handler is pending. The resolver, the publication check, the run-time refusal and the gateway primitives (route_gateway, ByokGateway) are in place.