alef 0.24.12

Opinionated polyglot binding generator for Rust libraries
Documentation

Alef

Alef is the polyglot binding generator behind Kreuzberg.dev projects. It extracts a Rust API surface and emits language-native bindings, package scaffolding, type stubs, README files, API docs, e2e tests, and release metadata from one alef.toml.

Installation | Quick Start | Supported Targets | CLI Reference

Key Features

  • One source of truth - Configure a Rust workspace once and generate every enabled language target from it.
  • Language-native bindings - Emit host-language types, docs, errors, async wrappers, callbacks, and package files.
  • Multi-crate workspaces - Drive multiple independently published binding packages from a shared workspace config.
  • End-to-end fixtures - Generate cross-language test suites and registry-mode test apps from shared JSON fixtures.
  • Release-aware packaging - Sync versions, generate registry metadata, build artifacts, and validate publication state.
  • Configurable pipelines - Run setup, update, format, lint, test, clean, build, and publish commands per language.
  • Staleness checks - Cache inputs, embed generation hashes, and verify whether generated files are up to date.

Installation

Alef requires Rust 1.85 or newer.

cargo install alef --locked

If you use cargo-binstall, Alef also publishes binary-install metadata:

cargo binstall alef

Quick Start

Create or edit alef.toml in your Rust workspace:

[workspace]
languages = ["python", "node", "ffi", "go"]
alef_version = "0.24.12"

[[crates]]
name = "sample_core"
sources = ["src/lib.rs"]
version_from = "Cargo.toml"

Then generate the language packages:

alef generate --format
alef scaffold
alef readme
alef docs --output docs/reference
alef verify --exit-code

For a new project, Alef can create the initial config and first generated files:

alef init --lang python,node,ffi

For the full local generation pass, use:

alef all --format

Use --lang python,node to restrict commands to selected targets and --crate <name> to restrict commands to one configured crate.

Supported Targets

Target Backend / package style
Python PyO3 bindings with Python type stubs
TypeScript / Node.js NAPI-RS native addon with .d.ts output
WebAssembly wasm-bindgen package for browser and JS runtimes
Ruby Magnus native extension
PHP Native PHP extension
Elixir Rustler NIF package
R extendr package
Go cgo package over the generated C FFI layer
Java JVM package over the generated native library
Kotlin Kotlin/JVM package over generated native bindings
Kotlin Android Android package with generated JNI shims
C# .NET package using P/Invoke
Dart / Flutter flutter_rust_bridge package
Swift Swift package with Rust bridge support
Zig Zig package over the generated C ABI
Gleam Gleam package backed by Rustler
C FFI C ABI, header, and shared-library glue
JNI Rust JNI shim crate for Android-facing APIs

Canonical language slugs are python, node, wasm, ruby, php, elixir, r, go, java, csharp, kotlin, kotlin_android, swift, dart, gleam, zig, ffi, and jni.

Configuration Model

Alef uses the current multi-crate schema:

  • [workspace] stores shared target languages, tool preferences, and pipeline defaults.
  • [[crates]] describes each Rust API surface that should become one or more published packages.
  • [crates.<language>] sections customize module names, package names, feature flags, output paths, field naming, dependency extras, and language-specific generation behavior.
  • [[crates.adapters]], trait bridge config, service API config, and e2e config opt into higher-level generated wrappers when a target supports them.

Generated binding files carry Alef hashes and are overwritten by generation commands. Scaffolded package files are generated once unless the command explicitly opts into overwrite behavior; generated README and API doc files are owned by alef readme and alef docs.

CLI Reference

Command Purpose
alef init Create alef.toml, generate initial bindings, and scaffold package files.
alef extract Extract Rust source into Alef IR JSON.
alef generate Generate bindings, service API wrappers, public API wrappers, and type stubs.
alef stubs Generate type stubs only.
alef scaffold Generate package manifests, native build files, and package scaffolding.
alef readme Generate per-language README files.
alef docs Generate Markdown API reference pages.
alef setup Install per-language development dependencies.
alef fmt / alef lint Run configured formatters, linters, and type checks.
alef test Run configured unit, integration, e2e, or coverage test commands.
alef build Build language bindings using native tools.
alef verify Check generated files and optional compile/lint state for CI.
alef diff Show what generation would change without writing files.
alef e2e Initialize, scaffold, validate, list, or generate local e2e suites.
alef test-apps Generate and run standalone registry-mode test applications.
alef publish Prepare, build, package, and validate release artifacts.
alef all Run the full generation workflow in one command.

Run alef --help or alef <command> --help for the full option set.

Development

This repository uses task for common workflows:

task setup
task build
task test
task lint

The most useful targeted commands while working on Alef itself are:

cargo test <module_or_test_name>
cargo insta review
prek run --all-files

Part of Kreuzberg.dev

  • Kreuzberg - document intelligence for text, tables, metadata, OCR, and code intelligence.
  • Kreuzberg Cloud - managed extraction API with SDKs, dashboards, and observability.
  • kreuzcrawl - web crawling and scraping with HTML-to-Markdown and headless Chrome fallback.
  • html-to-markdown - fast, lossless HTML-to-Markdown conversion.
  • liter-llm - universal LLM API client with native bindings.
  • tree-sitter-language-pack - tree-sitter grammars and code-intelligence primitives.
  • Discord - community, roadmap, and release discussion.

License

MIT - see LICENSE for details.