Metadata-Version: 2.4
Name: aquamind
Version: 0.0.3
Summary: LLM 应用量化质量测试开源平台：像水质检测一样量化大模型应用的质量
Author: hu-chenyu
License-Expression: MIT
Project-URL: Homepage, https://github.com/hu-chenyu/AquaMind
Project-URL: Repository, https://github.com/hu-chenyu/AquaMind
Keywords: llm,testing,evaluation,rag,agent,quality
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AquaMind

> **AquaMind —— 大模型应用量化质量测试开源平台**
> 像水质检测一样，量化输出 LLM 应用的质量体检报告。

[![CI](https://github.com/hu-chenyu/AquaMind/actions/workflows/ci.yml/badge.svg)](https://github.com/hu-chenyu/AquaMind/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aquamind.svg)](https://pypi.org/project/aquamind/)
[![Python](https://img.shields.io/pypi/pyversions/aquamind.svg)](https://pypi.org/project/aquamind/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## 1. 一句话定位

**AquaMind —— 大模型应用量化质量测试开源平台。**

把 LLM 应用当作一管待测水样：用自动化测试用例充当检测试剂，把幻觉率、事实忠实度、抗诱导鲁棒性这些原本只能"感觉不好"的问题，变成可以写进 CI 门禁、可以随版本对比的**数字**。

```bash
pip install aquamind
```

---

## 2. 水质隐喻映射表

| 水质检测概念 | AquaMind 对应 | 说明 |
|---|---|---|
| 待测水样 | LLM 应用 | 被测对象，通过 API 接入（聊天机器人 / RAG 问答 / Agent） |
| 检测试剂 | 自动化测试用例 | 用例集与攻击语料，决定能检出什么问题 |
| 浑浊度 | 幻觉率 | 输出中无法被上下文或事实支撑的陈述占比 |
| 纯净度 | 事实忠实度 | 输出与给定上下文、给定事实的一致程度 |
| 抗污染能力 | 抗诱导鲁棒性 | 面对提示注入、越狱、对抗扰动时的守界能力 |
| 体检报告 | 可量化质量报告 | 自包含单文件 HTML，可离线打开、可随版本归档对比 |

---

## 3. 三类被测对象路线图

AquaMind 按被测对象的复杂度递进交付，每类对象对应一个开发里程碑：

| 被测对象 | 里程碑 | 交付能力 |
|---|---|---|
| 聊天机器人 Chatbot | **M2**（2027 Q1） | 多轮会话评测、幻觉率 / 相关性 / 时延成本、HTML 报告、CLI 与 pytest 插件原型 |
| RAG 问答系统 | **M3**（2027 Q2） | 忠实度、答案相关性、上下文精确率与召回率、证据归因、检索与生成分治诊断 |
| Agent / Tool-use | **M5**（2027 Q4） | 决策路径验证、工具调用可靠性、状态记忆一致性、死循环与超轮次兜底检测 |

对抗鲁棒性用例库（**M6**）横切三类对象，为所有被测对象提供"抗污染能力"这一共同维度的度量。

---

## 4. 非目标（明确不做）

以下内容**不在** AquaMind 的范围内，也不在计划中：

- **UI 自动化层**（Playwright / Selenium 等）——被测对象一律通过 API 接入，不做界面操作层；
- **容器编排**（Kubernetes 等）——单机库形态，不引入集群依赖与运维负担；
- **自行训练或微调模型**——所有评估能力基于调用现有模型 API，本项目不产出模型；
- **企业级多人协作平台**——不做账号体系、权限中心与集中式调度服务。

---

## 5. 竞品立场

已知同类工具有 **RAGAS**、**DeepEval**、**TruLens**、**promptfoo**。它们是优秀的先行者，AquaMind 的定位与它们并不重合：

| 维度 | 主流工具普遍倾向 | AquaMind 的选择 |
|---|---|---|
| 使用者 | 研究团队 / 企业级评测流水线 | **个人开发者**：开箱即用，一条命令出报告 |
| 使用形态 | 评测库 + 外部看板服务 | **一体化**：评测、报告、门禁在同一份本地产物里闭环 |
| 报告形态 | 多为在线面板或需额外服务 | **自包含单文件 HTML**，可离线打开、可直接转发 |
| 运行成本 | 依赖持续调用模型 API | **默认可离线复现**（录制回放），零成本跑 CI |

实践原则：**成熟的基础库直接复用，核心评估流程与开发者体验自建。** 对通用能力保持克制，把工程量集中在"让个人开发者今天就能给自己的 LLM 应用做一次体检"这件事上。

---

## 6. 项目状态

- 当前版本：**v0.0.3（占位包）** —— 包名与元数据已就位，核心能力正在开发中。
- PyPI：<https://pypi.org/project/aquamind/>
- 源码：<https://github.com/hu-chenyu/AquaMind>
- 开发计划：[`docs/PROJECT-PLAN.md`](./docs/PROJECT-PLAN.md) ｜ 架构决策记录：[`docs/adr/`](./docs/adr/)
- 上方 CI 徽章为占位状态，完整流水线随 **M1** 上线。

### 当前可用范围

```python
import aquamind

aquamind.__version__  # "0.0.3"
```

除此之外暂无可用 API。首个端到端可用版本（聊天机器人体检闭环）预计随 **M2** 发布。

---

## 许可证

[MIT](./LICENSE) © 2026 hu-chenyu
