Your First Policy

Overview

This guide walks you through creating your first TealTiger policy and observing how it behaves at runtime — with real, runnable code in both TypeScript and Python. By the end you will have a working policy that:

Evaluates estimated cost against a budget
Considers risk scores
Blocks execution when thresholds are exceeded
Emits structured audit events with reason codes

Prerequisites

TypeScript
Python

npm install tealtiger

pip install tealtiger

Step 1: Define a Policy

A policy has three parts: conditions (when it applies), actions (what happens), and a mode (observe or enforce).

TypeScript
Python

import { TealEngine, Policy } from "tealtiger";

const costPolicy: Policy = {
  name: "cost-budget-guard",
  description: "Block requests that exceed budget with high risk",
  mode: "ENFORCE",
  conditions: {
    all: [
      { field: "cost.estimated", operator: "gt", value: 0.05 },
      { field: "risk.composite", operator: "gte", value: 70 },
    ],
  },
  actions: {
    onMatch: "BLOCK",
    reasonCodes: [
      "COST.LIMIT.BUDGET_EXCEEDED",
      "RISK.THRESHOLD.HIGH_RISK_SCORE",
    ],
  },
};

from tealtiger import TealEngine, Policy

cost_policy = Policy(
    name="cost-budget-guard",
    description="Block requests that exceed budget with high risk",
    mode="ENFORCE",
    conditions={
        "all": [
            {"field": "cost.estimated", "operator": "gt", "value": 0.05},
            {"field": "risk.composite", "operator": "gte", "value": 70},
        ]
    },
    actions={
        "on_match": "BLOCK",
        "reason_codes": [
            "COST.LIMIT.BUDGET_EXCEEDED",
            "RISK.THRESHOLD.HIGH_RISK_SCORE",
        ],
    },
)

Step 2: Create the Engine and Evaluate

TypeScript
Python

const engine = new TealEngine({
  policies: [costPolicy],
});

const decision = await engine.evaluate({
  cost: { estimated: 0.12, budget: 0.05 },
  risk: { composite: 82, security: 90, cost: 75 },
  identity: { agent: "order-processor", environment: "production" },
});

console.log(decision.outcome);     // "BLOCK"
console.log(decision.reasonCodes); // ["COST.LIMIT.BUDGET_EXCEEDED", "RISK.THRESHOLD.HIGH_RISK_SCORE"]
console.log(decision.riskScores);  // { composite: 82, security: 90, cost: 75 }

engine = TealEngine(policies=[cost_policy])

decision = engine.evaluate({
    "cost": {"estimated": 0.12, "budget": 0.05},
    "risk": {"composite": 82, "security": 90, "cost": 75},
    "identity": {"agent": "order-processor", "environment": "production"},
})

print(decision.outcome)      # "BLOCK"
print(decision.reason_codes) # ["COST.LIMIT.BUDGET_EXCEEDED", "RISK.THRESHOLD.HIGH_RISK_SCORE"]
print(decision.risk_scores)  # {"composite": 82, "security": 90, "cost": 75}

Step 3: Understand the Decision

Every evaluation produces a Decision object with:

Field	Description
`outcome`	`ALLOW`, `RESTRICT`, or `BLOCK`
`reasonCodes`	Machine-readable codes explaining why
`riskScores`	Normalized scores that influenced the decision
`actions`	What was executed (block, log, audit)
`correlationId`	Unique ID for distributed tracing

Decisions are deterministic — same inputs always produce the same output. No retries, no hidden overrides, no probabilistic behavior.

Step 4: Try Monitor Mode

Change the mode to MONITOR to observe without enforcing:

TypeScript
Python

const monitorPolicy: Policy = {
  ...costPolicy,
  mode: "MONITOR",
};

const engine = new TealEngine({ policies: [monitorPolicy] });
const decision = await engine.evaluate({
  cost: { estimated: 0.12, budget: 0.05 },
  risk: { composite: 82 },
});

console.log(decision.outcome);  // "ALLOW" (not enforced)
console.log(decision.wouldBlock); // true (would have blocked in ENFORCE mode)

monitor_policy = Policy(
    **{**cost_policy.dict(), "mode": "MONITOR"}
)

engine = TealEngine(policies=[monitor_policy])
decision = engine.evaluate({
    "cost": {"estimated": 0.12, "budget": 0.05},
    "risk": {"composite": 82},
})

print(decision.outcome)     # "ALLOW" (not enforced)
print(decision.would_block) # True (would have blocked in ENFORCE mode)

This lets you safely roll out policies in production before switching to ENFORCE.

Step 5: Inspect Audit Events

Every decision automatically emits a structured audit event:

{
  "version": "1.0",
  "correlationId": "ctx-a1b2c3d4",
  "policy": "cost-budget-guard",
  "outcome": "BLOCK",
  "mode": "ENFORCE",
  "reasonCodes": [
    "COST.LIMIT.BUDGET_EXCEEDED",
    "RISK.THRESHOLD.HIGH_RISK_SCORE"
  ],
  "riskScores": {
    "composite": 82,
    "security": 90,
    "cost": 75
  },
  "identity": {
    "agent": "order-processor",
    "environment": "production"
  },
  "timestamp": "2026-04-01T10:30:00Z"
}

Audit events are:

Redacted by default — prompts and completions are never logged
Versioned — schema changes are tracked
Correlation-aware — trace decisions across distributed systems

What You Learned

Policies evaluate signals deterministically against conditions you define
Decisions include reason codes, risk scores, and correlation IDs
Monitor mode lets you observe before enforcing
Audit events provide defensible evidence without data leakage

Next Steps

Policy Authoring Guide

Build richer policies with complex conditions.

Risk Scores

Tune thresholds for graduated enforcement.

Audit & Telemetry

Export and analyze audit events.

Configuration

Control enforcement, logging, and redaction.

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Overview

Prerequisites

Step 1: Define a Policy

Step 2: Create the Engine and Evaluate

Step 3: Understand the Decision

Step 4: Try Monitor Mode

Step 5: Inspect Audit Events

What You Learned

Next Steps

Policy Authoring Guide

Risk Scores

Audit & Telemetry

Configuration

​Overview

​Prerequisites

​Step 1: Define a Policy

​Step 2: Create the Engine and Evaluate

​Step 3: Understand the Decision

​Step 4: Try Monitor Mode

​Step 5: Inspect Audit Events

​What You Learned

​Next Steps

Policy Authoring Guide

Risk Scores

Audit & Telemetry

Configuration

Overview

Prerequisites

Step 1: Define a Policy

Step 2: Create the Engine and Evaluate

Step 3: Understand the Decision

Step 4: Try Monitor Mode

Step 5: Inspect Audit Events

What You Learned

Next Steps