Skip to main content

AxonX

Turn research prompts into quantitative code and traceable experiments.

Python 3.12+ PyPI version PyPI monthly downloads GitHub monthly commit activity GitHub clones in the last 14 days GitHub forks Apache License 2.0 CLI and MCP access AxonX documentation Read in English 阅读简体中文 Ask DeepWiki about AxonX

⭐ Give AxonX a Star on GitHub!

🧠 What is AxonX?

AxonX is an agent-native harness for quantitative research. Agents develop research plugins, execute experiments, and inspect the same parameters, logs, dependencies and artifacts as researchers.

You define the question; the Agent implements it; AxonX manages execution and evidence. Use CLI, HTTP, MCP or Studio. The reference plugins adapt Microsoft Qlib's Alpha158 baseline with configurable factors and portfolio policies.

Quick start · Plugins · Case study · Documentation · Try Playground

✨ Why AxonX?

  • Develop with Agents: use the AxonX Skill, source tools and live Task schemas.
  • Keep traceable experiments: typed inputs/outputs, process identity, logs and versioned artifact references.
  • Inspect in Studio: Task control, workspace previews, research charts and strategy comparisons.

📰 Latest Updates

  • 0.3.0 released: supports inheritable configuration, unified Task execution, and scheduled Tasks that continue across service restarts.
  • Alpha158 experiments: risk factors and rank retention improved Top20 net annualized returns by +1.36 pp and +24.70 pp over the adapted baseline. See results and evidence limits.
  • Studio Playground: explore Tasks and charts with simulated data. Try it online.

AxonX interfaces, commands and core capabilities

🚀 Quick start

This checkout is AxonX 0.3.0. Requires Python 3.12+ on macOS or Linux. Studio is an optional, independently released package.

1. Install and start

Install from pip:

pip install 'axonx[studio]'

Or install the backend and Studio from source:

git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e ./axonx_studio -e '.[studio]'
npm --prefix axonx_studio ci
npm --prefix axonx_studio run build

The source install uses editable packages. Building Studio requires Node.js 22.13+ (22.x), 24.x or 26+; rebuild after frontend changes.

Then start the service:

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

Defaults: port 1024, workspace .axonx, service/CLI logs logs/. Use example.env for optional settings; CLI startup loads the nearest .env from the launch directory or its parents, preserving existing environment values. Keep this terminal open and use another with the same Python environment and token.

For custom settings, save a YAML file such as axonx.local.yaml:

extends: default
workspace_dir: .axonx
service:
  host: 127.0.0.1

Start it with axonx app --config ./axonx.local.yaml. Custom configs inherit the bundled service, components and Jobs only with extends: default; mappings merge, while lists and scalars replace. Installed plugins can also provide named configs. See configuration.

2. Run Demo and open Studio

axonx get_task_def --task demo
axonx exec --task demo --task-name quickstart --x 2 --y 3
axonx status --task-id 'base#demo#quickstart' --detail full

exec waits and returns business output (result=5) plus the Task exit code. Demo needs no market data or model credentials. Open http://127.0.0.1:1024/ and enter the token in Settings → Local service token.

axonx --help shows offline usage; axonx help queries the running service's Jobs. Execution settings use explicit CLI options → service get_config → built-in defaults. The CLI falls back only when the service connection is unavailable; authentication and service errors are reported. Task-specific parameters come from get_task_def.

Keep the Task ID and metadata started_at. Use different instance names to preserve experiments: same-name reruns replace current records and outputs, retaining persistent/. See Task management.

3. Develop with an Agent

For the reference research plugins, use the source checkout above (or clone the repository if you installed from pip). From the repository root, install into the execution service's Python environment:

axonx plugin install -e ./plugins/qlib_a158
axonx restart_service

Research plugins are installed from source. Install extensions in Alpha158 → factor → strategy order. Restart persistent services after code changes; reinstall after dependency or entry-point changes. Wait for the service to be ready before querying definitions.

Provide the checkout, file/command tools and AxonX Skill. Choose an access path:

  • External Agent: the host manages model credentials. Use CLI or Streamable HTTP MCP at http://127.0.0.1:1024/mcp with Authorization: Bearer <token>. See MCP integration.
  • Built-in Agent: set the following model environment, restart the service, and open Studio → Agent. Configure its cwd for the checkout; see Agent configuration.
CLAUDE_CODE_API_KEY=your-model-api-key
CLAUDE_CODE_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_MODEL_NAME=your-model-name

Give the Agent a concrete objective, for example:

Read the AxonX Skill and Alpha158 implementation. Develop a separate plugin to test residual volatility and downside risk. Fix data, training settings, costs and evaluation windows; use only signal-time information. Test the code, run experiments, and report Task IDs, RankIC, net returns, drawdown and limitations. Reserve an independent confirmation window.

Prepare historical data and AXONX_TUSHARE_TOKEN before following the research workflow.

🧩 From Qlib Alpha158 to research plugins

The main chain is ETL → Train → Predict → Backtest, with optional factor analysis from ETL. qlib_a158_research composes these stages; leaf Tasks can reuse compatible upstream artifacts.

Plugin Capability
qlib_a158 158 price/volume features, LightGBM, factor analysis and TopN backtests
qlib_factor 13 optional features; training defaults to the 158-feature baseline
qlib_strategy Minimum holding periods, rank retention and replacement limits; reuses predictions

Other research methods use the same Task and plugin contracts. The baseline adapts Qlib's data, labels, training and trading assumptions; see differences from original Qlib.

📊 Alpha158 improvement case

This recorded experiment adds two risk features, then applies a rank-retention policy to the factor-model predictions:

Configuration Top20 net annualized Max drawdown Daily two-sided turnover
Alpha158 baseline 7.67% -38.65% 198.83%
Risk-factor model 9.03% -40.69% 199.35%
Rank-retention strategy 32.37% -24.91% 40.01%

Training: [20150101,20230101); evaluation: 20230103–20261008 (909 market dates). Buy/sell fees: 0.05% / 0.15%. The strategy uses a 3-day minimum holding period and a 20% replacement count cap per side; initial construction is exempt.

Signal quality

Portfolio performance

Evidence limits: no independent confirmation window; base/factor feature_fraction differs (0.9/1.0), so results do not isolate the added factors. All backtests report incomplete_market_data, use same-close fill proxies and include a partial 2026. These results do not establish outperformance over original Qlib.

Full settings, reproduction commands and historical Task provenance.

🛠️ CLI and remote execution

Set the destination token and keep the same target for execution and observation:

export AXONX_TARGET_TOKEN='replace-with-target-token'
axonx exec --task demo --task-name remote-check --x 2 --y 3 --target node-b:1024
axonx status --task-id 'base#demo#remote-check' --detail full --target node-b:1024

Replace the example address. --target uses AXONX_TARGET_TOKEN; default local calls use AXONX_SERVICE_TOKEN. Remote paths belong to the target. Deploy local plugins by build → upload → install location → clean path → restart/verify; see plugin management.

Studio uses backend-configured targets; AXONX_TARGET populates the bundled remote config and does not select a CLI destination by itself. See remote machines. Service restarts stop service-owned manual commands and preserve daemon-owned scheduled Tasks; schedules accept local axonx exec --task NAME commands. See service updates.

📚 Documentation

Goal Guide
Run research Quickstart · Research workflow
Use an Agent External Agents · Built-in Agent
Develop plugins Development guide · Artifact contracts
Evaluate results Experiment design · Strategy comparison
Operate or extend AxonX CLI · Configuration · Architecture

English documentation · 中文文档

💬 Contributing

Contributions to the framework, plugins, experiments and documentation are welcome. See CONTRIBUTING.md for setup and checks, or GitHub issues for bugs and proposals.

⚖️ License

Apache License 2.0.

Metadata

Release files for axonx 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for axonx 0.3.0
File Size Uploaded Provenance Actions
axonx-0.3.0.tar.gz 219.1 kB With provenance Details for axonx-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for axonx 0.3.0
File Interpreter ABI Platform Actions
axonx-0.3.0-py3-none-any.whl Python 3 none any Details for axonx-0.3.0-py3-none-any.whl

Total release size: 498.2 kB

Release files / axonx-0.3.0.tar.gz

Download URL axonx-0.3.0.tar.gz
Size 219.1 kB
Tags Source
SHA-256 checksum
How to use checksums
bfae6f704f7a452c1ca9980cb73f41a13ba3db20ca82beba6e2a0f3bcfa0a5f3
BLAKE2b-256 checksum
How to use checksums
e486df15c4aae4f3707ba1f88e87b2464f2204f07d07b7a752e84825fd8157c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / axonx-0.3.0-py3-none-any.whl

Download URL axonx-0.3.0-py3-none-any.whl
Size 279.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d529e4f066fc428b81df0a091c822cd21bb2fe51ce47b4a98679eb033d598a7b
BLAKE2b-256 checksum
How to use checksums
1acb5e73bea9ae82df4909d9d7bf31b8f81699b457f74f4ba8dcff63e5f2e289
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for axonx 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for axonx-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page