Incin
Incin is a deep learning framework in Rust focused on compile-time shape verification, developer ergonomics, and native multi-backend execution.
Incin enforces shape and type bounds at compile time to prevent tensor shape mismatches and runtime out-of-bounds panics.
Features
- Compile-Time Shape Verification: Tensor shapes can be statically tracked using
s![]macros, catching dimension and matrix multiplication mismatches at build time. - Named Dimensions:
symbolic_dim!(Batch, Seq, Feature)gives an axis a name that's part of its type —Tensor<s![Batch, Feature]>andTensor<s![Batch, Seq]>are different types even when both axes are the same runtime size, so passing one where the other is expected is a compile error, not a silently-wrong result. Unlike PyTorch's named tensors (runtime, opt-in, easy to bypass), a Incin name can't be forgotten — seecrates/incin/examples/named_dims_safety. - Python-Style Slicing: Expressive index manipulation macros (
idx![]) enable Python-like slicing and dynamic index selection. - ONNX Model Importing: Convert ONNX models directly into fully-typed Rust module structs at compile time with
import_model!. - Multi-Backend Support: Abstract
Backenddesign with native execution implementations for CPU, CUDA, and WGPU, plus Candle interop vialegacy. - Parallel Data Loading: Efficient multi-threaded batching and data loading (
incin-data). - Telemetry & Visualization: Real-time graph extraction and terminal UI visualization tools (
incin-telemetryandincin-viz).
Setup & Requirements
Incin serializes ONNX protocol graphs natively using Protocol Buffers. Building the workspace requires the Protocol Buffers compiler (protoc).
Ubuntu / Debian
macOS (Homebrew)
Environment Variables
INCIN_HUB_CACHE_DIR: Specifies a custom cache directory for downloaded models (defaults to~/.cache/huggingface/hub).INCIN_HUB_TOKEN: Authorization token for downloading private HuggingFace Hub repositories.INCIN_NO_META: Set to1to bypass.incin_metacache and force full ONNX graph re-parsing during macro compilation.
Quick Start
Tensor Creation & Shape Macro
use *;
// Statically dimensioned 2x3 tensor on default CPU backend
let static_tensor: > = zeros?;
// Dynamically dimensioned tensor
let dynamic_tensor: = zeros?;
Module Definition & Forward Pass
use *;
Slicing with idx!
use *;
let t = zeros?;
let sliced = t.slice?;
ONNX Model Import
use *;
import_model!;
Workspace Crates
incin: Primary facade crate providing unified imports and prelude, plus thecargo-incinCLI binary.incin-core: Statically-typedTensorimplementation, traits, and graph definitions.incin-backends: Native CPU, CUDA, WGPU, and legacy Candle execution engines.incin-macros: Procedural macros (s!,idx!,module,import_model!).incin-data: Data loading utilities, dataset traits, and HuggingFace Hub support.incin-telemetry: Event emission, transport streams, and graph snapshot recording.incin-viz: Terminal UI (TUI) model graph visualizer.incin-diagnostics: Typenum-to-decimal shape diagnostic humanization, shared by the CLI and the editor LSP proxy — see CLI and Editor / IDE Support below.incin-lsp: Transparent LSP proxy that routes rust-analyzer throughincin-diagnosticsso shape errors and inlay hints are humanized live in your editor.
CLI — cargo incin
cargo-incin wraps cargo check/build/test/run, rewriting the
compiler's typenum shape errors (UInt<UInt<...>> walls) into plain decimals
live in your terminal — the same translation the editor extensions use. It
also inspects exported model files and translates pasted error text ad hoc.
Install
This builds and installs the cargo-incin binary (the crate's only binary
target); invoke it as cargo incin <subcommand> from any Incin project.
Usage
Flags: --raw (skip translation, show the compiler's raw output), --explain
(append a plain-English shape-rule explanation for common errors), --help.
Editor / IDE Support
The same humanization is available live inside your editor via incin-lsp,
a thin proxy that sits between your editor and rust-analyzer and rewrites
diagnostics and shape inlay hints through incin-diagnostics before they
reach you — no forked rust-analyzer, no per-editor parsing logic. See
docs/growth/02-ide-extensions.md for the full architecture and verification
status of each client below.
| Editor | Status | Install guide |
|---|---|---|
| VS Code | Ships; activation + rust-analyzer config-rewriting verified by an automated test against a real VS Code (npm test). Full humanized-diagnostic pipeline (real incin-lsp + rust-analyzer) not yet exercised end-to-end |
editors/vscode/README.md |
| Neovim (0.11+, or nvim-lspconfig on older versions) | Verified against a real Neovim install | editors/nvim/README.md |
| RustRover / IntelliJ | External-tool fallback verified; native LSP-mode integration unverified | editors/rustrover/README.md |
VS Code and Neovim both need the proxy on PATH first (RustRover's shipped
fallback only needs the CLI above):
Documentation
- Growth & architecture plans (
docs/growth/): task-by-task execution plans for adoption-facing features — named dimensions, this CLI/IDE tooling, deployment, and more — each with its own dated status ledger. - The Book ("Incinnomicon"): planned, not yet built. See
docs/growth/07-the-book.mdfor the full chapter outline; it will ship as an mdBook atdocs/book/, built withmdbook build docs/book, deployed to GitHub Pages. Until it lands, this README, the growth docs, andcrates/incin/examples/are the best starting points.
License
Dual-licensed under either MIT or Apache 2.0.