echolon 0.2.0__tar.gz → 0.3.2__tar.gz

echolon-0.3.2/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.3.0 — AI-Native Layer (unreleased)
+
+### Added
+- `echolon.native` subpackage with error system, validators, CLI, and templates
+- `EchelonError` class hierarchy with 13 initial error codes
+- `echolon` CLI with 5 commands: `validate`, `init-strategy`, `run`, `schema`, `examples`
+- 3 strategy templates: `minimal`, `momentum_breakout`, `rsi_mean_reversion`
+- 3 working examples at `examples/`
+- `llms.txt` at repo root (AI agent entry point)
+- `docs/` directory with QUICK_START, API_REFERENCE, COMPONENT_GUIDE, CONFIG_REFERENCE, PATTERNS, ERROR_CATALOG, and per-error docs
+
+### Changed
+- Added `typer>=0.9.0` as a dependency for the CLI
+
+## 0.2.0 — Config Interface
+
+### Breaking Changes
+- BacktestRunner, OptunaOptimizer, WFARunner, and PortfolioBacktestRunner now require explicit configs
+- Removed module-level globals from `echolon.config.quant_engine`
+
+### Added
+- BacktestConfig, OptunaConfig, IndicatorConfig Pydantic models
+- `TradingContext.from_market()` classmethod
+- `echolon.quick_start()` convenience helper
+
+## 0.1.0 — Initial Release
+
+Initial extraction from DolphinQuantStrategy monorepo.

echolon-0.3.2/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: echolon
+Version: 0.3.2
+Summary: See what others can't. Market-agnostic quantitative trading engine for futures backtesting, optimization, and deployment.
+Project-URL: Homepage, https://github.com/dolphinquant/echolon
+Project-URL: Repository, https://github.com/dolphinquant/echolon
+Author-email: DolphinQuant <contact@dolphinquant.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: CTA,SHFE,backtesting,futures,quantitative-trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: backtrader>=1.9.78
+Requires-Dist: ccxt>=4.0.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: optuna>=3.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pytz>=2023.3
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: ta-lib>=0.4.28
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Echolon
+
+See what others can't.
+
+> Private development repo. Full README with launch content coming before public release.
+
+## Configuration
+
+Echolon exposes typed configuration via Pydantic models. Each component
+receives only the configs it needs.
+
+### Quick start
+
+```python
+import echolon
+
+ctx, bt, opt = echolon.quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2025-12-31",
+)
+
+# Override defaults as needed
+opt.n_trials = 500
+```
+
+### Full API
+
+- `TradingContext` — market, instrument, frequency
+- `BacktestConfig` — dates, paths, thresholds
+- `OptunaConfig` — trials, target, parallelism
+- `WFAConfig` — walk-forward windows
+- `IndicatorConfig` — indicator period caps (defaults usually fine)
+
+### Environment variables
+
+- `ECHOLON_WORKSPACE_DIR` (default `./workspace`) — results, strategy code
+- `ECHOLON_DATA_DIR` (default `./data`) — market data, indicator cache
+- `ECHOLON_LOG_LEVEL` (default `INFO`)
+- `ECHOLON_N_JOBS_DEFAULT` (default `-1`) — Optuna parallelism
+
+## AI-Native Documentation
+
+Echolon is designed for both humans and AI coding agents. See:
+
+- [`llms.txt`](./llms.txt) — AI agent entry point with instructions
+- [`docs/`](./docs/) — structured documentation
+- [`examples/`](./examples/) — working strategies to learn from
+
+## CLI
+
+```bash
+pip install echolon
+echolon init-strategy my_first --template minimal
+echolon validate my_first/
+echolon run my_first/ --instrument cu --start 2020-01-01 --end 2023-12-31
+```

echolon-0.3.2/README.md

@@ -0,0 +1,58 @@
+# Echolon
+
+See what others can't.
+
+> Private development repo. Full README with launch content coming before public release.
+
+## Configuration
+
+Echolon exposes typed configuration via Pydantic models. Each component
+receives only the configs it needs.
+
+### Quick start
+
+```python
+import echolon
+
+ctx, bt, opt = echolon.quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2025-12-31",
+)
+
+# Override defaults as needed
+opt.n_trials = 500
+```
+
+### Full API
+
+- `TradingContext` — market, instrument, frequency
+- `BacktestConfig` — dates, paths, thresholds
+- `OptunaConfig` — trials, target, parallelism
+- `WFAConfig` — walk-forward windows
+- `IndicatorConfig` — indicator period caps (defaults usually fine)
+
+### Environment variables
+
+- `ECHOLON_WORKSPACE_DIR` (default `./workspace`) — results, strategy code
+- `ECHOLON_DATA_DIR` (default `./data`) — market data, indicator cache
+- `ECHOLON_LOG_LEVEL` (default `INFO`)
+- `ECHOLON_N_JOBS_DEFAULT` (default `-1`) — Optuna parallelism
+
+## AI-Native Documentation
+
+Echolon is designed for both humans and AI coding agents. See:
+
+- [`llms.txt`](./llms.txt) — AI agent entry point with instructions
+- [`docs/`](./docs/) — structured documentation
+- [`examples/`](./examples/) — working strategies to learn from
+
+## CLI
+
+```bash
+pip install echolon
+echolon init-strategy my_first --template minimal
+echolon validate my_first/
+echolon run my_first/ --instrument cu --start 2020-01-01 --end 2023-12-31
+```

