AINode Guidelines

These instructions apply to iotdb-core/ainode/ and supplement the repository instructions.

Python environment and source ownership

  • Use an isolated Python environment matching pyproject.toml; the runtime currently requires Python 3.11 (>=3.11.0,<3.12.0). The Python version in the formatting-only CI job does not define the supported runtime.
  • AINode implementation lives in iotdb/ainode/core/. Keep configuration parsing and defaults (config.py and constant.py there) aligned with resources/conf/iotdb-ainode.properties.
  • Maven copies the Python client and generated Thrift modules from iotdb-client/client-py/iotdb into this module. Fix their original sources or Thrift IDL rather than the copied files under iotdb/. Build metadata under iotdb/ainode/conf/ is generated from resources/pom.properties and Git; do not edit generated metadata or files under build/, dist/, or target/.

Formatting

Always run Black and isort after editing Python files here. Use the versions pinned by AINode Code Style Check, currently black==25.1.0 and isort==6.0.1. Use a separate formatter environment if the Black dependency in pyproject.toml differs from the CI pin.

From iotdb-core/ainode/, apply and check formatting:

black .
isort --profile black .
black --check .
isort --check-only --profile black .

Targeted verification

  • Existing Python tests use unittest. From this module directory, with the runtime environment active, select the affected test file, for example:

    python -m unittest discover -s tests -p 'test_config.py'

  • Model tests such as tests/test_sundial_flow_loss.py require the relevant ML dependencies. Preserve checkpoint parameter names/shapes and tensor shape/gradient contracts when changing model code. Keep small unit cases independent of model downloads or a running cluster where possible; do not treat a CPU-only run as GPU validation.

  • For registration, RPC, or cluster inference changes, read integration-test/AGENTS.md. The cluster verification setup is in Cluster IT - 1C1D1A: it uses AIClusterIT, with-integration-tests, and with-ainode, and runs on a GPU runner.

Binary packaging

  • AINode is opt-in through with-ainode. From the repository root, build the module and its dependencies with a Python 3.11 executable available under the selected name:

    mvn clean package -pl iotdb-core/ainode -am -P with-ainode -DskipTests -Dpython.exe.bin=python3.11

  • The Maven compile phase invokes build_binary.py, which installs Poetry/dependencies, regenerates poetry.lock, and builds or restores a PyInstaller binary. It is not a lightweight Python syntax check. The script stores its environment and binary cache under ~/.cache/iotdb-ainode-build/ on Unix or %LOCALAPPDATA%\iotdb-ainode-build\ on Windows; TMPDIR and pip cache settings do not relocate that script-managed directory. Check cache placement against the active workspace policy before invoking it.

  • For dependency, dynamic-import, or bundled-resource changes, inspect ainode.spec and ainode.xml and verify the packaged executable, not only imports from the source tree. Keep AINode-specific NOTICE and license resources aligned with the bundled contents.

  • Read distribution/AGENTS.md when changing the final AINode distribution, and scripts/AGENTS.md when changing its launchers.