Metadata-Version: 2.5
Name: axiolune
Version: 0.6.0
Summary: Explicit financial data acquisition, immutable snapshots and shared research
Author: Moonweave AI
License-Expression: Apache-2.0
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Requires-Python: <3.14,>=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=18
Requires-Dist: tzdata>=2025.2
Requires-Dist: xlrd<3,>=2.0.2
Provides-Extra: all
Requires-Dist: catboost<2,>=1.2.10; extra == 'all'
Requires-Dist: cryptography<51,>=43; extra == 'all'
Requires-Dist: duckdb<2,>=1.2; extra == 'all'
Requires-Dist: fastapi<1,>=0.115; extra == 'all'
Requires-Dist: lightgbm<5,>=4.7; extra == 'all'
Requires-Dist: numpy<3,>=2; extra == 'all'
Requires-Dist: omegaconf<2.4,>=2.3.1; extra == 'all'
Requires-Dist: onnxruntime<2,>=1.26; (sys_platform != 'darwin' or platform_machine != 'x86_64') and extra == 'all'
Requires-Dist: onnxruntime==1.23.2; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'all'
Requires-Dist: plotly<8,>=7.1; extra == 'all'
Requires-Dist: polars<2,>=1; extra == 'all'
Requires-Dist: psycopg[binary]<4,>=3.3.6; extra == 'all'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'all'
Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'all'
Requires-Dist: pypdf<7,>=6.18; extra == 'all'
Requires-Dist: pypdfium2<6,>=5.13; extra == 'all'
Requires-Dist: pyshacl<0.31,>=0.26; extra == 'all'
Requires-Dist: pyyaml<7,>=6; extra == 'all'
Requires-Dist: rapidocr==3.9.2; extra == 'all'
Requires-Dist: rdflib<8,>=7.1; extra == 'all'
Requires-Dist: scikit-learn<2,>=1.5; extra == 'all'
Requires-Dist: scipy<2,>=1.14; extra == 'all'
Requires-Dist: sqlalchemy<3,>=2; extra == 'all'
Requires-Dist: ta-lib<0.9,>=0.8.1; extra == 'all'
Requires-Dist: uvicorn<1,>=0.30; extra == 'all'
Requires-Dist: websockets<18,>=17.0.1; extra == 'all'
Requires-Dist: xgboost<4,>=3.4.1; extra == 'all'
Provides-Extra: data
Provides-Extra: documents
Requires-Dist: pypdf<7,>=6.18; extra == 'documents'
Provides-Extra: financial
Requires-Dist: pydantic<3,>=2.13.5; extra == 'financial'
Provides-Extra: ingest
Requires-Dist: pydantic<3,>=2.13.5; extra == 'ingest'
Provides-Extra: local
Requires-Dist: duckdb<2,>=1.2; extra == 'local'
Requires-Dist: polars<2,>=1; extra == 'local'
Provides-Extra: ml
Requires-Dist: duckdb<2,>=1.2; extra == 'ml'
Requires-Dist: numpy<3,>=2; extra == 'ml'
Requires-Dist: polars<2,>=1; extra == 'ml'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'ml'
Requires-Dist: scikit-learn<2,>=1.5; extra == 'ml'
Requires-Dist: scipy<2,>=1.14; extra == 'ml'
Provides-Extra: ml-advanced
Requires-Dist: catboost<2,>=1.2.10; extra == 'ml-advanced'
Requires-Dist: duckdb<2,>=1.2; extra == 'ml-advanced'
Requires-Dist: lightgbm<5,>=4.7; extra == 'ml-advanced'
Requires-Dist: numpy<3,>=2; extra == 'ml-advanced'
Requires-Dist: polars<2,>=1; extra == 'ml-advanced'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'ml-advanced'
Requires-Dist: scikit-learn<2,>=1.5; extra == 'ml-advanced'
Requires-Dist: scipy<2,>=1.14; extra == 'ml-advanced'
Requires-Dist: xgboost<4,>=3.4.1; extra == 'ml-advanced'
Provides-Extra: ocr
Requires-Dist: omegaconf<2.4,>=2.3.1; extra == 'ocr'
Requires-Dist: onnxruntime<2,>=1.26; (sys_platform != 'darwin' or platform_machine != 'x86_64') and extra == 'ocr'
Requires-Dist: onnxruntime==1.23.2; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'ocr'
Requires-Dist: pypdf<7,>=6.18; extra == 'ocr'
Requires-Dist: pypdfium2<6,>=5.13; extra == 'ocr'
Requires-Dist: rapidocr==3.9.2; extra == 'ocr'
Provides-Extra: plot
Requires-Dist: plotly<8,>=7.1; extra == 'plot'
Provides-Extra: research
Requires-Dist: duckdb<2,>=1.2; extra == 'research'
Requires-Dist: numpy<3,>=2; extra == 'research'
Requires-Dist: polars<2,>=1; extra == 'research'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'research'
Requires-Dist: scipy<2,>=1.14; extra == 'research'
Provides-Extra: semantic
Requires-Dist: pydantic<3,>=2.13.5; extra == 'semantic'
Requires-Dist: pyshacl<0.31,>=0.26; extra == 'semantic'
Requires-Dist: pyyaml<7,>=6; extra == 'semantic'
Requires-Dist: rdflib<8,>=7.1; extra == 'semantic'
Provides-Extra: server
Requires-Dist: duckdb<2,>=1.2; extra == 'server'
Requires-Dist: fastapi<1,>=0.115; extra == 'server'
Requires-Dist: polars<2,>=1; extra == 'server'
Requires-Dist: psycopg[binary]<4,>=3.3.6; extra == 'server'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'server'
Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'server'
Requires-Dist: sqlalchemy<3,>=2; extra == 'server'
Requires-Dist: uvicorn<1,>=0.30; extra == 'server'
Provides-Extra: source-crypto
Requires-Dist: cryptography<51,>=43; extra == 'source-crypto'
Provides-Extra: sql
Requires-Dist: psycopg[binary]<4,>=3.3.6; extra == 'sql'
Requires-Dist: sqlalchemy<3,>=2; extra == 'sql'
Provides-Extra: stream
Requires-Dist: websockets<18,>=17.0.1; extra == 'stream'
Provides-Extra: ta
Requires-Dist: duckdb<2,>=1.2; extra == 'ta'
Requires-Dist: numpy<3,>=2; extra == 'ta'
Requires-Dist: polars<2,>=1; extra == 'ta'
Requires-Dist: pydantic<3,>=2.13.5; extra == 'ta'
Requires-Dist: scipy<2,>=1.14; extra == 'ta'
Requires-Dist: ta-lib<0.9,>=0.8.1; extra == 'ta'
Provides-Extra: team
Description-Content-Type: text/markdown

