Metadata-Version: 2.4
Name: mnemos-embedkit
Version: 0.1.0a1
Summary: Open embedding devkit — same API across NPU / GPU / CPU silicon (Cix, NVIDIA, AMD, Intel, Apple, Rockchip, MediaTek)
Project-URL: Homepage, https://github.com/ncz-os/mnemos-embedkit
Project-URL: Repository, https://github.com/ncz-os/mnemos-embedkit
Project-URL: Issues, https://github.com/ncz-os/mnemos-embedkit/issues
Author-email: Jason Perlow <jperlow@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: transformers>=4.40
Provides-Extra: all
Requires-Dist: llama-cpp-python>=0.3; extra == 'all'
Requires-Dist: mlx-lm>=0.18; extra == 'all'
Requires-Dist: mlx>=0.19; extra == 'all'
Requires-Dist: onnxruntime-gpu>=1.18; extra == 'all'
Requires-Dist: onnxruntime-rocm>=1.18; extra == 'all'
Requires-Dist: onnxruntime-vitisai>=1.18; extra == 'all'
Requires-Dist: openvino>=2026.0; extra == 'all'
Requires-Dist: rknn-toolkit2>=2.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Provides-Extra: all-apple
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-apple'
Requires-Dist: mlx-lm>=0.18; extra == 'all-apple'
Requires-Dist: mlx>=0.19; extra == 'all-apple'
Requires-Dist: sentence-transformers>=3.0; extra == 'all-apple'
Provides-Extra: all-arm-cix
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-arm-cix'
Provides-Extra: all-arm-rockchip
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-arm-rockchip'
Requires-Dist: rknn-toolkit2>=2.0; extra == 'all-arm-rockchip'
Provides-Extra: all-cpu
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-cpu'
Requires-Dist: sentence-transformers>=3.0; extra == 'all-cpu'
Provides-Extra: all-x86-cuda
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-x86-cuda'
Requires-Dist: onnxruntime-gpu>=1.18; extra == 'all-x86-cuda'
Provides-Extra: all-x86-intel
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-x86-intel'
Requires-Dist: openvino>=2026.0; extra == 'all-x86-intel'
Provides-Extra: all-x86-rocm
Requires-Dist: llama-cpp-python>=0.3; extra == 'all-x86-rocm'
Requires-Dist: onnxruntime-rocm>=1.18; extra == 'all-x86-rocm'
Requires-Dist: onnxruntime-vitisai>=1.18; extra == 'all-x86-rocm'
Provides-Extra: cpu-llamacpp
Requires-Dist: llama-cpp-python>=0.3; extra == 'cpu-llamacpp'
Provides-Extra: cpu-sbert
Requires-Dist: sentence-transformers>=3.0; extra == 'cpu-sbert'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: gpu-amd-rocm
Requires-Dist: onnxruntime-rocm>=1.18; extra == 'gpu-amd-rocm'
Provides-Extra: gpu-apple-mlx
Requires-Dist: mlx-lm>=0.18; extra == 'gpu-apple-mlx'
Requires-Dist: mlx>=0.19; extra == 'gpu-apple-mlx'
Provides-Extra: gpu-intel-igpu
Requires-Dist: openvino>=2026.0; extra == 'gpu-intel-igpu'
Provides-Extra: gpu-nvidia-cuda
Requires-Dist: onnxruntime-gpu>=1.18; extra == 'gpu-nvidia-cuda'
Provides-Extra: gpu-nvidia-trt
Requires-Dist: onnxruntime-gpu>=1.18; extra == 'gpu-nvidia-trt'
Requires-Dist: tensorrt>=10.0; extra == 'gpu-nvidia-trt'
Provides-Extra: gpu-vulkan
Requires-Dist: llama-cpp-python>=0.3; extra == 'gpu-vulkan'
Provides-Extra: npu-amd-xdna
Requires-Dist: onnxruntime-vitisai>=1.18; extra == 'npu-amd-xdna'
Provides-Extra: npu-cix
Provides-Extra: npu-intel
Requires-Dist: openvino>=2026.0; extra == 'npu-intel'
Provides-Extra: npu-mediatek-apu
Requires-Dist: mtk-genio-apu>=0.1; extra == 'npu-mediatek-apu'
Provides-Extra: npu-rockchip
Requires-Dist: rknn-toolkit2>=2.0; extra == 'npu-rockchip'
Description-Content-Type: text/markdown

> # 📍 Moved to GitLab
> **The canonical, authoritative home of this project is GitLab — always:**
> ## 👉 https://gitlab.com/ncz-os/mnemos-embedkit
>
> This GitHub repository is a **frozen, read-only mirror**. All development, issues, and releases happen on GitLab. Please open issues and merge requests there. The full history of this stub is preserved on GitLab.

---

# mnemos-embedkit

> Open embedding devkit. Same API, every silicon.

`embedkit` lets you embed text once and run it on whatever hardware your box has — Cix Sky1 NPU, Apple Silicon Metal/MLX, NVIDIA CUDA/TensorRT, AMD ROCm/XDNA, Intel iGPU/NPU via OpenVINO, MediaTek APU, Rockchip RKNN, or just the CPU. The kit detects what's installed and picks the fastest adapter at runtime. **No vendor preference.**

