Metadata-Version: 2.5
Name: aibeta
Version: 0.4.0
Summary: 板块指标库 API SDK
Author: 伍老师
License-Expression: MIT
License-File: LICENSE
Keywords: aibeta,citics,indicator,research,sdk
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: pandas>=2.2.0
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tqdm>=4.66.0
Description-Content-Type: text/markdown

# aibeta-sdk

板块分析数据服务 API SDK，提供以下数据服务的统一查询接口。

- 主题分类体系
- 板块指标库

## 1、安装 Python SDK

```bash
pip install aibeta
```

## 2、配置凭证

SDK 需要 `app_key` / `secret_key` 两个凭证，二选一方式提供：

```python
import aibeta
# 方式一：代码内配置（对当前进程有效）
aibeta.configuration(app_key="XXX", secret_key="XXX")
```

或通过环境变量配置（不调用 `configuration` 时自动读取）：

```bash
# 方式二：通过环境变量配置（长期有效）
export BETA_INDICATOR_API_APP_KEY="XXX"
export BETA_INDICATOR_API_SECRET_KEY="XXX"
```

## 3、快速使用示例

```python
import aibeta

# 配置app-key，app-secret (避免设置环境变量，对单次程序运行有效)
aibeta.configuration(app_key='XXX', secret_key='XXX')

# 板块指标库模块：读取所有指标类型
aibeta.beta_indicator.list_indicator_types()
```

## 4、接口说明

数据类接口统一返回 `pandas.DataFrame`（`get_indicator_value_batch` 除外）。凭证配置见上方「配置凭证」。

### 4.1、全局配置

**`configuration`**

- **调用方式**：`aibeta.configuration(...)`
- **功能简介**：配置当前进程的凭证与超时参数
- **参数**：`app_key` / `secret_key` / `timeout`，均可选

### 4.2、主题分类 `theme_classification`

**`get_theme_classification_framework_inc`**

- **调用方式**：`theme_classification.get_theme_classification_framework_inc(view_date)`
- **功能简介**：主题库日度增量数据
- **参数**：`view_date: str`，查询日期

**返回样例**：

| level_1_name | level_2_name   | theme_name | theme_id              | create_time         | delete_time | sys_update_time     |
| ------------ | -------------- | ---------- | --------------------- | ------------------- | ----------- | ------------------- |
| 产业主题     | 制造类主题     | 电网概念   | `70b59e45…d8a5f5`  | 2026-06-26 18:54:16 | None        | 2026-06-26 18:54:28 |
| 产业主题     | 医药健康类主题 | 精准诊断   | `4ab53eda…d94f1c0` | 2026-06-26 18:57:48 | None        | 2026-06-26 18:57:59 |
| 产业主题     | 科技类主题     | MLCC       | `7d8d049f…673ab38` | 2019-02-28 00:00:00 | None        | 2026-06-26 18:58:00 |

---

**`get_theme_classification_framework_daily`**

- **调用方式**：`theme_classification.get_theme_classification_framework_daily(view_date)`
- **功能简介**：主题库日度截面数据
- **参数**：`view_date: str`，查询日期

**返回样例**：

| level_1_name | level_2_name     | theme_name   | theme_id              | create_time         | delete_time | sys_update_time     |
| ------------ | ---------------- | ------------ | --------------------- | ------------------- | ----------- | ------------------- |
| 事件主题     | 地缘事件主题     | 俄乌冲突概念 | `b7d49308…a941bc`  | 2022-03-31 00:00:00 | None        | 2024-09-26 17:04:21 |
| 事件主题     | 宏观事件主题     | 煤价下跌受益 | `b4c27ae6…6882af2` | 2018-01-31 00:00:00 | None        | 2024-09-26 17:04:21 |
| 事件主题     | 社会活动事件主题 | 进口博览会   | `09782039…0adb25c` | 2018-08-31 00:00:00 | None        | 2024-09-26 17:04:21 |

---

**`get_theme_classification_portfolio_inc`**

- **调用方式**：`theme_classification.get_theme_classification_portfolio_inc(view_date)`
- **功能简介**：主题成分股（标准池）日度增量数据
- **参数**：`view_date: str`，查询日期

**返回样例**：

