fasttextembed 1.0.0__tar.gz

fasttextembed-1.0.0/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.20)
+project(fasttextembed_py C)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+add_compile_options(-O3 -ffp-contract=off)
+
+# SIMD features. NOTE for publishing: -mcpu=native targets the BUILD machine and is wrong for
+# redistributable wheels. CI should override (e.g. -DCMAKE_C_FLAGS="-march=armv8.2-a+fp16" on
+# arm64, or a baseline + future runtime dispatch). Fine for local installs.
+include(CheckCCompilerFlag)
+check_c_compiler_flag("-mcpu=native" HAS_MCPU_NATIVE)
+if(HAS_MCPU_NATIVE AND NOT DEFINED ENV{FTE_PORTABLE})
+    add_compile_options(-mcpu=native)
+endif()
+
+# Repo layout when building in-tree; vendored ./csrc layout for sdist / isolated builds.
+set(ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../..)
+if(NOT EXISTS ${ROOT}/src)
+    set(ROOT ${CMAKE_CURRENT_SOURCE_DIR}/csrc)
+endif()
+file(GLOB CORE ${ROOT}/src/*.c ${ROOT}/src/kernels/*.c ${ROOT}/src/tokenizer/*.c)
+
+add_library(fte SHARED ${CORE})
+target_include_directories(fte PRIVATE ${ROOT}/include ${ROOT}/src)
+target_link_libraries(fte m)
+
+# Drop the compiled library into the importable package directory.
+install(TARGETS fte LIBRARY DESTINATION fasttextembed RUNTIME DESTINATION fasttextembed)

fasttextembed-1.0.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.2
+Name: fasttextembed
+Version: 1.0.0
+Summary: Fast, dependency-free text embeddings (BAAI/bge-small-en-v1.5) in pure C
+Keywords: embeddings,bge,vector-search,nlp,onnx-free
+Author: Cemsina Guzel
+License: MIT
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Homepage, https://github.com/cemsina/fasttextembed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# fasttextembed (Python)
+
+Fast, dependency-free text embeddings for `BAAI/bge-small-en-v1.5`, powered by a small pure-C
+engine (no PyTorch, no ONNX Runtime). The model (~64 MB) is downloaded and cached on first use.
+
+```bash
+pip install fasttextembed
+```
+
+```python
+from fasttextembed import TextEmbedding
+
+model = TextEmbedding()                          # downloads + caches the model on first call
+vectors = model.embed(["hello world", "fast"])   # list of 384-float vectors
+one = model.embed_one("hello world")
+```
+
+- `embed(texts, threads=0)` — batch; `threads<=0` uses all cores.
+- Returns plain `list[list[float]]` (wrap with `numpy.asarray(...)` if you want an array).
+
+Environment overrides: `FTE_MODEL_DIR` (use local `model.fte`/`vocab.tsv`), `FTE_MODEL_URL`
+(download base URL), `FTE_CACHE` (cache dir), `FTE_LIB` (path to the C shared library).

fasttextembed-1.0.0/README.md

@@ -0,0 +1,22 @@
+# fasttextembed (Python)
+
+Fast, dependency-free text embeddings for `BAAI/bge-small-en-v1.5`, powered by a small pure-C
+engine (no PyTorch, no ONNX Runtime). The model (~64 MB) is downloaded and cached on first use.
+
+```bash
+pip install fasttextembed
+```
+
+```python
+from fasttextembed import TextEmbedding
+
+model = TextEmbedding()                          # downloads + caches the model on first call
+vectors = model.embed(["hello world", "fast"])   # list of 384-float vectors
+one = model.embed_one("hello world")
+```
+
+- `embed(texts, threads=0)` — batch; `threads<=0` uses all cores.
+- Returns plain `list[list[float]]` (wrap with `numpy.asarray(...)` if you want an array).
+
+Environment overrides: `FTE_MODEL_DIR` (use local `model.fte`/`vocab.tsv`), `FTE_MODEL_URL`
+(download base URL), `FTE_CACHE` (cache dir), `FTE_LIB` (path to the C shared library).

fasttextembed-1.0.0/csrc/include/fte/fte.h

@@ -0,0 +1,30 @@
+#ifndef FTE_H
+#define FTE_H
+#include <stddef.h>
+
+typedef struct fte_model fte_model;
+
+typedef enum {
+    FTE_OK = 0,
+    FTE_ERR_IO,
+    FTE_ERR_FORMAT,
+    FTE_ERR_ARCH_MISMATCH,
+    FTE_ERR_OOM,
+    FTE_ERR_INPUT
+} fte_status;
+
+#define FTE_DIM 384
+
+fte_status  fte_init(const char *fte_path, const char *vocab_tsv, fte_model **out);
+fte_status  fte_embed(fte_model *m, const char *text, float *out384);
+
+/* Embed n documents into out[n*384]. Parallelized across `threads` worker threads
+ * (<=0 means auto = number of cores). Weights are shared read-only; each thread has
+ * its own scratch. Thread-safe for distinct calls. */
+fte_status  fte_embed_batch(fte_model *m, const char *const *texts, size_t n,
+                            float *out, int threads);
+
+void        fte_free(fte_model *m);
+const char *fte_strerror(fte_status s);
+
+#endif

fasttextembed-1.0.0/csrc/src/api.c

@@ -0,0 +1,197 @@
+#include "fte/fte.h"
+#include "loader.h"
+#include "tokenizer/tokenizer.h"
+#include "model_bert.h"
+#include "threadpool.h"
+#include "config.h"
+#ifndef FTE_NO_THREADS
+#include <pthread.h>
+#include <stdatomic.h>
+#endif
+#include <stdlib.h>
+#include <unistd.h>
+
+struct fte_model {
+    fte_weights w;
+    fte_packed packed;
+    fte_tokenizer *tok;
+    fte_arena arena;
+    fte_pool *pool;   /* intra-doc parallelism for single fte_embed calls */
+};
+
+#if defined(__APPLE__)
+#include <sys/sysctl.h>
+#endif
+
+/* Threads for intra-document parallelism, chosen for the actual hardware:
+ *   - FTE_THREADS env var overrides everything (tuning / explicit control).
+ *   - Apple Silicon: performance cores only minus 2 (efficiency cores straggle at the
+ *     fork/join barrier; leaving headroom avoids preempting the main thread).
+ *   - Homogeneous CPUs (Linux ARM/x86): all cores minus 1 (leave one for the OS).
+ * No reason to copy the Mac's "minus 2" onto a homogeneous machine. */
+static int fte_intra_threads(void) {
+    const char *env = getenv("FTE_THREADS");
+    if (env) { int v = atoi(env); if (v >= 1) return v; }
+#if defined(__APPLE__)
+    int v = 0;
+    size_t sz = sizeof v;
+    if (sysctlbyname("hw.perflevel0.physicalcpu", &v, &sz, NULL, 0) == 0 && v > 2)
+        return v - 2;
+#endif
+    long nc = sysconf(_SC_NPROCESSORS_ONLN);   /* homogeneous: use all cores (measured best on N1) */
+    return nc > 0 ? (int)nc : 1;
+}
+
+fte_status fte_init(const char *fte_path, const char *vocab, fte_model **out) {
+    if (!fte_path || !vocab || !out) return FTE_ERR_INPUT;
+    fte_model *m = calloc(1, sizeof *m);
+    if (!m) return FTE_ERR_OOM;
+
+    int r = fte_weights_open(fte_path, &m->w);
+    if (r == -3) { free(m); return FTE_ERR_ARCH_MISMATCH; }
+    if (r == -2) { free(m); return FTE_ERR_FORMAT; }
+    if (r != 0)  { free(m); return FTE_ERR_IO; }
+
+    if (fte_tokenizer_load(vocab, &m->tok) != 0) {
+        fte_weights_close(&m->w);
+        free(m);
+        return FTE_ERR_IO;
+    }
+    if (fte_arena_init(&m->arena, (size_t)64 * 1024 * 1024) != 0) { /* 64MB scratch */
+        fte_tokenizer_free(m->tok);
+        fte_weights_close(&m->w);
+        free(m);
+        return FTE_ERR_OOM;
+    }
+    if (fte_pack_build(&m->w, &m->packed) != 0) {
+        fte_pack_free(&m->packed);
+        fte_arena_free(&m->arena);
+        fte_tokenizer_free(m->tok);
+        fte_weights_close(&m->w);
+        free(m);
+        return FTE_ERR_OOM;
+    }
+    int pc = fte_intra_threads();
+    m->pool = fte_pool_create(pc > 1 ? pc : 1); /* intra-doc parallelism; NULL if 1 core */
+    *out = m;
+    return FTE_OK;
+}
+
+fte_status fte_embed(fte_model *m, const char *text, float *out) {
+    if (!m || !text || !out) return FTE_ERR_INPUT;
+    int ids[FTE_MAX_POS];
+    int seq = fte_tokenizer_encode(m->tok, text, ids, FTE_MAX_POS);
+    if (seq < 2) return FTE_ERR_INPUT;
+    fte_arena_reset(&m->arena);
+    fte_pool_begin(m->pool);
+    int rc = fte_bert_embed(&m->w, &m->packed, m->pool, &m->arena, ids, seq, out);
+    fte_pool_end(m->pool);
+    if (rc != 0) return FTE_ERR_OOM;
+    return FTE_OK;
+}
+
+#ifdef FTE_NO_THREADS
+/* Single-threaded batch (e.g. WebAssembly): embed each doc on the caller. */
+fte_status fte_embed_batch(fte_model *m, const char *const *texts, size_t n,
+                           float *out, int threads) {
+    (void)threads;
+    if (!m || !texts || !out) return FTE_ERR_INPUT;
+    int ids[FTE_MAX_POS];
+    for (size_t i = 0; i < n; i++) {
+        float *o = out + i * FTE_DIM;
+        int seq = fte_tokenizer_encode(m->tok, texts[i], ids, FTE_MAX_POS);
+        if (seq < 2) { for (int d = 0; d < FTE_DIM; d++) o[d] = 0.0f; continue; }
+        fte_arena_reset(&m->arena);
+        if (fte_bert_embed(&m->w, &m->packed, NULL, &m->arena, ids, seq, o) != 0) return FTE_ERR_OOM;
+    }
+    return FTE_OK;
+}
+#else
+
+typedef struct {
+    fte_model *m;
+    const char *const *texts;
+    float *out;
+    size_t n;
+    _Atomic size_t *next;   /* shared work-stealing doc counter */
+    int err;
+} batch_job;
+
+static void *batch_worker(void *p) {
+    batch_job *j = p;
+    fte_arena a;
+    if (fte_arena_init(&a, (size_t)64 * 1024 * 1024) != 0) { j->err = 1; return NULL; }
+    int ids[FTE_MAX_POS];
+    /* Work-stealing: grab the next document dynamically. On asymmetric CPUs (e.g. Apple
+     * Silicon's perf+efficiency cores) this stops slow cores from stalling the whole batch. */
+    for (;;) {
+        size_t i = atomic_fetch_add_explicit(j->next, 1, memory_order_relaxed);
+        if (i >= j->n) break;
+        float *o = j->out + i * FTE_DIM;
+        int seq = fte_tokenizer_encode(j->m->tok, j->texts[i], ids, FTE_MAX_POS);
+        if (seq < 2) { for (int d = 0; d < FTE_DIM; d++) o[d] = 0.0f; continue; }
+        fte_arena_reset(&a);
+        if (fte_bert_embed(&j->m->w, &j->m->packed, NULL, &a, ids, seq, o) != 0) { j->err = 1; break; }
+    }
+    fte_arena_free(&a);
+    return NULL;
+}
+
+fte_status fte_embed_batch(fte_model *m, const char *const *texts, size_t n,
+                           float *out, int threads) {
+    if (!m || !texts || !out) return FTE_ERR_INPUT;
+    if (n == 0) return FTE_OK;
+    if (threads <= 0) {
+        long nc = sysconf(_SC_NPROCESSORS_ONLN);
+        threads = nc > 0 ? (int)nc : 1;
+    }
+    if ((size_t)threads > n) threads = (int)n;
+
+    if (threads > 256) threads = 256;
+    pthread_t tid[256];
+    batch_job jobs[256];
+    char created[256] = {0};
+    _Atomic size_t next = 0;
+    for (int t = 0; t < threads; t++) {
+        jobs[t] = (batch_job){m, texts, out, n, &next, 0};
+        if (pthread_create(&tid[t], NULL, batch_worker, &jobs[t]) == 0)
+            created[t] = 1;
+        else
+            batch_worker(&jobs[t]); /* run inline if spawn fails */
+    }
+    fte_status st = FTE_OK;
+    for (int t = 0; t < threads; t++) {
+        if (created[t]) pthread_join(tid[t], NULL);
+        if (jobs[t].err) st = FTE_ERR_OOM;
+    }
+    return st;
+}
+#endif /* FTE_NO_THREADS */
+
+#ifdef FTE_PROFILE
+extern void fte_profile_dump(void);
+#endif
+
+void fte_free(fte_model *m) {
+    if (!m) return;
+#ifdef FTE_PROFILE
+    fte_profile_dump();
+#endif
+    fte_pool_destroy(m->pool);
+    fte_arena_free(&m->arena);
+    fte_pack_free(&m->packed);
+    fte_tokenizer_free(m->tok);
+    fte_weights_close(&m->w);
+    free(m);
+}
+
+const char *fte_strerror(fte_status s) {
+    switch (s) {
+        case FTE_OK: return "ok";
+        case FTE_ERR_IO: return "io error";
+        case FTE_ERR_FORMAT: return "bad format";
+        case FTE_ERR_ARCH_MISMATCH: return "arch mismatch";
+        case FTE_ERR_OOM: return "out of memory";
+        default: return "bad input";
+    }
+}

fasttextembed-1.0.0/csrc/src/config.h

@@ -0,0 +1,20 @@
+#ifndef FTE_CONFIG_H
+#define FTE_CONFIG_H
+
+/* Compile-time constants specialized to BAAI/bge-small-en-v1.5
+ * (model_optimized.onnx, fp16 weights run in fp32 via com.microsoft fused ops). */
+#define FTE_HIDDEN        384
+#define FTE_LAYERS        12
+#define FTE_HEADS         12
+#define FTE_HEAD_DIM      32      /* HIDDEN / HEADS */
+#define FTE_INTERMEDIATE  1536
+#define FTE_VOCAB         30522
+#define FTE_MAX_POS       512
+#define FTE_TYPE_VOCAB    2
+#define FTE_LN_EPS        1e-12f
+#define FTE_ATTN_SCALE    0.17677669529663687f  /* 1/sqrt(32) */
+#define FTE_MASK_FILTER   -3.4028234663852886e+38f
+#define FTE_GELU_C        0.7978845608028654f    /* sqrt(2/pi) */
+#define FTE_GELU_A        0.044715f
+
+#endif

fasttextembed-1.0.0/csrc/src/fp16.h

@@ -0,0 +1,43 @@
+#ifndef FTE_FP16_H
+#define FTE_FP16_H
+#include <stdint.h>
+#include <string.h>
+
+/* Raw IEEE-754 half stored as 16 bits. */
+typedef unsigned short fte_f16;
+
+#if defined(__FLT16_MAX__) && !defined(FTE_NO_FLOAT16)
+/* Hardware path (clang/gcc on arm64, x86-64 with the feature): matches NEON vcvt exactly. */
+static inline float fte_h2f(fte_f16 h) {
+    _Float16 v;
+    memcpy(&v, &h, sizeof v);
+    return (float)v;
+}
+#else
+/* Software IEEE half -> float, for targets without _Float16 (e.g. WebAssembly). */
+static inline float fte_h2f(fte_f16 h) {
+    uint32_t sign = (uint32_t)(h & 0x8000u) << 16;
+    uint32_t exp = (h >> 10) & 0x1fu;
+    uint32_t mant = h & 0x3ffu;
+    uint32_t bits;
+    if (exp == 0) {
+        if (mant == 0) {
+            bits = sign;                          /* +/- zero */
+        } else {                                  /* subnormal */
+            exp = 127 - 15 + 1;
+            while (!(mant & 0x400u)) { mant <<= 1; exp--; }
+            mant &= 0x3ffu;
+            bits = sign | (exp << 23) | (mant << 13);
+        }
+    } else if (exp == 0x1f) {                     /* inf / nan */
+        bits = sign | 0x7f800000u | (mant << 13);
+    } else {                                      /* normal */
+        bits = sign | ((exp - 15 + 127) << 23) | (mant << 13);
+    }
+    float f;
+    memcpy(&f, &bits, 4);
+    return f;
+}
+#endif
+
+#endif

fasttextembed-1.0.0/csrc/src/fte_format.h

@@ -0,0 +1,33 @@
+#ifndef FTE_FORMAT_H
+#define FTE_FORMAT_H
+#include <stdint.h>
+
+/* On-disk .fte format. Shared contract between tools/convert.py and src/loader.c. */
+#define FTE_MAGIC    0x31455446u   /* "FTE1" little-endian */
+#define FTE_VERSION  2u            /* v2: per-tensor dtype (fp32 or fp16) */
+#define FTE_NAME_MAX 64
+#define FTE_ALIGN    64
+
+#define FTE_DT_F32 0
+#define FTE_DT_F16 1
+
+typedef struct {            /* one entry per weight tensor; 104 bytes, no padding */
+    uint64_t offset;        /* absolute byte offset into the file */
+    uint64_t nbytes;        /* = product(shape) * elem_size(dtype) */
+    char     name[FTE_NAME_MAX];
+    int32_t  ndim;
+    int32_t  shape[4];
+    int32_t  dtype;         /* FTE_DT_F32 | FTE_DT_F16 */
+} fte_tensor_entry;
+
+typedef struct {
+    /* 8-byte fields first to avoid implicit padding (Python writer matches byte-for-byte) */
+    uint64_t table_offset;  /* byte offset of fte_tensor_entry[n_tensors] */
+    uint64_t blob_offset;   /* byte offset of the weight blob */
+    uint32_t magic, version;
+    uint32_t hidden, layers, heads, intermediate, vocab, max_pos, type_vocab;
+    uint32_t n_tensors;
+    uint32_t _pad;
+} fte_header;
+
+#endif

fasttextembed-1.0.0/csrc/src/kernels/kernels.h

@@ -0,0 +1,48 @@
+#ifndef FTE_KERNELS_H
+#define FTE_KERNELS_H
+#include <stddef.h>
+#include "fp16.h"
+
+/* All row-major. */
+
+/* A:[M,K] B:[K,N] -> C:[M,N]  (B not transposed), all fp32. */
+void fte_matmul(const float *A, const float *B, float *C, int M, int K, int N);
+
+/* Same, but B is fp16 weights (widened to fp32 in-flight); fp32 accumulation.
+ * Bit-identical to fte_matmul on the fp32-widened weights. NEON-accelerated on arm64. */
+void fte_matmul_f16w(const float *A, const fte_f16 *B, float *C, int M, int K, int N);
+
+/* B pre-packed into 16-column panels (see pack.h). Keeps a 16-wide C tile in NEON
+ * registers across k; reads packed fp16 contiguously. Same k-order ⇒ bit-identical
+ * to fte_matmul_f16w. N must be a multiple of 16. */
+void fte_matmul_f16w_packed(const float *A, const fte_f16 *Bp, float *C, int M, int K, int N);
+
+/* Same, but only computes output column-panels [nb0,nb1) (each panel is 16 cols).
+ * Used to split one matmul across threads — disjoint output, no races. */
+void fte_matmul_f16w_packed_range(const float *A, const fte_f16 *Bp, float *C,
+                                  int M, int K, int N, int nb0, int nb1);
+
+/* fp16-ACCUMULATE variant (matches ONNX Runtime MLAS HalfGemmKernelNeon): A is already
+ * fp16, B is packed fp16, accumulation is fp16 (8-wide .8h FMA — 2x the fp32 kernel per
+ * core). Output written as fp32. Panels [nb0,nb1). */
+void fte_matmul_f16_packed_range(const fte_f16 *A, const fte_f16 *Bp, float *C,
+                                 int M, int K, int N, int nb0, int nb1);
+
+/* C[m,n] += bias[n] */
+void fte_add_bias(float *C, const float *bias, int M, int N);
+
+/* in/out:[M,D]; LayerNorm over D with gamma,beta,eps (population variance) */
+void fte_layernorm(float *X, const float *gamma, const float *beta, int M, int D, float eps);
+
+/* OUT[M,D] = LayerNorm(X + skip + bias) over D, then * gamma + beta */
+void fte_skip_layernorm(const float *X, const float *skip, const float *bias,
+                        const float *gamma, const float *beta, float *OUT,
+                        int M, int D, float eps);
+
+/* in/out:[M,D]; FastGelu of (x + bias[d]) */
+void fte_fastgelu(float *X, const float *bias, int M, int D);
+
+/* in/out:[rows,cols]; softmax over each row's first `valid` entries, rest set to 0 */
+void fte_softmax_rows(float *X, int rows, int cols, int valid);
+
+#endif