echolon-0.3.2/docs/API_REFERENCE.md

@@ -0,0 +1,188 @@
+# API Reference
+
+All public Echolon classes and their signatures.
+
+## BacktestConfig
+
+**Module:** `echolon.config.backtest_config`
+
+**Purpose:** Configuration for a single backtest run — dates, paths, thresholds.
+
+**Signature:**
+
+```python
+BacktestConfig(
+    start_date: str,            # "YYYY-MM-DD"
+    end_date: str,              # "YYYY-MM-DD"
+    strategy_dir: Path,
+    market_data_dir: Path,
+    indicator_dir: Path,
+    results_dir: Path,
+    max_drawdown_pct: float = 15.0,
+    is_end_date: Optional[str] = None,
+    oos_start_date: Optional[str] = None,
+    market_research_end_date: Optional[str] = None,
+)
+```
+
+**Example:**
+
+```python
+from echolon import BacktestConfig
+from pathlib import Path
+
+cfg = BacktestConfig(
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+    strategy_dir=Path("./my_strategy"),
+    market_data_dir=Path("./data/market"),
+    indicator_dir=Path("./data/indicators"),
+    results_dir=Path("./results"),
+)
+```
+
+**Common errors:** CFG-001, CFG-002.
+
+## OptunaConfig
+
+**Module:** `echolon.config.optuna_config`
+
+**Purpose:** Optuna hyperparameter optimization settings.
+
+**Signature:**
+
+```python
+OptunaConfig(
+    n_trials: int = 100,
+    n_jobs: int = -1,
+    timeout: Optional[int] = None,
+    target: Literal["sharpe_ratio", "total_return", "annual_return", "drawdown", "multi_objective"] = "sharpe_ratio",
+    n_trials_debug: int = 20,
+    aggressive_memory_management: bool = False,
+    enhanced_monitoring: bool = True,
+)
+```
+
+## IndicatorConfig
+
+**Module:** `echolon.config.indicator_config`
+
+**Purpose:** Technical indicator period caps (most users never override).
+
+**Signature:**
+
+```python
+IndicatorConfig(
+    interday_caps: dict[str, int],
+    intraday_caps: dict[str, int],
+)
+```
+
+## TradingContext
+
+**Module:** `echolon.config.markets.core.context`
+
+**Purpose:** Market + instrument + frequency runtime context.
+
+**Classmethod:**
+
+```python
+TradingContext.from_market(
+    market: str,           # e.g., "shfe"
+    instrument: str,       # e.g., "cu"
+    frequency: str = "interday",
+    bar_size: str = "1d",
+) -> TradingContext
+```
+
+## quick_start()
+
+**Module:** `echolon`
+
+**Purpose:** Build sensible default configs for common cases.
+
+```python
+from echolon import quick_start
+
+ctx, bt, opt = quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+)
+```
+
+## EntrySignalOutput
+
+**Module:** `echolon.quant_engine.types`
+
+**Returned by:** `entry_rule.generate_signal()`
+
+**Required fields:**
+- `signal: Literal['LONG', 'SHORT', 'HOLD']`
+- `strength: float` (0.0 to 1.0)
+- `type: str`
+- `entry_reason: str`
+- `regime: str`
+
+**Optional:**
+- `intent: Optional[OrderIntent]` — required for non-HOLD signals
+
+**Common errors:** VAL-001, VAL-002.
+
+## ExitSignalOutput
+
+**Returned by:** `exit_rule.should_exit()`
+
+**Required fields:**
+- `should_exit: bool`
+- `exit_reason: str`
+- `position_size: float` (≥ 0)
+- `bars_since_entry: int` (≥ 0)
+
+**Optional:**
+- `intent: Optional[OrderIntent]` — required when `should_exit=True`
+
+## RiskOutput
+
+**Returned by:** `risk_manager.can_trade()`
+
+**Required fields:**
+- `trading_allowed: bool`
+- `risk_reason: str`
+
+## SizerOutput
+
+**Returned by:** `position_sizer.calculate_size(signal_data)`
+
+**Required fields:**
+- `calculated_size: int` (≥ 0, whole contracts)
+- `signal_direction: Literal['LONG', 'SHORT', 'HOLD']`
+- `sizing_reason: str`
+- `raw_size: float` (≥ 0)
+
+## OrderIntent (enum)
+
+**Module:** `echolon.quant_engine.core.interfaces.trading_interfaces`
+
+**Values:**
+- `ENTRY_LONG`, `ENTRY_SHORT`
+- `EXIT_LONG`, `EXIT_SHORT`
+- `FORCED_EXIT`
+- `ROLLOVER_CLOSE`, `ROLLOVER_OPEN`
+
+## EchelonError
+
+**Module:** `echolon` (top-level) or `echolon.native.validation.errors`
+
+**Base class** for all Echolon validation errors. Every error has `code`, `what`, `why`, `fix`, `context`, `docs_url`.
+
+**Subclasses:**
+- `ValidationError` (VAL-xxx)
+- `ConfigError` (CFG-xxx)
+- `StrategyStructureError` (STR-xxx)
+- `IndicatorError` (IND-xxx)
+- `ParameterError` (PRM-xxx)
+- `DataError` (DAT-xxx)
+
+See [ERROR_CATALOG.md](ERROR_CATALOG.md).

