aibeta 0.3.0__tar.gz

aibeta-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+# 只在推送 v 开头的 tag 时触发（例如 v0.3.0）
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tool
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # 环境名必须与 PyPI 上配置的 Trusted Publisher 一致
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aibeta
+    permissions:
+      id-token: write   # Trusted Publishing 必需
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aibeta-0.3.0/.gitignore

@@ -0,0 +1,38 @@
+# ---- 虚拟环境（本机相关，勿提交）----
+.venv/
+venv/
+env/
+
+# ---- Python 缓存与编译产物 ----
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# ---- 本机锁文件 / 缓存标记 ----
+.lock
+CACHEDIR.TAG
+
+# ---- 构建与打包产物 ----
+dist/
+build/
+*.egg-info/
+*.whl
+*.tar.gz
+
+# ---- 测试 / 类型检查 / 覆盖率缓存 ----
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ---- IDE / 编辑器 ----
+.idea/
+.vscode/
+*.swp
+
+# ---- 操作系统 ----
+.DS_Store
+Thumbs.db

aibeta-0.3.0/.trae/documents/aibeta-sdk-restructure.md

@@ -0,0 +1,199 @@
+# 方案：将项目重构为可发布的 `aibeta` Python SDK
+
+## 一、概述（Summary）
+
+将当前「单文件客户端类 + 错误引用」的结构，重构为符合 `examples/import_script.py` 期望调用方式的**模块化 Python SDK**：
+
+- 对外只暴露三个入口：`aibeta.configuration(...)`、`aibeta.theme_classification`、`aibeta.beta_indicator`。
+- 隐藏 `IndicatorLibraryClient` 类，用户不再直接 `new` 客户端，而是通过模块级函数调用，由内部共享单例客户端完成取数。
+- 保留现有全部业务逻辑（Token 管理、统一 API 调用、全量快照缓存等），仅调整文件结构与引用关系。
+
+目标调用方式（来自 `import_script.py`）：
+
+```python
+import aibeta
+
+aibeta.configuration(app_key='XXX', secret_key='XXX')
+
+from aibeta import theme_classification
+theme_classification.get_theme_classification_framework_inc("2026-06-26")
+# ... 其余主题分类接口
+
+from aibeta import beta_indicator
+beta_indicator.list_indicator_types()
+beta_indicator.get_indicator_value_batch(indicator_id_list)
+# ... 其余指标库接口
+```
+
+## 二、现状分析（Current State）
+
+当前文件结构：
+
+```
+src/aibeta/__init__.py                 # 错误地使用绝对导入，且对外暴露了客户端类
+src/aibeta/_beta_indicator_interface.py # 全部逻辑集中在一个类 IndicatorLibraryClient
+examples/my_script.py                  # 旧式调用：直接实例化 IndicatorLibraryClient
+examples/import_script.py              # 期望调用方式（含一处笔误 client.）
+```
+
+关键问题：
+
+1. [__init__.py](file:///data/project/aibeta_sdk/src/aibeta/__init__.py#L3-L5) 使用 `from _beta_indicator_interface import IndicatorLibraryClient`，是绝对导入，作为包安装后会报 `ModuleNotFoundError`；且把 `IndicatorLibraryClient` 暴露到了公共命名空间。
+2. 客户端类承载了「网络 + Token + 缓存 + 业务接口」全部职责，但没有模块级封装，用户必须手动 `new` 客户端，与期望的模块级调用方式不符。
+3. [import_script.py](file:///data/project/aibeta_sdk/examples/import_script.py#L59) 末行 `client.get_indicator_value_batch(...)` 是笔误（未定义 `client`），应为 `beta_indicator.get_indicator_value_batch(...)`。
+4. [my_script.py](file:///data/project/aibeta_sdk/examples/my_script.py#L7) 引用 `beta_indicator_interface`（无下划线）与真实文件名不一致，且为旧式实例化方式。
+
+## 三、改动方案（Proposed Changes）
+
+最终目标结构：
+
+```
+src/aibeta/
+├── __init__.py               # 公共入口：configuration + 子模块导出（不暴露客户端类）
+├── _client.py                # 内部客户端类（由 _beta_indicator_interface.py 重命名而来）
+├── _config.py                # 全局共享客户端管理：configuration() / get_client()
+├── theme_classification.py   # 主题分类模块级函数（薄封装，委托给共享客户端）
+└── beta_indicator.py         # 指标库模块级函数（薄封装，委托给共享客户端）
+```
+
+### 3.1 重命名：`_beta_indicator_interface.py` → `_client.py`
+
+- 将文件重命名为 `src/aibeta/_client.py`。
+- **保留** `IndicatorLibraryClient` 类的全部现有逻辑不变（Token 管理、`__call_api`、全量快照缓存、公开方法等），仅修改模块顶部 docstring 为「内部 API 客户端实现」。
+- 类名保持 `IndicatorLibraryClient`（通过私有模块前缀 `_client` 及不在 `__init__` 中导出，实现「不对外暴露」）。
+- 环境变量名**沿用现有**：`BETA_INDICATOR_API_APP_KEY` / `BETA_INDICATOR_API_SECRET_KEY`（用户已确认）。
+- 该模块不需要任何相对导入改动（只依赖标准库 + pandas/requests/tqdm）。
+
+### 3.2 新增：`_config.py`（全局共享客户端 + 配置入口）
+
+内容（单一事实来源，集中管理共享客户端）：
+
+```python
+"""SDK 全局配置与共享客户端管理。"""
+
+from ._client import IndicatorLibraryClient
+
+_client: IndicatorLibraryClient | None = None
+
+def configuration(app_key: str | None = None, secret_key: str | None = None) -> None:
+    """临时配置 app_key / secret_key（对当前进程有效，会替换共享客户端）。"""
+    global _client
+    _client = IndicatorLibraryClient(app_key=app_key, secret_key=secret_key)
+
+def get_client() -> IndicatorLibraryClient:
+    """获取全局共享客户端；未显式配置时，从环境变量读取凭证（懒加载）。"""
+    global _client
+    if _client is None:
+        _client = IndicatorLibraryClient()
+    return _client
+```
+
+设计要点：
+
+- `configuration()` 每次调用都会**重建**共享客户端（支持运行期切换凭证）。
+- `configuration()` 不传参时，等价于从环境变量读取凭证（`IndicatorLibraryClient` 已有此逻辑）。
+- `get_client()` 懒加载，未调用 `configuration` 时自动读环境变量。
+- 客户端内部的**类级全量缓存**（`__CACHE_DF`）跨实例共享，重建客户端不会导致缓存丢失或重复重建。
+
+### 3.3 新增：`theme_classification.py`（主题分类模块级函数）
+
+薄封装，每个函数委托给共享客户端，保持「业务逻辑集中在客户端、模块只做转发」：
+
+```python
+"""主题分类数据接口。"""
+
+from ._config import get_client
+
+def get_theme_classification_framework_inc(view_date: str):
+    """按 view_date 查询主题库日度增量数据。"""
+    return get_client().get_theme_classification_framework_inc(view_date)
+# ... 同样封装其余 5 个方法：
+# get_theme_classification_framework_daily
+# get_theme_classification_portfolio_inc
+# get_theme_classification_portfolio_daily
+# get_theme_classification_index_inc
+# get_theme_classification_index_by_id
+```
+
+### 3.4 新增：`beta_indicator.py`（指标库模块级函数）
+
+薄封装，同样委托给共享客户端：
+
+```python
+"""指标库数据接口。"""
+
+from ._config import get_client
+
+def list_indicator_types():
+    """读取所有指标类型。"""
+    return get_client().list_indicator_types()
+# ... 同样封装其余 7 个方法：
+# list_indicators(indicator_type)
+# get_indicator_value(indicator_id)
+# get_indicator_value_inc(view_date)
+# list_sector_types()
+# list_sectors(sector_type=None)
+# list_indicators_by_sector(sector_code)
+# get_indicator_value_batch(indicator_ids, max_workers=3)
+```
+
+### 3.5 重写：`__init__.py`（公共入口）
+
+```python
+"""板块指标库 API SDK。"""
+
+from . import beta_indicator
+from . import theme_classification
+from ._config import configuration
+
+__all__ = ["configuration", "theme_classification", "beta_indicator"]
+__version__ = "0.1.0"
+```
+
+- 不再导入 `IndicatorLibraryClient`，`__all__` 中不含该类 → 满足「不对外暴露」。
+- `aibeta.configuration(...)`、`from aibeta import theme_classification`、`from aibeta import beta_indicator` 三种用法均可正常工作。
+
+### 3.6 更新示例脚本
+
+- **`examples/my_script.py`**：改为新调用方式，保留现有 `_normalize_for_display` / `_print_demo_result` 辅助函数与全部演示调用，仅替换导入与实例化方式：
+
+```python
+import aibeta
+from aibeta import beta_indicator, theme_classification
+
+# 默认从环境变量读取凭证；如需临时配置，取消注释并填入真实凭证：
+# aibeta.configuration(app_key="XXX", secret_key="XXX")
+
+framework_inc = theme_classification.get_theme_classification_framework_inc("2026-06-26")
+# ... 其余调用
+indicator_values_batch = beta_indicator.get_indicator_value_batch(indicator_id_list)
+```
+
+- **`examples/import_script.py`**：修正第 59 行笔误 `client.get_indicator_value_batch(...)` → `beta_indicator.get_indicator_value_batch(...)`，其余保持不变。
+
+## 四、假设与决策（Assumptions & Decisions）
+
+1. **环境变量名**：沿用 `BETA_INDICATOR_API_APP_KEY` / `BETA_INDICATOR_API_SECRET_KEY`（用户已确认）。
+2. **示例文件**：同步更新为可运行示例，并修正 `import_script.py` 笔误（用户已确认）。
+3. **`configuration()` 签名**：仅接收 `app_key` / `secret_key`，不扩展 `base_url` / `timeout` 等参数（本次需求未涉及，保持最小改动）。
+4. **客户端类**：类名保持 `IndicatorLibraryClient`，通过私有模块 `_client.py` 与不导出实现隐藏；不重命名类。
+5. **缓存机制**：保持现有类级全量快照缓存（`__CACHE_DF`）不变，重建客户端时缓存复用。
+6. **`pyproject.toml`**：`packages = ["src/aibeta"]` 已正确指向包，无需改动。
+
+## 五、验证步骤（Verification）
+
+1. 以可编辑方式安装：`uv pip install -e .`（或 `pip install -e .`）。
+2. 校验公共命名空间：
+   ```bash
+   python -c "import aibeta; print(aibeta.__all__); print(aibeta.__version__); print(hasattr(aibeta, 'configuration')); print(hasattr(aibeta, 'IndicatorLibraryClient'))"
+   ```
+   期望：`__all__` 含 `configuration/theme_classification/beta_indicator`；`hasattr(aibeta, 'IndicatorLibraryClient')` 为 `False`。
+3. 校验子模块可导入且函数存在：
+   ```bash
+   python -c "from aibeta import theme_classification, beta_indicator; print(callable(theme_classification.get_theme_classification_framework_inc)); print(callable(beta_indicator.get_indicator_value_batch))"
+   ```
+4. 校验 `configuration` 可正常配置（不发起真实网络请求，仅验证不抛错时需提供真实凭证）：
+   ```bash
+   python -c "import aibeta; aibeta.configuration(app_key='XXX', secret_key='XXX')"
+   ```
+5. 在已配置环境变量的前提下，运行 `python examples/my_script.py`，确认所有接口按新方式正常取数。

aibeta-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 伍老师
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aibeta-0.3.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: aibeta
+Version: 0.3.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，提供主题分类与指标库数据的统一查询接口。
+
+## 安装
+
+```bash
+pip install aibeta
+```
+
+## 配置凭证
+
+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"
+```
+
+## 快速使用
+
+```python
+from aibeta import theme_classification, beta_indicator
+
+# 指标库：读取所有指标类型
+beta_indicator.list_indicator_types()
+```
+
+完整接口示例见 `examples/import_script.py`。
+
+## 接口说明
+
+数据类接口统一返回 `pandas.DataFrame`（`get_indicator_value_batch` 除外）。凭证配置见上方「配置凭证」。
+
+### 全局配置
+
+| 接口              | 调用方式                      | 功能简介                     | 参数                                               |
+| ----------------- | ----------------------------- | ---------------------------- | -------------------------------------------------- |
+| `configuration` | `aibeta.configuration(...)` | 配置当前进程的凭证与超时参数 | `app_key` / `secret_key` / `timeout`，均可选 |
+
+### 主题分类 `theme_classification`
+
+| 接口                                         | 调用方式                                                                     | 功能简介                         | 参数                         |
+| -------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------- | ---------------------------- |
+| `get_theme_classification_framework_inc`   | `theme_classification.get_theme_classification_framework_inc(view_date)`   | 主题库日度增量数据               | `view_date: str`，查询日期 |
+| `get_theme_classification_framework_daily` | `theme_classification.get_theme_classification_framework_daily(view_date)` | 主题库日度截面数据               | `view_date: str`，查询日期 |
+| `get_theme_classification_portfolio_inc`   | `theme_classification.get_theme_classification_portfolio_inc(view_date)`   | 主题成分股（标准池）日度增量数据 | `view_date: str`，查询日期 |
+| `get_theme_classification_portfolio_daily` | `theme_classification.get_theme_classification_portfolio_daily(view_date)` | 主题成分股（标准池）日度截面数据 | `view_date: str`，查询日期 |
+| `get_theme_classification_index_inc`       | `theme_classification.get_theme_classification_index_inc(view_date)`       | 主题指数点位日度增量数据         | `view_date: str`，查询日期 |
+| `get_theme_classification_index_by_id`     | `theme_classification.get_theme_classification_index_by_id(theme_id)`      | 查询特定主题的历史指数点位       | `theme_id: str`，主题 ID   |
+
+### 指标库 `beta_indicator`
+
+| 接口                          | 调用方式                                                                   | 功能简介                                        | 参数                                                                                         |
+| ----------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `list_indicator_types`      | `beta_indicator.list_indicator_types()`                                  | 读取所有指标类型（如市盈率 PE、市净率 PB 等）   | 无                                                                                           |
+| `list_indicators`           | `beta_indicator.list_indicators(indicator_type)`                         | 按指标类型读取指标列表                          | `indicator_type: str`，指标类型名称                                                        |
+| `get_indicator_value`       | `beta_indicator.get_indicator_value(indicator_id)`                       | 按指标 ID 读取该指标全部数值记录                | `indicator_id: str`，指标唯一标识                                                          |
+| `get_indicator_value_inc`   | `beta_indicator.get_indicator_value_inc(view_date)`                      | 按日期增量读取所有指标值                        | `view_date: str`，查询日期                                                                 |
+| `list_sector_types`         | `beta_indicator.list_sector_types()`                                     | 读取所有板块类型（如 ETF 指数、中信证券行业等） | 无                                                                                           |
+| `list_sectors`              | `beta_indicator.list_sectors(sector_type=None)`                          | 读取板块列表，可选按板块类型过滤                | `sector_type: str \| None`，传 `None` 返回全部                                            |
+| `list_indicators_by_sector` | `beta_indicator.list_indicators_by_sector(sector_code)`                  | 按板块代码读取该板块全部指标列表                | `sector_code: str`，板块代码（如 `000001.SH`）                                           |
+| `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 |
+
+> 返回类型：`get_indicator_value_batch` 返回 `dict[str, DataFrame | None]`（key 为指标 ID，读取失败对应 `None`），其余均返回 `DataFrame`。
+
+## 依赖
+
+- Python >= 3.10
+- pandas、pyarrow、requests、tqdm
+
+> 缓存说明：SDK 会在用户缓存目录（`~/.cache/aibeta/`）维护指标库的全量快照缓存，默认每 3 天自动重建一次。

aibeta-0.3.0/README.md

@@ -0,0 +1,81 @@
+# aibeta-sdk
+
+板块指标库 API SDK，提供主题分类与指标库数据的统一查询接口。
+
+## 安装
+
+```bash
+pip install aibeta
+```
+
+## 配置凭证
+
+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"
+```
+
+## 快速使用
+
+```python
+from aibeta import theme_classification, beta_indicator
+
+# 指标库：读取所有指标类型
+beta_indicator.list_indicator_types()
+```
+
+完整接口示例见 `examples/import_script.py`。
+
+## 接口说明
+
+数据类接口统一返回 `pandas.DataFrame`（`get_indicator_value_batch` 除外）。凭证配置见上方「配置凭证」。
+
+### 全局配置
+
+| 接口              | 调用方式                      | 功能简介                     | 参数                                               |
+| ----------------- | ----------------------------- | ---------------------------- | -------------------------------------------------- |
+| `configuration` | `aibeta.configuration(...)` | 配置当前进程的凭证与超时参数 | `app_key` / `secret_key` / `timeout`，均可选 |
+
+### 主题分类 `theme_classification`
+
+| 接口                                         | 调用方式                                                                     | 功能简介                         | 参数                         |
+| -------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------- | ---------------------------- |
+| `get_theme_classification_framework_inc`   | `theme_classification.get_theme_classification_framework_inc(view_date)`   | 主题库日度增量数据               | `view_date: str`，查询日期 |
+| `get_theme_classification_framework_daily` | `theme_classification.get_theme_classification_framework_daily(view_date)` | 主题库日度截面数据               | `view_date: str`，查询日期 |
+| `get_theme_classification_portfolio_inc`   | `theme_classification.get_theme_classification_portfolio_inc(view_date)`   | 主题成分股（标准池）日度增量数据 | `view_date: str`，查询日期 |
+| `get_theme_classification_portfolio_daily` | `theme_classification.get_theme_classification_portfolio_daily(view_date)` | 主题成分股（标准池）日度截面数据 | `view_date: str`，查询日期 |
+| `get_theme_classification_index_inc`       | `theme_classification.get_theme_classification_index_inc(view_date)`       | 主题指数点位日度增量数据         | `view_date: str`，查询日期 |
+| `get_theme_classification_index_by_id`     | `theme_classification.get_theme_classification_index_by_id(theme_id)`      | 查询特定主题的历史指数点位       | `theme_id: str`，主题 ID   |
+
+### 指标库 `beta_indicator`
+
+| 接口                          | 调用方式                                                                   | 功能简介                                        | 参数                                                                                         |
+| ----------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `list_indicator_types`      | `beta_indicator.list_indicator_types()`                                  | 读取所有指标类型（如市盈率 PE、市净率 PB 等）   | 无                                                                                           |
+| `list_indicators`           | `beta_indicator.list_indicators(indicator_type)`                         | 按指标类型读取指标列表                          | `indicator_type: str`，指标类型名称                                                        |
+| `get_indicator_value`       | `beta_indicator.get_indicator_value(indicator_id)`                       | 按指标 ID 读取该指标全部数值记录                | `indicator_id: str`，指标唯一标识                                                          |
+| `get_indicator_value_inc`   | `beta_indicator.get_indicator_value_inc(view_date)`                      | 按日期增量读取所有指标值                        | `view_date: str`，查询日期                                                                 |
+| `list_sector_types`         | `beta_indicator.list_sector_types()`                                     | 读取所有板块类型（如 ETF 指数、中信证券行业等） | 无                                                                                           |
+| `list_sectors`              | `beta_indicator.list_sectors(sector_type=None)`                          | 读取板块列表，可选按板块类型过滤                | `sector_type: str \| None`，传 `None` 返回全部                                            |
+| `list_indicators_by_sector` | `beta_indicator.list_indicators_by_sector(sector_code)`                  | 按板块代码读取该板块全部指标列表                | `sector_code: str`，板块代码（如 `000001.SH`）                                           |
+| `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 |
+
+> 返回类型：`get_indicator_value_batch` 返回 `dict[str, DataFrame | None]`（key 为指标 ID，读取失败对应 `None`），其余均返回 `DataFrame`。
+
+## 依赖
+
+- Python >= 3.10
+- pandas、pyarrow、requests、tqdm
+
+> 缓存说明：SDK 会在用户缓存目录（`~/.cache/aibeta/`）维护指标库的全量快照缓存，默认每 3 天自动重建一次。

aibeta-0.3.0/examples/import_script.py

@@ -0,0 +1,59 @@
+# 期待的python sdk调用方式
+
+# aibeta模块 #######################################################################
+import aibeta
+
+# 配置app-key，app-secret (避免设置环境变量，对单次程序运行有效)
+aibeta.configuration(app_key='XXX', secret_key='XXX')
+
+# theme_classification模块 #######################################################################
+from aibeta import theme_classification
+
+# 读取主题库日度增量数据
+theme_classification.get_theme_classification_framework_inc("2026-06-26")
+
+# 读取主题库日度截面数据
+theme_classification.get_theme_classification_framework_daily("2026-06-30")
+
+# 读取主题标准池日度增量数据
+theme_classification.get_theme_classification_portfolio_inc("2026-06-26")
+
+# 读取主题标准池日度截面数据
+theme_classification.get_theme_classification_portfolio_daily("2026-06-30")
+
+# 读取主题指数点位增量数据
+theme_classification.get_theme_classification_index_inc("2026-06-30")
+
+# 读取特定主题指数点位
+theme_classification.get_theme_classification_index_by_id("66f3c5b8562120df54e844485c9a1606b0d303d58427c7b28466789f7881ef14")
+
+# beta_indicator 模块 #######################################################################
+from aibeta import beta_indicator
+
+# 读取所有指标类型
+beta_indicator.list_indicator_types()
+
+# 读取市盈率PE相关的所有板块指标
+beta_indicator.list_indicators("市盈率PE")
+
+# 读取指定板块指标值
+beta_indicator.get_indicator_value("7023d2fa62ec5163b4d70dfb9f4ad3348beddf5580cf0118d97af7d7a838d76c")
+
+# 按日期增量读取所有指标值
+beta_indicator.get_indicator_value_inc("2026-06-30")
+
+# 读取所有板块类型
+beta_indicator.list_sector_types()
+
+# 读取指定板块类型下的所有板块列表
+beta_indicator.list_sectors("ETF指数")
+
+# 读取指定板块相关的所有指标列表
+beta_indicator.list_indicators_by_sector("000001.SH")
+
+# 批量读取多个指标值
+indicator_id_list = [
+    "f05d22906036b430fae3854635e8015b3384d04bcba38593c67c7e5d5b4aefee",
+    "831a95f5e39492edfd8a98397869a9c50496152faefba1e4bfbc0bab7abe227f",
+]  
+indicator_values_batch = beta_indicator.get_indicator_value_batch(indicator_id_list)