README.md

May 28, 2026 · View on GitHub

TealTiger SDK

The first open-source AI agent security SDK with client-side guardrails 🛡️

📖 Read the introduction blog post | 📚 Documentation

What's New in v1.3.0 — Autonomous Agent Governance

TealTiger v1.3 introduces cryptographically verifiable governance for autonomous AI agents with 7 new modules:

TealEngineV13 — Pre/post evaluation pipeline with FREEZE rules, automation levels, NHI verification
TealProof — Cryptographic governance receipts (Merkle trees + RFC 3161 timestamping)
TealFlow — Declarative YAML governance workflows with org-level inheritance
TealClassifier — Local ONNX-based ML inference for content classification (≤20ms)
TealDrift — Behavioral drift detection with statistical baselines
TealState — Context size governance with provenance metadata
TealTemporal — Session TTL, cooldown periods, time-of-day restrictions
TealMonitor v2 — Governance-owned cost ceilings, anomaly detection, reasoning-token budgets
OWASP Agentic Top 10 Policy Pack — Zero-config governance for all 10 ASI risks
Platform Adapters — AWS Bedrock Agents, AWS AgentCore, Azure AI Agent Service
12 LLM Providers — Added DeepSeek, Groq, Together AI, HuggingFace TGI, xAI

npm install tealtiger@1.3.0

🚀 Quick Start

npm install tealtiger

import { TealOpenAI } from 'tealtiger';

// Create a governed OpenAI client using the canonical integrated client API.
const client = new TealOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  agentId: 'my-agent',
  customGuardrails: [
    {
      name: 'block-secrets',
      check: async input => ({
        passed: !String(input).includes('sk-'),
        reason: 'Input appears to contain an API key'
      })
    }
  ]
});

const response = await client.chat.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);
console.log('TealTiger metadata:', response.metadata);

The package root exports the canonical integrated clients from src/client. Use client.chat.create() for OpenAI-compatible clients, client.messages.create() for Anthropic, and each provider-specific method listed below. The older src/clients wrappers are kept only for backward compatibility and are deprecated.

🌐 Supported Providers

95%+ market coverage with 7 LLM providers:

Provider	Client	Primary method	Models	Features
OpenAI	`TealOpenAI`	`client.chat.create()`	GPT-4, GPT-3.5 Turbo	Chat, Completions, Embeddings
Anthropic	`TealAnthropic`	`client.messages.create()`	Claude 3, Claude 2	Chat, Streaming
Google	`TealGemini`	`client.generateContent()`	Gemini Pro, Ultra	Multimodal, Safety Settings
AWS	`TealBedrock`	`client.invokeModel()`	Claude, Titan, Jurassic, Command, Llama	Multi-model, Regional
Azure	`TealAzureOpenAI`	`client.chat.create()`	GPT-4, GPT-3.5	Deployment-based, Azure AD
Mistral	`TealMistral`	`client.chat.create()`	Large, Medium, Small, Mixtral	EU Data Residency, GDPR
Cohere	`TealCohere`	`client.chat()` / `client.embed()`	Command, Embed	RAG, Citations, Connectors

🛡️ Key Features

TealEngine — Policy Evaluation

Deterministic policy evaluation with multi-mode enforcement:

import { TealEngine, PolicyMode, DecisionAction, ReasonCode } from 'tealtiger';

const engine = new TealEngine({
  policies: myPolicies,
  mode: {
    defaultMode: PolicyMode.ENFORCE,       // or MONITOR, REPORT_ONLY
    policyModes: {
      'tools.file_delete': PolicyMode.ENFORCE,
      'identity.admin_access': PolicyMode.ENFORCE
    }
  }
});

const decision = engine.evaluate({
  agentId: 'agent-001',
  action: 'tool.execute',
  tool: 'file_delete',
  correlation_id: 'req-12345'
});

switch (decision.action) {
  case DecisionAction.ALLOW:
    await executeTool();
    break;
  case DecisionAction.DENY:
    if (decision.reason_codes.includes(ReasonCode.TOOL_NOT_ALLOWED)) {
      throw new ToolNotAllowedError(decision.reason);
    }
    break;
  case DecisionAction.REQUIRE_APPROVAL:
    await requestApproval(decision);
    break;
}

// Risk-based routing
if (decision.risk_score > 80) {
  await escalateToHuman(decision);
}

Decision fields: action (ALLOW, DENY, REDACT, TRANSFORM, REQUIRE_APPROVAL, DEGRADE), reason_codes (standardized enums), risk_score (0-100), correlation_id, metadata

TealGuard — Security Guardrails

Client-side guardrails that run in milliseconds with no server dependency:

import { GuardrailEngine, PIIDetectionGuardrail, PromptInjectionGuardrail, ContentModerationGuardrail } from 'tealtiger';

const engine = new GuardrailEngine({ mode: 'parallel', timeout: 5000 });

engine.registerGuardrail(new PIIDetectionGuardrail({ action: 'redact' }));
engine.registerGuardrail(new PromptInjectionGuardrail({ sensitivity: 'high' }));
engine.registerGuardrail(new ContentModerationGuardrail({ threshold: 0.7 }));

const result = await engine.execute(userInput);
console.log('Passed:', result.passed);
console.log('Risk Score:', result.riskScore);

Detects: PII (emails, phones, SSNs, credit cards), prompt injection, jailbreaks, harmful content, custom patterns.

TealCircuit — Circuit Breaker

Cascading failure prevention with automatic failover:

import { TealCircuit } from 'tealtiger';

