Skip to content

Versions And Compatibility

Genja has Rust crates and Python bindings. This page describes the current package layout, version expectations, and how to read docs against releases.

Packages

Package Ecosystem Current role
genja Rust crate Main Rust runtime crate for applications.
genja-core Rust crate Core inventory, settings, task, result, state, and error types.
genja-core-derive Rust crate Procedural macros such as #[genja_task].
genja-plugin-manager Rust crate Plugin traits, registration, dynamic loading, and build helpers.
genja-cli Rust crate CLI library and binary for Rust applications.
genja-py Python distribution Python bindings that expose the genja import package.
genja-cli Python distribution Prebuilt genja executable with TUI support, installed by genja-py[cli] from v0.5.0.
genja-core-python Rust crate Internal PyO3 extension crate that builds the Python package.

See API Surface for which package to depend on.

v0.5.0 Release Versions

The v0.5.0 Rust release aligns these crates:

genja = 0.5.0
genja-core = 0.5.0
genja-core-derive = 0.5.0
genja-plugin-manager = 0.5.0
genja-cli = 0.5.0

The matching Python distribution is:

genja-py = 0.5.0

Until a more formal compatibility policy is published, treat matching minor versions of genja, genja-core, genja-plugin-manager, and genja-py as the supported combination. The v0.5.0 Rust crates, Python package, and CLI wheel share the 0.5.x release line.

Rust Compatibility

Rust applications should usually depend on genja:

[dependencies]
genja = "0.5.0"

The genja crate depends on and re-exports core pieces from the workspace, so most application code does not need direct dependencies on genja-core or genja-core-derive.

Use direct lower-level dependencies when building advanced integrations or standalone plugin crates:

[dependencies]
genja-plugin-manager = "0.5.0"
genja-core = "0.5.0"

When depending on multiple Genja crates directly, keep their versions aligned. Mixing genja 0.5.x with a different genja-core or genja-plugin-manager line is not a supported configuration.

Python Compatibility

Install the Python distribution with:

pip install genja-py

Import it as:

import genja

The Python package is built from the Rust runtime in this repository. Keep the Python package version aligned with the Rust crate version line when combining Python and Rust artifacts in the same project.

Python task discovery through an installed genja command requires genja-py v0.5.0 or later. The cli extra installs a matching prebuilt genja-cli wheel:

python -m pip install "genja-py[cli]>=0.5.0,<0.6.0"

The v0.5.x extra requires genja-cli>=0.5.0,<0.6.0; the base genja-py installation remains library-only. Supported wheel targets are CPython 3.10–3.14 on Linux x86_64, macOS arm64 or x86_64, and Windows x64. No CLI source distribution is published, so unsupported platforms cannot build it as a pip fallback.

During release preparation, bump the genja-py package, the genja-core-python and genja-cli crates, and the extra's version range together. The CLI wheel version must match the genja-py release.

Docs And Releases

The docs in the repository default branch describe the current development state. For release-specific behavior, use the docs or source for the matching release tag, such as:

git checkout rs-v0.5.0

When running repository examples for a specific release, check out the matching tag before running commands from Examples.

Compatibility Notes

  • Task result JSON has normalized and raw forms. Consumers should prefer normalized output unless they explicitly need raw enum-shaped data.
  • Plugin names and groups are runtime contracts. Renaming a plugin or changing its group is a compatibility-impacting change.
  • Task macro behavior is part of the Rust task authoring surface. Changes to #[genja_task] should be treated as API changes.
  • Python task and plugin base classes are public authoring APIs. Changes to method names or result shapes affect Python users.