Skip to main content

okf-embed — Jina v5 text embeddings (Rust core, PyO3)

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 of that pipeline by tests/test_parity.py (max abs diff ≤ 1e-5, cosine ≥ 0.999999).

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

Published to PyPI — okfgraph pulls it in automatically (platform wheels for Linux / Windows / macOS-arm64, Python 3.11–3.13):

uv sync          # editable path source, builds via maturin

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

cd rust/okf-embed
maturin build --release
uv pip install --python <venv> target/wheels/okf_embed-*.whl --reinstall

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 OS loader path. OKFgraph's resolve_ort_dylib() points the var at the pip-installed onnxruntime build when unset, so both bobine and okf-embed share one ORT binary — no version/CUDA drift between ingest and import.

Failure policy

Level Behaviour
Install The wheel is a core dependency of OKFgraph; if it is missing or fails to import, the router raises a clear RuntimeError with the install hint — never an ImportError from deep inside, never a silent fallback.
Device CUDA is opportunistic: auto/cuda use it when the loaded ORT registers the EP, else warn (stderr) + CPU. used_cuda reports the outcome. Never fatal.
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 like the router (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 (13, pure — no network, no dylib, no tokenizer file): device parsing, task-prefix idempotence, the L2 → truncate → re-normalise math, contract constants, and open() validation firing before I/O.

    cd rust/okf-embed && cargo test --locked
    

    Runs in CI (Ubuntu, --locked) alongside OKFgraph's pytest jobs.

  • Python parity (tests/test_parity.py, marked slow): Rust output vs a numpy/transformers replication across dims × tasks × texts, ≤ 1e-5. Needs the omni extra (transformers rides in via sentence-transformers).

  • Python e2e (tests/test_rust_backend.py, tests/test_rust_e2e.py): wheel import, count_tokens contract, encode against the real model.

Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

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

okf_embed-0.1.1-cp313-cp313-win_amd64.whl (5.8 MB view details)

Uploaded CPython 3.13Windows x86-64

okf_embed-0.1.1-cp313-cp313-manylinux_2_38_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.38+ x86-64

okf_embed-0.1.1-cp313-cp313-macosx_11_0_arm64.whl (6.2 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

okf_embed-0.1.1-cp312-cp312-manylinux_2_38_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.38+ x86-64

okf_embed-0.1.1-cp312-cp312-macosx_11_0_arm64.whl (6.2 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

okf_embed-0.1.1-cp311-cp311-manylinux_2_38_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.38+ x86-64

okf_embed-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 okf_embed-0.1.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: okf_embed-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 okf_embed-0.1.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4f85e97f658c3d72ff806cad0fb7d9f866478602981a2347ff3049b3ee02a8bf
MD5 07c6b5d8db7798a6894204b233b118e2
BLAKE2b-256 8f8fef6dbc6dbbf667ab5db1788f63e2eb9b27ec11aada27baecffc1e15d164c

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp313-cp313-win_amd64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp313-cp313-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp313-cp313-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 bf00b3ce209342103b45a9ead75c515ce273281d2e68e92894915124d505707f
MD5 cf318aa8e9a7ca1f404594aec34e389b
BLAKE2b-256 dee1e75d0621bfbd7f39c41d178ca0c773293198921a76bc99edf0ae028b6109

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp313-cp313-manylinux_2_38_x86_64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7ce5d10b8e40922730d634708c442773ec2942a37415befacd8ace92811aa3c1
MD5 36d82664c205316060657ba05be65fff
BLAKE2b-256 3269f72a2b06277ea2b1a43c492ded8653f1204c285feeade4e1513a38f180e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: okf_embed-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 okf_embed-0.1.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 1209b91f3efe56898b01688df156def218b0a02e6ef081cf29b4d4876d33d7fa
MD5 56a6e2ab57daf43243eef33a2c247763
BLAKE2b-256 242452ef2518e192489250eaf5eb8ec4279795c0839a3e3106dd38a7ef101dd5

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp312-cp312-win_amd64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp312-cp312-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp312-cp312-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 58bac3d693ac23c43f9e81c0351a3cafca4340edf8441523e82cd21fa5e5ca8b
MD5 bd92bca4f49a917bbeff2c2fd98f75c6
BLAKE2b-256 cef52e507537af49111d0215ff310a1f09cdba7282fb1261f5b462a981e91570

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp312-cp312-manylinux_2_38_x86_64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2e3d6e38555bfe63880fda1563550d42ad7f4b6e2478625deb2acb79cd0f51b0
MD5 2cfe8016f5b292998a572bfa99566e53
BLAKE2b-256 00db2106c566be4791c585f7f854bc3990f8e95e312f01b871b2f82d3149c106

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: okf_embed-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 okf_embed-0.1.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a6c3bd273c9a36360c557122df614b847fef61e4041e984139fc08e48881b438
MD5 385fc3209ab874cf7f29c911b584bc90
BLAKE2b-256 2f8549dce3e1d176a2b2d5b85b4f65f505c2281aaf7522c26cd838b37c46fc6c

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp311-cp311-win_amd64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp311-cp311-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp311-cp311-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 6f35f86ae9af7568a32fabd496042d379219beb2e42b3ffa23f3bd21791b5268
MD5 de2621d7bba293612ef389bb5ae4f9cb
BLAKE2b-256 6f0b67f422ec14eab93a00a620524e90ce3b0192bfd2a246f5e2e7863d0df63d

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp311-cp311-manylinux_2_38_x86_64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

File details

Details for the file okf_embed-0.1.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for okf_embed-0.1.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a5c66b471bf05f1c699f73a723a0837fd00c6259532af59f1c7d9fe9b7ce6cec
MD5 3c1bac35aeb4f6695254310422dc566b
BLAKE2b-256 ad8f8d355dfe55c98ee5e77cae786114652b1029265f56ce5e1ce61c1155d9ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_embed-0.1.1-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on opticsWolf/OKFgraph

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

9 files

This release

0.1.1 This release

9 files

0.1.0

9 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