# Axiolune Python SDK

用同一个 Python 包找数据、固定原始输入、研究公司与组合，再把研究交给团队执行、审阅和复算。SDK、CLI、脚本与 Notebook 共用计算和存储入口；单人研究不需要运行团队服务。

当前产品版本与安装状态见下方安装说明。常规取数使用 `session.services.get()`：按股票、基金、指数、债券、期货、期权、外汇和宏观业务能力选择服务，使用统一证券、日期、复权和返回字段。路由只在真实语义等价的来源之间切换，并保留同一 Session 预算、实际来源和失败尝试。`session.services.capabilities()` 返回可浏览的能力表；`describe()` 返回参数、单位、覆盖范围与来源合同。[业务服务指南](examples/business-services.md)列出使用方式和实际限制。

安装 `axiolune` 后，显式启用网络即可读取业务服务：

```python
import axiolune as ax

with ax.Session(network="enabled", timeout=45, max_rows=100000) as session:
    print(session.services.capabilities(domain="equity").to_string(index=False))
    quotes = session.services.get("equity.quote", securities=["600519.SH", "AAPL.US"])
    print(quotes.to_string(index=False))
```

使用 `session.catalog.bindings.search/describe` 查完整参数合同。[一次调用与来源可用性](examples/source-availability.md)说明有界自动备源、明确公共方法和分页续取。公开替代保留实际发布者、单位、历史和方法差异；需要凭据的来源由调用者提供自己的授权配置。各来源指南保留真实拒绝、空响应和历史限制。