| theme_id              | stock_code | create_time         | delete_time         |
| --------------------- | ---------- | ------------------- | ------------------- |
| `195ad447…7042e7`  | 600599.SH  | 2018-01-31 23:30:00 | 2026-06-26 00:00:00 |
| `1dc6c207…4e960c1` | 600599.SH  | 2018-01-31 23:30:00 | 2026-06-26 00:00:00 |
| `91c32f41…01cebc8` | 600599.SH  | 2025-05-31 23:30:00 | 2026-06-26 00:00:00 |

---

**`get_theme_classification_portfolio_daily`**

- **调用方式**：`theme_classification.get_theme_classification_portfolio_daily(view_date)`
- **功能简介**：主题成分股（标准池）日度截面数据
- **参数**：`view_date: str`，查询日期

**返回样例**：

| theme_id              | stock_code | create_time         | delete_time |
| --------------------- | ---------- | ------------------- | ----------- |
| `1b9d818e…f50e804` | 002727.SZ  | 2018-01-31 23:30:00 | None        |
| `4bf5576e…c0f6236` | 300003.SZ  | 2018-01-31 23:30:00 | None        |
| `b47d4a32…491b517` | 000969.SZ  | 2018-01-31 23:30:00 | None        |

---

**`get_theme_classification_index_inc`**

- **调用方式**：`theme_classification.get_theme_classification_index_inc(view_date)`
- **功能简介**：主题指数点位日度增量数据
- **参数**：`view_date: str`，查询日期

**返回样例**：

| theme_id               | index_name        | index_external_code | price_date | close_price | upddate_time        |
| ---------------------- | ----------------- | ------------------- | ---------- | ----------- | ------------------- |
| `66f3c5b8…81ef14`   | 液冷超充_主题指数 | CIS05816            | 20260630   | 2795.85     | 2026-06-30 23:00:02 |
| `279d8e2d…10bf73b`  | 健康中国_主题指数 | CIS05451            | 20260630   | 929.5       | 2026-06-30 23:00:02 |
| `33f156e4…8d4bd29a` | 氢能_主题指数     | CIS05588            | 20260630   | 1653.0      | 2026-06-30 23:00:02 |

---

**`get_theme_classification_index_by_id`**

- **调用方式**：`theme_classification.get_theme_classification_index_by_id(theme_id)`
- **功能简介**：查询特定主题的历史指数点位
- **参数**：`theme_id: str`，主题 ID

**返回样例**：

| theme_id             | index_name        | index_external_code | price_date | close_price |
| -------------------- | ----------------- | ------------------- | ---------- | ----------- |
| `66f3c5b8…81ef14` | 液冷超充_主题指数 | CIS05816            | 20231101   | 1000.00     |
| `66f3c5b8…81ef14` | 液冷超充_主题指数 | CIS05816            | 20231102   | 976.71      |
| `66f3c5b8…81ef14` | 液冷超充_主题指数 | CIS05816            | 20231103   | 995.99      |

### 4.3、板块指标库 `beta_indicator`

**`list_indicator_types`**

- **调用方式**：`beta_indicator.list_indicator_types()`
- **功能简介**：读取所有指标类型（如市盈率 PE、市净率 PB 等）
- **参数**：无

**返回样例**：

| indicator_type                             |
| ------------------------------------------ |
| 主题基础池下一年一致预测双周变化综合打分   |
| 主题基础池净利润下一年增速一致预测         |
| 主题基础池净利润下一年增速一致预测双周变化 |

---

**`list_indicators`**

- **调用方式**：`beta_indicator.list_indicators(indicator_type)`
- **功能简介**：按指标类型读取指标列表
- **参数**：`indicator_type: str`，指标类型名称

**返回样例**：

| indicator_id         | indicator_type | indicator_name                                                              | indicator_unit | indicator_frequency | indicator_caliber |
| -------------------- | -------------- | --------------------------------------------------------------------------- | -------------- | ------------------- | ----------------- |
| `7023d2fa…38d76c` | 市盈率PE       | 市盈率PE__['ETF指数']__{'ETF指数': '000001.SH'}__…__当期__周__无单位 | 无单位         | 周                  | 当期              |
| `e5527daa…425804` | 市盈率PE       | 市盈率PE__['ETF指数']__{'ETF指数': '000009.SH'}__…__当期__周__无单位 | 无单位         | 周                  | 当期              |
| `97591188…31dd4a` | 市盈率PE       | 市盈率PE__['ETF指数']__{'ETF指数': '000010.SH'}__…__当期__周__无单位 | 无单位         | 周                  | 当期              |

