Axiolune Python SDK

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

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

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

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 查完整参数合同。一次调用与来源可用性说明有界自动备源、明确公共方法和分页续取。公开替代保留实际发布者、单位、历史和方法差异；需要凭据的来源由调用者提供自己的授权配置。各来源指南保留真实拒绝、空响应和历史限制。

历史 a20 指标与长期历史

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

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

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

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

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

• 港美日历史价格与基金持仓：历史价格、基金证券级股债持仓和变动。

• 公司财报与市场历史：A/HK 三表、中债、国证样本与调样；历史权重路径的实际失败范围见指南。

• 市场披露：公司十大流通股东、银行间债券目录与条款、郑商所仓单。

• 发行人公告索引：按公司与日期查找官方公告及原 PDF 链接；深交所已有实际公告，港交所本次查询为空、巨潮返回 403，具体范围见指南。

• 通用财报绑定：原生宽表/长表科目映射到现有财报与公司研究；未知存储资格只做内存绑定检查。

安装与配置 / Installation

当前产品版本 / 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.

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

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

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:

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.

找数据、取数、固定输入

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

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

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

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 组织多个命名快照并保留原响应、全字段和输入闭包，见研究旅程与数据包。持久缓存、冻结、导出需要已建立的保存权利；cache="bypass" 可用于按合同允许的临时读取。目录卡会保留未知权利和真实读取失败。

继续操作：官方来源与历史参数 · 固定 SQL 规格 · 流式来源 · 有限批次与调度 · 来源健康。显式单位缩放、枚举映射和跨源身份候选/优先选择见来源映射。

从一份声明开始公司研究

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

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 共用于脚本和 Notebook，不依赖仓库 build 目录。

CompanyResearchSpec 支持财报指标、估值情景、同业比较与敏感性，也可发布固定输入并提交团队 Run。操作细节见公司研究、财报查询、比率。因子、条件持仓和时间研究可继续使用类型化 Frame、因子配对、观察标签与时间切分。

组合研究、paper 与绩效

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

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

公司行动和有效历史把实际源行绑定到行动、身份/成员/规则的有效版本，可继续用于回测和 paper 账本。

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

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

要做的事	入口与使用指南
协方差、组合风险、约束优化、策略组合、离散再平衡	axiolune.risk / axiolune.optimization；组合研究
多资产现金、持仓与标准期货记录	共用 ledger；多资产研究、共享账本
准备订单、预览、纸面撮合与提交	目标订单、纸面撮合
标准期货历史 bar 自动撮合、保证金和费用约束	axiolune.futures_bar；自动期货 paper
绩效、归因与报告	performance report；绩效指南

团队接续与日常运维

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

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

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

实际范围

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

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