AxonX Development and Operations Guide

This guide teaches an agent how to work with AxonX, a harness framework for financial quantitative research. AxonX organizes data acquisition and ETL, factor analysis, model training, prediction, and backtesting into Tasks that share consistent input and output contracts. Plugins register the research implementations, and Tasks link upstream to downstream work through Task IDs. The guide covers two jobs: developing or modifying research plugins with typed Task contracts, and operating an AxonX service by submitting Tasks, tracking runs, reading logs, and inspecting artifacts.

For plugin development it spells out the authoring contract. Every plugin Task must inherit from BaseTask, declare a fixed task_type, input_cls and output_cls, and carry a detailed class docstring, because a missing docstring raises a TypeError during Task resolution. Tasks implement build_task_steps() to yield synchronous callables in order and build_output_params() to return a validated instance of the declared output class. For ETL, Analysis, Train, Predict and Backtest stages, optional BaseTask, BaseInputParams and Base*OutputParams classes are provided, and once you adopt them their required fields and validators become part of your contract. The guide walks through registering a Task in plugin.yaml, declaring the entry point in pyproject.toml, and installing the plugin.

For operations it documents the CLI and the matching MCP tools: starting a local service, submitting Tasks, waiting on a specific run, streaming progress, reading logs, fetching the dependency graph, previewing CSV or Parquet artifacts, and managing plugins and remote machines.

Use it when you are developing or modifying AxonX research plugins and their typed Task contracts, when a user asks you to submit an AxonX research task, track its execution, investigate a failure, or inspect artifacts, or when you are integrating an external agent with an existing AxonX MCP service.

Do not treat the command examples as authorization. The guide is labeled critical because it documents package installation, task submission, remote shell execution, cancellation, deletion, and artifact replacement. Establish the exact service, workspace and scope of any destructive operation first, ask for clarification when the target is unclear, and perform only what the request requires. Never expose service or data-provider tokens in reports, logs, or committed files, and back up irreplaceable artifacts before an authorized replacement or deletion. The guide alone does not deploy a service, and it does not supply research plugins, market data, or model configuration.

Inputs are the user's requested operation, the address and authentication of the target AxonX service, and registered Task names and Task IDs. The CLI maps flag names onto input fields, so --start-date becomes start_date on the input class, and undeclared fields are rejected. Downstream Tasks take successful upstream Task IDs through --source-tasks. A submission returns task_id, run_id and task in its answer, and you should record the actual IDs rather than guess them. A successful submission only means execution was accepted, so inspect state, result, error, exit_code and log_path from status, wait_task or stream_task. Continue waiting while the state is queued or running, and submit downstream work only after succeeded.

Outputs are plugin code, registered Tasks, and artifacts written to the workspace, with metadata at workspace///metadata.json. An ETL output must include output_file, rows and date_range. The guide gives one verbatim registration example:

tasks:
  a158_etl: axonx_alpha158.etl:Alpha158Task

The guide works with the AxonX CLI and HTTP service, and with MCP clients that connect over Streamable HTTP using a Bearer token header; tools should be discovered from the connected service rather than assumed. Market-data downloads require the AXONX_TUSHARE_TOKEN variable, and model-backed agents need separate model configuration. The built-in demo Task verifies submission and tracking without market-data or model credentials. Remote execution targets are found with list_machines and machine_status, and the Alpha158 example plugin shows an ETL to Train to Predict to Backtest chain with Analysis reading ETL data. Local execution needs Python 3.12 or newer on macOS or Linux.

Quantitative researchers and plugin authors who build factor, training and backtest workflows on AxonX, and teams whose agents need to submit, monitor and debug those runs. Backtest results do not establish future investment performance, so costs and data assumptions should be compared before interpreting them.