echolon-0.3.2/docs/COMPONENT_GUIDE.md

@@ -0,0 +1,115 @@
+# Component Guide
+
+Every Echolon strategy has 4 components. This guide explains each one.
+
+## entry_rule (entry.py)
+
+**Class name:** `entry_rule` (exact — required by StrategyLoader)
+**Base:** `BaseComponent`
+**Method:** `generate_signal() -> EntrySignalOutput`
+
+Called every bar when there is no open position and no pending orders.
+
+**Example:**
+
+```python
+from echolon.quant_engine.core.base.base_component import BaseComponent
+from echolon.quant_engine.core.interfaces.trading_interfaces import OrderIntent
+from echolon.quant_engine.types import EntrySignalOutput
+
+
+class entry_rule(BaseComponent):
+    def __init__(self, trading_engine, **params):
+        super().__init__(trading_engine, **params)
+        self.rsi_period = self.params["rsi_period"]
+
+    def generate_signal(self) -> EntrySignalOutput:
+        rsi = self.get_indicator(f"rsi_{self.rsi_period}")
+        regime = self.get_market_regime()
+        if rsi < 30:
+            return EntrySignalOutput(
+                signal="LONG", strength=1.0,
+                type="oversold_entry",
+                entry_reason=f"RSI({self.rsi_period})={rsi} < 30",
+                intent=OrderIntent.ENTRY_LONG,
+                regime=regime,
+            )
+        return EntrySignalOutput(
+            signal="HOLD", strength=0.0, type="hold",
+            entry_reason="Not oversold", regime=regime,
+        )
+```
+
+**Common errors:**
+- VAL-001: missing required field
+- VAL-003: wrong __init__ signature
+- IND-001: uppercase indicator name
+
+## exit_rule (exit.py)
+
+**Class name:** `exit_rule`
+**Base:** `BaseComponent`
+**Method:** `should_exit() -> ExitSignalOutput`
+
+Called every bar when there is an open position.
+
+Stateful exit rules (trailing stops, bars-held counters) must reset their state when there is no position. See the minimal template's `exit.py`.
+
+## risk_manager (risk.py)
+
+**Class name:** `risk_manager`
+**Base:** `BaseComponent`
+**Method:** `can_trade() -> RiskOutput`
+
+Called at the start of every bar. Returns `trading_allowed=True` to permit trading, `False` to block all new entries.
+
+Use cases: max daily loss, max consecutive losses, trading-hours filter.
+
+## position_sizer (sizer.py)
+
+**Class name:** `position_sizer`
+**Base:** `BaseComponent`
+**Method:** `calculate_size(signal_data: EntrySignalOutput) -> SizerOutput`
+
+Called after `entry_rule.generate_signal()` produces a non-HOLD signal. Receives the signal (so sizer can branch on regime, strength, etc.).
+
+The sizer MUST call `self.validate_and_convert_position_size(raw_float)` before setting `calculated_size` — this rounds to whole contracts and handles edge cases.
+
+## Data access helpers
+
+All components inherit these helpers from `BaseComponent`:
+
+- `self.get_current_price() -> float` — close of current bar
+- `self.get_indicator(name: str) -> float` — value of pre-computed indicator (use lowercase names!)
+- `self.get_market_regime() -> str` — one of: `ranging`, `trending_up`, `trending_down`, `volatile`
+- `self.params: dict` — parameters from strategy_params.py
+- `self.portfolio: IPortfolio` — access position info
+- `self.validate_and_convert_position_size(float) -> int` — sizer helper
+
+## Strategy coordinator (strategy.py)
+
+**Class name:** `strategy_main`
+**Base:** `BaseStrategy`
+**Method:** `_execute_bar() -> None` (not `on_bar`)
+
+The canonical pattern:
+
+```python
+def _execute_bar(self) -> None:
+    risk_out = self.risk_manager.can_trade()
+    if not risk_out.trading_allowed:
+        return
+    if self.has_position() and not self.has_pending_orders():
+        exit_out = self.exit_rule.should_exit()
+        if exit_out.should_exit and exit_out.intent is not None:
+            self.exit(exit_out.intent)
+            return
+    if not self.has_position() and not self.has_pending_orders():
+        entry_out = self.entry_rule.generate_signal()
+        if entry_out.signal != "HOLD" and entry_out.intent is not None:
+            sizer_out = self.position_sizer.calculate_size(entry_out)
+            if sizer_out.calculated_size > 0:
+                self.entry(entry_out.intent, sizer_out.calculated_size)
+```
+
+Every bundled template uses this exact pattern. Only customize if your strategy truly needs a different structure.

