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.1.tar.gz (51.8 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.1-cp313-cp313-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.13Windows x86-64

embroider-0.1.1-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.1-cp313-cp313-macosx_11_0_arm64.whl (6.3 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

embroider-0.1.1-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.1-cp312-cp312-macosx_11_0_arm64.whl (6.3 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

embroider-0.1.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: embroider-0.1.1.tar.gz
  • Upload date:
  • Size: 51.8 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.1.tar.gz
Algorithm Hash digest
SHA256 77cf32eacdb622832a239fd010270f08d67e905bf3e93443c4f74222aaaf3149
MD5 fbc8551ec1795fa19df523c597d864f0
BLAKE2b-256 ca51d3f79f41024e3cdb058cfad93447657848e7f948b8382314f5dbf331bf05

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1.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.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.1-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.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ba9bbe96b56e0ae036db72e3ce519445fb1558507e6dd45dcb490abbd69a8867
MD5 b05f93e7ade52cb5d7764d7c40f11dfe
BLAKE2b-256 f8bccd6003cdee41ffe3ad3dab8b939fc78f1e52f77a18d935b615160bf1ffb0

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fe56d4b112107e1784bffc3f4ce3826a8d1546d520c5d56927ef39b9f688a1e5
MD5 cf1655b4ee6bc7128cfdda2f2013e5fd
BLAKE2b-256 8f6f2082bba4bf4cb6ba7e7c059b43f7abba1b2a5669c5a21407e7a4afbfc483

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7146a76daeb2094c0670d6f13f7484ace93dde3aea0628d0e74618af63460bde
MD5 afed010fd94e16336c741ea65fd6d0d4
BLAKE2b-256 6252400e3c54caff559c1a2d3c4fc0e2f479c1dcdcc05a92ed6e3c4d85c153fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.1-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.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 8d4eeebca52321fd67176a92283f4cf7602978a9ceda39924ec14f5a656c3393
MD5 ef3980958dadb02753e1f0b6fb19322d
BLAKE2b-256 01b0fc1349aa2374d0262b94e91f73ddba3046376d05a679d4ea56a278ebf029

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9eb799aefa42e9da1488b5bf4810bcd25c3f77e34917ea1f53dddab57bc6fecc
MD5 0e6c8596cb1918ff9301a9e5560f02ca
BLAKE2b-256 6547d1569ec493395381be5f548e3ca3571a30d2fd45148368a46fc045c3bd2f

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 07e1d526fa4c2d850d0c4ef8c23910d411157c406a19392067dc102c752d750f
MD5 fc248a5aa26604887f0483712231ea17
BLAKE2b-256 9e921349dcc81c6b367eeaca147ffdc90a5605075fa47776ffa9f83d16c3e866

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: embroider-0.1.1-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.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 6cabeae8facd4fcfdcfb0afa5e9b21d1fc02adcbd0695558e7e0a13c635584a0
MD5 0fa88191ca94796a594917c4acacd597
BLAKE2b-256 c6ab12f25929822958e0fa6e1f92c504c90acc98a8215fad2e4ed2d90fa4018d

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fec5f69b124785df1789b3026dfc8684b0a9be9037cbe93d4be02e30cb42c8af
MD5 df79b81706ca1064fb5917af0cd246e0
BLAKE2b-256 8164aed990c44cb270e05be274b1aec1e10f72a77035bb720f5f77195521541d

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for embroider-0.1.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bf9f2dc4ff849b20036fa33db3a145b05b66c5cf19e94ffd3c90829267f2c90e
MD5 8558b99b74d02fe55db085940c829116
BLAKE2b-256 3f0fa84eec0810793845bda06702f9bc8c3f1874ab46fe96d519fe1d3d5045c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for embroider-0.1.1-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

0.1.3

10 files

0.1.2

10 files

This release

0.1.1 This release

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