Axonx

AxonX Development and Operations Guide

This guide can be read independently or installed as an Agent skill. Documentation and source links use absolute URLs, so copying this file does not depend on its original directory. The maintained project is FlowLLM-AI/AxonX.

Source paths such as plugins/a158/... are relative to the root of an AxonX source checkout, not to this document or the Agent workspace. Run source development and plugin build commands from that checkout. Workspace paths passed to Jobs such as preview_file are relative to the selected service's workspace. Package installation alone does not provide the example plugin sources.

When to Use This Skill

• Use when developing or modifying AxonX research plugins and their typed Task contracts.
• Use when a user requests AxonX research task submission, execution tracking, failure investigation, or artifact inspection.
• Use when integrating an external Agent with an existing AxonX MCP service.

Security & Safety Notes

This skill is labeled critical because it documents package installation, task submission, remote shell execution, cancellation, deletion, and artifact replacement. Establish the user's requested operation and exact service/workspace first. Do not treat command examples as authorization. Request clarification when the execution target or the scope of a destructive operation is unclear; existing explicit authorization remains valid. Never expose service or data-provider tokens in reports, logs, or committed files. Back up irreplaceable artifacts before authorized replacement or deletion.

Prepare the Environment and Service

Use Python 3.12+ on macOS or Linux for local Task execution. In your chosen working directory, create and activate a virtual environment, then install the core:

python3 -m venv .venv
source .venv/bin/activate
pip install axonx
axonx help

For the prebuilt Studio UI, install axonx[studio] instead. Research plugins are installed separately. For source development, clone the project, enter its root, and install it in an activated virtual environment:

git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e .

Configure credentials through environment variables or a .env file discovered from the process working directory or its parents. Before starting a local service, replace the token placeholder with your own value:

export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
axonx start --service.host 127.0.0.1

Keep that process running. In another terminal, activate the same environment and configure the same token, then run axonx version to verify the connection. The default port is 1024; the default workspace is .axonx under the startup directory. If using an existing service, obtain its address and authentication configuration before making calls. Keep one execution target for plugin queries, submissions, status, logs, and artifact inspection.

For MCP clients, connect to http://127.0.0.1:1024/mcp using Streamable HTTP and the header Authorization: Bearer <service-token>; replace the address and token with those of your service. Discover tools from the connected service rather than assuming a fixed tool catalog. The CLI examples below describe the same operations; use the discovered MCP input schemas when calling tools.

The built-in demo Task can verify submission and tracking without market-data or model credentials; the Alpha158 workflow requires its research plugin and prepared input data. Market-data downloads require AXONX_TUSHARE_TOKEN; model-backed Agents require separate model configuration. See Quick start, Research workflow, and MCP integration for complete setup examples.

When using this document as a skill, perform only the operations required by the user's request. Documentation examples do not authorize installation, task execution, deletion, or remote changes by themselves. For changes to the source checkout, follow its AGENTS.md and contribution guide.

Background

AxonX is a harness framework for financial quantitative research, organizing data acquisition and ETL, factor analysis, model training, prediction, and backtesting into Tasks with consistent input/output contracts. Plugins register research implementations; Tasks link upstream and downstream work through Task IDs. The CLI and HTTP service support submitting execution on local or remote machines and querying machine resources, runtime status, and logs. The framework records task configuration, dependencies, result metadata, and artifacts in the workspace, and provides Agents with task, dependency graph, and file query tools to verify research results, investigate failures, and reuse upstream data.

