AI Policy

Every AI operation the platform performs on a workspace's documents, extraction, classification, resolution, OCR escalation, runs through a routing resolver, and the resolver obeys the workspace's AI policy. The policy is the workspace's standing answer to its own compliance questions: which providers may process our data, in which region, with which models excluded, and with which fallbacks. It is set once, versioned on every change, and enforced on every call without a Talonic operator in the loop.

The policy distinguishes mandatory constraints from preferences. Three fields are mandatory and enforced at routing time for every call: the region pin (eu or us), the provider allowlist, and the model denylist. A deployment outside the pinned region or on a disallowed provider is never a candidate. Everything else, preferred default models, model substitutions, per-operation class overrides, is preference: it steers which compliant candidate is chosen but can never override a mandatory constraint.

The model denylist deserves its own mention because an allowlist cannot replace it. A provider allowlist says "this vendor may process our data"; the denylist says "but never with that one model", which is what a regulated customer with a model-level approval process actually needs. Denial only narrows: it removes candidates from every routing path, including every step of every fallback chain, and never adds one.

The guarantee underneath all of this is that routing fails closed. When a policy leaves an operation with no compliant route, calls for that operation fail; they do not quietly fall through to a provider the policy forbids. To keep that guarantee from becoming a foot-gun, a satisfiability gate runs at activation: a policy that would strand a registered operation (one the platform requires a route for) is refused outright, with the stranded operations named, while advisory operations only produce warnings. A workspace can therefore deliberately leave an uncontracted OCR provider unroutable without breaking its extraction pipeline.

Managing the Policy

The policy is managed programmatically through the public API's /v1/ai surface with a workspace-scoped API key. The surface is deliberately small and evidence-oriented:

• GET /v1/ai/policy reads the effective policy, the enforced constraints, and a live satisfiability status.
• PUT /v1/ai/policy replaces the policy wholesale; PATCH /v1/ai/policy updates part of it. Both default to activating, so the satisfiability gate binds on the write.
• GET /v1/ai/models and GET /v1/ai/operations list every model, class, and operation with the exact constraint blocking each unreachable route.
• POST /v1/ai/routes:explain dry-runs a routing decision through the live production resolver, returning the ordered candidate chain or a fail-closed explanation.
• GET /v1/ai/policy/history reads the append-only version trail, each version with its changed fields and recorded change reason.

curl -X PUT "https://api.talonic.com/v1/ai/policy" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region_pin": "eu",
    "allowed_providers": ["bedrock"],
    "denied_models": ["claude-opus"],
    "change_reason": "Contractual EU residency"
  }'

Boundaries

The surface is precise about what it does not do. Only active policies are enforced; draft and shadow versions are stored and versioned without affecting routing. Nothing about the platform's infrastructure crosses the boundary: responses carry providers and regions, which is what a residency commitment is made of, never endpoint hosts, credentials, or wire-level model identifiers. Self-hosted or customer-operated inference endpoints appear only as deployments marked custom_endpoint: true; per-tenant endpoint credentials are out of scope by design, since endpoints are declared at deployment level. And every route acts only on the workspace of the authenticated key, so no request shape can read or write another workspace's policy.

Every policy write is versioned with an actor and a change reason, and the history is append-only: restoring an earlier configuration means submitting it again as a new version, so the audit trail records the rollback as a deliberate act. For teams running change governance, the policy write fits the same discipline as other workspace settings: stage the intended document, let the satisfiability gate verify it against the live operation catalog, then activate.