内容
# Provena
[](https://github.com/rajfirke/provena/actions/workflows/ci.yml)
[](https://pypi.org/project/provena/)
[](https://pypi.org/project/provena/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/astral-sh/ruff)
**智能代理系统的上下文治理** （最低可行产品）
你的智能代理根据来自 6 个不同来源的数据做出了决定。
你能告诉我哪些来源吗？你能证明数据没有被篡改吗？
你能验证数据仍然是当前的吗？
Provena 为任何智能代理的上下文管道添加了防篡改审计跟踪——只需 3 行 Python 代码。
```python
from provena import ContextTrail
trail = ContextTrail()
@trail.track(source="retriever")
def search(query):
return retriever.search(query)
```
每次调用 `search()` 现在都会记录 SHA-256 内容哈希、防篡改校验和
和哈希链审计跟踪。
## 为什么选择 Provena？
> **AGT 治理智能代理的行为。Guardrails AI 治理智能代理的输出。Provena 治理智能代理的知识。**
目前没有工具能够治理上下文输入层。Provena 填补了这一空白，提供：
- **防篡改审计跟踪** — SHA-256 哈希链（Merkle 风格）日志记录，可选 HMAC 签名
- **来源验证** — 验证上下文是否包含正确的来源元数据（有效 / 缺失 / 不完整）
- **新鲜度检查** — 通过元数据时间戳和正则表达式时间检测，检测过时上下文（新鲜 / 过时 / 未知）
- **任意上下文来源** — RAG 检索器、工具输出、智能代理消息、内存回忆、MCP 资源
- **毫秒级开销** — 纯 Python 实现，无机器学习模型，无 ONNX，无模型下载
- **零依赖** — 核心库仅使用 Python 标准库
## 安装
```bash
pip install provena # 核心库（零依赖）
pip install provena[cli] # + 命令行工具（click，rich）
pip install provena[otel] # + OpenTelemetry 导出
pip install provena[langchain] # + LangChain 适配器
pip install provena[llamaindex] # + LlamaIndex 适配器
pip install provena[all] # 所有功能
```
## 快速入门
```python
from provena import ContextTrail, ProvenanceMetadata
from datetime import datetime, timezone
trail = ContextTrail(storage_path="audit.db")
# 跟踪产生上下文的任何函数
@trail.track(source="retriever")
def search(query):
return retriever.search(query)
@trail.track(source="tool:pricing_api")
def get_price(product_id):
return api.get(f"/price/{product_id}")
# 手动记录带有来源元数据的上下文
trail.log(
content="企业计划费用为 $499/月。",
source="tool:pricing_api",
provenance=ProvenanceMetadata(
source_url="https://api.example.com/pricing",
created_at=datetime.now(timezone.utc),
),
)
# 验证审计跟踪是否未被篡改
verdict = trail.verify_chain()
print(f"链完整：{verdict.intact}")
print(f"总记录数：{verdict.total_records}")
```
## 命令行界面
使用 `pip install provena[cli]` 安装，然后：
```bash
# 验证哈希链完整性
provena --db audit.db verify
# PASS — 链完整（已验证 42 条记录）
# 查询审计日志
provena --db audit.db audit --source retriever --format json
# 生成治理报告
provena --db audit.db report --format text
# 快速总结
provena --db audit.db summary
```
对于 HMAC 签名跟踪，传递 `--signing-key` 或设置 `PROVENA_SIGNING_KEY`。
## 集成
### LangChain
```python
from provena.integrations.langchain import ProvenaCallback
chain = RetrievalQA.from_chain_type(
llm=llm,
retriever=retriever,
callbacks=[ProvenaCallback(trail=trail)],
)
```
### LlamaIndex
```python
from provena.integrations.llamaindex import ProvenaPostprocessor
query_engine = index.as_query_engine(
node_postprocessors=[ProvenaPostprocessor(trail=trail)]
)
```
### OpenTelemetry
```python
trail = ContextTrail(
storage_path="audit.db",
otel_enabled=True,
otel_service_name="my-agent",
)
# 每个 log() 调用现在都会发出带有治理属性的 OTel 跨度
```
## 架构
```
您的应用程序
│
│ 检索器 ──┐
│ 工具调用 ──┤
│ 智能代理消息 ──┼──► ContextTrail ──► LLM 上下文窗口
│ 内存 ──┤ │
│ MCP ──┘ │
│ ┌─────┴──────────────┐
│ │ 来源验证器 │
│ │ 新鲜度检查器 │
│ │ 哈希链（SHA-256） │
│ │ SQLite 后端 │
│ │ OTel 导出器 │
│ └────────────────────┘
```
## 合规性
Provena 直接映射到欧盟人工智能法案要求（强制执行：2026 年 8 月 2 日）：
| 条款 | 要求 | Provena 功能 |
|---------|------------|-----------------|
| 第 10 条 | 数据 lineage | 每个上下文输入的来源验证 |
| 第 12 条 | 防篡改日志 | SHA-256 哈希链审计跟踪，带有 HMAC 签名 |
| 第 13 条 | 透明度 | `trail.summary()` 和来源跟踪 |
| 第 14 条 | 人工监督 | `trail.annotate()` 用于审查员决策 |
还解决了 **OWASP ASI06** （内存和上下文中毒）。
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、架构指南和 PR 流程。
请在参与之前阅读我们的 [行为准则](CODE_OF_CONDUCT.md)。
## 许可证
[Apache 2.0](LICENSE)
MCP 市场