Skip to main content

embroider — Jina v5 text embeddings (Rust core, PyO3)

CI crates.io docs.rs PyPI Python License

One embedding engine, two consumers. embroider turns text into vectors via ONNX Runtime — and, like its name in the bobine/mordant family, the spool feeds the loom: bobine (PDF/Office → Markdown) uses the ONNX plumbing, okfgraph uses the Jina v5 text-embedding contract.

Provenance: a clean move out of OKFgraph's rust/okf-embed — an exact port of EmbeddingEngine._encode: task prefix → tokenize (8192) → ONNX forward → last-token pooling → L2 → Matryoshka truncate → re-normalise. Pinned against a numpy/transformers replication by OKFgraph's parity harness (tests/test_parity.py, max abs diff ≤ 1e-5).

The only embedding backend. There is no Python fallback stack, no embedding_backend selector, and no optimum/transformers in the runtime path — a mid-run stack switch would silently mix vector spaces in one index, so the design is fail-fast instead.

Install

PyPI wheels (Linux / Windows / macOS-arm64, Python 3.11+) — okfgraph pulls it in automatically; standalone:

pip install embroider

From source (Rust toolchain + maturin; maturin develop needs pip, which uv venvs lack — build the wheel and install it instead):

maturin build --release
uv pip install --python <venv> target/wheels/embroider-*.whl --reinstall

Module layout

Module Role
providers provider-name matrix (cuda/rocm/directml/openvino/coreml + implicit cpu) + clone-and-fallback application
probe corrected CUDA availability check (OnceLock-cached)
policy DeviceReq (auto/cpu/cuda) + explicit SessionPolicy (text_embed() vs ort_defaults())
acquire validated owner/name parsing, HF client, tokenizer-only fetch
error anyhow-based error plumbing (ort errors stringified at boundaries)
diag OrtReportORT_DYLIB_PATH value + CUDA usability for logs
jina JinaV5 + TokenizerHandle — the frozen embedding contract

The default (pure-Rust) build is Python-free — no pyo3 in downstream trees; the extension-module Cargo feature gates the PyO3 bindings and is enabled only for wheel builds (maturin), the same pattern bobine uses.

Runtime: ONNX Runtime discovery

ort loads dynamically (load-dynamic, same pin as bobine: 2.0.0-rc.13). Resolution order: ORT_DYLIB_PATH first (user override always wins), else the pip-installed onnxruntime/onnxruntime-gpu build when unset. okfgraph's resolve_ort_dylib() runs before the native module is imported, so bobine and embroider share one ORT binary — no version/CUDA drift between ingest and import.

Lifecycle: lazy session, cheap tokenizer

JinaV5.open (model download + ONNX session build) is the single expensive step. OKFgraph therefore holds a lazy proxy: construction validates the wheel import and device string eagerly, but the session opens on the first real encode — PPR search, budgeted reads, diff, and doctor stay cold.

JinaTokenizer.open fetches only tokenizer.json for exact token counts without the session. The truncation policy is shared, so counts are identical to the session path (verified). A failed session open is cached and re-raised — configuration errors fail fast once, not once per encode.

Explicit local files (air-gapped)

JinaV5.open_files(onnx_path, tokenizer_path) and JinaTokenizer.open_files(tokenizer_path) skip every download. The sidecar (model.onnx_data-style) must sit next to the ONNX file — ORT resolves it relative to the model path, same as the HF cache layout. OKFgraph's OKFRouter(model_path=..., tokenizer_path=...) uses them (both or neither; missing files raise FileNotFoundError at construction). Same bytes in → same vectors out (test-pinned against HF acquisition).

Session/threading policy (measured)

Tuning is Level3, intra = physical-cores/2, inter = 1 — kept because it measured fastest, not because it was inherited. Reference box: Windows, 32 logical cores, CPU-only ORT 1.29, warm model cache, best-of-5 reps on 4 fixed docs (short → ~400 tokens):

