Configuration Reference

This page covers all configuration options for TealTiger v1.1.0. Configuration controls how TealTiger behaves at runtime - not what your policies mean.

Quick start

Here’s a minimal configuration to get started:

import { TealEngine, PolicyMode } from 'tealtiger';

const engine = new TealEngine({
  policies: {
    // Your policies here
  },
  mode: PolicyMode.MONITOR,  // Start safe
  logging: {
    level: 'INFO',
    destination: 'console'
  },
  audit: {
    enabled: true,
    outputs: ['file']
  }
});

Configuration Principles

TealTiger configuration follows these principles:

Secure by default - Safe settings out of the box
Explicit over implicit - No hidden behavior
Deterministic - Same config = same behavior
Backward compatible - No breaking changes within v1.1.x
Policy-independent - Config doesn’t change policy logic

Configuration Scope (v1.1.0)

In v1.1.0, configuration controls:

Policy enforcement mode
Logging behavior
Audit emission
Cost estimation and limits
Redaction and data minimization
Error handling behavior

Configuration does not modify:

Policy logic
Condition semantics
Reason code meaning
Risk score calculation

Policy Mode Configuration

Controls whether policies are enforced or just monitored.

Global mode

Set a default mode for all policies:

import { TealEngine, PolicyMode } from 'tealtiger';

// Monitor mode - policies evaluate but don't block
const engine = new TealEngine({
  policies: { /* ... */ },
  mode: PolicyMode.MONITOR
});

// Enforce mode - policies block violations
const engine = new TealEngine({
  policies: { /* ... */ },
  mode: PolicyMode.ENFORCE
});

Policy-specific modes

Override the global mode for specific policies:

const engine = new TealEngine({
  policies: { /* ... */ },
  mode: PolicyMode.MONITOR,  // Default: monitor
  modeOverrides: {
    policy: {
      'security.pii_detection': PolicyMode.ENFORCE,  // Always enforce PII
      'cost.budget_limit': PolicyMode.MONITOR        // Just monitor costs
    }
  }
});

Environment-based modes

Different modes for different environments:

const env = process.env.NODE_ENV;

const engine = new TealEngine({
  policies: { /* ... */ },
  mode: env === 'production' ? PolicyMode.ENFORCE : PolicyMode.MONITOR
});

Available modes

Mode	Behavior	Use when
`MONITOR`	Evaluate policies, log violations, but don’t block	Testing new policies, collecting data
`ENFORCE`	Evaluate policies and block violations	Production, after testing in MONITOR
`REPORT_ONLY`	Evaluate policies, report metrics only	Compliance reporting without enforcement

Default: MONITOR (safe for testing) Best practice: Start with MONITOR, graduate to ENFORCE after validation.

Logging Configuration

Controls structured logging output for debugging and monitoring.

Basic logging setup

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    enabled: true,
    level: 'INFO',
    format: 'json',
    destination: 'console'
  }
});

Log levels

Level	Use when	Example
`DEBUG`	Troubleshooting issues	”Loaded 5 policies from config”
`INFO`	Normal operations	”Policy evaluated successfully”
`WARN`	Suspicious activity	”Budget at 85% in MONITOR mode”
`ERROR`	Failures	”Policy evaluation failed”

Default: INFO Best practice: Use INFO in production, DEBUG only when troubleshooting.

File logging

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    enabled: true,
    level: 'INFO',
    destination: 'file',
    file: {
      path: './logs/tealtiger.log',
      rotation: 'daily',
      maxSize: '100MB',
      maxFiles: 7
    }
  }
});

Custom logger

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    enabled: true,
    destination: 'custom',
    custom: {
      log: (entry) => {
        // Send to your logging service
        console.log(JSON.stringify(entry));
      }
    }
  }
});

Content logging (⚠️ Use with caution)

By default, TealTiger does NOT log prompts or completions for security. Enable only in isolated development:

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    enabled: true,
    includeContent: true  // ⚠️ Only in development!
  }
});

⚠️ Warning: Never enable includeContent in production. It logs sensitive user data.

Audit Configuration

Controls emission of structured audit events for compliance and forensics.

Basic audit setup

import { TealEngine, TealAudit } from 'tealtiger';

const audit = new TealAudit({
  enabled: true,
  outputs: [
    { type: 'file', path: './audit/events.jsonl' },
    { type: 'console' }
  ],
  redactionMode: 'metadata-only'
});

const engine = new TealEngine({
  policies: { /* ... */ },
  audit
});

Audit outputs

Send audit events to multiple destinations:

const audit = new TealAudit({
  enabled: true,
  outputs: [
    // File output
    {
      type: 'file',
      path: './audit/events.jsonl',
      rotation: 'daily'
    },
    // Database output
    {
      type: 'database',
      connection: process.env.DATABASE_URL
    },
    // Custom output
    {
      type: 'custom',
      handler: (event) => {
        // Send to SIEM, data lake, etc.
        sendToSIEM(event);
      }
    }
  ]
});

Redaction modes

Control how sensitive data is handled in audit events:

Mode	Behavior	Use when
`metadata-only`	Only metadata, no content	Production (recommended)
`hash-only`	Content replaced with hashes	Need to verify content without storing it
`partial`	Some content with redaction	Development/debugging

const audit = new TealAudit({
  enabled: true,
  redactionMode: 'metadata-only',  // Safest
  outputs: [{ type: 'file', path: './audit/events.jsonl' }]
});

Default: metadata-only (most secure)

Schema versioning

Audit events include schema version for compatibility:

const audit = new TealAudit({
  enabled: true,
  schemaVersion: '1.1.0',  // Current version
  outputs: [{ type: 'file', path: './audit/events.jsonl' }]
});

Default: 1.1.0 Best practice: Don’t change unless explicitly required for compatibility.

Cost Configuration

Controls cost estimation, tracking, and budget enforcement.

Basic cost tracking

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policies: { /* ... */ },
  cost: {
    estimation: {
      enabled: true
    },
    currency: 'USD',
    budget: {
      enforcement: 'enforce',
      limits: {
        perRequest: 0.50,
        perUser: {
          daily: 10.00,
          monthly: 100.00
        },
        global: {
          daily: 1000.00,
          monthly: 10000.00
        }
      }
    }
  }
});

Cost estimation

Enable cost estimation before making API calls:

const engine = new TealEngine({
  policies: { /* ... */ },
  cost: {
    estimation: {
      enabled: true,  // Estimate before execution
      providers: {
        'openai': {
          'gpt-4': { input: 0.03, output: 0.06 },  // per 1K tokens
          'gpt-3.5-turbo': { input: 0.0015, output: 0.002 }
        },
        'anthropic': {
          'claude-3-opus': { input: 0.015, output: 0.075 }
        }
      }
    }
  }
});

Default: enabled: true Best practice: Keep estimation enabled for cost-based policies to work.

Budget enforcement

Control whether budget violations block requests:

const engine = new TealEngine({
  policies: { /* ... */ },
  cost: {
    budget: {
      enforcement: 'enforce',  // or 'monitor'
      limits: {
        perRequest: 0.50,
        perUser: {
          daily: 10.00
        }
      }
    }
  }
});

Mode	Behavior	Use when
`monitor`	Log violations, don’t block	Testing budget limits
`enforce`	Block requests that exceed budget	Production

Default: monitor (safe for testing)

Currency

Set the currency for cost normalization:

const engine = new TealEngine({
  policies: { /* ... */ },
  cost: {
    currency: 'USD'  // Currently only USD supported
  }
});

Default: USD

Risk Configuration

Controls risk score calculation and threshold behavior.

Basic risk setup

const engine = new TealEngine({
  policies: { /* ... */ },
  risk: {
    scoring: {
      enabled: true
    },
    thresholdBehavior: 'strict'
  }
});

Risk scoring

Enable or disable risk score calculation:

enabled: true - Calculate risk scores (0-100) for all decisions
enabled: false - Skip risk scoring (may reduce policy effectiveness)

Default: enabled: true Best practice: Keep enabled for security and cost policies.

Threshold behavior

Control how risk thresholds are enforced:

Mode	Behavior	Use when
`strict`	Thresholds enforced exactly	Production (recommended)
`lenient`	Allow small buffer zones	Testing/tuning

const engine = new TealEngine({
  policies: { /* ... */ },
  risk: {
    thresholdBehavior: 'strict'  // Exact enforcement
  }
});

Default: strict

Redaction Configuration

Controls data minimization in logs and audit events.

Basic redaction setup

const engine = new TealEngine({
  policies: { /* ... */ },
  redaction: {
    enabled: true,
    strategy: 'metadata-only'
  }
});

Redaction strategies

Strategy	What’s redacted	Use when
`metadata-only`	All content, keep metadata	Production (most secure)
`hash-only`	Content replaced with hashes	Need content verification
`partial`	Sensitive fields only	Development/debugging

const engine = new TealEngine({
  policies: { /* ... */ },
  redaction: {
    enabled: true,
    strategy: 'metadata-only',  // Safest
    fields: [
      'input.prompt',
      'output.completion',
      'actor.email',
      'actor.ip'
    ]
  }
});

