bankai - v0.3.0

bankai/embed

embed — the embedding seam. Turns text into an L2-normalized vector for aarondb’s vec_index (HNSW). bankai’s vector features (dedup, memory RAG, semantic search) call embed here and nothing else.

Backends: a local ollama /api/embed endpoint (true semantic similarity) or a dependency-free signed-hashing-trick term-hash (lexical similarity only — catches overlapping terminology, not synonyms). Resolution is sticky for the life of the process because a single HNSW index build must never mix vector dimensionalities from two backends.

Configure: BANKAI_EMBED_BACKEND (auto|ollama|term-hash, default auto), BANKAI_OLLAMA_URL (default http://127.0.0.1:11434), BANKAI_EMBED_MODEL (default nomic-embed-text). auto and ollama prefer a reachable ollama and degrade to term-hash when it is not; term-hash skips the probe entirely.

Types

Backend

</>

The resolved embedding backend.

pub type Backend {
  Ollama(url: String, model: String, dims: Int)
  TermHash
}

Constructors 

  • Ollama(url: String, model: String, dims: Int)

    A reachable local ollama endpoint: base url, model, observed dims.

  • TermHash

    Deterministic signed-hashing-trick backend. Lexical, no model, total.

Values

active_backend

</> 
pub fn active_backend() -> String

The active backend’s honest name, e.g. “ollama/nomic-embed-text (semantic)” or “term-hash (lexical)”. Surfaced through doctor so the retrieval story stays honest.

backend

</> 
pub const backend: String

The fallback backend’s name (surfaced in CLI/help so the lexical limitation is honest, not hidden).

dims

</> 
pub const dims: Int

Vector dimensionality of the term-hash fallback backend.

embed

</> 
pub fn embed(text: String) -> List(Float)

Embed text into an L2-normalized vector. This is the seam — everything in bankai calls only this function. Total under term-hash; under a resolved ollama backend it panics if the endpoint dies mid-run so callers surface the failure honestly instead of silently mixing dimensionalities.

reset_resolution

</> 
pub fn reset_resolution() -> Nil

resolve

</> 
pub fn resolve() -> Backend

Resolve the backend once per process (sticky via persistent_term, which is VM-global): env mode, one reachability probe, then cached forever.

resolve_from

</> 
pub fn resolve_from(
  mode: String,
  url: String,
  model: String,
  probe: Result(Int, Nil),
) -> Backend

Pure decision core, public for tests: mode + probe outcome -> backend. ollama wins only when the probe succeeded; every failure degrades to the total term-hash backend.

term_hash

</> 
pub fn term_hash(text: String) -> List(Float)

Embed text into a 256-dim L2-normalized vector (signed hashing trick). Deterministic, no model. Lexical similarity only.

✨ Search Document