What's New in v1.6.0
TealEngineno longer permits everything it is asked to govern.evaluate_with_mode()raisesNotImplementedErrorunderPolicyMode.ENFORCEandPolicyMode.MONITOR, where it previously returned ALLOW for every request without reading the policy passed to it.PolicyMode.REPORT_ONLYis unchanged, because that mode promises no evaluation. This is a breaking change and it is the point of the release — see TealEngine below for what to use instead.- OWASP ASI coverage claims corrected from 7 of 10 to 2 of 10 with full coverage.
ASI02, ASI03 and ASI05 were credited to
TealEngine, which governs nothing. See the table for the per-row reasoning.
Earlier releases are in the
changelog,
including 1.5.0's PolicyHotSwapManager and the PolicyTester.test_policy() change that
set the precedent for this one.
Observe Mode (Zero-Config Adoption)
observe() — one line to instrument any LLM client with full visibility and an instant kill switch:
observe(client)— Zero-config proxy wrapping for any of 12 supported LLM providers- Automatic Cost Tracking — Per-request, per-session, per-agent cost accumulation across all providers
- Behavioral Baseline — Statistical profiling (P50/P95/P99 latency, token distribution, cost patterns)
- PII Detection (REPORT_ONLY) — Passive PII scanning without blocking — visibility before enforcement
freeze()/unfreeze()— Instant kill switch to halt any agent immediately, zero policy required- Structured Audit Trail — Every call logged with correlation IDs, cost, latency, and governance metadata
- Governance Dashboard — Real-time overview with KPI metrics, defense pipeline, canary alerts, agent matrix
- Under 5ms overhead — All instrumentation is in-process, deterministic, and offline-capable
pip install tealtiger
🚀 Quick Start
pip install tealtiger
import asyncio
from tealtiger import TealOpenAI, GuardrailEngine, PIIDetectionGuardrail, PromptInjectionGuardrail
async def main():
# Set up guardrails
engine = GuardrailEngine()
engine.register_guardrail(PIIDetectionGuardrail())
engine.register_guardrail(PromptInjectionGuardrail())
# Create guarded client — drop-in replacement for OpenAI
client = TealOpenAI(
api_key="your-openai-key",
agent_id="my-agent",
guardrail_engine=engine
)
response = await client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
print(f"Guardrails passed: {response.security.guardrail_result.passed}")
asyncio.run(main())
🌐 Supported Providers
Three clients are importable from the package root; the rest import from
tealtiger.clients.
| Provider | Client | Import from | Models |
|---|---|---|---|
| OpenAI | TealOpenAI |
tealtiger |
GPT-4, GPT-3.5 Turbo |
| Anthropic | TealAnthropic |
tealtiger |
Claude 3, Claude 2 |
| Azure | TealAzureOpenAI |
tealtiger |
GPT-4, GPT-3.5 |
TealGemini |
tealtiger.clients |
Gemini Pro, Ultra | |
| AWS | TealBedrock |
tealtiger.clients |
Claude, Titan, Jurassic, Command, Llama |
| Cohere | TealCohere |
tealtiger.clients |
Command, Embed |
| Mistral | TealMistral |
⚠️ see note | Large, Medium, Small, Mixtral |
from tealtiger import TealOpenAI
from tealtiger.clients import TealGemini
⚠️
TealMistralis currently broken. It imports themistralaiv0.x API (from mistralai.client import MistralClient), which v1.0 removed. Because the dependency floor is unbounded (mistralai>=0.1.0), any currentmistralaiinstall raisesImportError. Tracked separately — do not rely on this client until it is ported to the v1 API.
🛡️ Key Features
TealEngine — not implemented in the Python SDK
TealEnginedoes not evaluate policy in this SDK. Do not use it for enforcement.
evaluate_with_mode()now raisesNotImplementedErrorunderPolicyMode.ENFORCEandPolicyMode.MONITOR.PolicyMode.REPORT_ONLYstill returns aDecision, because that mode's contract is that evaluation is skipped rather than performed.Until this release the engine returned ALLOW for every request without reading the policy passed to it: a tool configured
{"allowed": False}was permitted, as were prompt injection, PII,os.system('rm -rf /'), and any cost above any limit. It produced no denials under any policy while reportingPOLICY_COMPLIANTand a risk score of 0. That silent allow has been replaced with a loud failure, following the same treatment given toPolicyTester.test_policy()in 1.5.0.It was also not callable as previously documented here: the constructor requires a
ModeConfigrather than a dict, and there is noevaluate()method. Earlier versions of this README showedengine.evaluate({...}), which raisesAttributeError.A previous revision of this section described multi-mode enforcement and risk-based routing. That was inaccurate and has been removed rather than reworded.
What to use instead. The components below are implemented and work: guardrails for PII,
prompt injection and content moderation; observe() for provider instrumentation and cost
tracking; freeze() as a kill switch; TealCircuit for failure isolation; and TealAudit
for the evidence trail.
For tool-allowlist policy enforcement that is specified and conformance-tested, use the TypeScript SDK, which passes the shared conformance corpus for that rule type. The Python engine is scheduled for implementation against the same specification; it is not implemented today.
TealGuard — Security Guardrails
Client-side guardrails that run in milliseconds with no server dependency:
from tealtiger import GuardrailEngine, PIIDetectionGuardrail, PromptInjectionGuardrail, ContentModerationGuardrail
engine = GuardrailEngine(parallel_execution=True, timeout=5000)
engine.register_guardrail(PIIDetectionGuardrail(action="redact"))
engine.register_guardrail(PromptInjectionGuardrail(sensitivity="high"))
engine.register_guardrail(ContentModerationGuardrail(threshold=0.7))
result = await engine.execute(user_input)
print(f"Passed: {result.passed}")
print(f"Risk Score: {result.risk_score}")
Detects: PII (emails, phones, SSNs, credit cards, IBANs, passport numbers), prompt injection, jailbreaks, harmful content, custom patterns.
TealCircuit — Circuit Breaker
Cascading failure prevention with automatic failover:
from tealtiger import TealCircuit
circuit = TealCircuit(
failure_threshold=5, # consecutive failures before opening
timeout=30000, # ms to wait before attempting to close
half_open_requests=3 # successes in half-open before closing
)
# Wraps provider calls with circuit breaker protection
response = await circuit.execute(
lambda: client.chat.completions.create(model="gpt-4", messages=messages)
)
TealAudit — Audit Logging & Redaction
Versioned audit events with security-by-default PII redaction:
from tealtiger import TealAudit, RedactionLevel
from tealtiger.core.audit.teal_audit import AuditConfig, ConsoleOutput
audit = TealAudit(
outputs=[ConsoleOutput()], # or CustomOutput for your own sink
config=AuditConfig(
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:
from tealtiger import ContextManager, ExecutionContextOptions
context = ContextManager.create_context(ExecutionContextOptions(
tenant_id="acme-corp",
application="customer-support", # not `app`
environment="production", # not `env`
))
# Context propagates through TealEngine, TealAudit, and all providers
response = await client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello"}],
context=context
)
# Query audit logs by correlation_id
events = await 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:
Use
PolicyTestRunner, notPolicyTester.PolicyTesteris a deprecated placeholder that never evaluated anything — as of v1.5.0 it raisesNotImplementedErrorrather than returning a misleadingallow.
from tealtiger import PolicyTestRunner, TestCorpora
tester = PolicyTestRunner(engine)
report = tester.run_suite({
"name": "Customer Support Policy Tests",
"tests": [
{
"name": "Block file deletion",
"context": {"agent_id": "support-001", "action": "tool.execute", "tool": "file_delete"},
"expected": {"action": DecisionAction.DENY, "reason_codes": [ReasonCode.TOOL_NOT_ALLOWED]}
},
*TestCorpora.prompt_injection(),
*TestCorpora.pii_detection()
]
})
print(f"Tests: {report.passed}/{report.total} passed")
# CLI usage
python -m tealtiger.cli.test ./policies/*.test.json --coverage --format=junit --output=./results.xml
Cost Tracking & Budget Management
Track costs across 49 models and enforce spending limits:
from tealtiger import CostTracker, BudgetManager, InMemoryCostStorage, TokenUsage
storage = InMemoryCostStorage()
tracker = CostTracker()
budget_manager = BudgetManager(storage)
budget_manager.create_budget({
"name": "Daily GPT-4 Budget",
"limit": 10.0,
"period": "daily",
"alert_thresholds": [50, 75, 90, 100],
"action": "block",
"enabled": True
})
# Estimate before request — takes a TokenUsage, not a dict
estimate = tracker.estimate_cost(
"gpt-4",
TokenUsage(input_tokens=1000, output_tokens=500, total_tokens=1500),
"openai",
)
# Check budget
check = await budget_manager.check_budget("agent-123", estimate)
if not check.allowed:
print(f"Blocked by: {check.blocked_by.name}")
🛡️ OWASP Top 10 for Agentic Applications Coverage
This SDK provides full coverage of 2 of 10 OWASP ASI categories, partial or supporting coverage of 3 more, and does not address the remaining 5.
Revised 2026-11. This table previously claimed "7 out of 10" overall, with 🟢 Full coverage of ASI02, ASI03 and ASI05 via
TealEngine, and listedTealEngineagainst ASI01 and ASI06.TealEnginedoes not evaluate policy in this SDK (see above), so those claims were not supportable and have been corrected. Rows attributed to components that do work are unchanged.
| ASI | Vulnerability | Coverage | Components |
|---|---|---|---|
| ASI01 | Goal Hijacking & Prompt Injection | 🟡 Partial | TealGuard |
| ASI02 | Tool Misuse & Unauthorized Actions | ❌ Not implemented | — |
| ASI03 | Identity & Access Control Failures | ❌ Not implemented | — |
| ASI04 | Supply Chain Vulnerabilities | 🔧 Support | TealAudit |
| ASI05 | Unsafe Code Execution | ❌ Not implemented | — |
| ASI06 | Memory & Context Corruption | ❌ Not implemented | — |
| 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 |
Notes on the corrected rows, so the reasoning is checkable:
- ASI01 keeps 🟡 Partial on the strength of the prompt-injection guardrail, which is
implemented.
TealEngineis removed because its content clause does nothing. - ASI02, ASI03, ASI05 were attributed to
TealEnginealone. With no working engine there is no tool, identity or code-execution enforcement in this SDK. - ASI06 required memory governance. This SDK has PII and secret detectors but no memory
policy engine, no memory decision actions, and no
TealMemoryexport.
📖 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
📚 Documentation
🤝 Contributing
We welcome contributions! Please see our Contributing Guide.
📄 License
Apache 2.0 — see LICENSE
🔗 Links
- PyPI: https://pypi.org/project/tealtiger/
- GitHub (this SDK): https://github.com/agentguard-ai/tealtiger-python-prod
- GitHub (monorepo): https://github.com/agentguard-ai/tealtiger
- TypeScript SDK: https://www.npmjs.com/package/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-python-prod/issues
Made with ❤️ by the TealTiger team
Metadata
Release files for tealtiger 1.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tealtiger-1.6.1.tar.gz | 8.8 MB | Without provenance | Details for tealtiger-1.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tealtiger-1.6.1-py3-none-any.whl | Python 3 | none | any | Details for tealtiger-1.6.1-py3-none-any.whl |
Total release size: 9.1 MB
Release files / tealtiger-1.6.1.tar.gz
| Download URL | tealtiger-1.6.1.tar.gz |
|---|---|
| Size | 8.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2289e6ae71177809b002f12480183855c20dfa1906321d1b1b139facd2727310
|
|
BLAKE2b-256 checksum How to use checksums |
d0029a00f25b96868b6ed9f8351f57184efa8aec5b20329fa5b562618b829218
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / tealtiger-1.6.1-py3-none-any.whl
| Download URL | tealtiger-1.6.1-py3-none-any.whl |
|---|---|
| Size | 286.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4c9ab45318152bc23c40075f3577d0267d0dc97a71e67463b7e3e356ebfeb98
|
|
BLAKE2b-256 checksum How to use checksums |
3a9f525eab4e0dc166758c225001c6920c5598ca07abd6b1ff9085cc3c3acb87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for tealtiger 1.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.