• Authentication: when service authentication is enabled, configure local AXONX_SERVICE_TOKEN or remote AXONX_TARGET_TOKEN in environment variables or .env beforehand.
• Local operations: use the “Command” column without --target. Submit and query Tasks and machine resources directly through the local AxonX HTTP service.
• Discover remote machines: use axonx list_machines to query addresses (address, such as http://192.168.1.10:1024) and health status (healthy) for all machines configured in the local service's targets, then use axonx machine_status --target <host:port> to inspect candidates' CPU, memory, and GPU resources.
• Remote operations: once the target address is known, append --target <host:port> from the “Remote arguments” column to commands that support remote operation.

192.168.1.10:1024 in the tables is an example target address; replace it before execution. — means remote operation is unsupported.

Plugin Development

A plugin can register multiple Tasks; the a158 example registers five Task types in plugins/a158/axonx_alpha158/plugin.yaml. The a158 paths, class names, registered names, and dependency chain here are illustrative; replace them with actual definitions when developing other research plugins. Plugin installation and Task submission are separate operations.

Required authoring contracts

Every plugin Task must directly or indirectly inherit BaseTask and follow the public authoring contract in axonx/task/core/task.py. Registration alone does not replace this contract:

• Declare a fixed task_type, input_cls, output_cls, and a detailed class docstring. Input and output models must inherit BaseInputParams and BaseOutputParams from core/params.py.
• Implement build_task_steps() to yield synchronous callables in execution order, and build_output_params() to return a validated instance of the declared output_cls; returning a plain dictionary does not satisfy the contract.
• Preserve framework-managed Task identity, context, lifecycle, and metadata persistence. Use self.task_dir, source_task_dir(), and resolve_workspace_path() for task artifacts and workspace paths; leave execution and status recording to the framework runtime.

axonx/task/contracts/ provides optional standard research Task and parameter classes for ETL, Analysis, Train, Predict, and Backtest. For these research stages, prefer the corresponding Base*Task, Base*InputParams, and Base*OutputParams classes. Once adopted, their required fields, types, and validators are part of the plugin's contract: preserve them and declare additional fields in subclasses. A custom Task may inherit BaseTask directly with its own parameter models, but must still follow the core contract; registration does not require every Task to inherit one of the five research base classes.

Before implementation, read Task contracts, Task lifecycle, and Research artifact contracts. Standard Python fields alone do not guarantee compatibility with downstream plugins or Studio; also satisfy the artifact mappings and presentation fields used by the intended consumers.

Task Types

Tasks link upstream and downstream through Task IDs. The a158 example's main dependency chain is ETL → Train → Predict → Backtest; Analysis uses ETL data for factor analysis.

Development Steps

1. Modify Code and Registration

For ETL, the minimal structure includes input parameters, output parameters, a Task implementation, and registration. The following is a structural example; replace ... in transform with actual ETL logic that reads input and writes results to self.state["output"].

plugins/a158/axonx_alpha158/etl.py:

from pathlib import Path

from axonx.task.contracts import BaseETLInputParams, BaseETLOutputParams, BaseETLTask


class Alpha158InputParams(BaseETLInputParams):
    input_dir: Path = Path("tushare")


class Alpha158OutputParams(BaseETLOutputParams):
    pass  # Use the ETL base class's output fields directly


class Alpha158Task(BaseETLTask):
    """Clean and align raw market data to create an ETL dataset for training and factor analysis.
    """

    input_cls = Alpha158InputParams
    output_cls = Alpha158OutputParams
    input_params: Alpha158InputParams

    def build_task_steps(self):
        yield self.transform

    def transform(self):
        # Read data from self.resolve_workspace_path(self.input_params.input_dir),
        # save artifacts to self.task_dir, and populate self.state["output"].
        ...

    def build_output_params(self):
        return self.output_cls(**self.state["output"])

A Task class must define a nonempty class docstring, used as the Task definition's description. Without it, Task resolution and definition queries raise TypeError: Task ... must define a detailed class docstring. Describe the task's purpose, input, and artifacts; method docstrings alone are insufficient.

BaseETLOutputParams already defines required fields output_file, rows, and date_range, so self.state["output"] must contain at least these three fields. Add fields to Alpha158OutputParams when additional results are needed.

plugins/a158/axonx_alpha158/plugin.yaml registers the Task name used by the CLI:

tasks:
  a158_etl: axonx_alpha158.etl:Alpha158Task

a158_etl is the --task value for submission; the Python module precedes the colon and the Task class name follows it.

For a new plugin, the package directory must contain __init__.py, and plugins/a158/pyproject.toml must declare the plugin entry point and registration file distributed with the package. The existing a158 plugin already configures these:

[project.entry-points."axonx.plugins"]
alpha158 = "axonx_alpha158"

[tool.setuptools.package-data]
axonx_alpha158 = ["plugin.yaml"]

2. Install the Plugin

Build a wheel from source and install it into the current Python environment:

axonx plugin install plugins/a158

For Task execution on a remote machine, append --target 192.168.1.10:1024; the CLI uploads the wheel and installs it on the target service.

3. Confirm Plugin and Task Registration

• Confirm installation: use axonx plugin list to verify that the target plugin is installed and error is empty; keys in the returned tasks mapping are registered names for --task.
• View definitions: use axonx get_task_definition --task a158_etl to inspect the selected Task's description, type, and input/output schemas.
• Use a consistent target: append the same --target 192.168.1.10:1024 for remote queries and submission. Explicitly specify the service address when the local service uses a different Python environment as well.

4. Check Execution Resources

• Use axonx machine_status to query CPU, memory, and GPU resources on the execution machine; append --target 192.168.1.10:1024 for remote execution.
• Confirm that the machine meets the research task's resource requirements before submitting a Task to that service.

5. Submit Tasks

Run only the Tasks needed for the current change and reuse unaffected successful upstream artifacts. Control variables: change only the factor being evaluated, keeping all other data, intervals, and parameters consistent with the baseline.

• Add factors: ETL → Train → Predict → Backtest.
• Update model architecture: Train → Predict → Backtest, reusing existing ETL.
• Update position management: run only Backtest, reusing existing Predict.

Run Analysis only when factor diagnostics are needed. Select the following commands as required.

• Registered Task name: --task a158_etl corresponds to a key in plugin.yaml's tasks, pointing to axonx_alpha158.etl:Alpha158Task. Obtain registered Task names from tasks keys returned by axonx plugin list; use axonx get_task_definition --task a158_etl to view the complete definition.
• Input parameters: the Task's input_cls defines types and defaults. The CLI converts hyphens to underscores: for example, --start-date corresponds to Alpha158InputParams.start_date, read through self.input_params.start_date; --input-dir corresponds to input_dir. Undeclared fields are rejected.
• Task naming: omit --task-name by default. Names are generated as YYYYMMDDHH plus four random letters or digits, yielding Task IDs such as etl#a158_etl#<generated name>. Pass a name only when the user specifies one; reusing an explicit name replaces artifacts after the previous execution finishes.
• Return values: inspect the response's success and answer in full. Successful submission means only that execution was accepted. answer contains task_id, run_id, and task, but not state. Record both actual returned IDs to wait for this run. Downstream source-tasks uses the successful upstream task_id; do not guess IDs.
• Upstream/downstream linkage: fill --source-tasks with Task IDs returned by successful upstream tasks. Separate multiple IDs with commas, such as '<id1>,<id2>'; an empty value means no upstream tasks. Downstream tasks locate artifacts through upstream metadata.json.
• Execution target: omit --target locally; for remote execution, append the arguments in the table and replace the address with the actual target.

6. Track Execution and Inspect Artifacts

• Use the actual Task ID and Run ID from submission to wait, query status, read logs, and inspect artifacts on the same service.
• Inspect the complete answer from status, wait_task, or stream_task: verify task_id, run_id, and state, and review result, error, exit_code, log_path, step progress, and other fields. status's success means the query succeeded, not that the Task succeeded.
• Continue waiting while state is queued or running; submit downstream tasks only after succeeded. For failed or cancelled, inspect errors and logs first.
• wait_task requires the returned task_id and run_id to wait for that execution. Resubmitting the same Task ID changes Run ID; a mismatch produces an error. Use --poll-interval 1 to set the polling interval in seconds (must exceed 0; default 1). For long tasks, use --client-timeout 86400 to increase the client request timeout; it does not set a Task execution time limit. wait_task returns success: true only when the final state is succeeded.

For other Tasks, use their actual Task IDs and workspace paths for the corresponding type. See the CLI API below for live tracking, dependency graph queries, and data preview commands.