## 历史 a20 指标与长期历史

- [指标与 TA-Lib](examples/technical-indicators.md)：`ta` extra 提供多输入/多输出、显式预算的独立进程批量计算；原 14 个核心指标默认保留。201 个函数可发现并通过通用规格绑定，不代表每项已实测或 FinLab 全行为等价。
- [宏观长期历史](examples/macro-history.md)：FRED 单一通用系列入口。a20 的 World Bank/BLS 原站失败属于历史记录；World Bank 国家与指标读取现已成功，BLS 有明确 FRED/DBnomics 当前系列和独立历史档案路径，实际来源、时间与系列范围分别保留。
- [基金历史](examples/fund-history.md)：增强原净值产品，保留分红拆分多表原字段与公告全分页。

## 历史 a19 新增研究与执行入口

- [参数化指标与条件](examples/technical-indicators.md)：统一 Decimal 数值核、明确窗口/初始化/缺失政策，供 typed Frame、FinlabDataFrame 和 ML 共用。
- [公司行动](examples/corporate-actions.md)：配股权、行权交收、换股、碎股现金结算使用原账本；条款须显式声明。写入新增 V1 事件后，a18 无法重放；回退必须恢复写入前备份。
- [模型与批量推理](examples/ml-models.md) · [BrokerPort](src/axiolune/BROKER-PORT.md) · [运营与容量](OPERATING-CAPACITY.md)。

## 历史 a18 新增来源与财报绑定

以下入口已包含在 a18 wheel/sdist 中；实际成功、失败、空查询及来源权利边界仍以各指南为准：

- [港美日历史价格与基金持仓](examples/global-prices-fund-holdings.md)：历史价格、基金证券级股债持仓和变动。
- [公司财报与市场历史](examples/corporate-market-history.md)：A/HK 三表、中债、国证样本与调样；历史权重路径的实际失败范围见指南。
- [市场披露](examples/market-disclosures.md)：公司十大流通股东、银行间债券目录与条款、郑商所仓单。
- [发行人公告索引](examples/issuer-disclosures.md)：按公司与日期查找官方公告及原 PDF 链接；深交所已有实际公告，港交所本次查询为空、巨潮返回 403，具体范围见指南。

- [通用财报绑定](src/axiolune/SOURCE-FINANCIAL-BINDINGS.md)：原生宽表/长表科目映射到现有财报与公司研究；未知存储资格只做内存绑定检查。

## 安装与配置 / Installation

<!-- generated-install:start -->
当前产品版本 / Product version: **0.6.0** · **待发布到 PyPI / Awaiting PyPI publication**。

以下为发布后的标准索引安装方式，公共索引目前尚不能取得本版本。
These are the standard commands after publication; this version is not yet available from the public index.

```bash
pip install axiolune
uv pip install axiolune
uv add axiolune
```

基础安装包含常规取数、Arrow/pandas 与 Excel；Python `>=3.12,<3.14`。不同安装器择一使用，pip/uv pip 面向环境，uv add 面向项目。首次解析选择所用索引与 Python/平台/依赖约束允许的最新正常版本；已有环境和 uv.lock 不会自动追新。
Core installation includes routine data retrieval, Arrow/pandas and Excel. Choose one workflow: pip/uv pip manages an environment; uv add manages a project. Initial resolution chooses the latest normal release permitted by the index and environment constraints, without automatically upgrading existing environments or lockfiles.

### 按需组合 / Combine capabilities

```bash
pip install "axiolune[local]"
uv pip install "axiolune[research,plot,team]"
uv add "axiolune[documents,ocr]"
```

可同时选择多个 extras；其下层依赖自动包含。data 和 team 的依赖已含基础安装，保留兼容别名；all 仅用于需要全部可选依赖的环境。
Select multiple extras; their dependencies are included automatically. data and team retain compatibility aliases with dependencies already in the core. Choose all only when every optional dependency is needed.

