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).

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 13, 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:
Newer release available (0.1.4)

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 13, 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.2.tar.gz (52.2 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.2-cp313-cp313-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

embroider-0.1.2-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.2-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.2.tar.gz.

File metadata

  • Download URL: embroider-0.1.2.tar.gz
  • Upload date:
  • Size: 52.2 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.2.tar.gz
Algorithm Hash digest
SHA256 3882e770e98302c151d707e69c4f742a5d1b7766b8d1302afe9b7dca4d11a8ce
MD5 09c99fcb8b73b78a468f0729da4dd1e1
BLAKE2b-256 103251f76b596076964f2b78d959f22cbb74601e6e0d923905dcccf01a27fbc8

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.2-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.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 7de957cb3f33e63ad1d0b8495af23d3e174a02aaf75bf1c2c6882048308f3a68
MD5 3dd82ccb643f059fd3a6cfb4f1450a9a
BLAKE2b-256 27c6565d0fb72ad646f1e92ad2c97b7011141981abe40776ba811b320ed7aac0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 38552e3e7080fbaea20c761c2715d61f6326db0c96d3abb077025af0f3626dd0
MD5 7e551f72fe8ccaab9daaabda7598a154
BLAKE2b-256 2f02db5fa4dd22c4d2c4753c00a46ce769631144b9ec2be7ad05a1a0fe3c0d5a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 04c905dfcf9bc276b6862ed5d3137ab7cc26b08a6194c55ef30b8b23882f339d
MD5 d886b9ee4b4d4045fc4ce9ebf035dd06
BLAKE2b-256 5dc897eb9f2bf331b53ef68e970b007047b4f822c3e24ebc1f278eaa3045ece8

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.2-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.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b03c21fa6ff9fc1b40e3ada1ce5b3bd8a7511d83395944af2d1d64f72737c13f
MD5 7e52fb129b5fbbcc7a7b11274943ba1f
BLAKE2b-256 6d8054131f26b3660e1055daa5e5785c6467304605edee79131061e51d7ac2eb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 66604b0ab947ed3b04eee3ccff46765c88d729be7078d98db5cfebd80b9a2973
MD5 4942bc51ebcefdd58632e8ebf5e4559f
BLAKE2b-256 a298fd60bdea99f8e100e9ad8235772ee05740164d47e6421f287c65a23fa68d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2047bf73c19a469b1c77b1936fed27fad193c249e08ff5ec1fdd2119705760e8
MD5 65d27d5a3cf08026e91b5cb735706963
BLAKE2b-256 be66577c77c8c9cf6cfbf469e05492015d3c8c8c5567f011337a6b4f6a040194

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: embroider-0.1.2-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.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 1f629a95a1b74ba6a24cd0ae5c94a35beeb98eaac71c520d5cbb91c678c824aa
MD5 ff6582ff43962b455a8a94048daae5df
BLAKE2b-256 8aef512938f895115f5cbd5ebda6b0860d77ed91b46b9406b7cb10b75c5d7292

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 172dace8250cd2ad09b89392f1d165a5700aa58fb82cb26b0ed464a02e22f5a7
MD5 5774711cf7b328074799739c0fa9d243
BLAKE2b-256 f87d858f5159c6e9f2c1ad44a0f3ff9a13a588fea7d013d0d5b3d411751480e8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for embroider-0.1.2-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b6c721e1533957b4266c97de01554f9e0122981a9114d9be254fb65ebc210b76
MD5 36955dc937e1810647e1025af02b05c2
BLAKE2b-256 55eb97e574bc8e2a46015b5c560aebbc0fb8c19e343ffefe74ed505e5d4eeec0

See more details on using hashes here.

Provenance

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

This release

0.1.2 This release

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