Metadata-Version: 2.4
Name: precis-cli
Version: 0.1.9
Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
Author: Precis Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/AirSaiga/Precis
Project-URL: Repository, https://github.com/AirSaiga/Precis
Project-URL: Bug Tracker, https://github.com/AirSaiga/Precis/issues
Project-URL: Discussions, https://github.com/AirSaiga/Precis/discussions
Keywords: data-quality,data-validation,csv,excel,json,yaml,cli,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pandas<3.0,>=2.2.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: xlrd>=2.0.1
Requires-Dist: SQLAlchemy>=2.0.48
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: ruamel.yaml>=0.19.0
Requires-Dist: rich>=13.0.0
Requires-Dist: readchar>=4.2.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: simpleeval>=1.0.0
Requires-Dist: filelock>=3.12.0
Provides-Extra: api
Requires-Dist: fastapi!=0.136.3,>=0.135.0; extra == "api"
Requires-Dist: uvicorn>=0.42.0; extra == "api"
Requires-Dist: email-validator>=2.3.0; extra == "api"
Requires-Dist: uritemplate>=4.2.0; extra == "api"
Requires-Dist: python-multipart>=0.0.26; extra == "api"
Requires-Dist: cryptography>=44.0.0; extra == "api"
Provides-Extra: ai
Requires-Dist: openai>=1.6.0; extra == "ai"
Requires-Dist: aiohttp>=3.9.0; extra == "ai"
Requires-Dist: psutil>=5.9.6; extra == "ai"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.30.0; extra == "mcp"
Provides-Extra: completion
Requires-Dist: pyreadline3>=0.1.8; sys_platform == "win32" and extra == "completion"
Provides-Extra: full
Requires-Dist: precis-cli[ai,api,completion,mcp]; extra == "full"
Provides-Extra: dev
Requires-Dist: precis-cli[ai,api,mcp]; extra == "dev"
Requires-Dist: debugpy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# Precis CLI

> Local-first data validation engine — define schemas and constraints in YAML, validate CSV / Excel / JSON with a single command.
> 本地优先的数据校验引擎：用 YAML 定义表结构与约束规则，一条命令校验 CSV / Excel / JSON。

**Alpha** — 核心功能稳定，配置格式有版本保障（V2）。

## 安装

```bash
pip install precis-cli          # 需要 Python >= 3.12

# 或免安装直接运行（需要 uv）
uvx --from precis-cli precis --version
```

## 快速上手

```bash
# 1. 从数据文件推断 schema 草稿
precis infer-schema orders.csv > schemas/orders.schema.yaml

# 2. 在项目清单 project.precis.yaml 中登记 schema 与约束文件
#    （格式见下方示例）

# 3. 执行校验
precis validate --manifest project.precis.yaml --format json
```

退出码契约（CI / AI agent 友好）：

| 退出码 | 含义 |
|--------|------|
| `0` | 校验通过 |
| `1` | 校验完成，发现数据违规（详情见 JSON 输出的 `errors`） |
| `2` | 工具自身错误（参数错误、文件不存在、异常崩溃） |

## 配置示例（V2 YAML）

`project.precis.yaml`：

```yaml
version: 2
project:
  id: my-project
  name: 订单数据校验
schemas:
  - id: orders
    path: schemas/orders.schema.yaml
constraints:
  - id: orders_amount_range
    path: constraints/orders_amount_range.constraint.yaml
```

`constraints/orders_amount_range.constraint.yaml`：

```yaml
version: 2
id: orders_amount_range
type: Range
enabled: true
refs:
  table_id: orders
  column_id: amount
params:
  min: 0
  max: 1000000
  boundary_mode: inclusive
```

## 10 种约束类型

`NotNull` 非空 · `Unique` 唯一 · `AllowedValues` 枚举 · `Range` 数值区间 ·
`ForeignKey` 跨表引用 · `Conditional` 条件约束 · `Scripted` 脚本表达式 ·
`Charset` 字符集 · `DateLogic` 日期逻辑 · `Composite` 组合约束

数据类型：`string` / `integer` / `float` / `decimal` / `boolean` / `date`。
大文件（>500MB）自动分块加载。

## 与 AI Agent 集成

`--format json` 输出为机器可读契约（含行级错误定位与约束来源文件回溯），
可直接被 AI 编程助手消费：

- **MCP server**：`pip install "precis-cli[mcp]"` 后运行 `precis-mcp`（stdio），
  提供 `validate_data` / `infer_schema` / `check_config` / `describe_constraints` 四个工具
- **Kimi Code 插件**：`/plugins install https://github.com/AirSaiga/Precis`
- **CLI 自带 AI 命令**（自然语言生成/修改校验配置，独立于宿主 agent）：
  `pip install "precis-cli[ai]"`，然后 `precis ai chat` 或 `precis ai ask "..."`

## 链接

- 仓库与文档：<https://github.com/AirSaiga/Precis>
- 问题反馈：<https://github.com/AirSaiga/Precis/issues>
- 桌面 GUI 版本（画布式可视化编辑）见仓库 releases

License: Apache-2.0