| 能力 | 用途 | 自动包含的能力 |
|---|---|---|
| `data` | 常规取数、Arrow/pandas 和 Excel；当前已包含在基础安装，保留此兼容选项。 | — |
| `source-crypto` | 需要加密能力的数据来源适配。 | `data` |
| `local` | 本地快照、DuckDB SQL 与 Polars 表格计算。 | `data` |
| `research` | 指标、筛选、回测、风险和组合研究。 | `local`, `financial` |
| `plot` | 交互图表与可导出的 HTML 报告。 | `data` |
| `team` | 连接现有团队服务的远程客户端；依赖已含基础安装，保留此兼容选项。 | — |
| `sql` | 连接外部 SQL 数据库与读取查询结果。 | `data` |
| `server` | 团队 HTTP 服务、PostgreSQL 接入与工作进程；数据库服务另行配置。 | `local`, `financial` |
| `ingest` | 数据连接器与财务导入适配。 | `financial` |
| `ml` | 基于 scikit-learn 的常规模型研究。 | `research` |
| `ml-advanced` | CatBoost、LightGBM、XGBoost 树模型后端。 | `ml` |
| `ta` | 独立进程中的 TA-Lib 指标计算。 | `research` |
| `semantic` | 语义映射、RDF 与 SHACL 校验。 | `financial` |
| `documents` | PDF 文本解析与文档证据。 | — |
| `ocr` | PDF 渲染与 OCR；模型权重不随安装命令下载。 | `documents` |
| `stream` | WebSocket 流式数据来源。 | `data` |
| `financial` | 财报合同、财务计算与公司研究。 | `data` |
| `all` | 安装所有可选依赖；适合确实使用全部能力的环境。 | `data`, `source-crypto`, `local`, `research`, `plot`, `team`, `sql`, `server`, `ingest`, `ml`, `ml-advanced`, `ta`, `semantic`, `documents`, `ocr`, `stream`, `financial` |

### 升级 / Upgrade

```bash
pip install -U axiolune
uv pip install --upgrade axiolune
```

升级时保留所需 extras，例如 `pip install -U "axiolune[research,plot]"`。普通重复 install 不等于升级。uv 项目更新锁文件后再同步：
Retain required extras during upgrades. An ordinary repeated install is not an upgrade request. For uv projects:

```bash
uv lock --upgrade-package axiolune
uv sync
```

uv.lock 保留已解析版本；升级仍遵守 pyproject.toml 的版本范围。
uv.lock retains resolved versions; upgrades remain subject to pyproject.toml constraints.

使用独立虚拟环境。Windows 用 `py -3.13 -m venv .venv`，Linux/macOS 用 `python3.13 -m venv .venv`；或统一使用 `uv venv --python 3.13`。不激活时用 `.venv/Scripts/python -m pip`（Windows）、`.venv/bin/python -m pip`（Linux/macOS），或 `uv pip install --python .venv axiolune`。uv 项目同时声明完整 Python 范围：`uv init --python ">=3.12,<3.14" my-research` 后 `uv add axiolune`。
Use an isolated environment and its own interpreter. Python 3.12 is also supported. uv projects manage their environment automatically.

可选系统依赖：Linux OCR 需要 OpenGL/GLib（Debian/Ubuntu：`libgl1 libglib2.0-0`）；macOS 的 ml-advanced/all 需要 `brew install libomp`。server 不自动部署 PostgreSQL；OCR 模型权重另行准备。Windows x64、Linux x86_64/glibc ≥ 2.28、macOS Intel ≥ 13 / Apple Silicon ≥ 14 是完整依赖目标；实际平台执行记录须分别查看，历史 a34 结果仍属于 a34。
Optional system libraries: OpenGL/GLib for Linux OCR and libomp for macOS advanced tree models. server does not provision PostgreSQL; OCR weights are separate. Historical a34 execution records remain a34 evidence.

依赖与版本唯一来源为 SDK pyproject.toml 和根 VERSION；安装/升级命令不固定版本号。需要精确复现时才显式使用 `==`。
The SDK pyproject.toml and root VERSION are authoritative. Version pins are reserved for explicit reproduction.
<!-- generated-install:end -->

## 找数据、取数、固定输入

