axonx 0.2.0

Turn research prompts into quantitative code and traceable experiments.

⭐ Give AxonX a Star on GitHub!

🧠 What is AxonX?

AxonX is an agent-native harness for quantitative research, providing unified tools and a runtime for quantitative code development, experiment execution, and result analysis.

Combine your exploration prompt with the AxonX Skill, and use an external or built-in Agent to develop a new research plugin or optimize an existing one. The Agent writes quantitative code, runs experiments through AxonX, inspects results, and iterates on factors, models, and portfolio strategies. You define the research question; the Agent implements it; the Harness manages execution and evidence.

The current research plugins adapt Microsoft Qlib’s Alpha158 baseline, extending it with configurable factors and portfolio strategies. Agents can improve these plugins or develop new ones through the same Harness.

CLI, HTTP, MCP, and AxonX Studio share Jobs for submitting and querying Tasks. The selected execution service runs plugin code and stores parameters, status, dependencies, and artifacts in its workspace, so researchers and Agents can inspect the same evidence.

Quick start · Plugins · Experiments · Documentation · Try Playground

✨ Why AxonX?

• Turn research questions into quantitative code. The Skill teaches plugin authoring, Task contracts, execution, and evidence inspection; your prompt defines what the Agent explores. → AxonX Skill
• Build on Qlib’s Alpha158 baseline. Add features, change training logic, or develop portfolio policies in plugins while reusing compatible implementations and artifacts. → Alpha158 · Factor · Strategy
• Execute experiments with consistent contracts. Discover typed inputs and outputs, submit worker-process Tasks, follow progress and logs, wait for completion, or cancel a run. → Task management
• Connect code changes to evidence. Inspect configurations, Task/Run IDs, dependencies, models, predictions, and backtest artifacts to investigate failures and compare candidates. → Task lineage · Experiment design
• Use your preferred Agent and execution target. Work through an external Agent or Studio's built-in Agent, inspect results visually, and run Tasks on a selected local or remote service. → Agent integration · Remote machines

📰 Latest Updates

• Qlib Alpha158 enhancement experiments: the risk-factor model and rank-retention strategy report Top20 net annualized return improvements of +1.36 pp and +24.70 pp, respectively, over the adapted baseline (pp = percentage points). → Results and evidence limits
• Studio Playground: explore Tasks and research charts with simulated data and execution. → Try Playground

🚀 Quick start: develop quantitative plugins with an Agent

Requires Python 3.12+; local Task execution supports macOS and Linux.

1. Install and start

pip install "axonx[studio]"
git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
# Install in the execution service's Python environment for local Agent development
axonx plugin install -e ./plugins/qlib_a158

Research plugins are not published to PyPI; their sources are under plugins/ in this checkout. Use -e for local development: Python source changes do not require reinstallation, but restart persistent services; reinstall after dependency or entry-point metadata changes. Install extensions in Alpha158 → factor → strategy order; see plugin management. For the built-in demo alone, skip the checkout and plugin installation.

Create .env in the startup directory with your local service token:

AXONX_SERVICE_TOKEN=replace-with-your-local-service-token

axonx start

The CLI loads .env from the current directory or a parent; existing environment variables take precedence. Keep the service running and use another terminal for subsequent commands. See example.env for model, market-data, and remote settings; see CONTRIBUTING.md for source development and Studio builds. Restart the service after direct pip installation or editable source changes.

Deploy local plugin changes before remote submission; a Git push or matching package version does not update the execution service. Check error and restart_required, complete any required restart within the authorized service-management scope, and verify the target Task definition and resources before submitting. Stop and report installation or verification failures; record returned Task/Run IDs. See the development guide for the full workflow.

For remote execution, replace <host:port> with the selected service address and configure AXONX_TARGET_TOKEN. The plugin and Task below are examples; use the actual source path and registered Task.

axonx list_machines
axonx plugin install ./plugins/qlib_a158 --target <host:port>
axonx get_task_definition --task qlib_a158_etl --target <host:port>
axonx machine_status --target <host:port>
axonx submit --task qlib_a158_etl --start-date 20150101 --target <host:port>

2. Verify the service and open Studio

The built-in demo requires no market-data or model credentials:

axonx submit --task demo --x 2 --y 3
axonx wait_task --task-id '<returned_task_id>' --run-id '<returned_run_id>' --client-timeout 120
axonx get_task_context --task-id '<returned_task_id>'

Use answer.task_id and answer.run_id returned by submit, and wait for succeeded before reading outputs or submitting downstream Tasks. source_tasks records lineage; it does not automatically run the DAG.

Visit http://127.0.0.1:1024/ and enter AXONX_SERVICE_TOKEN in Settings → Local service token. See the Studio guide for Tasks, research charts, and the Agent workspace.

Home	Task management

3. Prepare the source and connect an Agent

