Skip to content

Contributing to AxonX ​

English · 简体中文

We welcome fixes, research plugins, experiment evidence and documentation. Search existing issues first. Report reproducible steps, expected/actual behavior, versions and sanitized logs. Discuss substantial public-contract changes before implementation; keep each PR focused.

Development setup ​

Use Python 3.12+ on macOS or Linux, from your source checkout:

bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pre-commit install

For Studio, use Node.js 22.13+ (22.x), 24.x or 26+:

bash
cd axonx_studio
npm ci
npm run dev

Start the Python service from the repository root in another terminal:

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

The default port is 1024; runtime data goes into .axonx/, Task logs into each Task directory, and service/startup logs into logs/. Use example.env for optional credentials and bundled configuration variables. CLI startup loads the nearest .env from the current directory or up to five parents, preserving existing environment values. See Studio development for proxy and build settings.

Use server configuration for YAML inheritance and installed configs, and CLI reference for execution options. Custom configs inherit defaults only with extends: default. Keep credentials and runtime outputs out of commits.

Choose the right area ​

LocationResponsibility
axonx/task/Typed models, authoring bases, synchronous runtime, storage and built-in Tasks
axonx/plugin/Plugin discovery, wheel validation and installation
axonx/utils/Shared environment, logging, value conversion and async cleanup
axonx/app/, axonx/client/Application capabilities, Jobs, transports and caller connections
axonx/cli/, axonx/daemon/Command routing, service supervision and scheduled process ownership
plugins/Research algorithms, manifests and plugin tests
axonx_studio/UI, forms, API client and research views
docs/, github-pages/Bilingual guides, figures, navigation and site tooling

Keep algorithms in Tasks/plugins. Task execution must not depend on App, Plugin or CLI; startup assembles catalogs and injects host capabilities. app/core/composition.py selects concrete Providers and orders managed lifecycles; Steps adapt Jobs to component base contracts. HTTP/MCP clients remain independent of App. Import from owning modules, keep data contracts free of execution side effects, and make resource cleanup explicit. See architecture, framework extensions and the dependency map.

Develop a plugin ​

Keep research algorithms in plugins. Follow the development and operations guide for Task authoring, plugin management for installation and remote deployment, and artifact contracts for Studio integration. Install qlib_a158 from source first; qlib_factor and qlib_strategy each extend it independently.

Agent-authored changes use the same checks. Improvement claims must retain code/data versions, windows, parameters, costs, Task IDs and started_at; follow experiment design.

Validate the change ​

Run focused checks first, then the relevant suite. Report commands, results and skipped checks in the PR.

AreaChecks
Frameworkpython -m pytest tests
PluginIts test directory, for example python -m pytest plugins/qlib_factor/tests
StudioIn axonx_studio/: npm test, npm run lint, npm run format:check, npm run build
Python wire contractsIn axonx_studio/: npm run contracts:generate and npm run contracts:check
Documentation examplespython -m pytest tests/unit/test_documentation_contracts.py

Also check Agent resources with python -m scripts.sync_agent_guides --check and architecture changes with python -m pytest tests/unit/test_module_boundaries.py.

Bare pytest also collects plugin tests and needs their research dependencies. Integration tests are deselected by default; run python -m pytest tests/integration -m integration only with the required services and credentials after reviewing external effects.

Contract generation updates both axonx_studio/src/shared/api/contracts.ts and axonx_studio/src/playground/job-contracts.json. Regenerate after changing serialized Python models, or default Jobs; do not edit the generated output.

Use temporary workspaces. Keep credentials, private data, .axonx/, logs and generated research outputs out of commits. Check affected UI flows in both languages, including empty and failed requests. Run pre-commit run --files <changed-files> with actual paths; review automatic fixes. Hooks use Ruff for import ordering, Black for formatting, and additional lint checks.

Update documentation ​

Keep documentation self-contained to this framework, its bundled components and plugins. Use repository-owned examples; external plugins document their own business rules, storage layouts and deployment.

Edit canonical bilingual sources in docs/{en,zh}/ or the root/plugin READMEs imported by the site. Procedures belong in guides, fields in Reference, algorithms in plugin READMEs, and experiment evidence in case studies. Link to the owner instead of repeating its content. Navigation lives in docs/.vitepress/navigation.mjs; shared figures live in docs/figures/.

Job arguments come from axonx/app/config/default.yaml; CLI syntax from axonx/cli/parser.py, execution from commands.py/remote.py, and Task contracts from axonx/task. Update affected examples and diagrams together. Preserve recorded research results and provenance.

After editing docs/{en,zh}/dev_guide.md, run python -m scripts.sync_agent_guides and python -m scripts.sync_agent_guides --check to regenerate package guides and skills/axonx/SKILL.md. These standalone resources intentionally contain the full guide.

With dependencies installed in axonx_studio/ and github-pages/, run:

bash
npm --prefix github-pages test
npm --prefix github-pages run build

The build validates bilingual navigation, links, anchors, assets and Markdown exports. See site maintenance for generation, figures and deployment, including Vercel settings.

Submit a pull request ​

Explain the problem, resulting behavior, affected contracts and validation. Include screenshots for visible UI changes and note documentation updates. Conventional Commit titles are encouraged. Contributions use the Apache License 2.0.

Releases ​

AxonX and Studio share the version in axonx/_version.py and one Release / AxonX workflow:

  1. Edit and commit only axonx/_version.py. Studio Python packaging reads it through the source symlink, Vite injects it at build time, and npm packaging stamps a temporary manifest. Version bumps require no metadata, contract or documentation edits. Use X.Y.Z for stable releases or X.Y.Z-{alpha,beta,rc}.N for prereleases; Python package metadata normalizes prerelease spelling.
  2. After CI passes, push v<version> and publish its GitHub Release. This defaults to both: axonx and axonx-studio on PyPI, plus @flowllm-ai/axonx-studio on npm.
  3. For selective publication, run the same workflow manually with the existing tag's version without v. publish_target offers both (default), backend (AxonX PyPI only), and studio (Studio PyPI and npm). These inputs are in Actions → Release / AxonX → Run workflow; the GitHub Release form has no package selector.

Every run tests and builds both packages from the same tag and checks its version against the source before any upload. Research plugins are verified during the build but are not published. Studio publishes to PyPI before npm; npm uses latest for stable versions and next for prereleases.

Configure the Trusted Publishers for both PyPI projects and the npm package with workflow filename release.yml, using the pypi/npm environments respectively. Releases reject existing versions; keep tags fixed. Uploads across registries are not atomic. If a publishing job fails, rerun failed jobs in the original workflow to reuse its artifacts and avoid republishing successful jobs.

The PyPI publishing matrix uses Twine's built-in Trusted Publishing authentication. Each job checks package metadata before attempting to generate Sigstore attestations. If attestation generation fails or exceeds two minutes, the workflow emits a warning and uploads without attestations. Metadata, authentication, duplicate-version and upload errors still fail the release.

The AxonX Skill ships in the same repository and AxonX release tags. Synchronize the Agent guides as described above and run gh skill publish --dry-run before release. Reuse the AxonX Release; running gh skill publish without --dry-run creates a GitHub Release, and a v<version> release triggers the unified publishing workflow.

Agent-native quant research.