本节示例包含 DuckDB SQL 查询，先安装 `pip install "axiolune[local]"`。只浏览目录或常规取数使用基础安装即可。

先查看目录卡的参数、字段、历史范围和权利，再抓取所需产品：

```powershell
python -m axiolune catalog search "汇率"
python -m axiolune catalog card taifex.DailyForeignExchangeRates
```

```python
from axiolune import Session

with Session.local(data_root="./research-data", network="enabled") as session:
    product = session.catalog.describe("taifex.DailyForeignExchangeRates")
    result = session.data.fetch(product["dataset_id"], cache="refresh")
    print(result.to_records())
    print(result.receipt.to_dict())
    fixed = session.snapshots.freeze(result)
    snapshot_id = fixed.id
    answer = session.data.query(fixed, "SELECT count(*) AS observations FROM source")
    print(answer.table.to_pylist())

with Session.local(data_root="./research-data") as offline:
    same_input = offline.data.read(snapshot_id)
```

`to_records()` 恢复原始值和缺席字段，`to_arrow/to_pandas/to_polars` 提供表格表示。`SourceResult.export` 导出单个结果，`SourceBundle.export/read` 组织多个命名快照并保留原响应、全字段和输入闭包，见[研究旅程与数据包](examples/research-journey.md)。持久缓存、冻结、导出需要已建立的保存权利；`cache="bypass"` 可用于按合同允许的临时读取。目录卡会保留未知权利和真实读取失败。

继续操作：[官方来源与历史参数](examples/public-source-history.md) · [固定 SQL 规格](src/axiolune/QUERY-SPECS.md) · [流式来源](src/axiolune/STREAMING.md) · [有限批次与调度](src/axiolune/SOURCE-SCHEDULING.md) · [来源健康](src/axiolune/SOURCE-HEALTH.md)。显式单位缩放、枚举映射和跨源身份候选/优先选择见[来源映射](SOURCE-MAPPING.md)。

## 从一份声明开始公司研究

先安装 `pip install "axiolune[financial]"`，生成声明，编辑公司、期间、科目、作者与估值假设，再准备输入并运行。输出文件和目录使用尚不存在的新路径：

```powershell
python -m axiolune journey template --output company-request.json
# 编辑 company-request.json，确认要获取的公司与研究假设。
python -m axiolune journey prepare --config company-request.json --data-root ./data --output ./prepared
python -m axiolune journey run --config ./prepared/journey.json --output ./my-research
```

模板使用 Apple 的指定年度申报和显式 P/E 假设，不附带市场原件或计算结果。`prepare` 通过真实来源抓取与快照固定，自动生成唯一事实指针、单位、来源引用和可执行规格；已有快照时填写 `snapshot_id` 并传 `--network offline`。`run` 共用于[脚本](examples/research_journey.py)和 [Notebook](examples/research_journey.ipynb)，不依赖仓库 `build` 目录。

`CompanyResearchSpec` 支持财报指标、估值情景、同业比较与敏感性，也可发布固定输入并提交团队 Run。操作细节见[公司研究](src/axiolune/COMPANY_RESEARCH.md)、[财报查询](src/axiolune/FINANCIAL-QUERIES.md)、[比率](src/axiolune/FINANCIAL-RATIOS.md)。因子、条件持仓和时间研究可继续使用[类型化 Frame](src/axiolune/TYPED-FRAMES.md)、[因子配对](src/axiolune/FACTOR-PAIRS.md)、[观察标签](src/axiolune/OBSERVATION-LABELS.md)与[时间切分](src/axiolune/TIME-SPLITS.md)。

## 组合研究、paper 与绩效

组合、风险与回测安装 `pip install "axiolune[research]"`；下述模型任务另选 `ml`，高级树模型选 `ml-advanced`，图表导出选 `plot`，可按需组合。

`ml template/prepare/evaluate` 沿同一 Research/Run 保存 Artifact、登记全部试验和 registry 版本；分类、回归、参数试验、验证集选择以及 `ml export-model/predict` 见[模型指南](examples/ml-models.md)。原生模型需精确版本后端，缺包保留失败，不切换算法。导出和推理为有界批处理，在线部署尚未完成。

