static_embeddings 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a6d1a316162408c80a3de7afce3e1bc1f6e7cce0707c58df8737c86e0748183
+  data.tar.gz: c6e117117e09740437da333ec7203b62695b53233d5f64caa8cd15cc16f82d7c
+SHA512:
+  metadata.gz: 274b82bff6ffbe3f650687b9e30a611c919ffeedea859d98864857d095100f0142f3ed56954b9420eddf17ab9aac1d879dcf7648539af9a852c4d4a08df150c3
+  data.tar.gz: e9f11243e8e73ea99ab215620fa024b7cf78ccae8c5e9b2bb1d06dd88e60862fadaa37b8d2fb56b2251740a474c5d556f262e827b35ec898b1dfeadac938fc3d

data/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+## 0.1.1 (unreleased)
+
+Safety and correctness release. Everything here was found by re-reviewing 0.1.0
+against a built extension rather than against the source, and every item has a
+regression test that fails on 0.1.0.
+
+### Fixed
+
+- **Concurrent `top_k` on a shared matrix (blocker).** 0.1.0 wrapped the matrix
+  in `rb_str_locktmp` before releasing the GVL. That is an exclusive lock, so a
+  second thread searching the same corpus got
+  `RuntimeError: temporal locking already locked string` - 900 failures out of
+  1200 calls with four threads over a 51 MB matrix. The lock is gone. A matrix
+  at or above 1 MiB must now be `frozen`, which makes mutation impossible and
+  lock-free concurrent scanning safe. A large unfrozen matrix raises
+  `ArgumentError`; `allow_unfrozen: true` scans it while holding the GVL.
+- **`embed_batch` read the caller's Array after releasing the GVL (blocker).**
+  Elements were validated once and then re-read on every round, so another
+  thread replacing an element with a non-String turned a later `RSTRING_LEN`
+  into undefined behaviour - a reproducible `[BUG] Segmentation fault` from
+  ordinary Ruby. Input is now snapshotted into a private Array before any GVL
+  release, and the caller's Array is never read again.
+- **Silent `f32`/`f16` mixing.** An `f32` query against an `f16` matrix used to
+  divide out to a consistent row count and return plausible garbage.
+  `StaticEmbeddings.cosine_top_k` / `dot_top_k` now require `dim:` and check the
+  query length against it. `Model#cosine_top_k` / `Model#dot_top_k` supply
+  `dim:` automatically and are the recommended form.
+- **Prefix cutting only worked on ASCII.** The cut had to land on an ASCII
+  whitespace or punctuation byte, so CJK and NBSP-separated documents grew the
+  budget to the full length and copied the whole input under the GVL - cost
+  scaled linearly with input size again. `se_prefix_boundary_len` now uses the
+  tokenizer's own predicates: ASCII and Unicode whitespace, ASCII and Unicode
+  punctuation, and either side of a CJK codepoint, skipping any codepoint the
+  normaliser rewrites. A 24 MB CJK document went from 2.24 ms to 0.10 ms and is
+  byte-identical to `embed_token_ids(tokenize(text))`.
+- A large unaligned matrix is rejected instead of being silently copied in full
+  while holding the GVL.
+- **`f16` top-k was scalar and unusably slow on large corpora.** Half-precision
+  rows are now decoded with AArch64 `FCVTL` / x86 `VCVTPH2PS` kernels when
+  available, and with a lookup-table fallback otherwise. Measured on x86 with
+  F16C at dim 512 over 20k rows: 55 -> 978 ops/s, which is also 1.8x the `f32`
+  scan since it moves half the bytes. The fallback alone is 220 ops/s.
+- The AArch64 kernel was gated on `__ARM_FEATURE_FP16_VECTOR_ARITHMETIC`, which
+  is only defined with an explicit `-mcpu`. Default builds - including
+  `rake compile` on Apple silicon - therefore fell back to the lookup table.
+  `vcvt_f32_f16` is baseline AArch64, so the gate is now just `__aarch64__`.
+- The half-precision lookup table (256 KB) is populated only when the fallback
+  kernel is selected; native builds never touch those pages.
+- `cosine_top_k` scored a row containing `NaN` as `0.0`, making a corrupt row
+  indistinguishable from a zero-norm one, while `dot_top_k` dropped it. Both
+  now drop it.
+- `cold_start` reported `cold_page_cache=likely` from a ratio that cannot tell a
+  page-cache read from a device read - it said "cold" while faulting 132 MB in
+  4.3 ms. It now reports `warmup_mapped_bytes_per_sec` and
+  `page_cache_state=unknown` with instructions for a real cold measurement.
+- The valgrind job no longer passes `--undef-value-errors=no`. The harness is
+  pure C with no Ruby noise, so the flag only hid the class of bug most likely
+  in a parser reading an mmapped file.
+
+### Added
+
+- `StaticEmbeddings.encode_f16` / `decode_f16`: the storage codec that backs
+  `format: :f16`, exposed directly and covered by table tests for zero, negative
+  zero, subnormals, the smallest normal, the largest finite half, overflow to
+  infinity, mantissa carry and NaN. `Ruby`'s duplicate half decoder in `unpack`
+  was deleted; there is now one implementation.
+- `StaticEmbeddings.pack`, the inverse of `unpack`.
+- `StaticEmbeddings.simd_backend`, reporting the live `f16` kernel.
+- `Model#cosine_top_k`, `Model#dot_top_k`.
+- `test/top_k_contract_test.rb`, `test/input_snapshot_test.rb`,
+  `test/f16_codec_test.rb`, and Unicode-boundary cases in
+  `test/prefix_chunking_test.rb`.
+
+### Changed
+
+- `se_scratch_reserve` no longer takes an `input_bytes` argument it ignored.
+- README documents the frozen-matrix contract, the required `dim:`, the
+  non-ASCII prefix fallback, `verify: true` at artifact-entry time, the
+  `embed_batch` peak-memory factor of two, and that `load_builtin` is a
+  checkout-only fixture.
+
+## 0.1.0
+
+First working cut of the runtime and the offline converter.
+
+- `.semb` v2 container: 320-byte header, 64-byte aligned sections, SHA-256
+  over the file with the checksum field zeroed, mandatory provenance section.
+- C runtime: mmap loader with full bounds validation, read-only
+  open-addressing vocabulary hash table straight out of the mapping,
+  `BERT_WORDPIECE_V1` tokenizer, f32 mean pooling with optional L2
+  normalisation, binary vector output with `format: :f32` by default and compact
+  `format: :f16` storage for single embeddings, batches, and token-id pooling.
+- Model semantics (`max_tokens`, unk policy, empty policy, normalizer flags)
+  are header fields, not hardcoded assumptions. Default truncation is 512
+  tokens, matching `model2vec.StaticModel` rather than `model_max_length`.
+- Unicode tables (NFD, simple lowercase, Mn/P/C/Zs ranges) are generated by
+  the converter and shipped inside the model file. No utf8proc, no vendored
+  dependency of any kind.
+- Concurrency: GVL released for batches above 2 KB, real-thread hand-off when
+  a `Fiber::Scheduler` is installed; internal `threads:` fan-out is intentionally rejected.
+- Large inputs are not copied whole. When truncation is active `embed` and
+  `embed_batch` copy a leading slice sized from `max_tokens`, cut on a word
+  boundary, and grow it only if that slice did not reach `max_tokens`. Cost per
+  call stops scaling with input size (3 MB behaves like 10 KB).
+- `cosine_top_k` returns real cosine similarity; `dot_top_k` returns the raw dot
+  product. They are separate kernels, not aliases. Both skip `NaN` rows and
+  accept `format: :f16` when query and matrix blobs are half-precision encoded.
+- `embed_token_ids` / `embed_token_ids_with_stats` pool a caller-supplied id
+  array, honouring `max_tokens` truncation.
+- Strict fail-closed converter: refuses non-WordPiece models, unknown
+  normalizer or pre-tokenizer types, non-standard `added_tokens`, and any
+  vocabulary/matrix size mismatch.
+- CLI: `convert`, `verify`, `inspect`, `tokenize`, `embed`, `cache-path`.
+- Tiny demo model is generated by `bundle exec rake demo_model` for smoke tests.
+- Test suite runs offline against a synthetic source model: format fuzzing over
+  the whole file, tokenizer parity and fuzzing against a pure-Ruby reference,
+  vector tolerance, converter determinism, batch/thread determinism, GVL
+  release, and the large-input prefix path (including a sweep over every
+  printable ASCII separator).
+- `tools/model2vec_oracle.py` and `tools/check_model2vec_parity.rb` compare
+  token ids and vectors against Python `model2vec.StaticModel`. Run via
+  `rake parity`.
+
+### Known gaps
+
+- `format: :f16` is a storage encoding, not a new model. The runtime computes in
+  float32, converts the returned blob to IEEE float16, and decodes half-precision
+  top-k inputs on the fly. Use `format: :f32` when exact float32 parity is needed.
+
+### Not in this release
+
+- int8 weights (the format has the slot, the runtime has no path)
+- SIMD distance kernels
+- SentencePiece / Unigram tokenizers

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Roman Haydarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,439 @@
+# static_embeddings
+
+`static_embeddings` is a Ruby runtime for converted Model2Vec / potion static embedding models.
+The current production target is `minishlab/potion-retrieval-32M` converted once into a local `.semb` file and loaded through a small C extension.
+
+Runtime goals:
+
+- no ONNX Runtime;
+- no Rust or Python dependency at runtime;
+- no runtime network access;
+- no HuggingFace parsing in the hot path;
+- one mmap-able model file;
+- binary float32 output suitable for storing or passing to a vector index.
+
+```ruby
+require "static_embeddings"
+
+model = StaticEmbeddings.load_model("potion-retrieval-32m")
+
+blob = model.embed("postgres pipeline mode in Ruby")
+blob.bytesize == model.dim * 4
+
+batch = model.embed_batch([
+  "postgres pipeline mode in Ruby",
+  "local static embeddings without ONNX Runtime"
+])
+
+batch.bytesize == 2 * model.dim * 4
+```
+
+## Runtime contract
+
+The runtime does not load arbitrary HuggingFace models. It loads only `.semb` files produced by this repository's converter.
+
+A `.semb` file contains:
+
+- validated model metadata;
+- a BERT WordPiece tokenizer profile;
+- a mmap-ready vocabulary lookup table;
+- float32 embedding rows;
+- provenance and checksum data;
+- the Model2Vec inference decisions needed by the C runtime.
+
+The first supported tokenizer profile is `BERT_WORDPIECE_V1`. The converter must reject unsupported tokenizer features instead of approximating them.
+
+## Current model workflow
+
+The expected workflow for `potion-retrieval-32M` is explicit.
+
+```bash
+git lfs install
+git clone https://huggingface.co/minishlab/potion-retrieval-32M
+
+bundle exec rake compile
+
+bundle exec ruby -Ilib exe/static_embeddings convert ./potion-retrieval-32M \
+  --id potion-retrieval-32m
+```
+
+The converted model is written to:
+
+```text
+~/.cache/static_embeddings/models/potion-retrieval-32m.semb
+```
+
+Inspect and verify it:
+
+```bash
+bundle exec ruby -Ilib exe/static_embeddings inspect \
+  ~/.cache/static_embeddings/models/potion-retrieval-32m.semb
+
+bundle exec ruby -Ilib exe/static_embeddings verify \
+  ~/.cache/static_embeddings/models/potion-retrieval-32m.semb
+```
+
+Load it from Ruby:
+
+```ruby
+model = StaticEmbeddings.load_model("potion-retrieval-32m")
+```
+
+Or load the file directly:
+
+```ruby
+model = StaticEmbeddings.load(
+  File.expand_path("~/.cache/static_embeddings/models/potion-retrieval-32m.semb")
+)
+```
+
+`load` does not verify the SHA-256 by default: hashing a 135 MB file on every
+boot would undo the point of mmapping it lazily. Structural validation always
+runs, so a malformed container is rejected, but a bit flip inside the matrix is
+not detected and silently changes the vectors. Verify once where the artifact
+enters your system - during the image build, in CI, or right after conversion -
+and load without verification at runtime:
+
+```ruby
+StaticEmbeddings.load(path, verify: true)   # image build / CI
+StaticEmbeddings.load(path)                 # hot path, artifact already trusted
+```
+
+## Demo model
+
+A tiny demo model can be generated for smoke tests without network access or external model files.
+
+```bash
+bundle exec rake demo_model
+```
+
+```ruby
+model = StaticEmbeddings.load_builtin
+```
+
+`load_builtin` only works inside a checkout after `rake demo_model` has run. The
+demo model is a build artifact, it is not shipped in the published gem, and
+`StaticEmbeddings.builtin_available?` returns `false` when it is missing. Treat
+it only as a test fixture and API demo. Do not use it as a retrieval quality
+baseline.
+
+## API
+
+```ruby
+model.path
+model.dim
+model.vocab_size
+model.max_tokens
+model.normalized?
+model.lowercase?
+model.unk_id
+model.mapped_bytes
+model.provenance
+model.model_id
+
+vector_blob = model.embed("postgres pipeline mode in Ruby")               # f32 by default
+small_blob  = model.embed("postgres pipeline mode in Ruby", format: :f16) # half-size storage
+array       = model.embed_array("postgres pipeline mode in Ruby")
+
+batch_blob  = model.embed_batch(texts)
+small_batch = model.embed_batch(texts, format: :f16)
+arrays      = model.embed_batch_arrays(texts)
+
+stats = model.embed_with_stats("postgres pipeline mode in Ruby")
+stats[:vector]
+stats[:token_count]
+stats[:unk_count]
+stats[:truncated]
+
+ids = model.tokenize("postgres pipeline mode in Ruby")
+
+vector_blob = model.embed_token_ids(ids)
+stats       = model.embed_token_ids_with_stats(ids)
+
+model.cosine_top_k(query_blob, matrix_blob, 10)
+model.dot_top_k(query_blob, matrix_blob, 10)
+
+StaticEmbeddings.cosine_top_k(query_blob, matrix_blob, 10, dim: model.dim)
+StaticEmbeddings.cosine_top_k(query_f16, matrix_f16, 10, dim: model.dim, format: :f16)
+
+StaticEmbeddings.pack(rows, format: :f16)     # Array(s) of Float -> blob
+StaticEmbeddings.unpack(blob, model.dim)      # blob -> Array of Array(Float)
+```
+
+Default embedding output is a binary `String` containing little-endian float32 values in row-major order.
+Pass `format: :f16` to `embed`, `embed_batch`, `embed_with_stats`, `embed_token_ids`,
+or `embed_token_ids_with_stats` when you want IEEE float16 storage instead. For a
+512-dimensional model this changes one vector from `512 * 4 = 2048` bytes to
+`512 * 2 = 1024` bytes. The model still computes in float32; `format:` only
+controls the returned storage encoding.
+
+`embed_array` and `embed_batch_arrays` are convenience methods and allocate Ruby `Float` objects.
+They accept the same `format:` option and decode the returned storage format for debugging or application code.
+
+`f16` top-k scans decode half rows with native conversion where the CPU has it:
+`FCVTL` on AArch64 (baseline, no `-mcpu` needed) and `VCVTPH2PS` on x86 when
+CPUID reports F16C with OS support for AVX state. Everything else falls back to
+a 65,536-entry lookup table, which is populated only when that fallback is
+actually selected.
+
+`StaticEmbeddings.simd_backend` reports which kernel is live and returns
+`"neon-fp16"`, `"f16c"` or `"lut"`. Check it before drawing conclusions from an
+`f16` benchmark - the difference between the native and fallback kernels is
+several-fold.
+
+With a native kernel `f16` search can be faster on memory-bound corpora, but it
+is not guaranteed: half rows still have to be decoded before scoring. Treat
+`f16` primarily as a storage/RAM trade-off and benchmark on the target CPU. On
+the lookup-table fallback it is usually slower than `f32`.
+
+`embed_token_ids` skips the tokenizer and pools the rows you give it. It applies
+the same `max_tokens` truncation as `embed`, so `embed_token_ids(model.tokenize(text))`
+equals `embed(text)`. Pass `max_tokens: false` to pool every id. It exists for
+debugging, for reusing a cached tokenization, and for benchmarking the pooling
+loop in isolation; it is not a faster path for ordinary text.
+
+### Similarity helpers
+
+`cosine_top_k` divides by both vector norms and returns cosine similarity in
+`[-1, 1]`. It raises `ArgumentError` on a zero-norm query and scores zero-norm
+rows as `0.0`.
+
+`dot_top_k` returns the raw dot product with no normalization. Use it when your
+vectors are already unit length, including output from a model whose
+`normalized?` is `true`, because then the two agree and the dot product is
+cheaper. Use `cosine_top_k` in every other case.
+
+Both skip rows whose score is `NaN` rather than letting them into the result.
+That includes a row that itself contains `NaN`: `cosine_top_k` returns `0.0`
+only for a genuinely zero-norm row, so a corrupt row is never reported as if it
+were merely empty.
+
+```ruby
+if model.normalized?
+  model.dot_top_k(query_blob, matrix_blob, 10)
+else
+  model.cosine_top_k(query_blob, matrix_blob, 10)
+end
+```
+
+#### `dim:` is required on the module-level form
+
+An embedding blob is bare bytes. It carries no dimension and no format tag, so
+a query and a matrix stored in different formats can divide out to a consistent
+row count and produce plausible nonsense. The module-level helpers therefore
+require `dim:` and check the query against it:
+
+```ruby
+StaticEmbeddings.cosine_top_k(query_f32, matrix_f16, 10, dim: 512, format: :f16)
+# ArgumentError: query is 2048 bytes but dim: 512 with format :f16 needs 1024 bytes
+```
+
+`model.cosine_top_k` / `model.dot_top_k` fill `dim:` in from the model and are
+the recommended form.
+
+#### The matrix must be frozen
+
+A matrix at or above 1 MiB is scanned with the GVL released, so other Ruby
+threads keep running while the scan is in flight. Nothing stops one of them from
+reallocating the blob mid-scan, and copying a corpus-sized matrix on every query
+would defeat the point of the API. A frozen `String` cannot be mutated at all,
+so freezing is the contract:
+
+```ruby
+MATRIX = model.embed_batch(corpus).freeze
+
+model.dot_top_k(query, MATRIX, 10)          # lock-free, concurrent, GVL released
+```
+
+Passing a large unfrozen matrix raises `ArgumentError`. If you cannot freeze it,
+`allow_unfrozen: true` scans it while holding the GVL: correct, but it blocks
+every other thread in the process for the duration of the scan.
+
+A large matrix must also be 4-byte aligned when `format: :f32`. A blob produced
+by `pack`, `embed_batch` or `File.binread` always is; a `byteslice` at an odd
+offset may not be, and is rejected rather than silently copied.
+
+## Language safety
+
+`potion-retrieval-32M` is an English retrieval model. Russian text can produce a high `[UNK]` ratio while still returning a valid vector.
+
+Check unknown-token pressure before trusting a corpus:
+
+```ruby
+stats = model.embed_with_stats(text)
+ratio = stats[:token_count].zero? ? 0.0 : stats[:unk_count].to_f / stats[:token_count]
+
+warn "high [UNK] ratio: #{ratio.round(3)}" if ratio > 0.3
+```
+
+Use `tokenize` when vector quality looks wrong:
+
+```bash
+bundle exec ruby -Ilib exe/static_embeddings tokenize \
+  ~/.cache/static_embeddings/models/potion-retrieval-32m.semb \
+  "postgres pipeline mode in Ruby"
+```
+
+## Correctness contract
+
+The reference implementation is `model2vec.StaticModel`.
+
+The converter records these decisions in the `.semb` file:
+
+- default truncation is 512 tokens;
+- truncation happens after tokenization and before pooling;
+- `[UNK]` tokens are dropped;
+- input with no usable tokens returns a zero vector;
+- vectors are L2-normalized when the source model requires it.
+
+`docs/MODEL_AUDIT.md` records the source model revision, file digests, tokenizer facts, added-token audit, edge-case behavior and reference parity result for every trusted converted model. The audited `potion-retrieval-32m` conversion is recorded there with `.semb` bytes, SHA256, token-id parity and vector parity. New conversions must add their own parity record before they are treated as trusted.
+
+Run the parity check with:
+
+```bash
+python3 -m venv .venv-model2vec && . .venv-model2vec/bin/activate
+pip install -U model2vec numpy
+python tools/model2vec_oracle.py minishlab/potion-retrieval-32M --out tmp/model2vec_oracle.json
+bundle exec rake parity \
+  MODEL="$HOME/.cache/static_embeddings/models/potion-retrieval-32m.semb" \
+  ORACLE=tmp/model2vec_oracle.json
+```
+
+The oracle records token ids as well as vectors, and includes inputs on both sides of the large-input prefix window.
+
+Token ids must match the reference exactly. Float vectors are checked with tolerance because floating-point addition order is not bit-stable across implementations.
+
+Accepted vector tolerance:
+
+```text
+cosine >= 1 - 1e-6
+max_abs_diff < 1e-5
+```
+
+## Large inputs
+
+Ruby strings have to be copied into C-owned memory before the GVL can be
+released, and that copy is charged to the calling thread while it still holds
+the GVL. When truncation is active the runtime therefore does not copy the whole
+string: it copies a leading slice sized from `max_tokens`, cut immediately after
+an ASCII byte that ends a word, and only accepts the result once that slice has
+actually reached `max_tokens`. If it has not, the budget doubles and the text is
+tokenized again.
+
+The result is identical to tokenizing the whole document — WordPiece
+segmentation is word-local, and the cut is always on both a codepoint and a word
+boundary — but the cost of `embed` stops growing with input size:
+
+```text
+10 KB    43-47 us
+100 KB   43-47 us
+1 MB     43-47 us
+3 MB     43-47 us
+```
+
+A cut is legal where the tokenizer would have started a fresh word: after
+whitespace, after punctuation, and on either side of a CJK codepoint, using the
+model's own Unicode tables rather than an ASCII-only rule. Text with no legal
+cut anywhere in the scan window - one enormous word, or a run of combining marks
+- falls back to copying the whole input, which is the only correct thing to do
+there.
+
+`embed_batch` applies the same strategy per text. With `max_tokens: false` there
+is nothing to truncate, so the whole input is copied and processed.
+
+`embed_batch` builds its result in C memory and then copies it into a Ruby
+`String`, so peak memory for one call is about twice the size of the returned
+blob. Split very large corpora into chunks if that matters.
+
+## Concurrency
+
+`embed_batch` copies Ruby input into C-owned memory, then releases the GVL for large C computations. That is the intended web-runtime behaviour: one request can run a CPU-bound embedding batch while other Puma threads in the same process continue serving work.
+
+The runtime does not expose internal parallelism through `threads:`. For offline indexing, split work at the application/job level and run multiple Ruby workers explicitly.
+
+Do not mutate an Array while it is being embedded. `embed_batch` snapshots the
+elements it was given before it releases the GVL, so a concurrent mutation
+cannot corrupt memory, but the call embeds the snapshot and ignores anything
+that happened afterwards.
+
+`cosine_top_k` and `dot_top_k` scan a frozen matrix without any lock, so any
+number of threads can search one shared corpus at the same time. See the
+similarity helpers section for the frozen-matrix contract.
+
+When a `Fiber::Scheduler` is installed and the current fiber is non-blocking,
+work above 2 KB is handed to a real thread that the fiber joins, so the
+scheduler keeps running other fibers. Note that this creates one OS thread per
+call: under high concurrency prefer batching over many small `embed` calls.
+
+For Puma with `preload_app!`, load and warm the model before workers fork:
+
+```ruby
+preload_app!
+
+before_fork do
+  MODEL = StaticEmbeddings.load(ENV.fetch("EMBEDDING_MODEL"))
+  MODEL.warmup!
+end
+```
+
+## Docker / production
+
+Convert models during image build or deploy preparation. Production runtime should only see `.semb` files.
+
+```dockerfile
+RUN bundle exec ruby -Ilib exe/static_embeddings convert ./potion-retrieval-32M \
+  --id potion-retrieval-32m
+```
+
+Then set the path explicitly:
+
+```bash
+export EMBEDDING_MODEL=/root/.cache/static_embeddings/models/potion-retrieval-32m.semb
+```
+
+```ruby
+model = StaticEmbeddings.load(ENV.fetch("EMBEDDING_MODEL"))
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake clean compile
+bundle exec rake test
+```
+
+Build the synthetic fixture model:
+
+```bash
+ruby tools/make_fixture_model.rb
+```
+
+Run the benchmark:
+
+```bash
+ruby tools/benchmark.rb
+```
+
+Run the C memory smoke binary locally after building a fixture:
+
+```bash
+ruby tools/make_fixture_model.rb
+ruby -Ilib -e 'require "static_embeddings"; StaticEmbeddings.convert("test/fixtures/tiny-wordpiece", output_path: "tmp/test-tiny.semb", model_id: "fixture/tiny-wordpiece")'
+cc -O2 -std=c99 -Wall -Wextra -Iext/static_embeddings \
+  tools/memory_smoke.c \
+  ext/static_embeddings/se_format.c \
+  ext/static_embeddings/se_unicode.c \
+  ext/static_embeddings/se_tokenizer.c \
+  ext/static_embeddings/se_embed.c \
+  -lm -o tmp/memory_smoke
+./tmp/memory_smoke tmp/test-tiny.semb
+```
+
+## Notes
+
+The runtime is intentionally narrow. If a model requires unsupported tokenizer behavior, fix the converter whitelist and audit first; do not make the C runtime guess.
+
+## License
+
+MIT. See `LICENSE.txt`.