Decision Contract (Python)

from pydantic import BaseModel
from typing import List, Optional, Dict, Any

class Decision(BaseModel):
    action: DecisionAction
    reason_codes: List[ReasonCode]
    risk_score: int  # 0-100
    
    # Policy context
    mode: PolicyMode
    policy_id: Optional[str] = None
    policy_version: Optional[str] = None
    
    # Traceability
    correlation_id: str
    trace_id: Optional[str] = None
    
    # Metadata
    provider: Optional[str] = None
    reason: Optional[str] = None
    component_versions: ComponentVersions
    metadata: Optional[Dict[str, Any]] = None

from enum import Enum

class DecisionAction(str, Enum):
    ALLOW = 'ALLOW'
    DENY = 'DENY'
    REQUIRE_APPROVAL = 'REQUIRE_APPROVAL'
    REDACT = 'REDACT'
    TRANSFORM = 'TRANSFORM'
    DEGRADE = 'DEGRADE'

class ReasonCode(str, Enum):
    # Security
    PROMPT_INJECTION = 'PROMPT_INJECTION'
    PII_DETECTED = 'PII_DETECTED'
    UNSAFE_CONTENT = 'UNSAFE_CONTENT'
    
    # Cost
    COST_LIMIT_EXCEEDED = 'COST_LIMIT_EXCEEDED'
    TOKEN_LIMIT_EXCEEDED = 'TOKEN_LIMIT_EXCEEDED'
    
    # Reliability
    CIRCUIT_OPEN = 'CIRCUIT_OPEN'
    RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED'
    
    # Governance
    POLICY_VIOLATION = 'POLICY_VIOLATION'
    APPROVAL_REQUIRED = 'APPROVAL_REQUIRED'

class ComponentVersions(BaseModel):
    sdk: str
    engine: str
    guard: Optional[str] = None
    circuit: Optional[str] = None
    monitor: Optional[str] = None

from tealtiger import TealEngine, DecisionAction

engine = TealEngine(config)
decision = await engine.evaluate(request, context)

if decision.action == DecisionAction.ALLOW:
    return await make_request(request)
    
elif decision.action == DecisionAction.DENY:
    raise PolicyViolationError(
        f"Request denied: {decision.reason}",
        decision.reason_codes
    )
    
elif decision.action == DecisionAction.REQUIRE_APPROVAL:
    return await request_approval(request, decision)
    
elif decision.action == DecisionAction.REDACT:
    redacted = await redact_pii(request)
    return await make_request(redacted)
    
else:
    raise ValueError(f"Unexpected action: {decision.action}")

decision = await engine.evaluate(request, context)

if decision.risk_score >= 86:
    # Critical risk - block and alert
    await alert_security_team(decision)
    raise SecurityViolationError(decision)
    
elif decision.risk_score >= 61:
    # High risk - require approval
    return await request_approval(request, decision)
    
elif decision.risk_score >= 31:
    # Medium risk - log and proceed
    await audit.log('medium_risk_request', decision)
    return await make_request(request)
    
else:
    # Low risk - proceed normally
    return await make_request(request)

decision = await engine.evaluate(request, context)

if ReasonCode.PII_DETECTED in decision.reason_codes:
    # Handle PII detection
    redacted = await redact_pii(request)
    return await make_request(redacted)

if ReasonCode.COST_LIMIT_EXCEEDED in decision.reason_codes:
    # Handle cost limit
    degraded = await use_cheaper_model(request)
    return await make_request(degraded)

if ReasonCode.CIRCUIT_OPEN in decision.reason_codes:
    # Handle circuit breaker
    return await use_fallback(request)

decision = await engine.evaluate(request, context)

if decision.mode == PolicyMode.REPORT_ONLY:
    # Decision is informational only, always proceed
    await audit.log('report_only_decision', decision)
    return await make_request(request)

if decision.mode == PolicyMode.MONITOR:
    # Decision is logged but not enforced
    if decision.action == DecisionAction.DENY:
        await audit.log('would_have_denied', decision)
    return await make_request(request)

if decision.mode == PolicyMode.ENFORCE:
    # Decision is enforced
    if decision.action == DecisionAction.DENY:
        raise PolicyViolationError(decision)
    return await make_request(request)

match decision.action:
    case DecisionAction.ALLOW:
        return await make_request(request)
    case DecisionAction.DENY:
        raise PolicyViolationError(decision)
    case DecisionAction.REQUIRE_APPROVAL:
        return await request_approval(request, decision)
    case DecisionAction.REDACT:
        redacted = await redact_pii(request)
        return await make_request(redacted)
    case _:
        raise ValueError(f"Unexpected action: {decision.action}")

# v1.0.x code continues to work
result = await engine.evaluate(request)
if result.action == 'DENY':
    raise Exception('Denied')

# v1.1.x adds new fields but doesn't break existing code
decision = await engine.evaluate(request, context)
print(decision.correlation_id)  # New in v1.1.x
print(decision.risk_score)  # New in v1.1.x

from tealtiger import Decision, DecisionAction, ReasonCode

async def handle_decision(decision: Decision) -> bool:
    """Handle a policy decision."""
    if decision.action == DecisionAction.ALLOW:
        return True
    elif decision.action == DecisionAction.DENY:
        return False
    else:
        # Handle other actions
        return await handle_special_case(decision)