echolon-0.3.2/docs/CONFIG_REFERENCE.md

@@ -0,0 +1,68 @@
+# Configuration Reference
+
+Echolon uses Pydantic v2 models for all configuration. Each config class is a typed object — IDEs and LLMs can introspect it.
+
+## BacktestConfig
+
+See [API_REFERENCE.md#backtestconfig](API_REFERENCE.md#backtestconfig).
+
+Common mistakes:
+- `end_date` before `start_date` → CFG-001
+- Missing directory path → CFG-002
+
+## OptunaConfig
+
+See [API_REFERENCE.md#optunaconfig](API_REFERENCE.md#optunaconfig).
+
+The `target` field accepts:
+- `"sharpe_ratio"` — maximize risk-adjusted return (default)
+- `"total_return"` — maximize absolute return
+- `"annual_return"` — maximize annualized return
+- `"drawdown"` — minimize max drawdown
+- `"multi_objective"` — Pareto frontier over Sharpe + drawdown
+
+## TradingContext
+
+Runtime context: market, instrument, frequency, bar size.
+
+```python
+from echolon import TradingContext
+
+ctx = TradingContext.from_market(
+    market="shfe",
+    instrument="cu",
+    frequency="interday",
+    bar_size="1d",
+)
+```
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ECHOLON_WORKSPACE_DIR` | `./workspace` | Workspace root |
+| `ECHOLON_DATA_DIR` | `./data` | Market data + indicators |
+| `ECHOLON_LOG_LEVEL` | `INFO` | Logging verbosity |
+| `ECHOLON_N_JOBS_DEFAULT` | `-1` | Default Optuna parallelism |
+
+Set via shell export, `.env` file, or Docker env config.
+
+## quick_start()
+
+For common cases, use the convenience helper:
+
+```python
+from echolon import quick_start
+
+ctx, bt, opt = quick_start(
+    market="shfe",
+    instrument="cu",
+    start_date="2020-01-01",
+    end_date="2023-12-31",
+)
+# Override anything
+opt.n_trials = 500
+bt.max_drawdown_pct = 20.0
+```
+
+`quick_start` uses env vars for paths with fallbacks to `./workspace` and `./data`.

echolon-0.3.2/docs/ERROR_CATALOG.md

@@ -0,0 +1,19 @@
+# Error Catalog
+
+All Echolon errors use stable codes. Click any code for the full fix guide.
+
+| Code | Category | What went wrong |
+|------|----------|-----------------|
+| [VAL-001](errors/VAL-001.md) | Validation | Missing required field in component output |
+| [VAL-002](errors/VAL-002.md) | Validation | Invalid enum value in signal field |
+| [VAL-003](errors/VAL-003.md) | Validation | Component class signature mismatch |
+| [CFG-001](errors/CFG-001.md) | Config | end_date before start_date |
+| [CFG-002](errors/CFG-002.md) | Config | Required directory does not exist |
+| [STR-001](errors/STR-001.md) | Structure | Strategy directory missing required file |
+| [STR-002](errors/STR-002.md) | Structure | Required class not found in file |
+| [STR-003](errors/STR-003.md) | Structure | Required method not implemented |
+| [IND-001](errors/IND-001.md) | Indicator | Indicator name casing mismatch |
+| [IND-002](errors/IND-002.md) | Indicator | Indicator not declared in JSON |
+| [PRM-001](errors/PRM-001.md) | Parameter | Missing 'printlog' key in component params |
+| [PRM-002](errors/PRM-002.md) | Parameter | DEFAULT_PARAMS structure mismatch |
+| [DAT-001](errors/DAT-001.md) | Data | Missing OHLCV file |