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. 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.
🚀 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/mcpwithAuthorization: Bearer <token>. See MCP integration. - Built-in Agent: set the following model environment, restart the service, and open Studio → Agent. Configure its
cwdfor 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.
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 |
💬 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.