CortenForge

Shared Rust crates for the CortenForge simulation substrate (capture, ETL, training, inference, and tooling). This repo is library-only; the colon_sim app and other demos now live in their own repositories.

• What’s here: the root cortenforge umbrella crate, core libraries under crates/, and tooling under tools/.
• Example app: see https://github.com/via-balaena/Deep-Poo for a colonoscopy robot sim built with CortenForge.
• Docs:
  • CortenForge book (primary): https://via-balaena.github.io/CortenForge/ (source in docs/cortenforge_book, build with mdbook build docs/cortenforge_book).
  • Legacy contributor/dissection books have been retired.
• User quickstart (apps): clone the app repo (e.g., https://github.com/via-balaena/Deep-Poo), build with cargo run -p sim_view or inference_view, and wire hooks as needed. This repo stays library-only.
• Releases: see RELEASE.md for publish/tag steps.
• License: Apache-2.0 by default; see LICENSE and COMMERCIAL_LICENSE.md.

Repository layout

• Cargo.toml: workspace root + umbrella crate (cortenforge).
• crates/: core and mid‑layer libraries (sim_core, vision_*, data_contracts, models, training, inference, capture_utils, burn_dataset, cli_support).
• tools/: cortenforge-tools crate (app‑agnostic tooling bins and helpers; not bundled by the umbrella crate).
• docs/: books and release material (docs/cortenforge_book is the primary book).
• todo/: local planning (gitignored).

Quick start

• Build/test the crates: cargo test --workspace --locked
• Format: cargo fmt --all
• Docs: mdbook build docs/cortenforge_book
• Tools config: create cortenforge-tools.toml at repo root (or set CORTENFORGE_TOOLS_CONFIG) to customize paths/commands.

Using the crates from crates.io

• Add deps with version = "0.6.0" (examples: cortenforge-sim-core, cortenforge-vision-core, cortenforge-vision-runtime, cortenforge-data-contracts, cortenforge-capture-utils, cortenforge-models, cortenforge-training, cortenforge-inference, cortenforge-cli-support, cortenforge-burn-dataset, cortenforge-tools).
• Umbrella crate: cortenforge is at 0.6.0 (core stacks only; add cortenforge-cli-support and cortenforge-tools directly if needed).
• Feature flags:
  • cortenforge-training: backend-wgpu (optional GPU); defaults to NdArray.
  • cortenforge-inference: backend-wgpu (optional GPU); defaults to NdArray; tinydet/bigdet feature gates.
  • Tools (cortenforge-tools): scheduler, tui, gpu-nvidia.
  • Vision/runtime crates are lean by default; enable only what you need.
• Feature policy: keep defaults light, gate heavy backends/tools behind explicit flags, and document any new feature in the book’s feature matrix.
• MSRV: Rust 1.85+ across crates (CI uses 1.89.0 for toolchain compatibility).
• Note: burn-core is now on the fixed 0.19.1 release; no vendored patch is required.

Versioning

CortenForge follows Semantic Versioning with coordinated releases across all workspace crates:

• Major version (X.0.0): Breaking API changes to stable interfaces (Detector, Recorder, core model types).
• Minor version (0.X.0): New features, non-breaking API additions, experimental API changes.
• Patch version (0.0.X): Bug fixes, documentation updates, internal refactoring.

All crates in the workspace are released together with synchronized version numbers. When upgrading between minor versions, check the CHANGELOG.md for any experimental API changes that may affect your code.

Stability guarantees:

• Stable APIs (marked in docs): Follow strict SemVer. Breaking changes require major version bump.
• Experimental APIs (marked as "experimental" in docs): May change in minor versions. Use with caution in production.

Contributing

See docs/cortenforge_book for architecture, guided app building, and crate deep dives.