Decision Model - TealTiger Docs

Every time TealTiger evaluates a request, it returns a single, deterministic Decision object. This Decision tells your application exactly what to do and why.

What is a Decision?

A Decision is TealTiger’s answer to: “Should this action be allowed?” It contains three essential pieces of information:

Action - What should happen (ALLOW, DENY, TRANSFORM, etc.)
Reason codes - Why this decision was made
Risk score - How risky is this action (0-100)

Think of it like a traffic light with an explanation:

🟢 Green (ALLOW) - “Safe to proceed because…”
🔴 Red (DENY) - “Blocked because…”
🟡 Yellow (REQUIRE_APPROVAL) - “Needs review because…”

Decision structure

Here’s what a typical Decision looks like:

{
  "action": "DENY",
  "reason_codes": ["TOOL_NOT_ALLOWED", "HIGH_RISK_OPERATION"],
  "risk_score": 85,
  "mode": "ENFORCE",
  "policy_id": "security.tool_access.v1",
  "policy_version": "1.0.0",
  "correlation_id": "req-abc123",
  "metadata": {
    "tool": "file_delete",
    "environment": "production"
  }
}

Decision actions

TealTiger supports six decision actions:

ALLOW

The request is safe and should proceed normally.

if (decision.action === 'ALLOW') {
  // Execute the action
  await executeTool(toolName, args);
}

When it happens:

Request meets all policy requirements
Risk score is below thresholds
No violations detected

DENY

The request is blocked and should not proceed.

if (decision.action === 'DENY') {
  // Block the action
  throw new Error(`Action denied: ${decision.reason_codes.join(', ')}`);
}

When it happens:

Policy explicitly blocks the action
Risk score exceeds limits
Required conditions not met

REQUIRE_APPROVAL

The request needs human review before proceeding.

if (decision.action === 'REQUIRE_APPROVAL') {
  // Queue for human review
  await queueForApproval(request, decision);
  return { status: 'pending_approval', approvalId: decision.correlation_id };
}

When it happens:

High-value operations (e.g., refunds over $1000)
Sensitive data access
Unusual patterns detected

REDACT

The request can proceed, but sensitive data must be removed.

if (decision.action === 'REDACT') {
  // Remove sensitive fields before proceeding
  const redactedData = redactFields(data, decision.redaction.fields);
  await processData(redactedData);
}

When it happens:

PII or PHI detected in output
Sensitive data in logs
Compliance requirements

TRANSFORM

The request can proceed, but parameters must be modified.

if (decision.action === 'TRANSFORM') {
  // Use transformed values
  const clampedTokens = decision.transformations.maxTokens;
  await callLLM({ ...params, max_tokens: clampedTokens });
}

When it happens:

Token limits exceeded (clamp to max)
Cost limits exceeded (downgrade model)
Parameter validation (use safe defaults)

DEGRADE

The request can proceed with reduced capabilities.

if (decision.action === 'DEGRADE') {
  // Use degraded mode
  const fallbackModel = decision.degradation.model;
  await callLLM({ ...params, model: fallbackModel });
}

When it happens:

Budget constraints
Rate limits approaching
Service degradation

Reason codes

Reason codes explain why a decision was made. They’re stable, machine-readable identifiers you can use in your code.

Common reason codes

Security:

TOOL_NOT_ALLOWED - Tool is blocked by policy
PII_DETECTED - Personal information found
PROMPT_INJECTION_DETECTED - Attack attempt detected
UNAUTHORIZED_ACCESS - Insufficient permissions

Cost:

BUDGET_EXCEEDED - Daily/monthly budget limit reached
TOKEN_LIMIT_EXCEEDED - Request exceeds token limits
COST_THRESHOLD_EXCEEDED - Single request too expensive

Reliability:

RATE_LIMIT_EXCEEDED - Too many requests
CIRCUIT_BREAKER_OPEN - System is recovering
TIMEOUT_EXCEEDED - Operation took too long

Using reason codes

const decision = await engine.evaluate(request);

if (decision.reason_codes.includes('BUDGET_EXCEEDED')) {
  return {
    error: 'Daily budget exceeded',
    message: 'Please try again tomorrow',
    resetAt: getNextDayTimestamp()
  };
}

if (decision.reason_codes.includes('TOOL_NOT_ALLOWED')) {
  return {
    error: 'Tool access denied',
    message: 'This tool is not available in your environment',
    allowedTools: getAllowedTools()
  };
}

Risk scores

Risk scores quantify how risky an action is on a scale of 0-100:

0-30: Low risk (routine operations)
31-60: Medium risk (requires monitoring)
61-85: High risk (requires approval)
86-100: Critical risk (usually denied)

Risk score breakdown

Risk scores can be broken down by domain:

{
  "risk_score": 75,
  "risk_breakdown": {
    "security": 85,
    "cost": 40,
    "reliability": 30
  }
}

This tells you that the high overall risk (75) is primarily driven by security concerns (85), not cost or reliability.

Policy modes

Decisions behave differently based on the policy mode:

MONITOR mode

Policies are evaluated
Decisions are recorded
Actions are NOT enforced
Useful for testing policies

// In MONITOR mode, even DENY decisions don't block
const decision = await engine.evaluate(request);
// decision.action === 'DENY', but request still proceeds
// Violation is logged for analysis

