Skip to main content
Glama

Echolon

PyPI Python License Status By DolphinQuant

📖 Englisch · 简体中文

Ein LLM-Agent-natives Backtest-Framework für die Futures-Forschung. Enthält einen MCP-Server, 22 integrierte Skills, 32 katalogisierte Fehlercodes und typisierte Pydantic-Konfigurationen – Agenten rufen strukturierte Tools auf, anstatt API-Formen aus Prosatexten zu erraten. End-to-End für tägliche SHFE-Futures.

Produktions-Engine innerhalb von Qorka, dem KI-nativen Strategiegenerierungsprodukt von DolphinQuant. Wird jeden Handelstag mit echtem Geld an der SHFE eingesetzt.

Schnellstart

Drei Befehle decken den natürlichen Einstieg ab:

Befehl

Zweck

Zeit

echolon hello

Kurze Demo. Lädt SHFE-Aluminium (letzte 2 Jahre) über akshare herunter, erstellt ein Strategie-Gerüst und führt einen Backtest durch. Netzwerk erforderlich.

~30s

echolon init <workspace> --market SHFE --instrument <i> --start <d> --end <d> --template <t>

Startet ein echtes Projekt. Lädt Marktdaten über akshare herunter (kostenlos, keine Registrierung), erstellt ein Strategie-Gerüst aus einer Vorlage und schreibt eine Workspace-Markierung.

~1–5 Min

echolon backtest single <strategy_dir> [--json]

Iteration nach der Bearbeitung. Navigiert nach oben, um den Kontext aus der Workspace-Markierung wiederherzustellen, berechnet Indikatoren neu und führt den Backtest durch. Keine Flags erforderlich.

~5–10s

pip install echolon
mkdir -p ~/echolon-playground && cd ~/echolon-playground
echolon hello                  # 30-second demo

echolon hello lädt ca. 2 Jahre Aluminiumdaten herunter, erstellt das momentum_breakout-Gerüst, schreibt .echolon-workspace.json und führt den Backtest aus. Öffnen Sie ./echolon-hello/strategy/baseline/entry.py, passen Sie einen Parameter an und führen Sie dann echolon backtest single ./echolon-hello/strategy/baseline/ erneut aus, um zu sehen, wie sich die Sharpe-Ratio verändert.

Drei Vorlagen sind im Paket enthalten — minimal, momentum_breakout, rsi_mean_reversion. echolon examples --list zeigt diese an; übergeben Sie --template <name> an echolon init / echolon hello, um mit einer davon zu beginnen.

Falls pip install fehlschlägt unter Linux ARM64 / Alpine / FreeBSD, führen Sie echolon doctor aus — es diagnostiziert die C-Bibliothek von ta-lib, die einzige Abhängigkeit, die möglicherweise außerhalb der standardmäßigen vorgefertigten Wheel-Plattformen (Linux x86_64, macOS x86_64+arm64, Windows x86_64; Python 3.11–3.12) aus dem Quellcode erstellt werden muss.

Related MCP server: BotSpot

Steuerung durch Ihren Agenten

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

Fragen Sie dann:

"Erstelle eine Trendfolge-Strategie für Kupfer, Backtest 2018–2024."

Hinter den Kulissen ruft der Agent list_skills auf → wählt patterns und quick_start → load_template("momentum_breakout") → list_indicators(has_lookback=True) → bearbeitet entry.py und exit.py → durchläuft validate_strategy_full(strategy_dir), bis alles erfolgreich ist → führt den Backtest aus. Wenn etwas fehlschlägt, analysiert er [CODE-NNN] aus dem Traceback und ruft get_error_doc(code) auf. Es gibt keinen Punkt, an dem er raten muss.

Laufzeit

Einrichtung

Claude Code

claude mcp add -s user echolon -- echolon-mcp

Cursor

Fügen Sie in ~/.cursor/mcp.json einen Eintrag unter mcpServers hinzu: "echolon": {"command": "echolon-mcp", "args": []}

OpenAI Codex CLI

codex mcp add echolon -- echolon-mcp (schreibt [mcp_servers.echolon] in ~/.codex/config.toml)

OpenAI Agents SDK (Python)

MCPServerStdio(name="echolon", params={"command": "echolon-mcp", "args": []})

LangChain / LangGraph

langchain-mcp-adapters: MultiServerMCPClient({"echolon": {"transport": "stdio", "command": "echolon-mcp", "args": []}})