Provide an AxonX source checkout and load AxonX Skill in your Agent, either by reading it directly or using the host's supported installation mechanism. A package installation alone does not include the example plugin sources. Choose an external Agent or Studio's built-in Agent below.

External Agent: CLI or MCP

Use Codex, Claude Code, or another host with file and command tools for the checkout. The host supplies model credentials. Use the axonx CLI, or connect through MCP with these settings:

Use the connected service's token and adjust the address for custom ports or remote services. See MCP integration.

Built-in Agent: Studio

The default backend uses the Claude Agent SDK. Add your provider's credentials, Claude-compatible URL, and model name to .env, then restart the service:

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

To load the bundled English development guide:

axonx start --language en

Open Studio → Agent and configure cwd and SDK file/command tools for the checkout. Guide loading defaults to true. Use the CLI described in the guide for task queries, installation, and submission. Ensure the Agent can run axonx with the selected service address and token. job_tools is an optional in-process bridge; uncomment and customize its example list when direct Job tools are needed. See Agent configuration.

4. Give the Agent a research objective

Specify the baseline, hypothesis, data, evaluation windows, metrics, and execution target. For example:

Read the AxonX Skill and the qlib_a158 implementation. Develop a separate research plugin to investigate whether residual volatility and downside risk improve Alpha158 ranking. Use only information available at signal time. Keep the data snapshot, labels, training parameters, evaluation windows, and trading costs fixed for factor ablations. Implement and test the quantitative code, register and install the plugin, and run ETL, training, prediction, and backtest Tasks through AxonX. Preserve Task/Run IDs and report RankIC, net returns, drawdown, turnover, and limitations. Select candidates within the development window and reserve an independent confirmation window.

You can also ask the Agent to optimize an existing plugin's feature calculation, training procedure, or portfolio policy. Specify whether the goal is runtime efficiency, signal quality, or trading performance, and how to evaluate it.

Keep code/version, data, windows, parameters, costs, and Task/Run IDs with each experiment so the Agent can compare candidates and iterate on the same evidence. See the development guide for plugin authoring, service installation, and Task contracts.

For Alpha158, configure AXONX_TUSHARE_TOKEN and prepare enough historical data before running the research workflow. The Alpha158 case study provides complete reproduction commands.

🧩 From Qlib Alpha158 to extensible research plugins

The research chain is ETL → Train → Predict → Backtest, with factor analysis branching independently from ETL. Three plugins progressively reuse implementations and artifacts; other research methods can use the same plugin contracts:

The baseline uses Tushare data and adapts the universe, labels, training, and trading protocol; see Differences from original Qlib. Plugin registration, Task contracts, and artifact requirements are covered in the development guide.

📊 Alpha158 improvement case: factors and portfolio strategy

The experiment compares the Alpha158 baseline, a model with two added risk factors, and a portfolio strategy that reuses the factor-model predictions:

Training covers [20150101,20230101); evaluation covers 20230103–20261008, or 909 market dates. Buy/sell fees are 0.05% / 0.15%. The replacement cap limits stock counts, not transaction notional; initial construction is exempt. The strategy plugin's default minimum holding period is 10 days; this experiment explicitly uses 3.

Evidence limits: the three configurations were rerun on 2026-10-10, but have no independent confirmation window. Base/factor feature_fraction is 0.9/1.0, so differences do not isolate the added factors. All three backtests report incomplete_market_data; fills use same-close quote proxies and 2026 is a partial year. These results describe the adapted AxonX experiments and do not establish outperformance over the original Qlib benchmark.

Full settings, metrics, reproduction commands, and Task provenance.

🛠️ CLI and remote execution

See the CLI reference for definitions, progress, and logs, and plugin management for installation and updates.

Connect directly to a remote service with the CLI

Set the target service's AXONX_TARGET_TOKEN and use the same --target for installation, submission, waiting, and queries:

axonx plugin install ./plugins/qlib_a158 --target 'http://<host>:1024'
axonx plugin install ./plugins/qlib_factor --target 'http://<host>:1024'
axonx get_task_definition --task qlib_factor_train --target 'http://<host>:1024'

An explicit --target uses AXONX_TARGET_TOKEN by default; default local calls use AXONX_SERVICE_TOKEN. Without a target, plugin commands use the current Python environment.

Use remote machines in Studio

Set AXONX_TARGET and AXONX_TARGET_TOKEN in the local service environment, run axonx start --config remote, and select the machine in Studio. The target service owns its plugins, data, and workspace; see remote machines for multiple-target configuration.

📚 Documentation

English documentation · 中文文档

💬 Contributing

Contributions to the Harness, research plugins, experiment evidence, and documentation are welcome. See CONTRIBUTING.md for setup and checks, and GitHub issues for bugs and proposals. Keep algorithms in plugins, preserve public contracts, update both documentation languages, and include reproducible settings and artifacts when contributing research results.

⚖️ License

Apache License 2.0.