Default: enabled: true, strategy: 'metadata-only' Best practice: Always keep redaction enabled in production.

Error Handling Configuration

Controls how enforcement errors are surfaced and handled.

Basic error handling

const engine = new TealEngine({
  policies: { /* ... */ },
  errors: {
    returnReasonCodes: true,
    failOpen: false
  }
});

Return reason codes

Include reason codes in error responses:

true - Include reason codes (helps debugging)
false - Suppress reason codes (more opaque)

Default: true Best practice: Keep enabled for better debugging.

Fail-open vs fail-closed

Control behavior when TealTiger encounters internal errors:

Mode	Behavior	Use when
`failOpen: false`	Block request on internal error	Security-critical workloads (recommended)
`failOpen: true`	Allow request on internal error	High availability requirements

const engine = new TealEngine({
  policies: { /* ... */ },
  errors: {
    failOpen: false  // Fail-closed (secure)
  }
});

Default: false (fail-closed) Best practice: Use fail-closed for security workloads, fail-open only if availability is critical.

Environment-Specific Configuration

Configure TealTiger differently for each environment.

Development environment

const devConfig = {
  mode: PolicyMode.MONITOR,
  logging: {
    enabled: true,
    level: 'DEBUG',
    destination: 'console',
    includeContent: true  // OK in dev
  },
  audit: {
    enabled: true,
    outputs: [{ type: 'console' }],
    redactionMode: 'partial'
  },
  cost: {
    budget: {
      enforcement: 'monitor'
    }
  },
  errors: {
    failOpen: true  // Don't block in dev
  }
};

Production environment

const prodConfig = {
  mode: PolicyMode.ENFORCE,
  logging: {
    enabled: true,
    level: 'INFO',
    destination: 'file',
    includeContent: false  // Never in prod!
  },
  audit: {
    enabled: true,
    outputs: [
      { type: 'file', path: './audit/events.jsonl' },
      { type: 'database', connection: process.env.DATABASE_URL }
    ],
    redactionMode: 'metadata-only'
  },
  cost: {
    budget: {
      enforcement: 'enforce',
      limits: {
        perRequest: 0.50,
        perUser: { daily: 10.00 }
      }
    }
  },
  errors: {
    failOpen: false  // Fail-closed for security
  }
};

Environment-based selection

const env = process.env.NODE_ENV || 'development';
const config = env === 'production' ? prodConfig : devConfig;

const engine = new TealEngine({
  policies: { /* ... */ },
  ...config
});

Complete Production Example

Here’s a complete, production-ready configuration:

import { TealEngine, TealAudit, PolicyMode } from 'tealtiger';

// Initialize audit
const audit = new TealAudit({
  enabled: true,
  outputs: [
    {
      type: 'file',
      path: './audit/events.jsonl',
      rotation: 'daily',
      maxFiles: 30
    },
    {
      type: 'database',
      connection: process.env.DATABASE_URL
    }
  ],
  redactionMode: 'metadata-only',
  schemaVersion: '1.1.0'
});

// Initialize engine
const engine = new TealEngine({
  // Policies
  policies: {
    security: {
      pii_detection: { enabled: true },
      prompt_injection: { enabled: true }
    },
    cost: {
      budget_limits: {
        perRequest: 0.50,
        perUser: { daily: 10.00, monthly: 100.00 },
        global: { daily: 1000.00 }
      }
    }
  },
  
  // Enforcement mode
  mode: PolicyMode.ENFORCE,
  modeOverrides: {
    environment: {
      'development': PolicyMode.MONITOR,
      'staging': PolicyMode.MONITOR,
      'production': PolicyMode.ENFORCE
    }
  },
  
  // Logging
  logging: {
    enabled: true,
    level: 'INFO',
    format: 'json',
    destination: 'file',
    file: {
      path: './logs/tealtiger.log',
      rotation: 'daily',
      maxSize: '100MB',
      maxFiles: 7
    },
    includeContent: false
  },
  
  // Audit
  audit,
  
  // Cost tracking
  cost: {
    estimation: {
      enabled: true,
      providers: {
        'openai': {
          'gpt-4': { input: 0.03, output: 0.06 },
          'gpt-3.5-turbo': { input: 0.0015, output: 0.002 }
        }
      }
    },
    currency: 'USD',
    budget: {
      enforcement: 'enforce',
      limits: {
        perRequest: 0.50,
        perUser: {
          daily: 10.00,
          monthly: 100.00
        },
        global: {
          daily: 1000.00,
          monthly: 10000.00
        }
      }
    }
  },
  
  // Risk scoring
  risk: {
    scoring: {
      enabled: true
    },
    thresholdBehavior: 'strict'
  },
  
  // Redaction
  redaction: {
    enabled: true,
    strategy: 'metadata-only',
    fields: [
      'input.prompt',
      'output.completion',
      'actor.email',
      'actor.ip'
    ]
  },
  
  // Error handling
  errors: {
    returnReasonCodes: true,
    failOpen: false
  }
});

