TealTiger

---

⚡ 60 秒快速开始

安装：npm install tealtiger 或 pip install tealtiger，然后封装一个现有的 OpenAI 调用：```typescript import { TealOpenAI } from 'tealtiger'; const client = new TealOpenAI({ apiKey: process.env.OPENAI_API_KEY, guardrails: { promptInjection: true } }); const res = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] }); console.log(res.security?.decision ?? 'ALLOW');

（没有输入内容，因此无任何输出。）```python
import os
from tealtiger import TealOpenAI
client = TealOpenAI(api_key=os.environ["OPENAI_API_KEY"], guardrails={"prompt_injection": True})
print(client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello!"}]).security.decision)

（无内容）```text ALLOW Governance receipt emitted; cost and guardrails tracked.

下一步：[完整快速入门](#-quick-start) 和 [示例](https://github.com/agentguard-ai/tealtiger/blob/main/examples).

---

## 🔭 observe() — 零配置仪表化 (v1.4)

一行代码即可为任何LLM客户端添加成本追踪、审计日志、PII检测和行为基线。无需配置文件，无需策略定义。```typescript
import { observe, freeze } from 'tealtiger';
const client = observe(new OpenAI());  // done — all calls are now instrumented
console.log(client.getCost());         // { totalCost: 0.0023, requestCount: 1, ... }

框架还需要调用用户提供的回调函数 on_response。以下是 OpenAI、Anthropic 和 Google 的具体返回结构：

• OpenAI:

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)
callback.on_response(response)

• Anthropic:

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
callback.on_response(response)

• Google:

response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Hello",
)
callback.on_response(response)

总体而言，框架确保以统一的格式调用 LLM，然后将结构化结果返回给回调函数，从而使用户能够在主框架链路上完全控制数据处理结果。

Usage Demo

from tealtiger.observe import observe, freeze
client = observe(OpenAI())             # done — all calls are now instrumented
print(client.get_cost())               # ObserveCostSummary(total_cost=0.0023, ...)
```
**自动获得的功能：** 跨12个提供商的每次请求成本跟踪、带关联ID的结构化审计日志、行为基线（P50/P95/P99）、REPORT_ONLY模式下的PII检测，以及通过 `freeze()` 实现的即时终止开关。每次调用开销低于5毫秒。

参见 [examples/observe-quickstart.ts](https://github.com/agentguard-ai/tealtiger/blob/main/examples/observe-quickstart.ts) 和 [examples/observe_quickstart.py](https://github.com/agentguard-ai/tealtiger/blob/main/examples/observe_quickstart.py)。

---

---

## 📊 治理仪表盘 (v1.4)

实时查看你的 AI 智能体集群——安全状况、成本治理和行为告警，尽在一个界面。

<div align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12842/41f95973c706522c5b907a5d7d96565247adff159a2de9a15c45087ae8dd1351.png" alt="TealTiger 治理仪表盘" width="900">
</div>



**一览无余：**
- **KPI 行** — 总请求数、成本、治理拒绝次数、预算消耗，带颜色编码指标
- **成本速度与预算预测** — 消耗率趋势和耗尽预测
- **防御管道** — 3阶段安全评估流程，含短路率和每阶段延迟
- **金丝雀告警** — 行为漂移检测，含智能体冻结状态和偏差百分比
- **智能体矩阵** — 集群状态表（活跃/空闲/已冻结），含每个智能体的请求指标
- **成本节约** — 按影响排序的优化建议
- **模型路由** — 源到目标路由，含每次请求节约
- **协议治理** — ENFORCE/MONITOR/REPORT_ONLY 策略卡片，含拒绝计数

每个面板独立数据获取，具备故障隔离——一个小部件故障不会级联影响其他面板。

本地运行：`cd dashboard/api && npm run dev` 然后 `cd dashboard/web && npm run dev`（API 位于 :3100，UI 位于 :3000）

### 渐进式公开路径

| 级别 | 入口点 | 获得的功能 |
|-------|-------------|--------------|
| 0 | `observe(client)` | 成本跟踪、审计跟踪、PII检测、行为基线、终止开关 |
| 1 | + guardrails config | 提示注入、内容审核、秘密检测 |
| 2 | + TealEngine 策略 | 每条规则的 ENFORCE/MONITOR/REPORT_ONLY，确定性决策 |
| 3 | + TealFlow 工作流 | 组织级治理继承，声明式 YAML |



## 什么是 TealTiger？

TealTiger 是一个开源 SDK，为 AI 智能体提供**确定性治理**。它在运行时强制执行安全策略、跟踪成本并生成结构化证据——无需基础设施。

> **寻找源代码？** 这是中心仓库。SDK 源代码位于特定语言仓库中：
> - **TypeScript SDK**: [tealtiger-typescript-prod](https://github.com/agentguard-ai/tealtiger-typescript-prod)
> - **Python SDK**: [tealtiger-python-prod](https://github.com/agentguard-ai/tealtiger-python-prod)
>
> 或者使用子模块克隆此仓库：`git clone --recurse-submodules https://github.com/agentguard-ai/tealtiger.git`

