Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

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 Apache License 2.0 Read the AxonX Skill 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

Requires Python 3.12+ on macOS or Linux. Studio is an optional package sharing the AxonX version and release workflow.

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 Alpha158 first, then factor or strategy as needed; the two extensions do not depend on each other. 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. Install the Skill from main with GitHub CLI (--agent claude-code for Claude Code):

gh skill install FlowLLM-AI/AxonX axonx --agent codex --scope user --pin main

Install AxonX and the research plugins as described above, then 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 → Portfolio → 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.1

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

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

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

Built distribution (wheel)

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

Total release size: 500.2 kB

Release files / axonx-0.3.1.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL axonx-0.3.1.tar.gz
Size 219.7 kB
Tags Source
SHA-256 checksum
How to use checksums
847713e683f67354fe572c4734d1d78572dc0c08876d34ea2543e8b5d8ec3fe2
BLAKE2b-256 checksum
How to use checksums
62993f680da49244f9196f9773b44ce5a863008140f82258e1da965b94906e5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.15

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 31, 2026.

Transparency log

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

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL axonx-0.3.1-py3-none-any.whl
Size 280.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7b143359cf82c6b37842f86c78bf58a72f881880238438d0e97896f45f1f0f61
BLAKE2b-256 checksum
How to use checksums
c15cf868b239f1742348f9f4a3adab61c05c20f5bc9432bd73b2ee0315f77db6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.15

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 31, 2026.

Transparency log

Security for axonx 0.3.1

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.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for axonx-0.3.1.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 31, 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