Metadata-Version: 2.5
Name: axiolune
Version: 0.7.0
Summary: Explicit financial data acquisition, immutable snapshots and shared research
Author: Moonweave AI
License-Expression: Apache-2.0
License-File: LICENSE
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

用领域函数读取股票、基金、指数、债券、期货、期权、外汇与宏观数据，返回可以直接组合研究的 pandas 表格。常规数据读取不需要初始化数据目录或创建客户端。

[中文使用手册](https://moonweaveai.org/axiolune/docs/quickstart) · [English documentation](https://moonweaveai.org/axiolune/en/docs/quickstart) · [完整 API 与参数](https://moonweaveai.org/axiolune/docs/public-api)

## 第一次读取

```python
import axiolune as ax

matches = ax.stock.search(query="茅台", market="CN")
print(matches)

prices = ax.stock.history(
    symbols="600519.SH",
    start="2026-09-01",
    end="2026-09-30",
    adjustment="none",
)
print(prices[["symbol", "date", "close", "currency"]].head())
```

`symbols` 使用带市场后缀的代码；`start`、`end` 是包含边界的日期。`adjustment="none"` 表示不复权。调用会访问真实数据来源；返回值和空表取决于来源及所选范围。每列含义、单位、可选值与默认值见 [stock.history](https://moonweaveai.org/axiolune/docs/api-stock-history)。

## 不知道填什么时

```python
print(ax.search("净值"))
print(ax.help("fund.history", language="zh"))
contract = ax.describe("stock.history")
print(contract["parameters"])
print(contract["output"])
```

发现与帮助操作不取网络数据。每个操作有独立参数页，列出必填项、格式、默认值、枚举、参数依赖、输出字段与实际留存结果。证券和指标示例不代表动态全集；先查相应目录再选值。

## 从表格组合研究

安装研究功能 `pip install "axiolune[research]"` 后，复用上一步的价格表：

```python
close = ax.research.prices(prices, field="close")
average = ax.research.sma(close, window=5)
returns = ax.research.returns(close, periods=1)
print(average.tail())
print(returns.tail())
```

矩阵以日期为行、证券为列；收益率为小数比例，缺失值保持缺失。继续使用 [完整组合教程](https://moonweaveai.org/axiolune/docs/public-workflow)、指标、模型、回测、组合风险和报告手册。研究结果取决于实际输入与明确的交易、费用和时间假设。

## 安装与功能选择

<!-- 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 -->

## 本地输入与持久研究

需要导入文件、快照、本地 SQL 或研究声明时使用 `Client`；一般数据读取仍直接使用领域函数。

```python
import axiolune as ax

with ax.Client(data_root="./research-data") as client:
    result = client.inputs.import_file("prices.csv")
    print(result.to_pandas().head())
```

`prices.csv` 是调用者已有的本地文件。快照与 SQL 使用 `axiolune[local]`。`offline=True` 禁止新网络采集；默认允许读取。客户端的全部参数、预算与生命周期见 [本地客户端](https://moonweaveai.org/axiolune/docs/session-configuration)。团队通过 `ax.team.connect(endpoint, credential)` 接入已有服务。

## 原始来源与升级

发布者特有字段使用 `ax.source.search/describe/fetch/frame`。先读来源合同，再传来源参数；普通行情优先使用股票、基金等领域函数。

0.7 为不兼容重构，旧顶层 Session、fetch/frame、Ticker/download、init/data/catalog/universe/sim 入口已撤下。[迁移说明](https://moonweaveai.org/axiolune/docs/migration)列出对应的新入口。历史观测记录保留其原始日期与 SDK 版本，不当作本版本重新执行的证据。

## 项目与贡献

由 Moonweave AI 维护，文档与公共操作合同随 SDK 一起生成。缺陷与改进请提交到 [项目仓库](https://github.com/Moonweave-AI/axiolune)，提供版本、最小复现、参数和脱敏后的来源错误。不要提交凭据、个人数据或未经允许分发的数据。

包使用 Apache-2.0，见 [LICENSE](LICENSE)。数据来源权利独立于代码许可证，见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