---

**`get_indicator_value`**

- **调用方式**：`beta_indicator.get_indicator_value(indicator_id)`
- **功能简介**：按指标 ID 读取该指标全部数值记录
- **参数**：`indicator_id: str`，指标唯一标识

**返回样例**：

| data_id                          | indicator_id         | data_value | data_date  | data_publish_date   | update_time         |
| -------------------------------- | -------------------- | ---------- | ---------- | ------------------- | ------------------- |
| `7023d2fa…38d76c__2019-01-04` | `7023d2fa…38d76c` | 11.09      | 2019-01-04 | 2019-01-05 09:00:00 | 2026-02-12 13:37:38 |
| `7023d2fa…38d76c__2019-01-11` | `7023d2fa…38d76c` | 11.25      | 2019-01-11 | 2019-01-12 09:00:00 | 2026-02-12 14:07:26 |
| `7023d2fa…38d76c__2019-01-18` | `7023d2fa…38d76c` | 11.46      | 2019-01-18 | 2019-01-19 09:00:00 | 2026-02-12 14:44:34 |

---

**`get_indicator_value_inc`**

- **调用方式**：`beta_indicator.get_indicator_value_inc(view_date)`
- **功能简介**：按日期增量读取所有指标值
- **参数**：`view_date: str`，查询日期

**返回样例**：

| data_id                          | indicator_id         | data_value    | data_date  | data_publish_date   | update_time         |
| -------------------------------- | -------------------- | ------------- | ---------- | ------------------- | ------------------- |
| `00014458…b8be4b__2026-08-14` | `00014458…b8be4b` | 18821959.0    | 2026-08-14 | 2026-08-14 00:00:00 | 2026-08-17 12:01:36 |
| `0002e4db…f5c437__2026-08-14` | `0002e4db…f5c437` | 66757527744.0 | 2026-08-14 | 2026-08-14 00:00:00 | 2026-08-17 12:01:36 |
| `00035dc7…676c90__2026-08-14` | `00035dc7…676c90` | 0.0           | 2026-08-14 | 2026-08-14 00:00:00 | 2026-08-17 12:01:41 |

---

**`list_sector_types`**

- **调用方式**：`beta_indicator.list_sector_types()`
- **功能简介**：读取所有板块类型（如 ETF 指数、中信证券行业等）
- **参数**：无

**返回样例**：

| sector_type  |
| ------------ |
| ETF指数      |
| 中信证券行业 |
| 主题概念     |

---

**`list_sectors`**

- **调用方式**：`beta_indicator.list_sectors(sector_type=None)`
- **功能简介**：读取板块列表，可选按板块类型过滤
- **参数**：`sector_type: str | None`，传 `None` 返回全部

**返回样例**（`sector_type="ETF指数"`）：

| sector_type | sector_code | sector_name  |
| ----------- | ----------- | ------------ |
| ETF指数     | 000001.SH   | 上证综合指数 |
| ETF指数     | 000009.SH   | 上证380指数  |
| ETF指数     | 000010.SH   | 上证180指数  |

---

**`list_indicators_by_sector`**

- **调用方式**：`beta_indicator.list_indicators_by_sector(sector_code)`
- **功能简介**：按板块代码读取该板块全部指标列表
- **参数**：`sector_code: str`，板块代码（如 `000001.SH`）

**返回样例**（`sector_code="000001.SH"`）：

| indicator_type                             | sector_type | sector_code | sector_name  | indicator_id         | update_time         |
| ------------------------------------------ | ----------- | ----------- | ------------ | -------------------- | ------------------- |
| 主题基础池净利润下一年增速一致预测双周变化 | ETF指数     | 000001.SH   | 上证综合指数 | `831a95f5…be227f` | 2026-08-19 10:26:12 |
| 主题基础池净利润下一年增速一致预测         | ETF指数     | 000001.SH   | 上证综合指数 | `45168a2f…adbe83` | 2026-08-19 10:26:12 |
| 主题基础池下一年一致预测双周变化综合打分   | ETF指数     | 000001.SH   | 上证综合指数 | `f05d2290…4aefee` | 2026-08-19 10:26:12 |

---

**`get_indicator_value_batch`**

