Pure-Rust, zero-dependency .gguf deserializer and
Mixture-of-Experts per-expert weight extractor.
- Parses the GGUF file format (magic, version 3 header, KV metadata,
tensor directory) into an in-memory [
GgufLayout]. - Enumerates MoE experts discovered in the checkpoint.
- Rips out the raw byte buffers for any single expert's
gate,up, anddownprojections — supporting both the stacked (blk.{B}.ffn_{role}_exps.weight) and per-expert (blk.{B}.ffn_{role}.{E}.weight) on-disk conventions.
- No neural-network math. No
matmul, noforward, no routing, no softmax, no dequantization in the default build. F16→F32 bit conversion is available as an optional helper only. - No CUDA, no GPU, no SIMD.
- No runtime dependencies.
[dependencies]is intentionally empty.
This crate owns:
- GGUF v3 deserialization (header, KV metadata, tensor directory).
- Safetensors header deserialization, deterministic manifests, and MoE
router/expert candidate discovery — single file, Hugging Face shard index,
or directory. Cargo feature
safetensors, off by default; port in flight, see #10. - MoE expert enumeration (
list_experts). - Per-expert raw weight extraction (
extract_expert— gate/up/down byte buffers with shape and dtype metadata). - Zero-dependency, layout-aware dtype handling (F32/F16/BF16 plus opaque quant types as raw bytes).
This crate does not own:
- Neural-network math (matmul, forward, routing, softmax, dequantization in the default build).
- CUDA/GPU/SIMD execution.
- Tokenization, inference orchestration, or SNN dynamics.
- Full checkpoint routing or model-family adapters (see
cortex-tensor). - Safetensors payload loading (mmap tensor extraction) and Hugging Face
config.jsoninterpretation — those stay corinth-specific (src/moe/safetensors/{map,config}.rs) and are not ported.
Allowed dependencies: none — [dependencies] stays empty in every
feature combination, including --features safetensors. The safetensors
header and HF shard-index JSON parsers are hand-written; the upstream
safetensors and serde_json crates are forbidden dependencies.
Forbidden dependencies: inference engines, GPU backends, domain-specific adapters.
| Crate | Role |
|---|---|
engram-parser |
GGUF parse + per-expert weight extraction; feature-gated safetensors header parse, manifest, and discovery (no payload) |
cortex-tensor |
Tensor math + MoE routing on extracted weights |
hybrid-fusion |
ANN→SNN orchestration |
neuromod |
SNN neuron dynamics (downstream consumer) |
See LIM-9 for the full Rust runtime/deployment boundary matrix and issue #4 for this repo's tracking issue.
Charter note (2026-08): earlier revisions of this section and of #10 said the charter was "GGUF-only" and that safetensors would live in a separate
safetensors-parsercrate. Superseded — see Origin / modularization (#10).
GGUF layout parsing and MoE expert raw byte extraction were expanded
using one-way inspiration from the experimental
rmems/corinth-canal reference
implementation (no runtime dependency on corinth-canal).
- Tracking: engram-parser#7
- Corinth migration companion: corinth-canal#115
- Cortex coordination: cortex-tensor#8
- Linear: LIM-123, LIM-88
GGUF wire types vs “GGML”: GGUF stores each tensor’s dtype as a
ggml_type integer. This crate only maps those codes to labels and packed
byte sizes so payloads and MoE slices stay in-range. It does not
implement GGML dequant, kernels, or the ggml runtime (that stays
downstream / corinth-canal reference). Wire-type labels follow the
corinth-canal table (e.g. type 31 is historical Q4_0_4_4, not the
HuggingFace “IQ3_M” preset). MoE extraction remains free functions
(list_experts / extract_expert); traits are out of scope for #7.
Safetensors header inspection, deterministic manifest generation, and MoE
router/expert candidate discovery will be ported using one-way inspiration
from the same rmems/corinth-canal
reference implementation (no runtime dependency on corinth-canal, in
either direction). Set to port: manifest, discovery, json, paths,
validate from src/moe/safetensors/. Not ported: config (HF
config.json) and map (mmap load / token extraction) — corinth-specific.
Status: planned, not shipped. This section records the decision. No safetensors code has landed yet and there is no
safetensorscargo feature to enable —cargo build --features safetensorswill fail until the port lands. Track progress on #10.
- Tracking: engram-parser#10
- Corinth extraction companion: corinth-canal#116, unblocked by corinth-canal#147 (that module split drew this exact boundary in code)
- Consumer coordination: cortex-tensor#9, hybrid-fusion#27
- Linear: RM-344, LIM-9
Charter reversal (2026-08). #10, this README, corinth's
docs/MODULE_STATUS.md, and cortex-tensor#9 all previously stated that the
reusable safetensors surface would land in a dedicated safetensors-parser
crate and that "engram-parser charter remains GGUF-only." That is
reversed. The charter was never "GGUF" — it is zero-dependency checkpoint
deserialization plus MoE raw-weight extraction, and safetensors header
inspection is exactly that shape: header-only parse, deterministic manifest,
name/shape candidate discovery — tensor names, dtypes, shapes, shard
attribution and byte offsets out; no payload bytes, no math, no mmap. A separate
crate would have duplicated this crate's error type, dtype model, MSRV policy,
CI, Docker, and release plumbing to host ~1.4k lines that share every one of
its invariants, and
hybrid-fusion#27 already
names engram-parser as the home for concrete safetensors loaders. The
safetensors cargo feature provides the same isolation a separate crate would
have: default builds are unchanged and GGUF-only, and [dependencies] stays
empty in every feature combination. No safetensors-parser repo was or will
be created.
Unchanged from the original plan: one-way copy from inspiration; no dep
on corinth-canal, and — for safetensors specifically — no corinth dep on
this crate either; corinth keeps an unmodified reference copy of
src/moe/safetensors/ and keeps using it in its Router / CheckpointBackend
experiment paths. (GGUF is the opposite case: corinth intends a real
engram-parser dependency there, see
corinth-canal#115.) This is not a
PROMOTION_RULES.md "frozen" handoff — see that file's One-way extractions
section.
use engram_parser::{extract_expert, list_experts, load_gguf};
let layout = load_gguf("./model.gguf")?;
println!("architecture = {}", layout.metadata.architecture());
for (block, expert) in list_experts(&layout) {
let weights = extract_expert(&layout, block, expert)?;
if let Some(gate) = &weights.gate {
println!("blk.{block}.expert{expert}.gate: dims={:?} dtype={:?} bytes={}",
gate.dims, gate.dtype, gate.bytes.len());
}
}
# Ok::<(), engram_parser::ParserError>(())Layout-aware parsing (packed byte sizes only — no dequant, no GGML
compute) for GGUF wire types: F32, F16, BF16 (30), F64,
I8–I64, Q4_0/Q4_1, Q5_0/Q5_1, Q8_0/Q8_1, K-quants
Q2_K/Q3_K/Q4_K/Q5_K/Q6_K/Q8_K (no Q7_K), and IQ packed
layouts IQ2_XXS/IQ2_XS/IQ2_S, IQ3_XXS/IQ3_S, IQ1_S/IQ1_M,
IQ4_NL/IQ4_XS. Remaining codes use DType::Other(u32) (including
historical wire type 31 = Q4_0_4_4, which is not HF “IQ3_M”
and fails closed without a modeled size).
Only F32 and F16 have in-crate numeric accessors; everything else
is returned as raw Vec<u8>. Unknown layouts fail closed at parse time
when element count cannot be converted to a byte length.
GgufMetadata::quantization() prefers general.quantization_type, then
falls back to general.file_type (0→F32, 1→F16, else GGUF(n)).
load_gguf, parse_bytes, GgufLayout, GgufMetadata, Tensor,
DType, ggml_type_label, extract_expert, list_experts,
MoeExpertWeights, RawTensor, ParserError, Result, plus public
GGML_TYPE_* and GGUF_VALUE_TYPE_* constants.
- engram-parser (this crate): the canonical zero-dep GGUF v3 deserializer +
per-expert MoE raw weight ripper (shipped). Safetensors header parsing —
manifest + candidate discovery only, no payload extraction — is planned
behind a
safetensorscargo feature that does not exist yet; see #10. - There is no sibling parser crate. The plan to ship safetensors from a
dedicated
safetensors-parsercrate is superseded (2026-08); see Origin / modularization (#10). Normems/safetensors-parserrepo exists or will be created. - Clarification (unchanged): one-way extraction/copy of code from
inspiration. We add no dependency on
rmems/corinth-canal, and corinth-canal adds no dependency on this crate for safetensors. corinth-canal keeps an unmodified reference copy ofsrc/moe/safetensors/and keeps using it. - Source-side tracking: corinth-canal#116
(safetensors extraction) and corinth-canal#115
(GGUF). Note the asymmetry: corinth intends a real
engram-parserdependency for GGUF in #115, gated on #45; safetensors is a copy, never a dependency, and is not gated on #45 because that surface is header-only. - Consumer coordination: cortex-tensor#9 (closed as duplicate; its premise is superseded by this decision) and hybrid-fusion#27, which already names this crate as the home for concrete GGUF/safetensors loaders.
This is a pure-Rust, zero-dependency crate. Build, lint, and test commands use --all-features.
# Format
cargo fmt --check
# Lint (fail on warnings)
cargo clippy --all-targets --all-features -- -D warnings
# Build
cargo build --all-features
# Test
cargo test --all-features
# Coverage (local; requires cargo-llvm-cov: cargo install cargo-llvm-cov)
cargo llvm-cov --all-targets --all-features --locked --lcov --output-path lcov.info
# Real GGUF pilots (xai-dissect style; not CI — needs weights on disk)
# Full-file load (no mmap): one ENGRAM_GGUF per process; free RAM ≥ file size + margin
ENGRAM_GGUF=~/.models/gguf/.../model.gguf cargo test --test real_gguf -- --ignored --nocapture
# Large MoE: ENGRAM_EXPECT_MOE=1 ENGRAM_MOE_SAMPLES=3 (see REVIEW.md T1 large MoE)
cargo run --example inspect_gguf -- ~/.models/gguf/.../model.ggufGPU experiments on real models live in ~/rmems/blackwell-kernel-lab
(and production kernels in myelin-accelerator) — not as deps of this crate.
See REVIEW.md for the T0/T1/T2 quality-gate layout.
# Build the image locally (includes build + test verification)
docker build -t engram-parser .
# Run tests in the container
docker run --rm engram-parser
# Pull from GHCR (published on merges to main)
docker pull ghcr.io/rmems/engram-parser:main- GitHub Actions:
.github/workflows/ci.yml(hardened via #11; uses Codecov per https://about.codecov.io/language/rust/) - Security:
.github/workflows/security.yml(RustSec audit always runs; Snyk SCA+SAST opt-in viaSNYK_TOKENsecret, see #12) - Azure Pipelines:
azure-pipelines.yml(tracked in #8 for cross-platform ubuntu/mac/windows) - Docker:
Dockerfile+.github/workflows/docker-build.yml(tracked in #9 for GHCR reproducible builds; use user's Docker CLI for local verification) - Other CI/DX issues: #13 (releases on tags w/ sentry option), #14 (MSRV), #15 (Dependabot no auto-merge), #16 (layout clean)
See the issue bodies for full ACs and corinth-canal inspiration patterns (one-way copy only; no dep on corinth-canal).
Cross-reference: #11, #8, #9, #7, #10, #5, LIM-9.
MSRV: 1.97.1 (current stable floor as of 2026-08)
This crate guarantees compatibility with Rust 1.97.1 and later. The MSRV is:
- Declared in
Cargo.tomlviarust-version = "1.97.1" - Tested in CI on every PR and push (see
msrvjob in.github/workflows/ci.yml) - Verified alongside stable (always latest) in the
validatejob so both toolchains pass
Local development defaults to the toolchain in rust-toolchain.toml
(stable + rustfmt / clippy).
MSRV Policy:
- MSRV bumps will be documented in release notes
- Bumps are considered breaking changes and follow semver conventions
- Justification is required when bumping MSRV (e.g., dependency requirements, critical features)
See issue #14 for the full MSRV policy discussion.
This repository intentionally does not use a GitHub Wiki; documentation lives in
README.md and REVIEW.md.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE-2.0 or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.