ENFORCE mode

Policies are evaluated
Decisions are recorded
Actions ARE enforced
Production mode

// In ENFORCE mode, DENY decisions block the request
const decision = await engine.evaluate(request);
if (decision.action === 'DENY') {
  throw new Error('Request blocked by policy');
}

Determinism guarantee

TealTiger guarantees that the same inputs always produce the same Decision:

// Same request, same policy version = same decision
const decision1 = await engine.evaluate(request);
const decision2 = await engine.evaluate(request);

assert(decision1.action === decision2.action);
assert(decision1.reason_codes === decision2.reason_codes);
assert(decision1.risk_score === decision2.risk_score);

This determinism is critical for:

Testing - Verify policy behavior with confidence
Debugging - Reproduce issues reliably
Compliance - Prove consistent enforcement
Auditing - Explain past decisions

Complete example

Here’s a complete example showing how to handle all decision types:

async function handleRequest(request: Request) {
  // Evaluate the request
  const decision = await engine.evaluate({
    action: 'tool.execute',
    tool: request.tool,
    arguments: request.args,
    context: request.context
  });
  
  // Handle the decision
  switch (decision.action) {
    case 'ALLOW':
      // Proceed normally
      return await executeTool(request.tool, request.args);
    
    case 'DENY':
      // Block the request
      throw new Error(
        `Request denied: ${decision.reason_codes.join(', ')}`
      );
    
    case 'REQUIRE_APPROVAL':
      // Queue for human review
      const approvalId = await queueForApproval(request, decision);
      return {
        status: 'pending_approval',
        approvalId,
        message: 'This request requires supervisor approval'
      };
    
    case 'REDACT':
      // Remove sensitive fields
      const redactedArgs = redactFields(
        request.args,
        decision.redaction.fields
      );
      return await executeTool(request.tool, redactedArgs);
    
    case 'TRANSFORM':
      // Use transformed parameters
      const transformedArgs = {
        ...request.args,
        ...decision.transformations
      };
      return await executeTool(request.tool, transformedArgs);
    
    case 'DEGRADE':
      // Use degraded mode
      return await executeTool(
        decision.degradation.fallbackTool,
        request.args
      );
    
    default:
      throw new Error(`Unknown decision action: ${decision.action}`);
  }
}

async def handle_request(request: Request):
    # Evaluate the request
    decision = await engine.evaluate({
        "action": "tool.execute",
        "tool": request.tool,
        "arguments": request.args,
        "context": request.context
    })
    
    # Handle the decision
    if decision["action"] == "ALLOW":
        # Proceed normally
        return await execute_tool(request.tool, request.args)
    
    elif decision["action"] == "DENY":
        # Block the request
        raise Exception(
            f"Request denied: {', '.join(decision['reason_codes'])}"
        )
    
    elif decision["action"] == "REQUIRE_APPROVAL":
        # Queue for human review
        approval_id = await queue_for_approval(request, decision)
        return {
            "status": "pending_approval",
            "approvalId": approval_id,
            "message": "This request requires supervisor approval"
        }
    
    elif decision["action"] == "REDACT":
        # Remove sensitive fields
        redacted_args = redact_fields(
            request.args,
            decision["redaction"]["fields"]
        )
        return await execute_tool(request.tool, redacted_args)
    
    elif decision["action"] == "TRANSFORM":
        # Use transformed parameters
        transformed_args = {
            **request.args,
            **decision["transformations"]
        }
        return await execute_tool(request.tool, transformed_args)
    
    elif decision["action"] == "DEGRADE":
        # Use degraded mode
        return await execute_tool(
            decision["degradation"]["fallbackTool"],
            request.args
        )
    
    else:
        raise Exception(f"Unknown decision action: {decision['action']}")

Best practices

Always check the action - Don’t assume ALLOW
Handle all action types - Use a switch/if-else for all six actions
Log decisions - Record all decisions for debugging and compliance
Use reason codes - Provide helpful error messages based on reason codes
Test in MONITOR mode - Validate policies before enforcing
Preserve correlation IDs - Link decisions to audit events

Next steps

Decision lifecycle

Learn how decisions flow through evaluation and enforcement

Policy modes

Understand MONITOR vs ENFORCE modes

Policy authoring

Write custom policies for your use case

Audit schema

See how decisions are logged

​What is a Decision?

​Decision structure

​Decision actions

​ALLOW

​DENY

​REQUIRE_APPROVAL

​REDACT

​TRANSFORM

​DEGRADE

​Reason codes

​Common reason codes

​Using reason codes

​Risk scores

​Risk score breakdown

​Policy modes

​MONITOR mode

​ENFORCE mode

​Determinism guarantee

​Complete example

​Best practices

​Next steps

Decision lifecycle

Policy modes

Policy authoring

Audit schema

What is a Decision?

Decision structure

Decision actions

ALLOW

DENY

REQUIRE_APPROVAL

REDACT

TRANSFORM

DEGRADE

Reason codes

Common reason codes

Using reason codes

Risk scores

Risk score breakdown

Policy modes

MONITOR mode

ENFORCE mode

Determinism guarantee

Complete example

Best practices

Next steps