Metadata-Version: 2.4
Name: alphadata-cli
Version: 0.1.0.dev4
Summary: Alpha 法律数据查询命令行工具（案例 / 法规 / 实务文章）
Author: Alpha
License: MIT
Project-URL: Homepage, https://alphalawyer.cn
Keywords: alpha,law,legal,cli,case,lawregu,article
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Legal Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# alphadata-cli

Alpha 法律数据查询命令行工具。封装案例、法规、实务文章三大数据接口，提供统一的 `alphadata` 命令行入口。

- 🔑 **两级鉴权**：API Key 持久化（环境变量 / 配置文件），Token 自动换取并缓存（内存级缓存文件，权限 600）
- 🌳 **字段表内置**：按需查询字段表，避免一次性拉取撑爆上下文
- 🧩 **结构化查询**：传入英文参数 + 中文值，CLI 自动查字段表拼查询字符串（支持多级层级自动判断、code 映射）
- 🪶 **零第三方依赖**：纯 Python 标准库实现（urllib / argparse / json）

## 安装

支持两种安装方式，任选其一。

> 要求 Python 3.8+。

### 方式一：uv（推荐）

[uv](https://github.com/astral-sh/uv) 会自动处理命令的 PATH 注册，**不会出现「装好了但命令找不到」的问题**，适合所有用户。

```bash
# 没装 uv 先装（Homebrew，一次性）
brew install uv

# 装本工具
uv tool install alphadata-cli

# 验证
alphadata --version
```

升级 / 卸载：

```bash
uv tool upgrade alphadata-cli   # 升级到最新版
uv tool uninstall alphadata-cli # 卸载
```

### 方式二：pip

```bash
pip install alphadata-cli
```

> ⚠️ **macOS 系统 Python 常见坑**：用系统自带 Python（非 Homebrew）时，pip 默认装到用户目录，可能装完后提示 `command not found`。解决办法二选一：
> - 推荐改用上面的 **uv** 方式（自动处理 PATH）
> - 或手动把用户 bin 加进 PATH：
>   ```bash
>   echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.bash_profile && source ~/.bash_profile
>   ```
>   （`3.9` 换成你实际的 Python 版本）

安装后即获得 `alphadata` 命令。

## 快速开始

### 1. 配置 API Key

```bash
alphadata auth login --api-key ak_xxx
```

API Key 会保存到 `~/.alpha/config.json`，Token 缓存到 `~/.alpha/.token`（权限 600，30 天有效）。

也可通过环境变量配置：

```bash
export ALPHADATA_API_KEY=ak_xxx
```

### 2. 查询

```bash
# 法规：先查专题字段，再查
alphadata law fields --topic --search 股权
alphadata law search --topic 股权代持 --validity 现行有效

# 案例：结构化参数，CLI 自动判层级
alphadata case search --cause 民事 --court_level 最高人民法院
alphadata case search --court_view "诈骗 自首" --region 北京市

# 实务文章
alphadata article search --topic 公司法 --publish_time 近三个月
```

### 3. 详情

```bash
alphadata law detail --lid <法规ID> --title 民法典 --article 1
alphadata case detail --jid <案例ID>
alphadata article detail --aid <文章ID>
```

## 命令总览

```
alphadata
├── case      案例查询（search / detail / fields）
├── law       法规查询（search / detail / fields）
├── article   实务文章查询（search / detail / fields）
└── auth      鉴权管理（login / status / logout）
```

### 鉴权流程

```
API Key (持久化)  →  换取 Token (缓存)  →  Token 鉴权查询数据
                          ↑                       │
                          └── 过期/失效自动重换 ←──┘
```

- **API Key**：持久存储在 `~/.alpha/config.json` 和环境变量 `ALPHADATA_API_KEY`
- **Token**：仅在本地缓存文件中，自动管理，关机/过期后自动用 API Key 重新换取

## 结构化查询

`search` 子命令支持两种查询方式：

1. **结构化参数（推荐）**：英文 flag + 中文值，CLI 自动查字段表拼查询字符串
   ```bash
   alphadata law search --topic 股权代持 --validity 现行有效
   # CLI 自动拼成: Alpha实务专题_3:股权代持,时效性_1:现行有效
   ```

2. **原始查询（兜底）**：直接透传，跳过字段校验
   ```bash
   alphadata law search --query "全文_99:民法典"
   ```

## 开发

本项目采用标准 Python 包结构（src layout）：

```bash
# 本地开发安装
pip install -e .

# 构建
pip install build
python -m build
```

## License

MIT
