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 OrtReport — ORT_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)
4× 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).

Conformance

fixtures/golden_jina_v5_text_small.json pins the frozen vector space: 4 canonical texts × Query/Document prefixes × dims 64/512 (12 vectors) + exact token counts, generated with embroider 0.1.3 / onnxruntime 1.29.0 CPU / text-embed policy. Consumers vendor this file and assert live vectors against it (abs=1e-6 — catches wrong model, pooling, prefix, or truncation; immune to cross-CPU noise). Regenerate only on an intentional contract change, which is a new minor version plus a re-index-everything notice. See COMPAT.md for the release matrix.

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.

Project links

Data verified by PyPI on Sep 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for opticsWolf from gravatar.com opticsWolf

GitHub Statistics

Data verified by PyPI on Sep 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.11

Report project as malware

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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

embroider-0.1.4-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.4-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.4.tar.gz.

File metadata

  • Download URL: embroider-0.1.4.tar.gz
  • Upload date:
  • Size: 83.1 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.4.tar.gz
Algorithm Hash digest
SHA256 320ab198f3addeed914cda4e07cb84f087993385b4c8c1c96580db0ce9c61de6
MD5 02a60db54d92d699b72b2d532f975367
BLAKE2b-256 990fedc7560e1eff68d22101ab0b8cfcc27e4167a0252feada8d96d23d65b58d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.4-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.4-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 02a497e081b353f424580313a2f4ccd0356d8b97ed7b0d96a03a820d35f27e97
MD5 d1314d882c71c373323c15009ba046de
BLAKE2b-256 442ce452eb5596243f10c27b76e4d8841ee1fce834123919ea2a14bc2933b114

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 da24213f70d6c9d0d5c4c38f4ae2318d38861b1acbf712d8fde51fe62b1e3612
MD5 eb8ef5c56ffea536bbaee385aaa9b45e
BLAKE2b-256 e2844cf38522ae532a59ac860422f665b7e04593e222340d4ba46d56cca15039

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1a60bf1b88de57fc17a188d33aa6446e0e10c4547727adda0254c5618f28daac
MD5 f9220e953d8f6f06e39674d8631eadc5
BLAKE2b-256 bb67605e3db0aa01fe61690c9a36e99c03add466dc5015c54ae464564aaecfa7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.4-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.4-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 8c64c926a9b181a5fc842677bc4c47d3ad1ad3e9fbe462ea9a7230e416e77069
MD5 40c42df14ed77986cffa7cf808cc9204
BLAKE2b-256 cccef25699fc0007c1ce3ab6fd0de2d9086cd1bd67111309c401f157d21896fa

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e3abcafd957bb097c1d3743dbdf6ca5256a3261e939cad32a66b0c60482c077f
MD5 750ced72e1d040ef0421ff525787bb78
BLAKE2b-256 828bee2cc0ba50c1fade1d9db1b3e99caebf9fed2d5e954cd42c4d66ef283451

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2dd834314beac9d184234973eb8dae345d427c626a27cbfaf3a14bfbe66d2341
MD5 6fe4b025ff3ed43fed04e4ac8994ffee
BLAKE2b-256 1dea5ad6dc0daea44c8e58728eb7788239dbb6f2d14d01915ec40d39e64ff6e5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.4-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.4-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a2b8c8197b1238884e7cd32d9a1a2f6ef2b32782391979c2981876217fb74655
MD5 a8f99aa4621ad19516e75beea90f4e50
BLAKE2b-256 714e5a60dabbb8743aba2badcf9130667d400bbcb27806f3b024e7b4886b63b2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9abeec171db0e0783034c860d574047de71f9d18ae07c210e980ee57b96e6398
MD5 19aaa20ef6fc37a642992d6eec520176
BLAKE2b-256 4bdd1d988791251bb47b15106d7d78aa9fe5ebb78d5a088b9b7a5d71a19513a9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.4-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c68e3c8130839b2c0c7f3fa5d5b5954b9e996fe829b7b8287025b27d64502f9c
MD5 e01a2777afc381df4e073423f668376e
BLAKE2b-256 c13eb8d8878d0303480ff3d74828a21c304bfcfe2a79f1fb7364a0a53709802f

See more details on using hashes here.

Provenance

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

This release

0.1.4 This release

10 files

0.1.3

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