Skip to main content
Version: v1.1.0
This page shows you how to use TealTiger correctly.

​
Best Practices

You’ve learned what TealTiger does (Goals), what it doesn’t do (Non-Goals), and what to avoid (Anti-Patterns). Now let’s talk about how to use it effectively.

​
Core Principles

Before diving into specific practices, remember these principles:
  1. Policies are contracts - Treat them like API contracts, not config files
  2. Determinism is a feature - Same input = same output is what you want
  3. Context flows through inputs - Dynamic data goes in context, not policies
  4. Compose by concern - Separate cost, security, and reliability policies
  5. Audit is first-class - Treat audit events as durable governance records

​
Best Practices

​
1. Treat Policies as Governance Contracts

The practice: Policies should be explicit, reviewed, versioned, and stable. 
// ✅ GOOD: Versioned, reviewed policies
// policies/v1.0.0.ts
export const policies_v1_0_0 = {
  cost: {
    budget_limit: {
      perUser: { daily: 10.00 }
    }
  },
  security: {
    pii_detection: {
      enabled: true,
      block_on_pii: true
    }
  }
};

// In your app
import { policies_v1_0_0 } from './policies/v1.0.0';
const engine = new TealEngine({ policies: policies_v1_0_0 });
Why it works:
  • Policies are versioned in source control
  • Changes require code review
  • You can roll back to previous versions
  • Audit logs reference specific policy versions
Checklist:
  • Store policies in version control
  • Require code review for policy changes
  • Tag policy versions
  • Document why policies exist

​
2. Keep Policies Deterministic and Explainable

The practice: Every decision should have a clear, understandable reason. 
// ✅ GOOD: Clear, deterministic policy
const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        allowed: false,  // Clear: never allowed
        reason: 'File deletion is disabled for safety'
      },
      web_search: {
        allowed: true,   // Clear: always allowed
        conditions: {
          environment: 'production'  // Clear condition
        }
      }
    }
  }
});

// Decision is always explainable
const decision = engine.evaluate({
  action: 'tool.execute',
  tool_name: 'file_delete'
});
console.log(decision.reason_code);  // "POLICY.TOOL.NOT_ALLOWED"
Why it works:
  • Developers understand why decisions happen
  • Debugging is straightforward
  • Audit logs are meaningful
  • No surprises
Checklist:
  • Use clear condition names
  • Avoid ambiguous thresholds
  • Document policy intent
  • Test edge cases

​
3. Pass Context Through Inputs, Not Policy Logic

The practice: Encode dynamic behavior in inputs, keep policy logic stable. 
// ✅ GOOD: Dynamic context, stable policies
const engine = new TealEngine({
  policies: {
    cost: {
      budget_limit: {
        perUser: { daily: 10.00 }  // Stable policy
      }
    }
  }
});

// Dynamic data flows through context
const decision = engine.evaluate({
  action: 'llm.call',
  estimated_cost: 2.50,
  context: {
    user_id: user.id,              // Dynamic
    user_tier: user.tier,          // Dynamic
    environment: process.env.NODE_ENV,  // Dynamic
    request_id: generateId()       // Dynamic
  }
});
Why it works:
  • Policies remain stable and testable
  • Dynamic data doesn’t require policy changes
  • Audit logs capture full context
  • Easier to reason about behavior
Checklist:
  • Pass user identity through context
  • Pass environment through context
  • Pass request metadata through context
  • Keep policies environment-agnostic

​
4. Separate Policies by Concern

The practice: Compose policies by domain (cost, security, reliability). 
// ✅ GOOD: Separated by concern
const engine = new TealEngine({
  policies: {
    // Cost governance
    cost: {
      budget_limit: { perUser: { daily: 10.00 } },
      token_limit: { max_input_tokens: 4000 }
    },
    
    // Security governance
    security: {
      pii_detection: { enabled: true, block_on_pii: true },
      prompt_injection: { enabled: true, block_on_injection: true }
    },
    
    // Reliability governance
    reliability: {
      rate_limit: { requests_per_minute: 60 },
      circuit_breaker: { failure_threshold: 5 }
    },
    
    // Tool governance
    tools: {
      file_delete: { allowed: false },
      web_search: { allowed: true },
      database_query: { allowed: true, requires_approval: true }
    }
  }
});
Why it works:
  • Each policy is focused and testable
  • Easy to review individual concerns
  • Can evolve policies independently
  • Clear ownership (security team owns security policies, etc.)