const circuit = new TealCircuit({
  failureThreshold: 5,
  resetTimeout: 30000,
  monitorInterval: 10000
});

// Wraps provider calls with circuit breaker protection
const response = await circuit.execute(() =>
  client.chat.create({ model: 'gpt-4', messages })
);

TealAudit — Audit Logging & Redaction

Versioned audit events with security-by-default PII redaction:

import { TealAudit, RedactionLevel } from 'tealtiger';

const audit = new TealAudit({
  outputs: [new FileOutput('./audit.log')],
  config: {
    input_redaction: RedactionLevel.HASH,    // SHA-256 hash + size (default)
    output_redaction: RedactionLevel.HASH,
    detect_pii: true,
    debug_mode: false
  }
});

Redaction levels: HASH (default, production-safe), SIZE_ONLY, CATEGORY_ONLY, FULL, NONE (debug only).

Correlation IDs & Traceability

End-to-end request tracking across all components:

import { ContextManager } from 'tealtiger';

const context = ContextManager.createContext({
  tenant_id: 'acme-corp',
  app: 'customer-support',
  env: 'production'
});

// Context propagates through TealEngine, TealAudit, and all providers
const response = await client.chat.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
  context: context
});

// Query audit logs by correlation_id
const events = audit.query({ correlation_id: context.correlation_id });

Features: Auto-generated UUID v4 correlation IDs, OpenTelemetry-compatible trace IDs, HTTP header propagation, multi-tenant support.

Policy Test Harness

Validate policy behavior before production deployment:

import { PolicyTester, TestCorpora } from 'tealtiger';

const tester = new PolicyTester(engine);
const report = tester.runSuite({
  name: 'Customer Support Policy Tests',
  tests: [
    {
      name: 'Block file deletion',
      context: { agentId: 'support-001', action: 'tool.execute', tool: 'file_delete' },
      expected: { action: DecisionAction.DENY, reason_codes: [ReasonCode.TOOL_NOT_ALLOWED] }
    },
    ...TestCorpora.promptInjection(),
    ...TestCorpora.piiDetection()
  ]
});

console.log(`Tests: ${report.passed}/${report.total} passed`);

// Export for CI/CD
const junitXml = tester.exportReport(report, 'junit');

# CLI usage
npx tealtiger test ./policies/*.test.json --coverage --format=junit --output=./results.xml

Secret scanning with SARIF

Generate a GitHub Code Scanning-compatible SARIF report from repository source files:

npx tealtiger scan . --format sarif --output results.sarif

The report uses stable detector rule IDs, repository-relative source locations, and fingerprints for deduplication across runs. Upload it with github/codeql-action/upload-sarif@v3; see examples/ci/github-code-scanning-sarif.yml.

Cost Tracking & Budget Management

Track costs across 50+ models and enforce spending limits:

import { CostTracker, BudgetManager, InMemoryCostStorage } from 'tealtiger';

const storage = new InMemoryCostStorage();
const tracker = new CostTracker({ enabled: true });
const budgetManager = new BudgetManager(storage);

budgetManager.createBudget({
  name: 'Daily GPT-4 Budget',
  limit: 10.0,
  period: 'daily',
  alertThresholds: [50, 75, 90, 100],
  action: 'block',
  enabled: true
});

// Estimate before request
const estimate = tracker.estimateCost('gpt-4', { inputTokens: 1000, outputTokens: 500 }, 'openai');

// Check budget
const check = await budgetManager.checkBudget('agent-123', estimate);
if (!check.allowed) {
  console.log(`Blocked by: ${check.blockedBy?.name}`);
}

🛡️ OWASP Top 10 for Agentic Applications Coverage

TealTiger v1.2.0 covers 7 out of 10 OWASP ASIs through its SDK-only architecture:

ASI	Vulnerability	Coverage	Components
ASI01	Goal Hijacking & Prompt Injection	🟡 Partial	TealGuard, TealEngine
ASI02	Tool Misuse & Unauthorized Actions	🟢 Full	TealEngine
ASI03	Identity & Access Control Failures	🟢 Full	TealEngine
ASI04	Supply Chain Vulnerabilities	🔧 Support	TealAudit
ASI05	Unsafe Code Execution	🟢 Full	TealEngine
ASI06	Memory & Context Corruption	🟢 Full	TealEngine, TealGuard
ASI07	Inter-Agent Communication Security	❌ Platform	N/A
ASI08	Cascading Failures & Resource Exhaustion	🟢 Full	TealCircuit
ASI09	Harmful Content Generation	🔧 Support	TealGuard
ASI10	Rogue Agent Behavior	🟢 Full	TealAudit

📖 Complete OWASP ASI Mapping | OWASP Top 10 for Agentic Applications

🎯 Use Cases

Customer Support Bots — Protect customer PII
Healthcare AI — HIPAA compliance
Financial Services — Prevent data leakage
E-commerce — Secure payment information
Enterprise AI — Policy enforcement and audit trails
Education Platforms — Content safety

npm: https://www.npmjs.com/package/tealtiger
GitHub: https://github.com/agentguard-ai/tealtiger
Python SDK: https://pypi.org/project/tealtiger/
Documentation: https://docs.tealtiger.ai
Discord: https://discord.gg/X2ePf8QAj
LinkedIn: https://www.linkedin.com/company/tealtiger/
X (Twitter): https://x.com/TealtigerAI
Contact: reachout@tealtiger.ai
Issues: https://github.com/agentguard-ai/tealtiger/issues

Made with ❤️ by the TealTiger team