[公司行动和有效历史](examples/market-lifecycle.md)把实际源行绑定到行动、身份/成员/规则的有效版本，可继续用于回测和 paper 账本。

[BrokerPort](src/axiolune/BROKER-PORT.md)提供原账本上的 paper 提交、撤单、回报和对账端口；真实券商执行保持关闭。团队 worker 心跳/排空、运行窗口观察和服务组启动见[运营与容量](OPERATING-CAPACITY.md)，新范围登记与批次执行见[团队扩展](src/axiolune/TEAM-EXTENSIONS.md)。

在同一声明中添加 `quotes/portfolio/performance`，即可把真实报价与指定纸面账户的账本序号绑定，准备器自动生成精确账本引用。先按[组合输入准备](examples/portfolio-input-preparation.md)填输入，再使用相同的 `journey prepare/run`。

| 要做的事 | 入口与使用指南 |
|---|---|
| 协方差、组合风险、约束优化、策略组合、离散再平衡 | `axiolune.risk` / `axiolune.optimization`；[组合研究](examples/portfolio-research.md) |
| 多资产现金、持仓与标准期货记录 | 共用 ledger；[多资产研究](examples/multi-asset-research.md)、[共享账本](src/axiolune/SHARED-LEDGER.md) |
| 准备订单、预览、纸面撮合与提交 | [目标订单](src/axiolune/TARGET-ORDERS.md)、[纸面撮合](src/axiolune/PAPER-MATCHING.md) |
| 标准期货历史 bar 自动撮合、保证金和费用约束 | `axiolune.futures_bar`；[自动期货 paper](FUTURES-AUTO-PAPER.md) |
| 绩效、归因与报告 | `performance report`；[绩效指南](src/axiolune/PERFORMANCE.md) |

## 团队接续与日常运维

连接现有团队服务的客户端依赖已含基础安装；维护服务和工作进程先安装 `pip install "axiolune[server]"`。数据库服务仍需按下方说明配置。

维护者按[团队操作指南](src/axiolune/team/OPERATIONS.md)初始化 PostgreSQL、为实际成员创建独立凭据，启动 `axiolune serve` 和 `axiolune worker`。研究员连接现有服务即可，不需要数据库凭据。

1. 数据员固定来源输入，维护者按项目权限共享；见[团队来源](src/axiolune/TEAM-SOURCES.md)。
2. 研究员发布公司输入并提交 Run，读取实际结果；见[旅程的团队接续](examples/research-journey.md#团队接续)。
3. 团队比较实验、请求审阅、注册精确版本并晋级；见 [Registry 与实验](src/axiolune/TEAM-REGISTRY.md)。CLI 的 `python -m axiolune team operations` 列出可调用操作。
4. 组合作者准备 paper 计划，审阅人预览并决定，组合操作员执行、对账和交接；见[组合计划操作](TEAM-PORTFOLIO-PLANS.md)。后续批次使用新账本头和新计划。
5. 维护者通过 `team.operations` 配置队列配额、维护暂停、环境兼容期限、来源负责人和事件；见[容量与运维](OPERATING-CAPACITY.md)。本地数据备份与回收见[存储维护](STORAGE-MAINTENANCE.md)。

## 实际范围

2026-09-21 来源扩展一轮新增 10 个合同，7 个读取成功、3 个失败；成功项为 5 个新独立产品和 2 个既有产品的历史入口。累计历史独立成功覆盖 12 域、78 产品，逐项范围见[来源扩展记录](../../../docs/plan/package-system/implementation/public-source-expansion-20260921.md)。该数字不表示全部产品都获准保存/分享，也不表示全球全历史。来源权利、单位/会计口径、PIT 与研究假设需按具体合同使用；paper 不连接券商。真人多人使用、长期运行及原 P0–P7 完整范围仍有未完成工作。数据许可独立于包的 Apache-2.0，见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

本轮安装不改变原冻结 164,919 条非容器记录的全量范围；真人多人协作、长期观察/SLO 和完整 P0–P7/FinLab 对标仍未完成。
