Skip to main content
Version: v1.1.0
This page explains TealTiger’s core goals and design principles.

​
Goals

TealTiger exists to give you control, visibility, and safety for your AI agents. This page explains what we’re trying to achieve and why we made the design choices we did.

​
The Big Picture

Building AI agents is exciting, but it comes with real risks:
  • Cost spirals - A bug in your agent loop costs $10,000 overnight
  • Security breaches - Your agent leaks customer PII to an LLM
  • Reliability issues - Rate limits crash your production system
  • Compliance gaps - No audit trail when regulators ask questions
TealTiger solves these problems with policy-based governance that’s deterministic, auditable, and developer-friendly.

​
Core Goals

​
1. Make AI Governance Deterministic

The problem: You can’t trust systems that behave unpredictably. Our goal: Same input + same policy = same decision. Every time. 
// This will ALWAYS return the same decision
const decision = engine.evaluate({
  action: 'tool.execute',
  tool_name: 'file_delete',
  context: { user_id: 'user-123' }
});

// decision.action === 'deny' (guaranteed)
// decision.reason_code === 'POLICY.TOOL.NOT_ALLOWED' (guaranteed)
Why it matters:
  • You can debug issues by replaying decisions
  • Audit logs are meaningful and defensible
  • Your team can trust the system won’t surprise them

​
2. Unify Cost, Security, and Reliability Governance

The problem: Siloed tools create gaps and complexity. Our goal: One policy framework for all AI governance concerns. 
const engine = new TealEngine({
  policies: {
    // Cost governance
    cost: {
      budget_limit: {
        perUser: { daily: 10.00 }
      }
    },
    // Security governance
    security: {
      pii_detection: {
        enabled: true,
        block_on_pii: true
      }
    },
    // Reliability governance
    reliability: {
      rate_limit: {
        requests_per_minute: 60
      }
    }
  }
});
Why it matters:
  • One SDK, one audit model, one enforcement mechanism
  • Consistent governance across your entire AI system
  • Easier to understand, maintain, and evolve

​
3. Be Developer-First

The problem: Governance tools that require UI workflows slow teams down. Our goal: SDK-first design that fits naturally into your code. 
// Install
npm install @tealtiger/sdk

// Use in 3 lines
import { TealEngine } from '@tealtiger/sdk';
const engine = new TealEngine({ policies });
const decision = engine.evaluate(context);
Why it matters:
  • Minimal integration friction
  • Works in CI/CD pipelines
  • No dependency on dashboards or UIs
  • Developers stay in their flow

​
4. Make Every Decision Auditable

The problem: “Why was this blocked?” shouldn’t be a mystery. Our goal: Every decision produces structured audit events with clear explanations. 
{
  "event": {
    "id": "evt_abc123",
    "type": "policy.decision",
    "timestamp": "2026-03-06T10:30:00Z"
  },
  "decision": {
    "action": "deny",
    "reason_code": "COST.BUDGET.EXCEEDED"
  },
  "metadata": {
    "budget_limit": 10.00,
    "current_spend": 12.50
  }
}
Why it matters:
  • Compliance teams get the evidence they need
  • Developers can debug policy behavior
  • Security teams can investigate incidents
  • Regulators get defensible audit trails

​
5. Stay Focused and Composable

The problem: Monolithic platforms create lock-in and complexity. Our goal: Do one thing well and integrate with everything else. What TealTiger does:
  • Policy evaluation
  • Cost tracking
  • Security guardrails
  • Audit logging
What TealTiger doesn’t do:
  • Model hosting (use OpenAI, Anthropic, etc.)
  • Identity management (use your IAM)
  • Log analytics (use your SIEM)
  • Secrets handling (use your KMS)
Why it matters:
  • No vendor lock-in
  • Works with your existing stack
  • Safe to adopt incrementally
  • Easy to remove if needed

​
6. Enable Scalable Policy Design

The problem: Monolithic policies become unmaintainable. Our goal: Compose policies by concern, scale from simple to complex. 
// Start simple
const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: { allowed: false }
    }
  }
});

// Grow to complex
const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        allowed: true,
        conditions: {
          environment: 'production',
          user_role: 'admin',
          requires_approval: true
        }
      }
    },
    cost: { /* ... */ },
    security: { /* ... */ }
  }
});
Why it matters:
  • Policies evolve safely as systems grow
  • Easy to review and test individual policies
  • Clear separation of concerns

