Metadata-Version: 2.4
Name: arithmion-core
Version: 0.1.0
Summary: Interface tier of the Arithmion agent-native quant platform: contracts, typed data carriers, and the plugin registry.
Author: Arithmion-git
License-Expression: MIT
Project-URL: Homepage, https://arithmion.com
Project-URL: Repository, https://github.com/Arithmion-git/arithmion-core
Keywords: quant,trading,backtesting,framework,plugins,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: loguru>=0.7
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# arithmion-core

The interface tier of [Arithmion](https://arithmion.com), an AI-native
quantitative research and trading platform. This package contains the
contracts the platform is built on: abstract base classes, typed data
carriers, and the entry-point plugin registry. It contains no engine, no
providers, and no agent runtime — those live in the Arithmion product, which
implements these contracts.

**Links** — [arithmion.com](https://arithmion.com) for the product;
[arithmion.com/learn](https://arithmion.com/learn/) for the learning center, a
free bilingual (English / 中文) quant curriculum covering market structure,
statistics, machine learning, and a validation track on multiple testing, PBO
and the deflated Sharpe ratio — also available as markdown in
[quant-learning-path](https://github.com/Arithmion-git/quant-learning-path).

The package installs into the `apexquant` namespace (`import apexquant.core`),
which is the platform's historical package name; the import path is shared
with the full product so that code written against these contracts runs
unchanged in both.

## What is in here

**Data contracts** — the shapes that cross every boundary:

- `bar` / `signals` / `result` / `trade_plan` — OHLCV bars, signal proxies,
  prediction results, trade plans
- `backtest.result` / `backtest.serialize` — the backtest result carrier and
  its canonical JSON wire shape
- `panel` — the cross-sectional factor-panel shape and its OHLCV converters
- `config_schema` — the typed schema plugins use to declare their
  configuration surface
- `model_meta` — the `meta.json` schema describing trained-model artifacts

**Plugin contracts** — subclass one of these, register it via an entry
point, and the platform discovers it:

- `strategy` / `portfolio_strategy` — bar-driven and rebalance-driven
  strategies
- `predictor` — per-bar inference
- `datasource` / `streaming` — bounded (batch) and unbounded (live) data
- `broker` — order routing
- `engine` — the backtest-engine protocol and factory
- `metric` / `validation` — result metrics and trustworthiness validators
- `risk` — risk manager, position sizer, stop policy
- `training` — the trainer contract and the walk-forward window partitioner
- `universe` / `calendar` — point-in-time stock pools and trading calendars

**Mechanism**:

- `registry` / `plugins` — the domain registry and the entry-point scanner
  that performs discovery

## Install

```bash
pip install -e .
```

Requires Python ≥ 3.11. Runtime dependencies are `pandas` and `loguru` only.

## A minimal strategy

```python
from apexquant.core.bar import Bar
from apexquant.core.strategy import BaseStrategy, Signal

class Momentum(BaseStrategy):
    name = "momentum"
    freq = "daily"

    def on_bar(self, bar: Bar) -> Signal:
        if bar.close > bar.open:
            return Signal.BUY
        return Signal.HOLD
```

Third-party packages expose implementations through entry-point groups
(`apexquant.strategies`, `apexquant.datasources`, `apexquant.metrics`, …);
see `plugins.py` for the group inventory and `registry.py` for the domain
registry the scanner populates.

## Stability

Interface versioning follows the platform's roadmap: during v0.x no
interface is frozen, and breaking changes are recorded in `CHANGELOG.md`.
Contracts carry an `__apexquant_api_version__` tuple where versioned.

## Relationship to the main repository

The Arithmion product repository is the source of truth; this repository is
a curated export of its `src/apexquant/core` interface tier
(`scripts/sync_from_apexquant.py` performs the sync and enforces the scope).
Issues and contributions against the contracts are welcome here.

## Why `apexquant` (and `aq`)?

Arithmion grew out of **ApexQuant**, a graduate thesis project on applying
deep time-series learning to stock forecasting and quantitative trading:

- [Applying Deep Time-Series Learning to Stock Forecasting and Quant
  Trading](https://github.com/Heeeeeeliang/Applying-Deep-Time-Series-Learning-to-Stock-Forecasting-and-Quant-Trading)
  — the thesis
- [Apexquant](https://github.com/Heeeeeeliang/Apexquant) — the thesis-era
  codebase this platform descends from

When the project became the Arithmion platform, the brand changed but the
Python package kept its original `apexquant` name — frankly, because
renaming it was not worth the churn: imports, entry-point groups
(`apexquant.strategies`, …), and the `__apexquant_api_version__` markers
would all have had to move for zero functional gain. A convenient side
effect is that thesis-era and current code interoperate as-is. The same
applies to the `aq` shorthand you may see elsewhere in the platform (CSS
tokens, UI prefixes). Wherever you read `apexquant` or `aq`, it means
Arithmion.

## License

MIT — see [LICENSE](LICENSE).

---

## 中文说明

arithmion-core 是 Arithmion（AI 原生量化平台）的接口层：平台赖以构建的
契约——抽象基类、类型化数据载体、以及基于 entry-point 的插件注册机制。
本仓库不包含引擎实现、数据/券商 provider 或 agent 运行时；它们属于实现了
这些契约的 Arithmion 产品本体。

**相关链接**——产品在 [arithmion.com](https://arithmion.com)；学习中心在
[arithmion.com/learn](https://arithmion.com/learn/)：免费的中英双语量化课程，
覆盖市场结构、数理统计、机器学习，以及围绕多重检验、PBO 与 Deflated Sharpe
的验证专线，markdown 版在 [quant-learning-path](https://github.com/Arithmion-git/quant-learning-path)。

包安装在 `apexquant` 命名空间下（`import apexquant.core`），与完整产品共享
导入路径：针对这些契约编写的代码在两侧无需修改即可运行。

安装：`pip install -e .`，要求 Python ≥ 3.11，运行时依赖仅 pandas 与 loguru。

**关于 `apexquant` 与 `aq` 命名**：Arithmion 的前身是毕业设计项目
**ApexQuant**（[论文](https://github.com/Heeeeeeliang/Applying-Deep-Time-Series-Learning-to-Stock-Forecasting-and-Quant-Trading)、
[当时的代码库](https://github.com/Heeeeeeliang/Apexquant)）。品牌更名后
Python 包沿用了原名 `apexquant`——说白了是改名不值得折腾：导入路径、
entry-point 组名、`__apexquant_api_version__` 标记全都得跟着动，却没有
任何功能收益。顺带的好处是论文时期与当前的代码无需迁移即可互通；平台
其它位置的 `aq` 简写同理。代码中的 `apexquant` 与 `aq` 均指 Arithmion。

v0.x 期间接口均不冻结，破坏性变更记录于 `CHANGELOG.md`。许可证为 MIT。