与概率性安全过滤器不同，TealTiger 使用**确定性策略评估**：相同的输入 + 相同的策略 = 相同的决策，每次都是。每个治理裁决都可重构、可追溯到编写策略的人员，并可导出为结构化证据（SARIF、JUnit XML、JSON）。

**关键原则：** 治理应作为工程属性嵌入运行时，而非事后审阅的文档。

---

## 🚀 快速开始

### TypeScript```bash
npm install tealtiger
```
INPUT:```typescript
import { TealOpenAI } from 'tealtiger';

const client = new TealOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  guardrails: {
    piiDetection: true,
    promptInjection: true,
    contentModeration: true,
  },
  budget: {
    maxCostPerRequest: 0.50,
    maxCostPerDay: 10.00,
  },
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
});
// Guardrails enforced. Cost tracked. Evidence produced.
```
### Python```bash
pip install tealtiger
```
请提供需要翻译的Markdown内容。```python
from tealtiger import TealOpenAI

client = TealOpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    guardrails={
        "pii_detection": True,
        "prompt_injection": True,
        "content_moderation": True,
    },
    budget={
        "max_cost_per_request": 0.50,
        "max_cost_per_day": 10.00,
    },
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)
# Guardrails enforced. Cost tracked. Evidence produced.
```
---

## ✨ 特性

### 🛡️ 安全护栏
- **PII 检测** — 自动检测并脱敏敏感信息
- **提示注入防护** — 阻止恶意提示注入攻击
- **内容审核** — 过滤有毒、有害或不恰当内容
- **秘密检测** — 支持 9 大类别 500+ 种模式，附带置信度评分
- **自定义规则** — 定义您自己的安全策略

### 💰 成本管控
- **预算执行** — 按请求、会话和日期的硬性限制
- **成本追踪** — 跨所有提供商的实时监控
- **成本告警** — 在可配置阈值下发送通知
- **断路器** — 自动阻止成本失控循环

### 🔌 12 个 LLM 提供商
- **OpenAI** — GPT-4、GPT-4o、GPT-3.5
- **Anthropic** — Claude 3.5、Claude 3
- **Google Gemini** — 多模态支持
- **AWS Bedrock** — Claude、Titan、Jurassic、Command、Llama
- **Azure OpenAI** — 基于部署的路由
- **Cohere** — 对话、RAG、嵌入
- **Mistral AI** — 欧洲数据驻留
- **DeepSeek** — 经济高效的推理模型
- **Groq** — 超低延迟推理
- **Together AI** — 开源模型托管
- **HuggingFace TGI** — 自托管推理
- **xAI (Grok)** — 实时知识

### 🔌 平台适配器
- **AWS Bedrock Agents** — 原生护栏适配器
- **AWS AgentCore** — 行动前后治理插件
- **Azure AI Agent Service** — 工具调用管道中间件

### 🏗️ 治理架构
- **确定性策略评估** — 治理路径中不依赖 LLM
- **结构化证据** — 每次决策产生可重建的记录
- **加密证明** — Merkle 树 + RFC 3161 时间戳 (TealProof)
- **非人类身份 (NHI)** — 代理生命周期、范围强制、零常驻特权
- **FREEZE 规则** — 不可变的紧急终止开关，带防篡改检测
- **关联 ID** — 决策链端到端可追溯
- **策略可追溯性** — 每项裁决均可追溯到制定该策略的人类
- **OWASP Agentic Top 10** — 零配置策略包，覆盖全部 10 项 ASI 风险

---