Metadata-Version: 2.5
Name: axiolune
Version: 0.8.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: numpy<3,>=2
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: 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'
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)、指标、模型、回测、组合风险和报告手册。研究结果取决于实际输入与明确的交易、费用和时间假设。

## 投资分析指标与交互图表 / Investment indicators and interactive charts

统一指标入口接受行情长表或具有明确单位的逐行分析输入，返回保留原列、追加具名结果列的 pandas 表。除行情、趋势、动量、量能、波动、统计、周期与蜡烛结构，还覆盖基金基准、组合币种、期货持有成本、财务与REIT、债券现金流及期权模型。目录按资产类型与用途筛选；函数与参数以 `ax.indicators.catalog()` 为准，形态规则与可选 TA-Lib 后端分别统计。

The unified indicator interface accepts long-form market observations or explicit-unit row inputs and appends named outputs. In addition to price, trend, momentum, volume, volatility, statistics, cycles and candle structure, it covers fund benchmarks, currency portfolios, futures carry, financials and REITs, bond cashflows and option models. Filter discovery by asset and purpose with `ax.indicators.catalog()`; candle rules and optional TA-Lib functions are counted separately.

```python
prices = ax.stock.history("600519.SH", start="2024-01-01", end="2024-12-31")
result = ax.indicators.compute(prices, indicators={
    "sma20": {"name": "sma", "window": 20},
    "macd": {"name": "macd"},
})
print(result[["date", "close", "sma20", "macd_histogram"]].tail())

chart = ax.plot.technical(prices, theme="light", locale="zh")
chart.show()
chart.to_html("technical.html")

# 复用已计算结果，不重复计算指标 / Plot retained results without recomputation
single = ax.plot.indicator(result, name="macd", theme="light", locale="zh")
single.to_html("macd.html")
single.to_csv("macd.csv")
```

绘图选择 `axiolune[plot]`。`returns` 返回小数比例，`roc` 返回百分数，`momentum` 返回价格差。成交量只在来源单位有依据时提供；检查 `volume_unit` 和 `volume_status`。窗口初始不足及必需输入缺失保留空值，递归指标重新预热。

`outputs=("roa", "roe")` 等结果选择会收敛到实际需要的输入；不必为未选择的 ROIC 填造 NOPAT。`describe(name, **parameters)`、单项调用与 `compute` 使用同一合同。资产适用性不代表来源覆盖，报表期间、币种/数量级、基准对齐与模型情景必须明确；真实观察与分析参数在每项示例中分别标注。

Result selections such as `outputs=("roa", "roe")` require only their actual inputs, without inventing NOPAT for an unselected ROIC. Parameterized `describe`, individual calls and `compute` share one contract. Asset applicability does not promise source coverage: declare reporting periods, currency/scales, benchmark alignment and model scenarios. Examples distinguish observed facts from analytical assumptions.

Choose `axiolune[plot]` for charts. `returns` is fractional, `roc` is percentage-scaled and `momentum` is a price difference. Check established volume units and warm-up gaps before interpretation.

`ax.plot.indicator` 按输出单位组织单项图形；时间序列使用日期轴，逐行模型保持真实观察点，不把单点伪成历史。风险预算、因子分解、利率曲线、信用及期权分析使用同一指标合同。依赖 SciPy 的模型安装 `axiolune[research]`，绘图与研究合用可安装 `axiolune[research,plot]`；每项的 `describe(...)["optional_dependency"]` 和独立参考页说明实际要求。

`ax.plot.indicator` organizes individual results by unit, retaining date axes for series and actual observation points for row models. Risk budgets, factor decomposition, rate curves, credit and option analysis share the same indicator contract. Install `axiolune[research]` for models requiring SciPy, or `axiolune[research,plot]` for both research and charts; inspect each function's `optional_dependency` and reference page for its requirements.

[指标目录与逐项真实结果](https://moonweaveai.org/axiolune/docs/indicators) · [English indicator reference](https://moonweaveai.org/axiolune/en/docs/indicators) · [真实交互图册](https://moonweaveai.org/axiolune/docs/technical-charts) · [组合计算与研究](https://moonweaveai.org/axiolune/docs/indicator-batch)

## 安装与功能选择

<!-- generated-install:start -->
产品版本 / Product version: **0.8.0**。

安装命令使用你所选索引与环境约束允许的已发布版本；当前发行状态请查看[安装文档](https://moonweaveai.org/axiolune/docs/installation)。
Installation selects a published release allowed by your index and environment constraints. See the [installation documentation](https://moonweaveai.org/axiolune/en/docs/installation) for current release status.

```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]"
uv add "axiolune[documents,ocr]"
```

可同时选择多个 extras，其下层依赖自动包含。常规取数与连接现有团队服务包含在基础安装；all 仅用于需要全部可选依赖的环境。
Select multiple extras; their dependencies are included automatically. Routine data retrieval and connections to existing team services belong to the core installation. Choose all only when every optional dependency is needed.

| 能力 | 用途 | 自动包含的能力 |
|---|---|---|
| `source-crypto` | 需要加密能力的数据来源适配。 | — |
| `local` | 本地快照、DuckDB SQL 与 Polars 表格计算。 | — |
| `research` | 指标、筛选、回测、风险和组合研究。 | `local`, `financial` |
| `plot` | 交互图表与可导出的 HTML 报告。 | — |
| `sql` | 连接外部 SQL 数据库与读取查询结果。 | — |
| `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 流式数据来源。 | — |
| `financial` | 财报合同、财务计算与公司研究。 | — |
| `all` | 安装所有可选依赖；适合确实使用全部能力的环境。 | `source-crypto`, `local`, `research`, `plot`, `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)` 接入已有服务。

## 原始来源与 API 指引

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

[公共 API 目录](https://moonweaveai.org/axiolune/docs/public-api)按任务列出当前入口、完整参数与返回字段；使用 `ax.search()`、`ax.describe()` 与 `ax.help()` 在本地查阅同一合同。历史观测记录保留其原始日期与 SDK 版本，不当作本版本重新执行的证据。

## 项目与贡献

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

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