export default engine;

Configuration Precedence

When multiple configurations apply, TealTiger uses this precedence order (highest to lowest):

Policy-specific configuration - Overrides for individual policies
Environment-level configuration - Settings per environment (dev/staging/prod)
Global configuration - Default settings for all policies
Built-in defaults - TealTiger’s safe defaults

Example

const engine = new TealEngine({
  // Global: MONITOR mode
  mode: PolicyMode.MONITOR,
  
  modeOverrides: {
    // Environment: ENFORCE in production
    environment: {
      'production': PolicyMode.ENFORCE
    },
    // Policy-specific: Always ENFORCE PII detection
    policy: {
      'security.pii_detection': PolicyMode.ENFORCE
    }
  }
});

// Result in production:
// - security.pii_detection → ENFORCE (policy-specific wins)
// - other policies → ENFORCE (environment wins)

// Result in development:
// - security.pii_detection → ENFORCE (policy-specific wins)
// - other policies → MONITOR (global wins)

Configuration Stability Guarantees

Within v1.1.x releases, TealTiger guarantees: ✅ No renamed keys - Configuration keys stay the same
✅ No changed meanings - Behavior stays consistent
✅ No silent default changes - Defaults won’t change without notice
✅ Additive only - New options added, old ones never removed Breaking configuration changes require a major version bump (v2.0.0).

What Configuration Does NOT Do

Configuration controls execution behavior, not governance logic: ❌ Does NOT modify policy logic
❌ Does NOT change reason code meanings
❌ Does NOT alter risk score calculations
❌ Does NOT introduce non-deterministic behavior Configuration affects how policies run, not what they decide.

Best Practices

Start in MONITOR mode - Test policies before enforcing
Keep content logging disabled - Never log prompts/completions in production
Use fail-closed - Block on errors for security workloads
Enable audit - Always emit audit events for compliance
Treat config as code - Version control your configuration
Test in staging - Validate config changes before production
Use environment variables - Don’t hardcode secrets or URLs
Monitor audit events - Set up alerts for policy violations
Rotate logs - Prevent disk space issues
Document overrides - Explain why you override defaults

Policy Modes

Understand MONITOR vs ENFORCE

Audit Event Schema

Complete audit event structure

Logging Behavior

How TealTiger emits logs

Cost Metadata

Track AI spending

Decision Lifecycle

How decisions are evaluated

Policy Authoring

Write effective policies

Get Started (v1.1.0)

Why TealTiger (v1.1.0)

Cookbook (v1.1.0)

Core Concepts (v1.1.0)

Policy Design (v1.1.0)

Integrations (v1.1.0)

Audit & Telemetry (v1.1.0)

Reference (v1.1.0)

Architecture (v1.1.0)

Versioning (v1.1.0)

About (v1.1.0)

API Reference - TypeScript

API Reference - Python

Governance & Compliance (v1.1.0)

Deployment (v1.1.0)

Guides (v1.1.0)

Versions

Roadmap

​Configuration Reference

​Quick start

​Configuration Principles

​Configuration Scope (v1.1.0)

​Policy Mode Configuration

​Global mode

​Policy-specific modes

​Environment-based modes

​Available modes

​Logging Configuration

​Basic logging setup

​Log levels

​File logging

​Custom logger

​Content logging (⚠️ Use with caution)

​Audit Configuration

​Basic audit setup

​Audit outputs

​Redaction modes

​Schema versioning

​Cost Configuration

​Basic cost tracking

​Cost estimation

​Budget enforcement

​Currency

​Risk Configuration

​Basic risk setup

​Risk scoring

​Threshold behavior

​Redaction Configuration

​Basic redaction setup

​Redaction strategies

​Error Handling Configuration

​Basic error handling

​Return reason codes

​Fail-open vs fail-closed

​Environment-Specific Configuration

​Development environment

​Production environment

​Environment-based selection

​Complete Production Example

​Configuration Precedence

​Example

​Configuration Stability Guarantees

​What Configuration Does NOT Do

​Best Practices

​Related Reading