Config Session cold open encode_batch (4 docs) Notes
Level3, intra=16, inter=1 (current) 4.7 s 375 ms kept
Level1, intra=16, inter=1 5.5 s 433 ms (+15%) slower and bit-different vectors
Level3, intra=32, inter=1 4.5 s 411 ms (+10%) full-logical loses to phys/2 (SMT contention)
encode_one vs 1× encode_batch 389 vs 375 ms one boundary crossing saves ~3%; sequential stays
Tokenizer-only cold open 0.5 s 9× cheaper than session open; budgeted reads stay cold

Two consequences:

  • Do not mix tuning in one index. Level1 vs Level3 fuse the graph differently, so bits differ (hashes diverged at 1e-8 formatting). Same model + same build + same tuning, or re-embed.
  • Sequential batching stays. Padded batching would waste attention on variable-length docs to save ~14 ms of boundary overhead — not worth the numerics risk.

SessionPolicy::ort_defaults() exists for consumers (bobine's vision sessions) that never tuned — policy is data, never a forced default. Re-measure on new hardware/ORT before changing the policy.

Pitfall: stale onnxruntime.dll on Windows

Windows boxes can carry a stale C:\Windows\System32\onnxruntime.dll (v1.17.1 in the wild). With ORT_DYLIB_PATH unset, ort may load it and die with BadVersion { version_str: "1.17.1" }, followed by an abort at shutdown (fallout from ort's exit handler, not the root cause). Point ORT_DYLIB_PATH at a modern build — e.g. the venv's onnxruntime/capi/onnxruntime.dll. Same pitfall bobine documents in its docs/benchmarks.md.

Failure policy

Level Behaviour
Install The wheel is a core dependency of the consumer; if it is missing or fails to import, the consumer raises a clear RuntimeError with the install hint — never an ImportError from deep inside, never a silent fallback.
Device Accelerators are opportunistic: auto/cuda use CUDA when the loaded ORT registers the EP, else warn (stderr) + CPU. used_cuda reports the outcome. Never fatal. Unknown provider names warn and are skipped; registration failure degrades to CPU.
Encode Fail fast. No fallback at encode time — vectors must stay bit-comparable within one index.
Tokenizer No transformers in the runtime path, anywhere: internal tokenize + count_tokens() (== tokenizer.encode(t, add_special_tokens=False)) feed the context-window guard.

Contract notes

  • Session IO is discovered at load (input_ids + attention_mask required, token_type_ids fed only if declared — v5's export doesn't declare it, which is where generic runners fail). Output prefers last_hidden_state.
  • truncate_dim validated (32–1024, warning off the Matryoshka ladder). MAX_LENGTH (8192) is exposed for the window guard.
  • Batch encoding is sequential by design (padded batches waste attention compute on variable-length docs). GIL is released during encode.
  • input_ids/attention_mask feed as int64; pooling takes the last attended token (mask_sum - 1, clamped ≥ 0).

Testing

  • Rust unit tests (21, pure — no network, no dylib, no tokenizer file): device parsing, model-id parsing, provider-matrix mapping, task-prefix idempotence, the L2 → truncate → re-normalise math, contract constants, and open() validation firing before I/O.

    cargo test --locked
    
  • Python parity lives with the consumers: OKFgraph's tests/test_parity.py (marked slow) pins Rust output against a numpy/transformers replication across dims × tasks × texts at ≤ 1e-5; tests/test_rust_backend.py / tests/test_rust_e2e.py cover the wheel import, the count-tokens contract, and real-model encodes.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

embroider-0.1.3.tar.gz (52.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

embroider-0.1.3-cp313-cp313-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.13Windows x86-64

embroider-0.1.3-cp313-cp313-manylinux_2_28_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64

embroider-0.1.3-cp313-cp313-macosx_11_0_arm64.whl (6.3 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

embroider-0.1.3-cp312-cp312-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.12Windows x86-64

embroider-0.1.3-cp312-cp312-manylinux_2_28_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

embroider-0.1.3-cp312-cp312-macosx_11_0_arm64.whl (6.3 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

embroider-0.1.3-cp311-cp311-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.11Windows x86-64

embroider-0.1.3-cp311-cp311-manylinux_2_28_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

embroider-0.1.3-cp311-cp311-macosx_11_0_arm64.whl (6.3 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file embroider-0.1.3.tar.gz.

File metadata

  • Download URL: embroider-0.1.3.tar.gz
  • Upload date:
  • Size: 52.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for embroider-0.1.3.tar.gz
Algorithm Hash digest
SHA256 cf46ee6e339aad861710c63ffb7033e52a0ce393696cef575839026868d5c662
MD5 dffca147ebbfccb23a03f18555650756
BLAKE2b-256 ddbc7d9807d80396c299626610ad6fb77c37980b90824964b5a5a3c9804ec823

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3.tar.gz:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.3-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 5.8 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for embroider-0.1.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 3e914ce2a3669abb5723c4a038557cb9ffbd26a59a75d7e84cfac3ad112fc8f7
MD5 6f3aac4cdfe5e18bc49015b60f27f9a4
BLAKE2b-256 8d4ca2fa62985ce5a59a1622a874ecb267c339cc62e56ab93e7b82b814a348ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp313-cp313-win_amd64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c2897c644e1d7ec9a5c1e7f1d00cae66071a8909408cdac6b115bdd5382aed65
MD5 36bffcf80a9df2cb0b47bd95464c9346
BLAKE2b-256 f6f918b349f086b412dca6a8e0eeccb284fb4366d8ec6e2ba5908a198a2e70a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp313-cp313-manylinux_2_28_x86_64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1c9f66a3e3a4ab41cece0c00282c388040db2d1e160302ad57ede515b1ecc8e2
MD5 0551c105ecf1ed6bc13d2b075886e82c
BLAKE2b-256 cdacc582dc5f8d9b886c0a5f74b1dc1ec7e8017b11291f3e27d332bdf1bebb63

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.3-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 5.8 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for embroider-0.1.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 8381c8b7d5e8eea16c1898ec94d245b0b9ba8dbe11cd99fa1aa62e672ccb952f
MD5 face77a12ea3369db5de6a4424de2c0d
BLAKE2b-256 1db6cb7845671dab197ebbd64de6e85508774d500173d5ae2c5ba644958bc577

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp312-cp312-win_amd64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 64a1004f3c99bfe4042a7018c62072a4002d3f739f5f342ddd93dde68e8ecf00
MD5 85ef768245f0046cae875dd99661acf6
BLAKE2b-256 c2dc05b0bc9d8252b9437463147db081ec4d3365e7f15b5beaef69a472e76960

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp312-cp312-manylinux_2_28_x86_64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7a1f8f00d883631c8697d9b2faebd3b9b19e71d84702d11dd528af5de7676bfc
MD5 d687b9d89c575e3501ed8085fc3f74c7
BLAKE2b-256 5f49c82477ef295f3f59cb08025f9bfd0ec652c1a50e0caff3afbf6132676dac

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.3-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 5.8 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for embroider-0.1.3-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7edd64e1d36b50e1eaa7bb0ca68ba0f0234001d53337c3a62303e4a46c14bc69
MD5 e57fab3afe83c1d599ce82b3f0b3916d
BLAKE2b-256 dd971c3996b743890ba95034c325f1c7532dbeb2922c097facb4a3a4d8c02a9b

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp311-cp311-win_amd64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 17791f858ea1541db55f626bd5c05cee59576364d2271145118b4625e3009d59
MD5 9dde463fc9be706d461abec3fd4ca6b3
BLAKE2b-256 155bb9c3ec65415f26457b0a9b7d5f1d71220c2ff6081564fc7e7a8d639bcd71

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp311-cp311-manylinux_2_28_x86_64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file embroider-0.1.3-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.3-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d88f04deb4a4f28eacf742abff3f61c634c7bc7daa753e9b87fe2e51d8eadee6
MD5 289b18f0506ed0610442850932398a83
BLAKE2b-256 ca539d1cb8eb66f04e4abd1ea87bdc851cf68a48eb6035221c5e6ca4e10afd24

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.3-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/embroider

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.4

10 files

This release

0.1.3 This release

10 files

0.1.2

10 files

0.1.1

10 files

0.1.0

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page