Metadata-Version: 2.4
Name: saqds
Version: 0.0.1
Summary: 序衍量化核心业务工具库，为量化研究与策略开发提供标准化的数据访问、因子分析、指标计算、可视化及命令行交互能力。覆盖 A 股、港股、美股多市场行情数据接入，支持安全受控的数据访问鉴权，提供完备的因子运算、效果评估、统计度量与图表渲染能力，面向投研业务封装统一上层接口，助力研究人员高效完成因子挖掘、策略回测前置分析与量化实验工作。
Author-email: SequArc 序衍 <ai-liuys@outlook.com>
License: 序衍量化 版权所有，未经书面许可禁止外部分发/商用
Project-URL: Homepage, https://gitlab.dc3.everonquant.net/foundation/python/core
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click>=8.3.2
Requires-Dist: vnpy[no-gui]>=4.4.0
Requires-Dist: akshare
Requires-Dist: ray[default]>=2.55.1
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.8
Requires-Dist: clickhouse-connect>=0.8
Requires-Dist: cryptography>=42.0
Requires-Dist: pandas>=2.0
Dynamic: license-file

# saqds · 序衍量化核心工具库

![PyPI Version](https://img.shields.io/pypi/v/saqds.svg)
![Python](https://img.shields.io/pypi/pyversions/saqds.svg)
![License](https://img.shields.io/badge/license-Proprietary-red.svg)

面向量化投研的一站式底层工具集：A 股 / 美股 / 港股行情（SAOIDC 密钥鉴权 + 直连 ClickHouse）、
因子运行与测评、数学 / 统计指标、公式可视化绘图、CLI 工具。

> 序衍量化专有软件，未经书面许可禁止外部分发、商用。

## 安装

```bash
pip install saqds
```

> 需要 Python >= 3.10。

## 快速上手

### 行情数据

```python
import saqds

# 配置 SAOIDC Access Key（二选一：代码内初始化，或设置环境变量 SAQDS_ACCESS_KEY）
saqds.init(key="saoidc_你的Key")

# A 股日线（纯数字代码，不带 .SH / .SZ）
df = saqds.get_stock_hist("600519", "20260101", "20260716")

# 批量 A 股 / 指数全成分 / 美股 / ETF
df = saqds.get_stock_hist_batch(["600519", "000001"], "20260101", "20260716")
df = saqds.get_index_hist("hs300", "20260101", "20260716")
df = saqds.get_us_stock_hist("AAPL", "20260101", "20260716")
df = saqds.get_etf_hist("510300", "20260101", "20260716")
```

### 数值工具

```python
import saqds
from saqds.stats import mean

saqds.sum_of_squares([1, 2, 3])  # 14.0
mean([2, 4, 6])                  # 4.0
```

### 因子运行与测评

```python
import saqds

# 运行因子脚本（safactor_factor_version 的 generate(df) 契约）
fv = saqds.compute_factor_value("ma_bias", "20260101", "20260716", codes=["600519"])

# 因子 IC / IR 测评
metrics = saqds.evaluate_factor("ma_bias", "20260101", "20260716", codes=["600519"])
```

### 公式绘图

```python
from saqds.formula_plot import plot_custom_formula

img = plot_custom_formula("x**2 - 4*x", save_path="curve.png")
```

### 命令行

```bash
saqds 1 2 3 4      # Sum of squares: 30.0
saqds -- -1 2.5    # 负数需用 -- 分隔
```

## 主要模块

| 模块 | 说明 |
|------|------|
| `saqds.clickhouse_tool` | 行情客户端（SAOIDC 鉴权 + 直连 ClickHouse）：A 股 / 美股 / 港股 / ETF / 指数成分 / 行业 |
| `saqds.factor` | 因子脚本加载与计算（`generate(df)` 契约） |
| `saqds.evaluate` | 因子 IC / IR 测评、去极值 |
| `saqds.math` / `saqds.stats` | 数学 / 统计指标 |
| `saqds.formula_plot` | 服务端无 GUI 公式绘图 |

## 配置

用户侧仅需配置 SAOIDC Access Key，其余参数（鉴权中心地址、ClickHouse 连接等）由数据提供方维护：

```bash
export SAQDS_ACCESS_KEY=saoidc_你的Key
```

或代码内初始化：

```python
saqds.init(key="saoidc_你的Key")
```

## 开发

```bash
uv sync --group dev                     # 安装开发依赖
uv run pytest                           # 单元测试（覆盖率门禁 80%）
uv run ruff check src tests --fix       # 静态检查
uv run ty check src                     # 类型检查
```

## 版权

序衍量化 版权所有，未经书面许可禁止外部分发、商用。