Jeder andere MCP-kompatible Client (CrewAI, AutoGen, …)

Konfigurieren Sie ihn als stdio-Server mit command="echolon-mcp", keine Argumente. Siehe die MCP-Dokumentation Ihres Clients für das Aufrufformat.

Für Claude Code: -s user sorgt dafür, dass die Registrierung für alle Ihre Projekte gilt (lassen Sie es weg, wenn es nur für das aktuelle Projekt gelten soll); -- trennt den Registrierungsnamen vom Startbefehl. Nach einmaligem Ausführen sollte claude mcp list echolon als verbundenen stdio-Server anzeigen. Der Orientierungsleitfaden für den Agenten ist llms.txt — er wird auch von echolon init / hello im Workspace-Stammverzeichnis abgelegt, sodass ein Agent, der das Projekt betritt, ihn findet, ohne das Paket zu benötigen.

Was heute im Umfang enthalten ist

End-to-End fertiggestellt (produktionsreif, täglich im Einsatz):

  • SHFE tägliche Futures-Forschung — Datenerfassung, Katalog mit 214 Indikatoren, Backtrader-Ausführung, Optuna TPE-Optimierung (Einzel- + Mehrzieloptimierung), Walk-Forward-Analyse mit Scoring für die Einsatzbereitschaft, KMeans-basierte robuste Auswahl von Testläufen.

  • Agenten-Oberfläche — 23 MCP-Tools, 22 Skills, 32 Fehlercodes, 3 funktionierende Vorlagen.

Noch nicht enthalten (eröffnen Sie ein Issue, wenn Sie einen Bereich vorantreiben möchten):

  • SHFE Intraday-Backtesting — Daten-Pipeline bereit, Engine-Infrastruktur wird derzeit gefestigt.

  • Live-Handel über MiniQMT — saubere öffentliche Veröffentlichung in Arbeit.

  • Krypto-Perpetuals (CCXT-Adapter-Gerüst vorhanden), CME-Futures, Aktien.

  • Optuna-Alternativen (kein Grid, kein Random, keine Bayesian-Budget-Suche), verteilte Orchestrierung, Python ≤ 3.10.

  • Vor 1.0 — öffentliche API kann sich zwischen Nebenversionen ändern. Breaking Changes sind in CHANGELOG.md dokumentiert.

Bringen Sie Ihre eigenen Daten mit

Wenn Sie bereits rohe SHFE-XLS-Dateien haben (heruntergeladen von shfe.com.cn), führen Sie SHFEFileDayExtractor direkt aus, anstatt akshare zu verwenden. Für andere Formate (Broker-CSV, Tushare, benutzerdefinierte DB) müssen drei Dateien unter {workspace}/workspace/data/market_data/SHFE/{instrument}/ landen:

Datei

Schema

sort_by_contract/{contract}.csv

contract, date, prev_close, prev_settlement, open, high, low, close, settlement, price_change, settlement_change, volume, turnover, open_interest

sort_by_date.csv

Gleiche Spalten, alle Zeilen verkettet und nach Datum sortiert.

trading_calendar.csv

date, is_trading_day (boolean).

Zusätzlich unter {workspace}/data/SHFE/{instrument_code}/ (beachten Sie den KURZ-Code, z. B. al nicht aluminum):

Datei

Schema

main_contract.csv

date, main_contract wobei main_contract der Vertragscode mit .SF-Suffix ist (z. B. al2401.SF). Eine Zeile pro Datum des Wechsels des Hauptkontrakts.

Echolon leitet main_contract.csv nicht automatisch aus rohen OHLCV-Daten ab — es ist eine BENUTZEREINGABE, die Ihre Roll-Konvention kodiert (Regeln basierend auf Volumen, Open Interest oder Tagen bis zum Verfall). Für SHFE via akshare leitet echolon init dies für Sie ab; andernfalls erstellen Sie es selbst und legen Sie es ab.

Projektinformationen

Apache 2.0 — siehe LICENSE. Frei verwendbar, kommerziell oder anderweitig. Aktive Entwicklung, v0.1.2 Beta. Erstellt und gewartet von DolphinQuant — demselben Team, das Qorka auf der SHFE betreibt. Issues und Pull Requests sind willkommen unter 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 tools
describe_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

    A3.7/5.0

    Scored across 23 tools

    Disambiguation5/5

    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.).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      6
      4
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Full-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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local-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.
      4
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      38
      945 PyPI
      231
      MIT