​
7. Reduce Surprise, Increase Trust

The problem: “Magic” systems that hide their logic destroy trust. Our goal: No hidden heuristics, no undocumented behavior, no surprises. How we achieve this:
  • Deterministic evaluation (same input = same output)
  • Clear reason codes (explains why)
  • Stable behavior across versions
  • Comprehensive documentation
// You always know why a decision was made
if (decision.action === 'deny') {
  console.log(`Blocked: ${decision.reason_code}`);
  console.log(`Details:`, decision.metadata);
}
Why it matters:
  • Developers trust the system
  • Security teams can rely on enforcement
  • Compliance teams get defensible evidence

​
8. Enable Fast, Safe Innovation

The problem: Governance shouldn’t slow teams down. Our goal: Act as guardrails, not blockers. How we achieve this:
  • Three policy modes: REPORT_ONLY → MONITOR → ENFORCE
  • Gradual rollout strategy
  • Fail fast when constraints are violated
  • Clear feedback on what’s allowed
// Week 1-2: Collect data without blocking
mode: PolicyMode.REPORT_ONLY

// Week 3-4: Log violations without blocking
mode: PolicyMode.MONITOR

// Week 5+: Enforce policies
mode: PolicyMode.ENFORCE
Why it matters:
  • Teams can experiment safely within boundaries
  • Policies catch risky behavior early
  • Innovation happens faster, not slower

​
9. Provide a Stable Foundation

The problem: Breaking changes destroy trust and slow adoption. Our goal: Stable primitives that support safe evolution. Our guarantees:
  • Same input + same policy = same output (within v1.1.x)
  • Audit schema won’t change (within v1.1.x)
  • Reason codes keep their meaning (within v1.1.x)
  • New features are additive, not breaking
Why it matters:
  • You can build on TealTiger with confidence
  • Policies work across versions
  • Audit logs remain valid long-term
  • Future features don’t break existing code

​
What Success Looks Like

TealTiger is successful when: ✅ Developers understand why decisions happen - No mysteries, no surprises
✅ Security teams trust audit evidence - Defensible, reproducible records
✅ Cost controls are predictable - No unexpected bills
✅ Governance feels boring - Reliable, explicit, deterministic If governance feels magical or surprising, we’ve failed.

​
Real-World Example

Here’s how all these goals come together: 
import { TealEngine, PolicyMode } from '@tealtiger/sdk';

// 1. Developer-first: Simple SDK integration
const engine = new TealEngine({
  // 2. Unified governance: Cost + Security + Reliability
  policies: {
    cost: {
      budget_limit: { perUser: { daily: 10.00 } }
    },
    security: {
      pii_detection: { enabled: true, block_on_pii: true }
    },
    tools: {
      file_delete: { allowed: false }
    }
  },
  // 8. Safe innovation: Start in MONITOR mode
  mode: PolicyMode.MONITOR,
  // 4. Auditable: Log all decisions
  audit: {
    enabled: true,
    outputs: [{ type: 'file', path: './audit/events.jsonl' }]
  }
});

// 1. Deterministic: Same input = same output
const decision = engine.evaluate({
  action: 'tool.execute',
  tool_name: 'file_delete',
  context: { user_id: 'user-123' }
});

// 7. No surprises: Clear reason codes
if (decision.action === 'deny') {
  console.log(`Blocked: ${decision.reason_code}`);
  // Output: "Blocked: POLICY.TOOL.NOT_ALLOWED"
}

// 4. Auditable: Structured event emitted
// {
//   "event": { "id": "evt_abc123", "type": "policy.decision" },
//   "decision": { "action": "deny", "reason_code": "POLICY.TOOL.NOT_ALLOWED" },
//   "actor": { "id": "user-123" }
// }

​
How These Goals Guide Design

Every feature in TealTiger is evaluated against these goals:
FeatureGoals it supports
Deterministic evaluation#1, #7, #9
Reason codes#4, #7
Policy modes#8
Audit events#4, #9
SDK-first design#3
Composable policies#6
Vendor-neutral#5
If a feature doesn’t support these goals, we don’t build it.

Non-Goals

What TealTiger intentionally avoids

Anti-Patterns

Common mistakes to avoid

Best Practices

How to use TealTiger effectively

Decision Philosophy

Why determinism matters