echolon
Echolon
LLMエージェントネイティブな先物リサーチ用バックテストフレームワーク。 MCPサーバー、22個のパッケージ内スキル、32個のカタログ化されたエラーコード、型定義されたPydantic設定を提供します。エージェントは、ドキュメントを読んでAPIの形状を推測する代わりに、構造化されたツールを呼び出します。上海先物取引所(SHFE)の日次先物データを用いたエンドツーエンドの分析に対応しています。
DolphinQuantのAIネイティブ戦略生成プロダクトであるQorkaの内部エンジンとして使用されています。毎日、SHFEでの実運用で鍛えられています。
クイックスタート
初心者がたどるべき自然な流れを3つのコマンドでカバーします:
コマンド | 目的 | 時間 |
| クイックデモ。akshare経由でSHFEのアルミニウムデータ(過去2年分)をダウンロードし、戦略をスキャフォールディングしてバックテストを実行します。ネットワーク接続が必要です。 | 約30秒 |
| 本格的なプロジェクトを開始します。akshare経由で市場データをダウンロードし(無料、登録不要)、テンプレートから戦略をスキャフォールディングし、ワークスペースマーカーを作成します。 | 約1〜5分 |
| 編集後の反復作業。ワークスペースマーカーからコンテキストを復元し、インジケーターを再計算してバックテストを実行します。フラグは不要です。 | 約5〜10秒 |
pip install echolon
mkdir -p ~/echolon-playground && cd ~/echolon-playground
echolon hello # 30-second demoecholon helloは、約2年分のアルミニウムデータをダウンロードし、momentum_breakoutテンプレートをスキャフォールディングし、.echolon-workspace.jsonを作成してバックテストを実行します。./echolon-hello/strategy/baseline/entry.pyを開いてパラメータを調整し、echolon backtest single ./echolon-hello/strategy/baseline/を再実行して、シャープレシオの変化を確認してください。
パッケージにはminimal、momentum_breakout、rsi_mean_reversionの3つのテンプレートが含まれています。echolon examples --listで確認でき、echolon init / echolon helloに--template <name>を渡すことで、それらから開始できます。
Linux ARM64 / Alpine / FreeBSDで
pip installが失敗する場合は、echolon doctorを実行してください。標準のプリビルドホイールプラットフォーム(Linux x86_64、macOS x86_64+arm64、Windows x86_64、Python 3.11〜3.12)以外でソースビルドが必要となる唯一の依存関係であるta-libのCライブラリを診断します。
Related MCP server: BotSpot
エージェントからの操作
pip install echolon # 1. install
claude mcp add -s user echolon -- echolon-mcp # 2. register MCP server (user-wide)
# 3. restart Claude Code to load mcp__echolon__* tools次に、以下のように指示を出します:
「銅のトレンドフォロー戦略を構築し、2018年から2024年までバックテストしてください。」
舞台裏では、エージェントがlist_skillsを呼び出し → patternsとquick_startを選択 → load_template("momentum_breakout") → list_indicators(has_lookback=True) → entry.pyとexit.pyを編集 → すべてがパスするまでvalidate_strategy_full(strategy_dir)をループ → バックテストを実行します。何らかのエラーが発生した場合は、トレースバックから[CODE-NNN]を解析し、get_error_doc(code)を呼び出します。推測が必要な場面はありません。
ランタイム | セットアップ |
Claude Code |
|
Cursor |
|
OpenAI Codex CLI |
|
OpenAI Agents SDK (Python) |
|
LangChain / LangGraph |
|
その他のMCP互換クライアント (CrewAI, AutoGen, …) |
|
Claude Codeの場合、-s userを指定するとすべてのプロジェクトで登録が適用されます(現在のプロジェクトのみにする場合は削除してください)。--は登録名と起動コマンドを分離します。一度実行した後、claude mcp listでecholonが接続されたstdioサーバーとして表示されるはずです。エージェント向けのオリエンテーションガイドはllms.txtです。これはecholon init / helloによってワークスペースのルートにも配置されるため、プロジェクトに入ったエージェントはパッケージなしでそれを参照できます。
現在のスコープ
エンドツーエンドで完了済み(本番グレード、毎日運用中):
SHFE日次先物リサーチ — データ取り込み、214個のインジケーターカタログ、Backtrader実行、Optuna TPE最適化(単一および多目的)、デプロイ準備スコアリング付きウォークフォワード分析、KMeansベースの堅牢なトライアル選択。
エージェントインターフェース — 23個のMCPツール、22個のスキル、32個のエラーコード、3個の動作テンプレート。
未対応(機能追加を希望する場合はIssueを作成してください):
SHFE日中バックテスト — データパイプラインは準備済み、エンジン配管を強化中。
MiniQMT経由のライブ取引 — クリーンなパブリックリリースを準備中。
暗号資産パーペチュアル(CCXTアダプターのスケルトンあり)、CME先物、株式。
Optunaの代替(グリッド、ランダム、ベイズ予算探索なし)、分散オーケストレーション、Python ≤ 3.10。
1.0未満 — パブリックAPIはマイナーバージョン間で変更される可能性があります。破壊的変更はCHANGELOG.mdに記載されています。
独自のデータの持ち込み
すでにSHFEの生XLSファイル(shfe.com.cnからダウンロードしたもの)がある場合は、akshareを使用せずにSHFEFileDayExtractorを直接実行してください。その他の形式(ブローカーCSV、tushare、カスタムDB)の場合、以下の3つのファイルが{workspace}/workspace/data/market_data/SHFE/{instrument}/の下に配置されている必要があります:
ファイル | スキーマ |
|
|
| 同じ列、すべての行が連結され、日付順にソートされていること。 |
|
|
さらに、{workspace}/data/SHFE/{instrument_code}/の下に(SHORTコードに注意してください。例:aluminumではなくal):
ファイル | スキーマ |
|
|
Echolonは、生のOHLCVからmain_contract.csvを自動生成しません。これは、ロール慣習(出来高、建玉、または満期までの日数に基づくルール)をエンコードするユーザー入力です。akshare経由のSHFEの場合、echolon initが自動生成しますが、それ以外の場合は自分で作成して配置してください。
プロジェクト情報
Apache 2.0 — LICENSEを参照してください。商用・非商用を問わず自由に使用できます。活発に開発中、v0.1.2ベータ版。SHFEでQorkaを運用しているDolphinQuantチームによって構築・保守されています。Issueやプルリクエストはgithub.com/dolphinquant/echolonで歓迎します。
@software{echolon,
title = {Echolon: AI-native quantitative trading engine},
author = {DolphinQuant},
year = {2026},
url = {https://github.com/dolphinquant/echolon},
}Available Tools
23 toolsdescribe_component_apiA
Return the live BaseComponent + IMarketData API surface.
Use this BEFORE writing any component code. The return value is
produced via ``inspect.signature()`` on the actual classes, so it
always reflects the current echolon version — there is no skill /
doc drift. If a method appears here, it exists; if it doesn't, it
doesn't. Pip-install or editable-install, same answer.
Returns a dict with shape::
{
"BaseComponent": {
"override_methods": [{"name": ..., "signature": ..., "doc": ...}, ...],
"helper_methods": [{...}, ...],
"properties": [{"name": ..., "doc": ...}, ...],
},
"IMarketData": {
"methods": [{"name": ..., "signature": ..., "doc": ...}, ...],
},
}
``override_methods`` are the four BaseComponent stubs each component
file must override (``generate_signal`` / ``should_exit`` /
``can_trade`` / ``calculate_size``). ``helper_methods`` are concrete
helpers strategies may call (``get_current_bar``, ``get_indicator``,
``log_*_output``, etc.). ``properties`` are read-only attribute
accessors (``self.market_data``, ``self.portfolio``, ``self.params``).
``signature`` is the formatted ``inspect.Signature`` (e.g.
``"(self, name: str, index: int = 0) -> float"``). ``doc`` is the
first line of the docstring; full docstrings live on the source.
Inputs: no named parameters.
generate_strategy_paramsA
Generate strategy_params.py from params_to_optimize.json.
Deterministic code generation: parses the JSON → determines parameter
ownership across components → emits ComponentParameterTemplate classes
+ framework registration + optuna_search_space with crossover
constraints → writes the target file. Period parameters that exceed
the frequency-appropriate indicator cap are auto-clamped and reported.
Args:
params_file_path: Absolute path to ``params_to_optimize.json``.
output_path: Absolute path to write ``strategy_params.py``.
frequency: ``"interday"`` (caps: TEMA≤62, ADX≤93, default≤180)
or ``"intraday"`` (caps: TEMA≤500, ADX≤750, default≤1000).
Returns ``{"success": bool, "output_path": str, "corrections":
[{"param", "type", "old_*", "new_*", "cap", "category", "changes"?}],
"message": str}``. Parse / IO failures surface as
``success=False`` rather than raising.
Inputs: params_file_path (required), output_path (required), frequency.
get_docA
Read any markdown file under echolon/native/ and return its body.
Generic fallback for content not covered by the dedicated tools
(``get_pattern``, ``get_skill``, ``get_error_doc``, ``load_template``).
Useful for skill-cross-reference resolution and supplementary files
(``echolon/native/skills/SKILLS.md``,
``echolon/native/errors/codes/README.md``, template READMEs).
Args:
path: Relative path under ``echolon/native/`` (e.g.
``"skills/SKILLS.md"``, ``"errors/codes/README.md"``,
``"templates/minimal/README.md"``). Absolute paths and
paths escaping the package root are refused with
``error="path_outside_native"``.
Returns ``{path, body}`` on success, or
``{error, message, path}`` on failure (path-traversal attempt,
file not found, not a markdown file).
Inputs: path (required). Returns: result
get_error_docA
Fetch the structured error documentation for a given error code.
``what`` and ``why`` come from the in-memory registry
(``echolon.errors.ERROR_CATALOG``); the long-form sections (``fix``,
``example``, ``common_causes``, ``related``) come from the per-code
markdown at ``echolon/native/errors/codes/{code}.md``. The full
markdown body is also returned as ``long_form_markdown`` so an
agent can consume the prose verbatim if the parsed sections are
empty (parser-resilience fallback).
Args:
code: Error code like 'VAL-001' or 'IND-003'.
Inputs: code (required).
get_patternB
Return a pattern's structured content, or None if unknown.
Inputs: name (required). Returns: result
get_skillA
Return one skill's body, or None if unknown.
Returns ``{name, description, body, body_no_frontmatter}``.
``body`` is the full file (including YAML frontmatter); use
``body_no_frontmatter`` for the prose alone.
Inputs: name (required). Returns: result
indicator_infoB
Return structured info for one indicator, or None if unknown.
Keys: ``name``, ``has_lookback``, ``function``, ``file``, ``params``
(list of ``{name, default, type}`` dicts). Column names emitted at
runtime by ``processor._build_suffix`` (handles multi-param sweeps).
Inputs: name (required). Returns: result
indicator_paramsA
Return the tunable parameters for an indicator, or None if unknown.
Convenience accessor — same as ``indicator_info(name)["params"]`` but
skips the wrapper dict. Each entry is ``{"name": str, "default": any, "type": str}``.
Inputs: name (required). Returns: result
list_indicatorsA
Return all indicator names in the echolon catalog, optionally filtered by lookback semantics.
Args:
has_lookback: Optional filter.
``True`` → only indicators with a period-like parameter
(e.g. RSI, ATR — sweepable single-dim lookback).
``False`` → only indicators without a period parameter
(no-param indicators like OBV, multi-param scalar indicators
like BBANDS, special-config indicators).
Omit for all.
Inputs: has_lookback. Returns: result
list_patternsA
Return all canonical pattern names.
Inputs: no named parameters. Returns: result
list_skillsA
Return all in-package skills as [{name, description}].
Each skill is one ``SKILL.md`` packet under
``echolon/native/skills/echolon_api/<name>/``. Description comes
from the YAML frontmatter ``description:`` field. Use this as a
directory of "what doctrine is available" before calling
``get_skill(name)`` for the body.
Inputs: no named parameters. Returns: result
list_templatesA
Return all shipped strategy template names.
Inputs: no named parameters. Returns: result
load_templateC
Load a template's files. Returns {'name': ..., 'files': {filename: content}}.
Inputs: name (required). Returns: result
scaffold_componentA
Write a framework-correct scaffold for a strategy component file.
Produces a minimal stub that matches echolon's loader contract —
class name + method signature + return schema — but contains no
trading logic. Coding agents refine the stub into real pathways.
Args:
kind: One of ``"entry"``, ``"exit"``, ``"risk"``, ``"sizer"``, ``"strategy"``.
strategy_dir: Absolute path to the directory where the file is written.
force: If True, overwrite an existing file. If False (default), refuse
and return ``success=False`` with ``error="file_exists"``.
Returns:
{
"success": bool,
"output_path": str (path to the scaffolded file, if success),
"kind": str (echoes the input),
"error": str | None (one of: "unknown_kind", "file_exists", None),
"message": str (human-readable summary),
}
Inputs: kind (required), strategy_dir (required), force.
suggest_similarA
Return up to limit catalog names close to name (difflib + substring).
Inputs: name (required), limit. Returns: result
validate_component_integrationA
Import each component module via StrategyLoader and check its
method arity + strategy_params.DEFAULT_PARAMS top-level shape.
- STR-002: module fails to import (= guaranteed runtime failure).
- PRM-002: DEFAULT_PARAMS missing a required top-level key, or a
value isn't a dict.
- VAL-005: method's required-positional arity (after ``self``)
doesn't match the protocol. Arg NAMES are not checked — the
framework calls positionally, so names are the author's choice.
Returns ``{"any_errors": bool, "findings": [...]}``.
Inputs: strategy_dir (required).
validate_component_loggingB
AST-check that each component's required method calls the
matching self.log_<component>_output(...) with a BaseModel
instance (not a dict, not a wrong schema).
Also flags ``self.params.get(...)`` anywhere in the file (PRM-004 —
defensive dict-access antipattern on the params container).
Returns ``{"any_errors": bool, "findings": [...]}``.
Inputs: strategy_dir (required).
validate_component_protocol_signaturesA
AST-check that each required component class has the required method with a matching return-type annotation (if annotated at all).
- STR-003: class is missing the required method.
- VAL-006: method declares a return annotation but it doesn't match
the expected BaseModel (EntrySignalOutput / ExitSignalOutput / ...).
Missing annotations are NOT flagged (policy vs correctness — missing
annotation is a stylistic choice, Pydantic catches runtime
mismatches). Missing files are silently skipped (preflight STR-001
territory).
Returns ``{"any_errors": bool, "findings": [...]}``.
Inputs: strategy_dir (required).
validate_debug_completionA
Validate post-run debug artifacts landed on disk with the right shape.
Three deterministic checks:
- STR-001: ``selected_robust_trial.json`` + log file both exist.
- VAL-003: artifact JSON parses and carries every required top-level key.
- BT-010: log contains each required marker substring (order irrelevant).
Args:
artifact_path: Absolute path to the JSON artifact (typically
``<workspace>/backtest/selected_robust_trial.json``).
log_path: Absolute path to the debug log file.
required_json_keys: Top-level keys expected on the artifact.
Defaults to ``["trial_number", "params", "metrics"]``.
required_log_markers: Substrings expected in the log. Defaults
to ``["STAGE 4 COMPLETE", "STAGE 5 COMPLETE", "FINAL SUCCESS"]``.
Returns ``{"any_errors": bool, "findings": [{"code", "message",
"context"}, ...]}``. Never raises — parse / file-access failures
surface as findings with the appropriate error code.
Inputs: artifact_path (required), log_path (required), required_json_keys, required_log_markers.
validate_indicator_listA
Validate a flat-dict strategy_indicator_list.json payload against the catalog.
Args:
payload_json: JSON string of the flat-dict
(e.g. ``'{"rsi": {"timeperiod": [10, 20]}}'``).
Returns a dict ``{"valid": bool, "errors": [{code, field, message, suggestion}]}``.
Bad JSON surfaces as a structured error, not a raise.
Inputs: payload_json (required).
validate_parameter_accessA
AST-check for hardcoded threshold literals (PRM-003) and defensive
self.params.get() calls (PRM-004) across the 4 component files.
Highest FP-risk of the B1 validators — PRM-003 findings include
``context["severity"] = "warning"`` so callers can treat them as
non-blocking while the allowlist is tuned. PRM-004 findings are
always bugs (framework contract violation).
Allowlist covers: range() args, index slicing, keyword args, default
args, None comparisons, small integer constants ``{-1, 0, 1, -1.0, 0.0, 1.0}``,
and string-literal comparisons (framework-defined regime / signal enums).
Returns ``{"any_errors": bool, "findings": [...]}``.
Inputs: strategy_dir (required).
validate_strategyB
Validate a strategy directory against echolon contracts.
Args:
path: Absolute path to the strategy directory.
Returns a dict with keys: status ("VALID"|"INVALID"), errors (list of dicts).
Inputs: path (required).
validate_strategy_fullA
Run every shipped validator and return merged findings.
Composes the individual MCP validators (``validate_strategy`` /
``validate_component_protocol_signatures`` /
``validate_component_integration`` / ``validate_component_logging``
/ ``validate_parameter_access``) so an agent gets a complete
validation report from a single tool call.
Args:
strategy_dir: Absolute path to the strategy directory.
Returns:
``{status, any_errors, total_findings, findings: [{code, ...}],
invocations: [{validator, count}]}``. ``status`` is ``"VALID"``
iff no findings were reported by any validator.
Inputs: strategy_dir (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool has a clearly distinct purpose: API introspection, parameter generation, documentation retrieval, catalog listing, scaffolding, and various validation checks. Overlap among validation tools is resolved by specific validation targets (integration, logging, protocol, parameters, etc.).
Tools follow a mostly consistent verb_noun pattern (e.g., get_doc, list_indicators, validate_strategy). Minor deviations like 'indicator_info' instead of 'get_indicator_info' and 'suggest_similar' instead of 'get_suggestions' are tolerable.
23 tools cover a comprehensive set of operations for a strategy framework: API description, parameter generation, documentation, catalog browsing, scaffolding, and multiple validation checks. The count is well-scoped for the domain.
The tool surface covers key development and validation workflows. Minor gaps exist (e.g., no tool for creating a new strategy directory or running backtests), but the core lifecycle of building and validating components is well-supported.
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn extensible framework that exposes quantitative research functions and financial data connectors, such as FRED, via an MCP server. It enables users to perform complex financial modelling, data retrieval, and autonomous research loops with built-in guardrails and pluggable components.64MIT
- FlicenseNot gradedqualityBmaintenanceFull-lifecycle algorithmic trading MCP server. AI strategy generation from plain English, backtesting, live bot deployment to 10+ brokers, portfolio monitoring, and prediction markets. Stocks, options, crypto, futures. 32 tools. Free tier.-
- AlicenseNot gradedqualityDmaintenanceLocal-first backtesting engine with built-in overfitting detection (PBO, deflated Sharpe, bootstrap CI, walk-forward) and a native MCP server for AI agents to validate trading strategies.4Apache 2.0
- AlicenseAqualityBmaintenanceMCP server for the FLOX trading framework. About 30 tools to run backtests, scaffold strategies, validate for lookahead bias, compute indicators, place orders, and query PnL from Claude/Cursor.38945 PyPI231MIT