## Quick start

```python
import embedkit

eng = embedkit.Engine.auto()              # picks the fastest adapter on this host
vec = eng.embed("Hello world")            # -> List[float]
vecs = eng.embed_batch(["a", "b", "c"])   # -> List[List[float]]

eng.info()
# {"adapter": "cix-npu", "model": "bge-small-zh-v1.5_256.cix",
#  "embed_dim": 512, "max_tokens": 256, "throughput_baseline": 55.0}
```

Explicit adapter pick:

```python
eng = embedkit.Engine(adapter="cix-npu",      model="bge-small-zh-v1.5")
eng = embedkit.Engine(adapter="nvidia-cuda",  model="nomic-embed-text-v1.5")
eng = embedkit.Engine(adapter="amd-rocm",     model="bge-large-en-v1.5")
eng = embedkit.Engine(adapter="apple-mlx",    model="mxbai-embed-large-v1")
eng = embedkit.Engine(adapter="cpu-llamacpp", model="bge-small-zh-v1.5")
```

## What the kit is

A pure-Python adapter layer over vendor-specific embedding runtimes, plus a uniform `Engine.embed*` API and a canonical bench harness. **The kit does not bundle drivers or kernel modules.** It detects what the host OS already provides and binds to it:

| Host has | Kit picks via |
|---|---|
| `cix-noe-umd 2.0.2` + `libnoe` (NCZ Magnetar / cixtech apt) | `npu-cix` adapter |
| `onnxruntime-gpu` (CUDA driver from Linux distro) | `nvidia-cuda` adapter |
| `tensorrt` python (NVIDIA tar/apt) | `nvidia-trt` adapter |
| `onnxruntime-rocm` (AMD ROCm dkms) | `amd-rocm` adapter |
| `onnxruntime-vitisai` (XDNA driver) | `amd-xdna` adapter |
| `openvino` (Intel CPU/iGPU/NPU) | `intel-igpu` / `intel-npu` adapter |
| `mlx` (Apple Silicon, macOS only) | `apple-mlx` adapter |
| llama-cpp-python with Metal | `cpu-llamacpp` adapter (auto-detects Metal at runtime) |
| llama-cpp-python with `-DGGML_VULKAN=1` | `gpu-vulkan` adapter |
| `rknn-toolkit2` (Rockchip RK3588 / RK3576) | `rockchip-rknn` adapter |
| `mtk-genio-apu` (MediaTek Genio) | `mediatek-apu` adapter |
| nothing else | `cpu-llamacpp` (CPU baseline, ships GGUF) |

## Install

```bash
# Pick the form-factor bundle that matches your host:
pip install embedkit[all-cpu]                 # baseline, CPU only
pip install embedkit[all-x86-cuda]            # CPU + NVIDIA CUDA
pip install embedkit[all-x86-rocm]            # CPU + AMD ROCm + XDNA
pip install embedkit[all-x86-intel]           # CPU + Intel iGPU + NPU via OpenVINO
pip install embedkit[all-arm-cix]             # CPU + Cix NPU + Mali Vulkan
pip install embedkit[all-arm-rockchip]        # CPU + Rockchip RKNN + Mali Vulkan
pip install embedkit[all-apple]               # CPU + Apple MLX + Metal
pip install embedkit[all]                     # everything
```

The kit pulls vendor *python bindings* from PyPI. Vendor *drivers* are managed by your OS package manager (cix-noe-umd via apt, nvidia-driver via ubuntu-drivers, rocm-dkms via amdgpu-install, intel-npu-driver via apt, etc.).

## Reference bench

The canonical multi-platform bench is in `benches/`. Run on your host:

```bash
embedkit-bench --corpus benches/corpora/mnemos-8038.json --engines auto
```

See `benches/results.md` for the cross-platform numbers we have today (Cix Sky1 NPU, Apple Silicon Metal, NVIDIA CUDA, x86 + ARM CPU, Pi 5, Pi 4).

## Reference implementation consumer

`ncz-os/mnemos` (the canonical MNEMOS memory layer) is the reference embedkit consumer. The plan is to migrate MNEMOS's embedding helper to call `embedkit.Engine(...)` directly. See `docs/mnemos-integration.md`.

## License

Apache-2.0.

## Status

**Bootstrap.** Design + cross-platform bench data exist. Adapter implementations are queued (Codex handoff prompt at `docs/CODEX-ADAPTER-HANDOFF.md`).

See `docs/DESIGN.md` for the full architecture.


## Build infrastructure & partners

Continuous integration and package distribution for this project are generously
supported by our open-source infrastructure partners:

- **[GitLab](https://gitlab.com/)** — canonical source hosting and CI pipelines
  (format / lint / test gates), via the
  [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/) program.
- **[Buildkite](https://buildkite.com/)** — CI/CD orchestration with hosted macOS
  and Linux agents, and our APT package registry host
  (`packages.buildkite.com/ncz-os/ncz`), via the
  [Buildkite Open Source](https://buildkite.com/pricing) program.

Thank you to both for backing open-source software.