Checklist:
  • Group policies by domain
  • Avoid mixing concerns in one policy
  • Test policies independently
  • Assign ownership by domain

​
5. Use Audit Events as First-Class Output

The practice: Treat audit events as durable governance records. 
// ✅ GOOD: Audit events forwarded to durable storage
const engine = new TealEngine({
  policies: { /* ... */ },
  audit: {
    enabled: true,
    outputs: [
      // Long-term storage
      {
        type: 'file',
        path: './audit/events.jsonl',
        rotation: 'daily',
        maxFiles: 365  // Keep 1 year
      },
      // Real-time monitoring
      {
        type: 'custom',
        handler: async (event) => {
          await datadog.log(event);
          
          // Alert on high-risk events
          if (event.signals?.risk?.score > 80) {
            await pagerDuty.alert({
              severity: 'high',
              message: `High-risk decision: ${event.decision.reason_code}`,
              details: event
            });
          }
        }
      }
    ]
  }
});
Why it works:
  • Compliance teams get evidence they need
  • Security teams can investigate incidents
  • Developers can debug policy behavior
  • Regulators get defensible audit trails
Checklist:
  • Enable audit logging
  • Forward to durable storage
  • Set up retention policies
  • Monitor for high-risk events

​
6. Integrate Early in the Execution Path

The practice: Evaluate policies BEFORE executing AI actions. 
// ✅ GOOD: Evaluate before executing
async function executeAgent(userInput: string, user: User) {
  // 1. Evaluate policy FIRST
  const decision = engine.evaluate({
    action: 'llm.call',
    input: userInput,
    estimated_cost: estimateCost(userInput),
    context: {
      user_id: user.id,
      user_tier: user.tier
    }
  });
  
  // 2. Handle decision
  if (decision.action === 'deny') {
    throw new Error(`Blocked: ${decision.reason_code}`);
  }
  
  if (decision.action === 'redact') {
    userInput = applyRedaction(userInput, decision.redactions);
  }
  
  // 3. Execute only if allowed
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: userInput }]
  });
  
  return response;
}
Why it works:
  • Fail fast when constraints are violated
  • Reduces cost (don’t call LLM if blocked)
  • Reduces blast radius (catch issues early)
  • Improves predictability
Checklist:
  • Evaluate before LLM calls
  • Evaluate before tool executions
  • Handle all decision types
  • Log evaluation results

​
7. Keep Policies Vendor-Neutral

The practice: Base policies on behavior and risk, not provider details. 
// ✅ GOOD: Vendor-neutral policies
const engine = new TealEngine({
  policies: {
    cost: {
      budget_limit: {
        perUser: { daily: 10.00 }  // Works with any provider
      }
    },
    security: {
      pii_detection: {
        enabled: true,  // Works with any provider
        block_on_pii: true
      }
    }
  }
});

// Provider selection in your app, not policies
const provider = user.tier === 'premium' ? openai : anthropic;
const response = await provider.call(prompt);
Why it works:
  • Policies survive provider changes
  • Easy to migrate between providers
  • Policies focus on governance, not infrastructure
  • Reduces vendor lock-in
Checklist:
  • Avoid provider-specific logic
  • Use behavior-based conditions
  • Test with multiple providers
  • Document provider assumptions

​
8. Version Policies Alongside Code

The practice: Release policies with application changes. 
// ✅ GOOD: Policies versioned with code
// package.json
{
  "name": "my-ai-app",
  "version": "2.1.0",
  "dependencies": {
    "@tealtiger/sdk": "^1.1.0"
  }
}

// policies/v2.1.0.ts
export const policies = {
  // Policies for app version 2.1.0
  cost: { /* ... */ },
  security: { /* ... */ }
};

// app.ts
import { policies } from './policies/v2.1.0';
const engine = new TealEngine({ policies });
Why it works:
  • Policies and code stay in sync
  • Rollbacks include policy rollbacks
  • Audit logs reference specific versions
  • Reproducible deployments
Checklist:
  • Store policies in source control
  • Version policies with app versions
  • Tag releases
  • Document policy changes in changelog

​
9. Start Simple, Then Expand Coverage

The practice: Begin with high-impact policies, expand deliberately. 
// Week 1: Start with cost control only
const engine_v1 = new TealEngine({
  policies: {
    cost: {
      budget_limit: { perUser: { daily: 10.00 } }
    }
  },
  mode: PolicyMode.MONITOR  // Observe first
});

