Metadata-Version: 2.5
Name: ai-traceguard
Version: 0.2.0
Summary: AI Agent 熔断器 —— 在工具执行前拦截，并在 Agent 反复犯错时熔断（本地、零联网、可审计）
Project-URL: Homepage, https://github.com/ve-loma/traceguard
Project-URL: Repository, https://github.com/ve-loma/traceguard
Project-URL: Issues, https://github.com/ve-loma/traceguard/issues
Author: TraceGuard Contributors
License: MIT
License-File: LICENSE
Keywords: agent,ai,guardrails,mcp,policy,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# TraceGuard

**AI Agent 的工具调用前置拦截器。在执行之前，把危险动作拦下来。**

[![PyPI](https://img.shields.io/pypi/v/ai-traceguard?color=FF5C36&label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/ai-traceguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-39FF88.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)

---

## 🚀 30 秒上手（先跑这一条）

```bash
pip install ai-traceguard
traceguard demo
```

它会**现场演一遍**：造一个文件 → 让 AI 去删 → 看 TraceGuard 把它拦下来。
不用配置、不联网、不会动你的项目。看完你就懂了。

然后三步接进你自己的代码：

```bash
traceguard init                 # ① 生成策略文件
```

```python
from traceguard import TraceGuard
guard = TraceGuard(policy="traceguard-policy.yaml", mode="strict")   # ② 创建护栏

def delete_file(path):
    d = guard.check("delete_file", {"path": path})   # ③ 在每个工具体最前面加这三行
    if not d.allowed:
        return f"被拦截：{d.reason}"
    Path(path).unlink()
```

```bash
traceguard test                 # 自检：应输出 delete_file: BLOCKED / read_file: ALLOWED
```

> 不确定装没装对？跑 `traceguard selfcheck` —— 它会检查策略文件、审计库，能修的自动修。

---

## 它解决什么问题

AI Agent 会**删掉生产库、把 API Key 发到外部、在死循环里把 Token 烧光**。
市面上的可观测 / 追踪工具只能**事后记录**——等你看到日志，数据已经没了。

TraceGuard 不同：它站在**工具调用的执行路径上**，在动作发生**之前**做出确定性的允许 / 阻断判断。

> 追踪工具告诉你「凌晨 3 点删了什么」；
> TraceGuard 让它在「凌晨 3 点删不掉」。

---

## 安装

```bash
pip install ai-traceguard
```

零依赖服务、零配置文件、零网络请求。装完即用。

---

## 快速开始

```python
from traceguard import TraceGuard

guard = TraceGuard(policy="policies/base.yaml", mode="strict")

decision = guard.check("delete_file", {"path": "/data/users.csv"})
if not decision.allowed:
    print(f"已阻断：{decision.reason}")
else:
    # 执行真正的工具逻辑
    pass
```

CLI 自检：

```bash
traceguard test
# delete_file: BLOCKED
# read_file: ALLOWED
```

---

## 策略包（Guard Packs）

开箱即用的策略模板，覆盖最常见的翻车场景：

| 策略包 | 作用 |
|---|---|
| `pack-anti-delete` | 拦截文件 / 数据库删除 |
| `pack-anti-token-runaway` | 拦截 Token 预算超支 |
| `pack-anti-data-leak` | 拦截敏感数据外发 |

```bash
traceguard init --pack anti-delete
# 生成 traceguard-policy.yaml
```

---

## 审计链（Audit Chain）

每一次裁决都会写入本地的 **SHA-256 哈希链**。任何后续篡改都会破坏链条，可被检出。

```bash
traceguard verify
# 审计链有效
```

导出给审计 / 合规团队（Pro 能力）：

```python
from traceguard_pro import export_audit_jsonl, verify_exported_jsonl

export_audit_jsonl("traceguard-audit.db", "audit-export.jsonl")
assert verify_exported_jsonl("audit-export.jsonl")   # 第三方可独立复核
```

---

## 三种模式

| 模式 | 行为 |
|---|---|
| `strict` | HIGH 风险阻断，MEDIUM 需要审批 |
| `balanced` | HIGH 需要审批，MEDIUM 放行 |
| `observe` | 全部放行，全部记录（灰度 / 观测用） |

---

## 合规与安全

TraceGuard 的设计目标是**架构上零风险**：

- **无网络请求。** 拦截层永不联系外部服务器，因此没有可被拦截、泄露或审查的东西。
- **无模型 API。** 不代理、不转售、不路由任何模型调用。
- **只存本地 SQLite。** 审计数据属于你，永远不出本机。
- **离线授权。** 授权码本地 HMAC 验签，可在气隙环境中运行。

因此：**无需 ICP 备案、无需生成式 AI 备案、无数据出境评估**。详见 [`docs/compliance.md`](docs/compliance.md)。

---

## 商业版（TraceGuard Pro）

开源核心（MIT）足够个人使用；**生产与合规场景**需要的确定性能力放在 Pro：

| 能力 | 说明 | 版本 |
|---|---|---|
| 参数级敏感信息扫描 | 拦截参数里的 `api_key` / `password` / `private_key` / PII | Pro |
| Token 预算 + 死循环拦截 | 会话超预算、同调用反复重试时阻断 | Pro |
| 可校验审计导出 | JSONL 导出，第三方可独立重算哈希链 | Pro |
| 行业策略包 | 金融 / 医疗 / DevOps 预设 | Pro |
| 人工审批流 | MEDIUM 风险改为人工审批而非静默放行 | Team |
| 席位报表 / 自定义包 / SLA | — | Enterprise |

> 未持有效授权时，`ProGuard` 会**优雅降级为开源核心行为**，方便先试后买。

---

## 文档

- [快速开始](docs/quickstart.md)（[中文版](docs/quickstart.zh.md)）
- [合规说明](docs/compliance.md)
- [安全策略](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
- [变更日志](CHANGELOG.md)

---

## 许可证

核心：**MIT**。商业增值包 `traceguard-pro` 采用商业许可，详见其 README。

---

## English (short)

TraceGuard is a **local runtime guardrail for AI agents**. It intercepts dangerous
tool calls *before* execution — no network, no server, deterministic decisions, and a
tamper-evident local SHA-256 audit chain. Install with `pip install ai-traceguard`.
Full English docs: [`README.en.md`](README.en.md).
