Metadata-Version: 2.5
Name: ai-traceguard
Version: 0.1.0
Summary: Runtime guardrail for AI agents — intercept dangerous tool calls before execution
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)

---

## 它解决什么问题

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).