// Week 3: Add security after observing cost patterns
const engine_v2 = new TealEngine({
  policies: {
    cost: { /* ... */ },
    security: {
      pii_detection: { enabled: true, block_on_pii: true }
    }
  },
  mode: PolicyMode.MONITOR  // Still observing
});

// Week 5: Add reliability and switch to ENFORCE
const engine_v3 = new TealEngine({
  policies: {
    cost: { /* ... */ },
    security: { /* ... */ },
    reliability: {
      rate_limit: { requests_per_minute: 60 }
    }
  },
  mode: PolicyMode.ENFORCE  // Now enforcing
});
Why it works:
  • Reduces initial friction
  • Builds confidence gradually
  • Allows learning from data
  • Avoids over-governing early
Checklist:
  • Start with 1-2 high-impact policies
  • Use MONITOR mode initially
  • Observe for 1-2 weeks
  • Expand based on data

​
10. Review Policies as Systems Evolve

The practice: Periodically review and adjust policies. 
// ✅ GOOD: Regular policy reviews
// Monthly review process:
// 1. Analyze audit logs
const stats = analyzeAuditLogs('./audit/events.jsonl', {
  period: 'last_30_days'
});

console.log('Denial rate:', stats.denialRate);
console.log('Top reason codes:', stats.topReasonCodes);
console.log('Cost trends:', stats.costTrends);

// 2. Adjust policies based on data
if (stats.denialRate < 0.01) {
  // Too permissive? Tighten policies
} else if (stats.denialRate > 0.10) {
  // Too restrictive? Loosen policies
}

// 3. Update policies with intent
const policies_v2 = {
  ...policies_v1,
  cost: {
    budget_limit: {
      perUser: { daily: 15.00 }  // Increased based on usage patterns
    }
  }
};

// 4. Test before deploying
testPolicies(policies_v2, goldenCorpus);
Why it works:
  • Policies stay relevant as systems evolve
  • Data-driven adjustments
  • Catches drift early
  • Maintains trust
Checklist:
  • Review policies monthly or quarterly
  • Analyze audit logs for patterns
  • Adjust thresholds based on data
  • Test changes before deploying

​
Putting It All Together

Here’s a complete example following all best practices: 
// policies/v1.0.0.ts - Versioned, reviewed policies
export const policies_v1_0_0 = {
  // Separated by concern
  cost: {
    budget_limit: { perUser: { daily: 10.00 } },
    token_limit: { max_input_tokens: 4000 }
  },
  security: {
    pii_detection: { enabled: true, block_on_pii: true },
    prompt_injection: { enabled: true, block_on_injection: true }
  },
  reliability: {
    rate_limit: { requests_per_minute: 60 },
    circuit_breaker: { failure_threshold: 5 }
  },
  tools: {
    file_delete: { allowed: false },
    web_search: { allowed: true }
  }
};

// app.ts - Integration following best practices
import { TealEngine, PolicyMode } from '@tealtiger/sdk';
import { policies_v1_0_0 } from './policies/v1.0.0';

const engine = new TealEngine({
  policies: policies_v1_0_0,
  mode: PolicyMode.ENFORCE,
  audit: {
    enabled: true,
    outputs: [
      { type: 'file', path: './audit/events.jsonl' },
      { type: 'custom', handler: sendToDatadog }
    ]
  }
});

async function executeAgent(userInput: string, user: User) {
  // Evaluate early
  const decision = engine.evaluate({
    action: 'llm.call',
    input: userInput,
    estimated_cost: estimateCost(userInput),
    // Context flows through inputs
    context: {
      user_id: user.id,
      user_tier: user.tier,
      environment: process.env.NODE_ENV,
      request_id: generateId()
    }
  });
  
  // Handle decision
  if (decision.action === 'deny') {
    throw new Error(`Blocked: ${decision.reason_code}`);
  }
  
  if (decision.action === 'redact') {
    userInput = applyRedaction(userInput, decision.redactions);
  }
  
  // Execute only if allowed
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: userInput }]
  });
  
  return response;
}

​
Summary

Following these best practices ensures: ✅ Predictable enforcement - Deterministic, explainable decisions
✅ Clean audit trails - Durable governance records
✅ Scalable governance - Policies that grow with your system
✅ Developer trust - No surprises, clear reasoning TealTiger works best when governance is visible, intentional, and boring.

Goals

What TealTiger is designed to achieve

Anti-Patterns

Common mistakes to avoid

Decision Philosophy

Why determinism matters

Quickstart

Get started with TealTiger