arithmion-core 0.1.0__tar.gz

arithmion_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Arithmion-git
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arithmion_core-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+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。

arithmion_core-0.1.0/README.md

@@ -0,0 +1,148 @@
+# 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。

arithmion_core-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arithmion-core"
+version = "0.1.0"
+description = "Interface tier of the Arithmion agent-native quant platform: contracts, typed data carriers, and the plugin registry."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Arithmion-git" }]
+requires-python = ">=3.11"
+dependencies = [
+    "pandas>=2.0",
+    "loguru>=0.7",
+]
+keywords = ["quant", "trading", "backtesting", "framework", "plugins", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://arithmion.com"
+Repository = "https://github.com/Arithmion-git/arithmion-core"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["apexquant*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"apexquant.core" = ["py.typed"]

arithmion_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

arithmion_core-0.1.0/src/apexquant/core/__init__.py

@@ -0,0 +1,6 @@
+"""apexquant.core — interface contracts, registry, and plugin discovery.
+
+The *interface tier*: minimal
+dependencies, no provider-specific code. Concrete provider implementations
+live under ``apexquant.bundled`` (Phase 1.6).
+"""

arithmion_core-0.1.0/src/apexquant/core/backtest/__init__.py

@@ -0,0 +1,17 @@
+"""apexquant.core.backtest — backtest RESULT contracts (contracts-only export).
+
+This repo ships the result carrier and its canonical JSON wire shape only.
+The engine implementations (``BacktestEngine``, the portfolio engine) live in
+the full Arithmion product, which satisfies these contracts; any engine that
+produces a :class:`BacktestResult` interoperates with tooling built on them.
+
+NOTE (sync): this ``__init__`` is OWNED BY THIS REPO — the main repo's
+counterpart also re-exports the engine implementation. See
+``scripts/sync_from_apexquant.py`` OVERRIDES.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CASH_TICKER", "BacktestResult", "CashFlowEvent"]
+
+from apexquant.core.backtest.result import CASH_TICKER, BacktestResult, CashFlowEvent

arithmion_core-0.1.0/src/apexquant/core/backtest/result.py

@@ -0,0 +1,192 @@
+"""Backtest result carrier (Phase E1 — relocated from ``backtest/engine.py``).
+
+``BacktestResult`` is the structurally-identical successor to the
+``BacktestResult`` defined in both legacy engines (``backtest/engine.py`` and
+``backtest/_legacy.py``).  It carries trades, the equity curve, headline
+metrics (populated by :func:`backtest.metrics.compute_metrics`), and run
+metadata.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CASH_TICKER", "BacktestResult", "CashFlowEvent"]
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from apexquant.core.strategy import Trade
+
+#: Reserved pseudo-ticker for the uninvested cash sleeve in ``weights_curve``.
+#: Cash is carried EXPLICITLY rather than derived as ``1 - sum(weights)`` so an
+#: all-cash date survives serialization: a date whose weights dict is empty
+#: would otherwise vanish from the long-table CSV entirely, and the consumer
+#: could not tell "flat that day" from "no data that day". The ``$`` prefix
+#: keeps it out of any real ticker namespace.
+CASH_TICKER = "$CASH"
+
+
+@dataclass
+class CashFlowEvent:
+    """One external cash injection/withdrawal during a backtest.
+
+    Distinct from trading P&L -- this is money that entered or left the
+    account from OUTSIDE the strategy's own decisions (a deposit, a
+    withdrawal, a scheduled contribution). ``metrics.compute_metrics``
+    reads a list of these to compute TWR/MWR without ever needing to know
+    WHY the flow happened.
+
+    Attributes:
+        timestamp: When the cash flow occurred (the bar timestamp it was
+            applied on).
+        amount: Positive = contribution/deposit, negative = withdrawal.
+    """
+
+    timestamp: datetime
+    amount: float  # positive = contribution/deposit, negative = withdrawal
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-native projection (round-trips via :meth:`from_dict`).
+
+        Follows the same ISO-timestamp convention as :meth:`Trade.to_dict`.
+        """
+        return {
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+            "amount": self.amount,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> CashFlowEvent:
+        """Reconstruct a :class:`CashFlowEvent` from :meth:`to_dict` output."""
+        return cls(
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+            amount=d.get("amount", 0.0),
+        )
+
+
+@dataclass
+class BacktestResult:
+    """Container for backtest output.
+
+    Attributes:
+        trades: All closed trades.
+        equity_curve: Portfolio value over time.
+        metrics: Performance metrics (populated by
+            :func:`backtest.metrics.compute_metrics`).
+        strategy_name: Name of the strategy that was tested — comes from the
+            strategy's own ``Strategy.name`` class attribute, so it need NOT
+            match the id the caller submitted (e.g. a user-authored workspace
+            strategy can set any ``name`` it likes). Kept for display/grouping;
+            do not use it to look the run back up in the strategy workspace.
+        start_date: First bar timestamp.
+        end_date: Last bar timestamp.
+        config_snapshot: Frozen copy of the config used.
+        strategy_id: The strategy-workspace id (or built-in type name, e.g.
+            ``"ai"``/``"technical"``) the caller actually submitted, captured
+            *before* ``_resolve_strategy`` rewrites it to an on-disk path.
+            ``None`` when the run has no such association (e.g. produced by a
+            legacy run predating this field, or a CLI/script invocation that
+            never went through the workspace-aware submission routes). Unlike
+            ``strategy_name``, this is reliable for looking the run back up in
+            the strategy workspace.
+        weights_curve: Per-date portfolio composition as
+            ``[(timestamp, {ticker: weight})]``, weights being **signed**
+            fractions of total equity (short exposure is negative) that sum to
+            1 including the :data:`CASH_TICKER` sleeve. **Experimental.**
+            Populated by portfolio mode (per rebalance mark) and by the
+            default event engine in mark-to-market mode (sampled once per
+            calendar day); left empty in stepped equity mode, which has no
+            marks to compose from. Every consumer must treat "empty" as a
+            normal case and degrade rather than assume composition data exists.
+        cash_flow_events: External cash injections/withdrawals applied during
+            the run, e.g. scheduled contributions or a one-off
+            deposit/withdrawal. Empty for every run that didn't configure
+            ``backtest.contributions`` -- additive field, default ``[]``, so
+            existing callers that don't know about it are unaffected.
+    """
+
+    trades: list[Trade] = field(default_factory=list)
+    equity_curve: pd.Series = field(default_factory=lambda: pd.Series(dtype=float))
+    metrics: dict[str, Any] = field(default_factory=dict)
+    strategy_name: str = ""
+    start_date: datetime | None = None
+    end_date: datetime | None = None
+    config_snapshot: dict[str, Any] = field(default_factory=dict)
+    strategy_id: str | None = None
+    weights_curve: list[tuple[Any, dict[str, float]]] = field(default_factory=list)
+    cash_flow_events: list[CashFlowEvent] = field(default_factory=list)
+
+    def summary(self) -> dict[str, Any]:
+        """Return a summary dict of key fields.
+
+        Returns:
+            Dict with strategy name, trade count, date range, and metrics.
+        """
+        return {
+            "strategy": self.strategy_name,
+            "trades": len(self.trades),
+            "start": self.start_date,
+            "end": self.end_date,
+            **self.metrics,
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-native projection (round-trips via :meth:`from_dict`).
+
+        Trades use :meth:`Trade.to_dict`; the equity curve becomes a list of
+        ``[iso_timestamp, value]`` pairs; datetimes become ISO strings. Makes the
+        backtest-output contract serializable end to end (agent / API / SaaS).
+        """
+        eq: list[list[Any]] = []
+        for ts, val in self.equity_curve.items():
+            key = ts.isoformat() if hasattr(ts, "isoformat") else str(ts)
+            eq.append([key, float(val)])
+        wt: list[list[Any]] = []
+        for ts, weights in self.weights_curve:
+            key = ts.isoformat() if hasattr(ts, "isoformat") else str(ts)
+            wt.append([key, {t: float(w) for t, w in weights.items()}])
+        return {
+            "trades": [t.to_dict() for t in self.trades],
+            "equity_curve": eq,
+            "weights_curve": wt,
+            "metrics": self.metrics,
+            "strategy_name": self.strategy_name,
+            "start_date": self.start_date.isoformat() if self.start_date else None,
+            "end_date": self.end_date.isoformat() if self.end_date else None,
+            "config_snapshot": self.config_snapshot,
+            "strategy_id": self.strategy_id,
+            "cash_flow_events": [cfe.to_dict() for cfe in self.cash_flow_events],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> BacktestResult:
+        """Reconstruct a :class:`BacktestResult` from :meth:`to_dict` output."""
+        from apexquant.core.strategy import Trade
+
+        pairs = d.get("equity_curve") or []
+        index = pd.DatetimeIndex([pd.Timestamp(p[0]) for p in pairs]) if pairs else None
+        values = [float(p[1]) for p in pairs]
+        equity = pd.Series(values, index=index, dtype=float)
+        weights_curve = [
+            (pd.Timestamp(p[0]), {str(t): float(w) for t, w in (p[1] or {}).items()})
+            for p in (d.get("weights_curve") or [])
+        ]
+        start = d.get("start_date")
+        end = d.get("end_date")
+        return cls(
+            trades=[Trade.from_dict(t) for t in d.get("trades", [])],
+            equity_curve=equity,
+            metrics=dict(d.get("metrics") or {}),
+            strategy_name=d.get("strategy_name", ""),
+            start_date=datetime.fromisoformat(start) if start else None,
+            end_date=datetime.fromisoformat(end) if end else None,
+            config_snapshot=dict(d.get("config_snapshot") or {}),
+            strategy_id=d.get("strategy_id"),
+            weights_curve=weights_curve,
+            cash_flow_events=[
+                CashFlowEvent.from_dict(cfe) for cfe in d.get("cash_flow_events") or []
+            ],
+        )