- **调用方式**：`beta_indicator.get_indicator_value_batch(indicator_ids, max_workers=3)`
- **功能简介**：并发批量读取多个指标的数值记录
- **参数**：`indicator_ids: list[str]`，指标 ID 列表（≤30）；`max_workers: int`，最大并发数，默认 3

**返回样例**：

```text
{
  "f05d2290…4aefee": DataFrame(398 行 × 6 列),
  "831a95f5…be227f": DataFrame(398 行 × 6 列)
}
```

其中 `f05d2290…4aefee` 前 3 行：

| data_id                          | indicator_id         | data_value | data_date  | data_publish_date   | update_time         |
| -------------------------------- | -------------------- | ---------- | ---------- | ------------------- | ------------------- |
| `f05d2290…4aefee__2019-01-04` | `f05d2290…4aefee` | -0.24      | 2019-01-04 | 2019-01-04 00:00:00 | 2026-02-12 13:34:27 |
| `f05d2290…4aefee__2019-01-11` | `f05d2290…4aefee` | -0.22      | 2019-01-11 | 2019-01-11 00:00:00 | 2026-02-12 14:04:43 |
| `f05d2290…4aefee__2019-01-18` | `f05d2290…4aefee` | 0.11       | 2019-01-18 | 2019-01-18 00:00:00 | 2026-02-12 14:42:35 |

> 返回类型：`get_indicator_value_batch` 返回 `dict[str, DataFrame | None]`（key 为指标 ID，读取失败对应 `None`），其余均返回 `DataFrame`。

## 5、依赖

- Python >= 3.10
- pandas、pyarrow、requests、tqdm

> 缓存说明：SDK 会在用户缓存目录（`~/.cache/aibeta/`）维护指标库的全量快照缓存，默认每 3 天自动重建一次。

## 6、板块指标库覆盖指标列表

指标持续扩充中，以下指标数据统计截止 2026-08-19 。

