axonx 0.1.1

An Agent Harness for financial quantitative research.

⭐ Give AxonX a Star on GitHub!

🧠 What is AxonX?

AxonX is an agent-native harness for financial quantitative research.

It packages data processing, factor analysis, training, prediction, and backtesting as Tasks with explicit inputs and outputs. Plugins provide the algorithms; the framework handles execution, records, and artifact management.

Researchers use forms and charts in AxonX Studio, while Agents and scripts access capabilities through CLI / MCP. Each interface submits, tracks, and queries tasks through Jobs, using research records in the same workspace to inspect logs, artifacts, and upstream and downstream relationships.

✨ Why AxonX?

• Reusable research Tasks. Typed inputs and outputs define data, model, and artifact requirements. → Task contracts
• Manage execution. Run Tasks in worker processes; track status, progress, logs, and results; wait or cancel. → Task management
• Trace research results. Saved parameters, artifacts, and dependency graphs help you reuse data and compare experiments. → Task lineage
• One workflow across interfaces. CLI / MCP, Studio, and Agents share Job and Task contracts, records, and artifacts. → AxonX Studio · Agent
• Extend and run remotely. Add research plugins and execute Tasks in a selected target environment. → Plugin management · Remote machines

📰 Latest Updates

• AxonX 0.1.0 released: an agent-native quantitative research harness with plugin-based Tasks, execution tracking, task lineage, and shared CLI / MCP / Studio access. → Documentation
• Connect your Agent with SKILL.md + CLI: load the AxonX Skill into Codex, Claude Code, or another Agent to discover Task contracts, develop plugins, submit research tasks, and inspect results. → Agent integration
• AxonX Studio available: browse tasks and artifacts, inspect training curves and backtests, and compare strategies in one workspace. → Try Playground (simulated data and execution)
• Qlib three-version experiment: base / added factors / 3-day policy Top20 net annualized returns are 7.67% / 9.03% / 32.37%, with 0.05% buy / 0.15% sell fees and missing quotes; the policy has not been independently confirmed. → Comparison and full results

🚀 Quick start

Requires Python 3.12+. Local Task execution supports macOS and Linux.

Install from PyPI

pip install "axonx[studio]"

Includes the CLI, HTTP API, MCP, and prebuilt AxonX Studio. For core capabilities alone, install axonx. Research plugins are installed separately.

Install from source

Building Studio requires Node.js 22.13+ (22.x), 24.x, or 26+:

git clone https://github.com/FlowLLM-AI/AxonX.git && cd AxonX
pip install -e .
(cd axonx_studio && npm ci && npm run build)
pip install ./axonx_studio

For development dependencies and frontend hot reload, see the contribution guide and Studio development documentation.

Configure environment variables

Create .env in the startup directory. The CLI automatically loads configuration from the current directory or a parent directory; existing environment variables take precedence.

# Local service authentication: replace with your own token
AXONX_SERVICE_TOKEN=replace-with-your-local-service-token

# Optional: target AxonX service (axonx start --config remote)
# AXONX_TARGET=192.0.2.10:1024
# AXONX_TARGET_TOKEN=your-target-service-token

For optional settings such as models, market-data downloads, and remote services, see example.env.

Start AxonX

Start with the defaults:

axonx start

Specify the listening IP and port:

axonx start --service.host 127.0.0.1 --service.port 8181

With a custom port, open http://127.0.0.1:8181/ in your browser. Append --target 127.0.0.1:8181 to subsequent CLI service commands and provide the local service token, for example:

axonx version --target 127.0.0.1:8181 --token '<local-service-token>'

When --target is specified, the CLI reads AXONX_TARGET_TOKEN by default; the --token above explicitly supplies local credentials. Local commands using the default port read AXONX_SERVICE_TOKEN. For remote service configuration, see remote execution.

Keep the service running and execute subsequent CLI commands in another terminal.

Open AxonX Studio

After starting with the defaults, open http://127.0.0.1:1024/, go to Settings → Local service token, and enter the AXONX_SERVICE_TOKEN configured in .env. You can then:

• Query Task definitions, fill in parameters, submit tasks, and inspect status, progress, logs, and upstream and downstream relationships.
• Browse workspace files and inspect parameters, metadata, and research artifacts.
• View factor analysis, training curves, predictions, backtest metrics, and period summaries.
• Query machine resources and switch between configured local and remote services.
• After configuring a model, use conversations on the Agent page to investigate tasks and analyze research results.

Home	Task management

Getting started with Studio

🧪 Quick CLI demo

Download Tushare data

Set AXONX_TUSHARE_TOKEN in the service's .env (example.env), then start or restart the service. Download a week's daily prices and adjustment factors with the built-in Tushare Task, then check its status and logs:

axonx submit \
  --task download_tushare_task \
  --task-name tushare-demo \
  --start-date 20230901 \
  --end-date 20230907 \
  --datasets 'daily,adj_factor'

axonx status --task-id 'api#download_tushare_task#tushare-demo'
axonx read_task_log --task-id 'api#download_tushare_task#tushare-demo'

--task selects the Task and --task-name names it. Dates use YYYYMMDD; --datasets selects comma-separated data groups. The submit command returns JSON (mock response):

{
  "answer": {
    "task_id": "api#download_tushare_task#tushare-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
    "task": "download_tushare_task"
  },
  "success": true,
  "metadata": {}
}

success: true confirms submission; the Task downloads asynchronously and saves Parquet files under the workspace's tushare/ directory when it succeeds. Use the returned task_id for queries and save run_id to wait for this execution with wait_task.

Other CLI commands

Replace placeholder IDs with the returned answer.task_id / answer.run_id; submit downstream Tasks only after their inputs succeed.

# Task status, logs, and dependencies
axonx wait_task --task-id '<task_id>' --run-id '<run_id>' --client-timeout 600
axonx status --task-id '<task_id>'
axonx read_task_log --task-id '<task_id>'
axonx get_task_graph --task-id '<task_id>'

# Service and workspace
axonx version
axonx machine_status
axonx list_entries --path ''

# Plugins: install in the service's Python environment, then restart the service
pip install axonx-qlib-a158
axonx plugin list
axonx plugin show axonx-qlib-a158

# Research workflow (skip downloads if historical data is already available)
axonx get_task_definition --task qlib_a158_etl
axonx submit --task download_tushare_task --start-date 20140101 --end-date 20231231 --datasets 'static,stk_limit,daily,adj_factor,index_weight'
axonx submit --task qlib_a158_etl --start-date 20150101 --end-date 20231231
axonx submit --task qlib_a158_train --source-tasks '<etl_task_id>' --train-start 20150101 --train-end 20230101
axonx submit --task qlib_a158_predict --source-tasks '<train_task_id>' --pred-start 20230101 --pred-end 20231231
axonx submit --task qlib_a158_backtest --source-tasks '<predict_task_id>'
# Optional factor analysis: an independent downstream stage of ETL
axonx submit --task qlib_a158_factor --source-tasks '<etl_task_id>'

View results in AxonX Studio; see the research workflow and CLI reference for details.

🤝 Agent access and development guides

Connect an external Agent through MCP

After starting the service with the defaults, use these connection parameters in your Agent host:

Use the AXONX_SERVICE_TOKEN of the service you connect to; adjust the host and port for a custom or remote service. For host configuration and tool discovery, see MCP integration.

Configure the built-in Agent

The default backend uses the Claude Agent SDK. Set the model credentials, compatible service URL, and model name in .env:

CLAUDE_CODE_API_KEY=your-model-api-key
CLAUDE_CODE_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_MODEL_NAME=your-model-name

Replace the placeholders with your provider's credentials and available model name, and use its Claude-compatible URL. Restart AxonX after changing .env; then open Studio → Agent. See example.env for other optional settings.

The built-in Agent's components.agent.default.load_dev_guide defaults to false. To load the Chinese guide, override the configuration in the startup command:

axonx start --components.agent.default.load_dev_guide true --language zh

Guide loading and tool configuration are independent. The Jobs available to the Agent are determined by job_tools, which provides task and artifact queries by default. See Agent configuration.

🧩 Alpha158 and the plugin system

Alpha158 packages 158 price and volume features, a LightGBM model, and TopN backtesting as research Tasks. The main chain is ETL → Train → Predict → Backtest, with factor analysis as an independent downstream stage of ETL.

For usage examples, see the Quick CLI demo above; for complete parameters and data requirements, see the plugin documentation. To extend your own research methods, inspect, build, and install plugins from source. Relevant commands appear under CLI commands below; for development and deployment, see plugin management.

📊 Benchmark: from Qlib baseline to agent-developed factors and strategy

The experiment starts by porting Qlib's Alpha158 / LightGBM setup, then uses an agent with the AxonX Skill to develop factors and a portfolio policy through AxonX. These steps produce three plugins: qlib_a158, qlib_factor, and qlib_strategy. AxonX saves task parameters, dependencies, and results.

1. Port Alpha158 to establish a baseline

qlib_a158 ports Qlib's 158 price/volume features and LightGBM model into ETL → Train → Predict → Backtest Tasks. The port adapts settings to this project's data and execution model:

• Data and labels: Tushare adjusted prices and volumes across Shanghai/Shenzhen, excluding Beijing. Labels use signal-close to next-market-close returns, transformed into daily ranks after removing 2.5% of samples at each tail.
• Training: [20150101,20230101), reserving the last 10% of dates for early stopping before refitting the full training period; exclude labels crossing the cutoff. This experiment uses the AxonX parameter preset, learning rate 0.03, 31 leaves, and feature_fraction=0.9.
• Backtesting: evaluate 20230103–20261008, with Top20 as the primary portfolio and fixed 1-day holding. Use same-close proxy fills, price-limit and tradability constraints, and 0.05% buy / 0.15% sell fees.

These are the ported experiment's settings and differ from the original Qlib example. See the migration comparison for details.

2. Have the agent develop factor enhancements

Using the AxonX Skill, the agent develops qlib_factor, submits training, prediction, and backtest Tasks through AxonX, and inspects artifacts to compare candidate factors. Training-period validation RankIC selects two stock-level risk factors: 20-day residual volatility and 20-day downside risk, increasing model inputs from 158 to 160 columns.

Example prompt:

Use the AxonX Skill to develop a separate qlib_factor plugin on the qlib_a158 baseline. Explore residual volatility, downside risk, and related candidate factors using only information available at signal time. Run controlled experiments through AxonX, select groups by training-period validation RankIC, retain task records, and report returns, drawdown, and factor definitions.

3. Have the agent develop a portfolio policy

The agent follows the same process to develop qlib_strategy, reusing augmented predictions to study holding and replacement rules. This experiment evaluates a fixed 3-day rank-retention policy: hold for at least 3 market dates, retain highly ranked stocks, exit lower-ranked holdings first, and cap daily replacements at 20% of the stock count per side.

Example prompt:

Use the AxonX Skill to develop a separate qlib_strategy plugin that reuses qlib_factor predictions. Explore minimum holding periods, rank retention, and capped replacements. Keep data, costs, and fill assumptions fixed; use AxonX to compare net returns, Sharpe, drawdown, and turnover. Save task records and explain the selection.

Results for the three versions

The figures compare signal quality and Top20/Top30 net annualized returns across the three versions. The compact table shows Top20 risk and turnover over 909 market dates. The strategy reuses factor-model predictions.

Top20 risk and trading metrics:

The three configurations were rerun on machine 45 on 2026-10-10 with Qlib buy/sell fees. They have no independent confirmation window; base/factor feature_fraction is 0.9/1.0, so differences do not isolate the added factors. Results include missing quotes, proxy fills and a partial 2026.

Full experiment settings, metrics, and reproduction commands include configurations and task provenance for all three versions. The prompts above are illustrative development instructions.

🛠️ AxonX CLI commands and remote execution

CLI service commands call the corresponding Jobs. exec and plugin management commands without a specified target run in the current Python environment.

Connect directly to a remote service with the CLI

First install AxonX and research plugins on the target machine, configure its own AXONX_SERVICE_TOKEN, and start a reachable service. On the client, configure the target token and explicitly specify the address for commands that support remote access:

export AXONX_TARGET_TOKEN='your-target-service-token'
axonx machine_status --target 192.0.2.10:1024
axonx plugin list --target 192.0.2.10:1024
axonx submit --task demo --x 2 --y 3 --target 192.0.2.10:1024
axonx wait_task --task-id '<task_id>' --run-id '<run_id>' \
  --client-timeout 120 --target 192.0.2.10:1024

Replace the example address with your actual service. Use the same --target for submission, waiting, status, logs, and artifact queries; tasks use the target machine's plugins, data, and workspace. Direct CLI access does not require starting a local service.

Remote plugin installation builds a wheel locally, uploads it, and installs it in the target environment:

axonx plugin install ./plugins/qlib_a158 --target 192.0.2.10:1024

plugin build always runs locally. Remote plugin inspect accepts a distribution or plugin name already installed on the target. start and exec do not execute remotely through --target.

Use remote machines in Studio

Configure the remote service address and token in the local .env:

# Optional: remote AxonX service for Studio
AXONX_TARGET=192.0.2.10:1024
AXONX_TARGET_TOKEN=your-target-service-token

Replace the example address with your actual service, then start with the built-in remote configuration:

axonx start --config remote

remote inherits the default configuration and adds the target address and token to the service's targets. Studio uses the local token to access the same-origin backend, which forwards requests to the selected remote service. For multiple targets, custom YAML, and connection troubleshooting, see the remote machines guide.

📚 AxonX documentation

Browse the complete Chinese documentation or English documentation.

💬 Contributing

Bug reports, feature requests, documentation improvements, research plugins, and code contributions are welcome. Search existing issues first; see the contribution guide for development setup, directory conventions, and required checks.

Keep research algorithms in plugins/ and reuse framework extension points. Update both English and Chinese documentation when behavior changes. When contributing experiments, include data and time windows, parameters, cost definitions, and result materials that others can verify.

⚖️ License

AxonX is released under the Apache License 2.0.