| 指标分类                                        | 指标名称                                   |
| ----------------------------------------------- | ------------------------------------------ |
| 板块_宏观面_状态_宏观敏感度                     | 宏观敏感度                                 |
| 板块_景气面_中观景气度_景气度                   | 景气度                                     |
| 板块_基本面_估值_股债相对盈利收益率             | 股债相对盈利收益率                         |
| 板块_基本面_估值_周度PEPBPS                     | 市盈率PE                                   |
| 板块_基本面_估值_周度PEPBPS                     | 市净率PB                                   |
| 板块_基本面_估值_周度PEPBPS                     | 市销率PS                                   |
| 板块_基本面_预期_上市公司年报预期乐观度         | 主题基础池企业年报展望乐观度               |
| 板块_情绪面_主题关注度_Choice热度指数统计       | 板块个股访问指数                           |
| 板块_情绪面_主题关注度_Choice热度指数统计       | 板块社区活跃指数                           |
| 板块_情绪面_主题关注度_Choice热度指数统计       | 板块新闻阅读指数                           |
| 板块_情绪面_主题关注度_Choice热度指数统计       | 板块公告阅读指数                           |
| 板块_情绪面_主题关注度_Choice热度指数统计       | 板块研报阅读指数                           |
| 板块_技术面_价格_MACD                           | MACD-DIF线                                 |
| 板块_技术面_价格_MACD                           | MACD-DEA线                                 |
| 板块_技术面_价格_MACD                           | MACD-柱状图                                |
| 板块_技术面_价格_RSI                            | RSI                                        |
| 板块_技术面_价格_周度涨跌幅统计                 | 近1周涨跌幅                                |
| 板块_技术面_价格_周度涨跌幅统计                 | 近4周涨跌幅                                |
| 板块_技术面_价格_周度涨跌幅统计                 | 本年度涨跌幅                               |
| 板块_技术面_价格_均线指标                       | 1日均线                                    |
| 板块_技术面_价格_均线指标                       | 5日均线                                    |
| 板块_技术面_价格_均线指标                       | 10日均线                                   |
| 板块_技术面_价格_均线指标                       | 20日均线                                   |
| 板块_技术面_价格_均线指标                       | 60日均线                                   |
| 板块_技术面_成交量_当日成交量                   | 当日成交量                                 |
| 板块_技术面_成交量_当日成交量                   | 当日成交金额                               |
| 板块_技术面_拥挤度_主题交易拥挤度               | 交易拥挤度指标                             |
| 板块_技术面_热度_主题交易热度                   | 交易热度指标                               |
| 板块_报告_算法决策_收入一致预测双周变化         | 主题基础池净利润下一年增速一致预测         |
| 板块_报告_算法决策_收入一致预测双周变化         | 主题基础池营收下一年增速一致预测           |
| 板块_报告_算法决策_收入一致预测双周变化         | 主题基础池净利润下一年增速一致预测双周变化 |
| 板块_报告_算法决策_收入一致预测双周变化         | 主题基础池营收下一年增速一致预测双周变化   |
| 板块_报告_算法决策_收入一致预测双周变化         | 主题基础池下一年一致预测双周变化综合打分   |
| 板块_报告_算法决策_政策文本提及热度             | 政策提及热度                               |
| 板块_报告_算法决策_机构调研热度                 | 主题基础池机构调研综合热度                 |
| 板块_报告_算法决策_研报情绪综合得分             | 主题基础池研报情绪综合得分                 |
| 板块_政策面_情绪_政策新闻情绪                   | 政策情绪                                   |
| 板块_资金面_ETF资金_ETF净值变化对板块的影响拆解 | ETF资金影响                                |
| 板块_资金面_两融资金_板块融资融券统计           | 融资余额                                   |
| 板块_资金面_两融资金_板块融资融券统计           | 融资买入额                                 |
| 板块_资金面_两融资金_板块融资融券统计           | 融资偿还额                                 |
| 板块_资金面_两融资金_板块融资融券统计           | 融券余额                                   |
| 板块_资金面_两融资金_板块融资融券统计           | 融券卖出额                                 |
| 板块_资金面_两融资金_板块融资融券统计           | 融券偿还额                                 |
| 板块_风险_风险偏好_收益波动秩相关系数           | 近20交易日收益与波动秩相关系数             |
| 板块_基本面_财务_主题基本财务指标               | 净利润TTM                                  |
| 板块_基本面_财务_主题基本财务指标               | 营业总收入TTM                              |
| 板块_基本面_财务_主题基本财务指标               | 营业总成本TTM                              |
| 板块_基本面_财务_主题基本财务指标               | 营业利润TTM                                |
| 板块_基本面_财务_主题基本财务指标               | 资产总计                                   |
| 板块_基本面_财务_主题基本财务指标               | 应收账款                                   |
| 板块_基本面_财务_主题基本财务指标               | 存货                                       |
| 板块_基本面_财务_主题基本财务指标               | 流动资产合计                               |
| 板块_基本面_财务_主题基本财务指标               | 流动负债合计                               |
| 板块_基本面_财务_主题基本财务指标               | 负债合计                                   |
| 板块_基本面_财务_主题基本财务指标               | 经营活动现金流入小计                       |
| 板块_基本面_财务_主题基本财务指标               | 经营活动现金流出小计                       |
| 板块_基本面_财务_主题基本财务指标               | 当日净资产                                 |
| 板块_基本面_财务_主题基本财务指标               | 企业自由现金流FCFF                         |
| 板块_基本面_财务_主题基本财务指标               | 总市值                                     |
| 板块_基本面_财务_主题基本财务指标               | 近12个月股息率                             |
| 板块_基本面_财务_主题基本财务指标               | 净资产收益率ROE                            |
| 板块_基本面_财务_主题基本财务指标               | 资产回报率ROA                              |
| 板块_基本面_财务_主题基本财务指标               | 毛利率                                     |
| 板块_基本面_财务_主题基本财务指标               | 净利率                                     |
| 板块_基本面_财务_主题基本财务指标               | 经营活动现金流净额                         |
| 板块_基本面_财务_主题基本财务指标               | 资产负债率                                 |
| 板块_基本面_财务_主题基本财务指标               | 流动比率                                   |
| 板块_基本面_财务_主题基本财务指标               | 速动比率                                   |
| 板块_基本面_财务_主题基本财务指标               | 营业收入增长率                             |
| 板块_基本面_财务_主题基本财务指标               | 净利润增长率                               |
| 板块_基本面_财务_主题基本财务指标               | 自由流通市值加权EPS                        |
| 板块_基本面_财务_主题基本财务指标               | 营业利润增长率                             |
| 板块_基本面_财务_主题基本财务指标               | 总资产周转率                               |
| 板块_基本面_财务_主题基本财务指标               | 应收账款周转率                             |
| 板块_基本面_财务_主题基本财务指标               | 存货周转率                                 |
