🥮 mooncakes.io

MoonEmbed

MoonBit-native word embedding loader and lightweight semantic retrieval library

moonbit
embeddings
vector-search
wasm
moon add wskwsk68/MoonEmbed@0.1.6
Download zip
Author
Version
0.1.6
License
Apache-2.0
Repository
Last updated
yesterday
Downloads
11
README

#MoonEmbed

MoonEmbed is a MoonBit-native library for loading word embeddings and running lightweight local semantic retrieval without Python, a database, or a network service. It is suitable for browser/Wasm examples, embedded tools, and small offline search pipelines.

#Install and verify

Clone the repository, then run:

moon fmt --check
moon check --deny-warn
moon test --deny-warn
moon build
moon run cmd/main

The demo uses a deterministic built-in corpus, so it does not download model weights or require credentials.

#Supported capabilities

  • Word2vec text, GloVe text, and word2vec binary ingestion.
  • Normalized cosine search with exact and bucketed approximate modes.
  • Token, phrase, prefix, threshold, batch, and tokenizer-aware queries.
  • Sentence embeddings and a metadata-filtered document store.
  • Corpus validation, index diagnostics, benchmark/recall reports, explainable score profiles, query plans, and deterministic quantization helpers.
  • Application knowledge-base workflow with bounded ingestion policies, audit results, metadata filters, session history, exports, health counters, and deterministic support/documentation scenarios.

#Minimal API example

///|
test "README minimal search" {
  let corpus = EmbeddingCorpus::from_glove_text(
    "king 0.92 0.10 0.00\nqueen 0.90 0.14 0.00\n",
  )
  let index = MoonEmbedIndex::from_corpus(corpus, 3)
  let report = index.search_token("king", 1)
  inspect(report.hits[0].token, content="king")
}

Unknown tokens and empty queries return empty reports. k <= 0 returns no results. Input records are copied and normalized; inconsistent dimensions are rejected. Use search_exact as a correctness baseline and evaluate to measure approximate-search recall on a domain corpus.

#Application workflow

The application layer turns the retrieval primitives into a complete offline knowledge-base flow. It validates and ingests documents, records rejected or skipped inputs, runs filtered queries, keeps bounded query history, exports documents, and reports health and usage counters. It also exposes query-admission traces, batch reports, inventory summaries, category exports, top-hit answers, and readiness snapshots for a small CLI or embedded operator panel.

///|
test "README application workflow" {
  let knowledge = support_knowledge_base()
  let results = knowledge.ingest_many([
    Document::new(
      "faq-login",
      "king queen",
      metadata=Map([("category", "support")]),
    ),
  ])
  inspect(results[0].accepted(), content="true")
  let report = knowledge.search(ApplicationQuery::new("king", k=3))
  inspect(report.is_empty(), content="false")
}

run_application_scenarios() and run_scenario_matrix() provide deterministic support, documentation, ingestion-guard, filtering, boundary, and export coverage suitable for an embedded CLI or an offline support tool.

#Project and license

The source is primarily MoonBit and is distributed under Apache-2.0. The repository contains no bundled model weights or third-party fixtures. See the root README.md for repository links, architecture, API boundaries, and source notes.

#
ApplicationAnswer

source
pub(all) struct ApplicationAnswer {
  found : Bool
  query : String
  document_id : String
  text : String
  category : String
  score : Double
}

A top-hit response suitable for a command-line or embedded UI preview.

#
ApplicationAnswer::describe

source
fn ApplicationAnswer::describe(self : ApplicationAnswer) -> String

#
ApplicationAnswer::found

source
fn ApplicationAnswer::found(self : ApplicationAnswer) -> Bool

#
ApplicationDocumentSummary

source
pub(all) struct ApplicationDocumentSummary {
  id : String
  category : String
  token_count : Int
  known_token_count : Int
  vector_ready : Bool
}

A compact, stable summary used by document inventory screens.

#
ApplicationDocumentSummary::describe

source

#
ApplicationHit

source
pub(all) struct ApplicationHit {
  document : Document
  score : Double
  rank : Int
}

A stable result returned by an application knowledge base.

#
ApplicationHit::category

source
fn ApplicationHit::category(self : ApplicationHit) -> String

#
ApplicationHit::describe

source
fn ApplicationHit::describe(self : ApplicationHit) -> String

#
ApplicationHit::id

source
fn ApplicationHit::id(self : ApplicationHit) -> String

#
ApplicationHit::score

source
fn ApplicationHit::score(self : ApplicationHit) -> Double

#
ApplicationHit::text

source
fn ApplicationHit::text(self : ApplicationHit) -> String

#
ApplicationKnowledgeBase

source
pub(all) struct ApplicationKnowledgeBase {
  corpus : EmbeddingCorpus
  index : MoonEmbedIndex
  store : DocumentStore
  tokenizer : TextTokenizer
  policy : IngestionPolicy
  session : QuerySession
  counters : UsageCounters
}

A small application knowledge base built on the core embedding index.

#
ApplicationKnowledgeBase::admit_query

source

Decide whether a query has enough known vocabulary to enter retrieval.

#
ApplicationKnowledgeBase::answer

source

Produce a top-document answer while preserving the full search API.

#
ApplicationKnowledgeBase::categories

source
fn ApplicationKnowledgeBase::categories(self : ApplicationKnowledgeBase) -> Array[String]

Return sorted-by-insertion category labels used by the knowledge base.

#
ApplicationKnowledgeBase::category_counts

source
fn ApplicationKnowledgeBase::category_counts(self : ApplicationKnowledgeBase) -> Map[String, Int]

Count documents by category, retaining deterministic insertion order.

#
ApplicationKnowledgeBase::document_count

source
fn ApplicationKnowledgeBase::document_count(self : ApplicationKnowledgeBase) -> Int

Return the current number of accepted documents.

#
ApplicationKnowledgeBase::document_ids

source
fn ApplicationKnowledgeBase::document_ids(self : ApplicationKnowledgeBase) -> Array[String]

Return the current document ids for administration and audit views.

#
ApplicationKnowledgeBase::document_summaries

source

Return one-line inventory summaries for operational inspection.

#
ApplicationKnowledgeBase::documents_for_category

source
fn ApplicationKnowledgeBase::documents_for_category(self : ApplicationKnowledgeBase, category : String) -> Array[Document]

Return the documents in one category in insertion order.

#
ApplicationKnowledgeBase::export_category

source
fn ApplicationKnowledgeBase::export_category(self : ApplicationKnowledgeBase, category : String) -> String

Export only one category for handoff to a downstream offline tool.

#
ApplicationKnowledgeBase::export_documents

source
fn ApplicationKnowledgeBase::export_documents(self : ApplicationKnowledgeBase) -> String

Export application documents as a deterministic line-oriented snapshot.

#
ApplicationKnowledgeBase::has_document

source
fn ApplicationKnowledgeBase::has_document(self : ApplicationKnowledgeBase, id : String) -> Bool

Return whether an id is currently present in the application store.

#
ApplicationKnowledgeBase::health

source

Return a health summary for a readiness or liveness command.

#
ApplicationKnowledgeBase::history

source

Retrieve a query history snapshot for an operator.

#
ApplicationKnowledgeBase::ingest

source

Add or skip one document according to policy and return an audit result.

#
ApplicationKnowledgeBase::ingest_many

source

Ingest a batch while preserving input order and returning per-document audit records.

#
ApplicationKnowledgeBase::ingest_with_report

source

Ingest a batch and aggregate per-document operator diagnostics.

#
ApplicationKnowledgeBase::new

source
fn ApplicationKnowledgeBase::new(corpus : EmbeddingCorpus, signature_bits? : Int, tokenizer? : TextTokenizer, policy? : IngestionPolicy, session_name? : String) -> ApplicationKnowledgeBase

#
ApplicationKnowledgeBase::ready

source

Return a compact health flag suitable for a readiness probe.

#
ApplicationKnowledgeBase::remove_document

source
fn ApplicationKnowledgeBase::remove_document(self : ApplicationKnowledgeBase, id : String) -> Bool

Remove an accepted document without touching the embedding corpus.

#
ApplicationKnowledgeBase::reset_session

source
fn ApplicationKnowledgeBase::reset_session(self : ApplicationKnowledgeBase) -> Unit

Clear only the interactive session while retaining the indexed documents.

#
ApplicationKnowledgeBase::search

source

Run a filtered semantic query through the application layer.

#
ApplicationKnowledgeBase::search_category

source
fn ApplicationKnowledgeBase::search_category(self : ApplicationKnowledgeBase, category : String, text : String, k? : Int) -> ApplicationSearchReport

Search one category without requiring callers to construct a filter.

#
ApplicationKnowledgeBase::search_many

source

Execute independent queries while keeping their input order.

#
ApplicationKnowledgeBase::snapshot

source
fn ApplicationKnowledgeBase::snapshot(self : ApplicationKnowledgeBase) -> String

Return a stable operational snapshot for a readiness endpoint or CLI.

#
ApplicationKnowledgeBase::trace_query

source

#
ApplicationKnowledgeBase::usage

source

Retrieve usage counters for diagnostics.

#
ApplicationKnowledgeBase::validate_document

source
fn ApplicationKnowledgeBase::validate_document(self : ApplicationKnowledgeBase, document : Document) -> IngestionResult

Validate a document against the current policy before adding it.

#
ApplicationKnowledgeBase::workflow_ready

source
fn ApplicationKnowledgeBase::workflow_ready(self : ApplicationKnowledgeBase) -> Bool

Verify the application lifecycle invariants used by the examples.

#
ApplicationQuery

source
pub(all) struct ApplicationQuery {
  text : String
  k : Int
  filter : DocumentFilter
  threshold : Double?
}

A query submitted by an application user.

#
ApplicationQuery::describe

source
fn ApplicationQuery::describe(self : ApplicationQuery) -> String

#
ApplicationQuery::new

source
fn ApplicationQuery::new(text : String, k? : Int, filter? : DocumentFilter, threshold? : Double) -> ApplicationQuery

#
ApplicationQuery::valid

source
fn ApplicationQuery::valid(self : ApplicationQuery) -> Bool

#
ApplicationQueryTrace

source
pub(all) struct ApplicationQueryTrace {
  admission : QueryAdmission
  report : ApplicationSearchReport
}

Return a query report plus an explicit admission decision for diagnostics.

#
ApplicationQueryTrace::describe

source
fn ApplicationQueryTrace::describe(self : ApplicationQueryTrace) -> String

#
ApplicationSearchReport

source
pub(all) struct ApplicationSearchReport {
  query : ApplicationQuery
  hits : Array[ApplicationHit]
  candidates : Int
  scanned : Int
  unknown_terms : Int
  filtered_documents : Int
}

A complete application query report with observability fields.

#
ApplicationSearchReport::describe

source
fn ApplicationSearchReport::describe(self : ApplicationSearchReport) -> String

#
ApplicationSearchReport::ids

source

#
ApplicationSearchReport::is_empty

source

#
ApplicationSearchReport::top

source

#
BenchmarkDocument

source
pub(all) struct BenchmarkDocument {
  id : String
  category : String
  text : String
  expected_tokens : Array[String]
}

A labelled benchmark document used for repeatable retrieval evaluation.

#
BenchmarkDocument::describe

source
fn BenchmarkDocument::describe(self : BenchmarkDocument) -> String

#
BenchmarkReport

source
pub(all) struct BenchmarkReport {
  suite : String
  documents : Int
  queries : Int
  passed : Int
  mean_recall : Double
  mean_candidates : Double
  filtered_documents : Int
}

A generated report that can be printed in CI logs.

#
BenchmarkReport::describe

source
fn BenchmarkReport::describe(self : BenchmarkReport) -> String

#
BenchmarkSuite

source
pub(all) struct BenchmarkSuite {
  name : String
  documents : Array[BenchmarkDocument]
  queries : Array[RetrievalCase]
}

A deterministic benchmark corpus with no network or model download.

#
BenchmarkSuite::add_document

source
fn BenchmarkSuite::add_document(self : BenchmarkSuite, document : BenchmarkDocument) -> Unit

#
BenchmarkSuite::add_query

source
fn BenchmarkSuite::add_query(self : BenchmarkSuite, query : RetrievalCase) -> Unit

#
BenchmarkSuite::categories

source
fn BenchmarkSuite::categories(self : BenchmarkSuite) -> Array[String]

#
BenchmarkSuite::describe

source
fn BenchmarkSuite::describe(self : BenchmarkSuite) -> String

#
BenchmarkSuite::document_count

source
fn BenchmarkSuite::document_count(self : BenchmarkSuite) -> Int

#
BenchmarkSuite::documents_in_category

source
fn BenchmarkSuite::documents_in_category(self : BenchmarkSuite, category : String) -> Array[BenchmarkDocument]

#
BenchmarkSuite::expected_category

source
fn BenchmarkSuite::expected_category(self : BenchmarkSuite, id : String) -> String?

#
BenchmarkSuite::new

source
fn BenchmarkSuite::new(name : String) -> BenchmarkSuite

#
BenchmarkSuite::query_count

source
fn BenchmarkSuite::query_count(self : BenchmarkSuite) -> Int

#
BenchmarkSuite::query_names

source
fn BenchmarkSuite::query_names(self : BenchmarkSuite) -> Array[String]

#
BenchmarkSuite::run

source
fn BenchmarkSuite::run(self : BenchmarkSuite, index : MoonEmbedIndex, k : Int) -> BenchmarkReport

fn BenchmarkSuite::sample_search(self : BenchmarkSuite, index : MoonEmbedIndex, repeats : Int, k : Int) -> SampleStats

#
CorpusCompatibility

source
pub(all) struct CorpusCompatibility {
  compatible : Bool
  same_dimension : Bool
  shared_tokens : Int
  left_only : Int
  right_only : Int
}

Compare two corpora for compatibility before loading a new model.

#
CorpusCompatibility::describe

source
fn CorpusCompatibility::describe(self : CorpusCompatibility) -> String

#
CorpusStats

source
pub(all) struct CorpusStats {
  records : Int
  dimension : Int
  zero_vectors : Int
  duplicate_tokens : Int
  min_norm : Double
  max_norm : Double
}

A compact summary useful for diagnostics, monitoring, and benchmark output.

#
CorpusStats::describe

source
fn CorpusStats::describe(self : CorpusStats) -> String

#
Document

source
pub(all) struct Document {
  id : String
  metadata : Map[String, String]
  text : String
  vector : Array[Double]?
}

#
Document::new

source
fn Document::new(id : String, text : String, metadata? : Map[String, String]) -> Document

#
DocumentFilter

source
pub(all) struct DocumentFilter {
  category : String?
  required_tokens : Array[String]
  excluded_tokens : Array[String]
}

A document-level filter that can combine category and token predicates.

#
DocumentFilter::describe

source
fn DocumentFilter::describe(self : DocumentFilter) -> String

#
DocumentFilter::empty

source

#
DocumentFilter::exclude

source
fn DocumentFilter::exclude(self : DocumentFilter, token : String) -> DocumentFilter

#
DocumentFilter::matches

source
fn DocumentFilter::matches(self : DocumentFilter, document : Document, tokenizer : TextTokenizer) -> Bool

#
DocumentFilter::require

source
fn DocumentFilter::require(self : DocumentFilter, token : String) -> DocumentFilter

#
DocumentFilter::with_category

source
fn DocumentFilter::with_category(self : DocumentFilter, category : String) -> DocumentFilter

#
DocumentHit

source
pub(all) struct DocumentHit {
  document : Document
  score : Double
}

A small result type that keeps a score beside a document without exposing the internal ranking tuple used by DocumentStore.

#
DocumentHit::id

source
fn DocumentHit::id(self : DocumentHit) -> String

#
DocumentHit::score

source
fn DocumentHit::score(self : DocumentHit) -> Double

#
DocumentStore

source
pub(all) struct DocumentStore {
  docs : Array[Document]
}

#
DocumentStore::add_document

source
fn DocumentStore::add_document(self : DocumentStore, doc : Document, corpus : EmbeddingCorpus) -> Unit

#
DocumentStore::add_documents

source
fn DocumentStore::add_documents(self : DocumentStore, documents : Array[Document], corpus : EmbeddingCorpus) -> Int

Add a batch of documents and return the number that produced a vector.

#
DocumentStore::categories

source
fn DocumentStore::categories(self : DocumentStore) -> Array[String]

#
DocumentStore::count_category

source
fn DocumentStore::count_category(self : DocumentStore, category : String) -> Int

#
DocumentStore::filter

source
fn DocumentStore::filter(self : DocumentStore, filter : DocumentFilter, tokenizer : TextTokenizer) -> Array[Document]

#
DocumentStore::get

source
fn DocumentStore::get(self : DocumentStore, id : String) -> Document?

#
DocumentStore::ids

source
fn DocumentStore::ids(self : DocumentStore) -> Array[String]

Return a snapshot of document ids in insertion order.

#
DocumentStore::is_empty

source
fn DocumentStore::is_empty(self : DocumentStore) -> Bool

#
DocumentStore::metadata_values

source
fn DocumentStore::metadata_values(self : DocumentStore, key : String) -> Array[String]

#
DocumentStore::new

source

fn DocumentStore::ranked_search(self : DocumentStore, query : Array[Double], filter_key : String?, filter_value : String?, k : Int) -> Array[RankedDocument]

#
DocumentStore::remove

source
fn DocumentStore::remove(self : DocumentStore, id : String) -> Bool

Remove a document by id and report whether it existed.

#
DocumentStore::search

source
fn DocumentStore::search(self : DocumentStore, query_vector : Array[Double], filter_key : String?, filter_value : String?, k : Int) -> Array[Document]

#
DocumentStore::search_scored

source
fn DocumentStore::search_scored(self : DocumentStore, query_vector : Array[Double], filter_key : String?, filter_value : String?, k : Int, threshold : Double) -> Array[DocumentHit]

Search all documents and retain scores for explainable applications.

#
DocumentStore::search_text

source
fn DocumentStore::search_text(self : DocumentStore, corpus : EmbeddingCorpus, text : String, filter_key : String?, filter_value : String?, k : Int) -> Array[Document]

Search text directly, avoiding a repeated query-vector boilerplate.

#
DocumentStore::size

source
fn DocumentStore::size(self : DocumentStore) -> Int

#
DocumentStore::texts

source
fn DocumentStore::texts(self : DocumentStore) -> Array[String]

#
DocumentStore::upsert

source
fn DocumentStore::upsert(self : DocumentStore, document : Document, corpus : EmbeddingCorpus) -> Bool

Replace an existing document, or append it when the id is new.

#
EmbeddingCorpus

source
pub(all) struct EmbeddingCorpus {
  records : Array[EmbeddingRecord]
  token_index : Map[String, Int]
  dim : Int
  source : SourceFormat
}

#
EmbeddingCorpus::describe

source
fn EmbeddingCorpus::describe(self : EmbeddingCorpus) -> String

#
EmbeddingCorpus::from_glove_text

source
fn EmbeddingCorpus::from_glove_text(text : String) -> EmbeddingCorpus raise

#
EmbeddingCorpus::from_records

source
fn EmbeddingCorpus::from_records(records : Array[EmbeddingRecord], source : SourceFormat) -> EmbeddingCorpus

#
EmbeddingCorpus::from_word2vec_binary

source
fn EmbeddingCorpus::from_word2vec_binary(bytes : Bytes) -> EmbeddingCorpus raise

#
EmbeddingCorpus::from_word2vec_text

source
fn EmbeddingCorpus::from_word2vec_text(text : String) -> EmbeddingCorpus raise

#
EmbeddingCorpus::has_token

source
fn EmbeddingCorpus::has_token(self : EmbeddingCorpus, token : String) -> Bool

#
EmbeddingCorpus::lookup

source
fn EmbeddingCorpus::lookup(self : EmbeddingCorpus, token : String) -> Array[Double]?

#
EmbeddingCorpus::phrase_embedding

source
fn EmbeddingCorpus::phrase_embedding(self : EmbeddingCorpus, phrase : PhraseQuery) -> Array[Double]?

#
EmbeddingCorpus::prefix

source
fn EmbeddingCorpus::prefix(self : EmbeddingCorpus, prefix : String, limit : Int) -> Array[EmbeddingRecord]

Return all records whose token starts with prefix, preserving corpus order.

#
EmbeddingCorpus::record

source
fn EmbeddingCorpus::record(self : EmbeddingCorpus, index : Int) -> EmbeddingRecord

#
EmbeddingCorpus::sentence_embedding

source
fn EmbeddingCorpus::sentence_embedding(self : EmbeddingCorpus, text : String) -> Array[Double]?

#
EmbeddingCorpus::sentence_embedding_with_tokenizer

source
fn EmbeddingCorpus::sentence_embedding_with_tokenizer(self : EmbeddingCorpus, text : String, tokenizer : TextTokenizer) -> Array[Double]?

#
EmbeddingCorpus::size

source
fn EmbeddingCorpus::size(self : EmbeddingCorpus) -> Int

#
EmbeddingCorpus::stats

source

#
EmbeddingCorpus::to_glove_text

source
fn EmbeddingCorpus::to_glove_text(self : EmbeddingCorpus) -> String

Serialize a corpus to a portable GloVe-style text representation.

#
EmbeddingCorpus::to_word2vec_text

source
fn EmbeddingCorpus::to_word2vec_text(self : EmbeddingCorpus) -> String

Serialize a corpus to word2vec text with an explicit header.

#
EmbeddingCorpus::tokens

source
fn EmbeddingCorpus::tokens(self : EmbeddingCorpus) -> Array[String]

#
EmbeddingCorpus::validate

source
fn EmbeddingCorpus::validate(self : EmbeddingCorpus) -> Bool

Validate structural invariants without exposing internal maps.

#
EmbeddingCorpus::vector

source
fn EmbeddingCorpus::vector(self : EmbeddingCorpus, token : String) -> Array[Double]?

Return the normalized vector for a token, if it exists.

#
EmbeddingCorpus::vectors

source
fn EmbeddingCorpus::vectors(self : EmbeddingCorpus) -> Array[Array[Double]]

Return a copy of every vector, suitable for callers that need to mutate it.

#
EmbeddingRecord

source
pub(all) struct EmbeddingRecord {
  token : String
  vector : Array[Double]
}

#
EmbeddingRecord::new

source
fn EmbeddingRecord::new(token : String, vector : Array[Double]) -> EmbeddingRecord

#
ExplainedHit

source
pub(all) struct ExplainedHit {
  token : String
  score : Double
  components : ScoreComponents
}

A ranked token with its component-level explanation.

#
ExplainedHit::describe

source
fn ExplainedHit::describe(self : ExplainedHit) -> String

#
IndexDiagnostics

source
pub(all) struct IndexDiagnostics {
  records : Int
  dimension : Int
  signature_bits : Int
  nonempty_buckets : Int
  largest_bucket : Int
}

A stable snapshot of index configuration for diagnostics.

#
IndexDiagnostics::describe

source
fn IndexDiagnostics::describe(self : IndexDiagnostics) -> String

#
IngestionBatchReport

source
pub(all) struct IngestionBatchReport {
  attempted : Int
  accepted : Int
  rejected : Int
  skipped : Int
  diagnostics : Array[IngestionIssue]
}

The outcome of a batch ingestion operation, including every diagnostic.

#
IngestionBatchReport::acceptance_rate

source
fn IngestionBatchReport::acceptance_rate(self : IngestionBatchReport) -> Double

#
IngestionBatchReport::complete

source
fn IngestionBatchReport::complete(self : IngestionBatchReport) -> Bool

#
IngestionBatchReport::describe

source
fn IngestionBatchReport::describe(self : IngestionBatchReport) -> String

#
IngestionIssue

source
pub(all) struct IngestionIssue {
  code : String
  message : String
  document_id : String
}

A single ingestion diagnostic that can be shown to an operator.

#
IngestionIssue::describe

source
fn IngestionIssue::describe(self : IngestionIssue) -> String

#
IngestionPolicy

source
pub(all) struct IngestionPolicy {
  max_documents : Int
  min_tokens : Int
  require_category : Bool
  reject_unknown_only : Bool
  replace_existing : Bool
}

Rules for deterministic, bounded document ingestion.

#
IngestionPolicy::conservative

source
fn IngestionPolicy::conservative() -> IngestionPolicy

#
IngestionPolicy::demo

source

#
IngestionPolicy::describe

source
fn IngestionPolicy::describe(self : IngestionPolicy) -> String

#
IngestionPolicy::valid

source
fn IngestionPolicy::valid(self : IngestionPolicy) -> Bool

#
IngestionResult

source
pub(all) struct IngestionResult {
  document_id : String
  status : IngestionStatus
  token_count : Int
  known_token_count : Int
  issues : Array[IngestionIssue]
}

Result for one document entering an application knowledge base.

#
IngestionResult::accepted

source
fn IngestionResult::accepted(self : IngestionResult) -> Bool

#
IngestionResult::describe

source
fn IngestionResult::describe(self : IngestionResult) -> String

#
IngestionStatus

source
pub(all) enum IngestionStatus {
  Accepted
  Rejected
  Skipped
}

Application-level ingestion status.

#
IngestionStatus::label

source
fn IngestionStatus::label(self : IngestionStatus) -> String

#
MoonEmbedIndex

source
pub(all) struct MoonEmbedIndex {
  corpus : EmbeddingCorpus
  buckets : Array[Array[Int]]
  signature_bits : Int
}

#
MoonEmbedIndex::corpus

source

#
MoonEmbedIndex::describe

source
fn MoonEmbedIndex::describe(self : MoonEmbedIndex) -> String

#
MoonEmbedIndex::diagnostics

source

#
MoonEmbedIndex::evaluate

source
fn MoonEmbedIndex::evaluate(self : MoonEmbedIndex, cases : Array[RetrievalCase], k : Int) -> RetrievalMetrics

Evaluate top-k membership with exact search as the reference.

#
MoonEmbedIndex::execute_plan

source
fn MoonEmbedIndex::execute_plan(self : MoonEmbedIndex, query : Array[Double], plan : QueryPlan) -> SearchReport

Execute a query plan while preserving the selected retrieval semantics.

#
MoonEmbedIndex::from_corpus

source
fn MoonEmbedIndex::from_corpus(corpus : EmbeddingCorpus, signature_bits : Int) -> MoonEmbedIndex

#
MoonEmbedIndex::new

source
fn MoonEmbedIndex::new(corpus : EmbeddingCorpus, signature_bits : Int) -> MoonEmbedIndex

fn MoonEmbedIndex::safe_search(self : MoonEmbedIndex, query : Array[Double], plan : QueryPlan) -> (ValidationReport, SearchReport)

#
MoonEmbedIndex::search

source
fn MoonEmbedIndex::search(self : MoonEmbedIndex, query : Array[Double], k : Int) -> SearchReport

#
MoonEmbedIndex::search_exact

source
fn MoonEmbedIndex::search_exact(self : MoonEmbedIndex, query : Array[Double], k : Int) -> SearchReport

#
MoonEmbedIndex::search_explained

source
fn MoonEmbedIndex::search_explained(self : MoonEmbedIndex, query : Array[Double], k : Int, profile : ScoreProfile) -> Array[ExplainedHit]

#
MoonEmbedIndex::search_many

source
fn MoonEmbedIndex::search_many(self : MoonEmbedIndex, queries : Array[Array[Double]], k : Int) -> Array[SearchReport]

Search several queries in one call. The output order matches the input order.

#
MoonEmbedIndex::search_phrase

source
fn MoonEmbedIndex::search_phrase(self : MoonEmbedIndex, phrase : PhraseQuery, k : Int) -> SearchReport

#
MoonEmbedIndex::search_prefix

source
fn MoonEmbedIndex::search_prefix(self : MoonEmbedIndex, prefix : String, k : Int) -> SearchReport

Search a token prefix and score each matching vector exactly.

#
MoonEmbedIndex::search_terms

source
fn MoonEmbedIndex::search_terms(self : MoonEmbedIndex, terms : String, k : Int) -> SearchReport

#
MoonEmbedIndex::search_text

source
fn MoonEmbedIndex::search_text(self : MoonEmbedIndex, text : String, k : Int) -> SearchReport

Search with a sentence average embedding. Unknown terms are ignored.

#
MoonEmbedIndex::search_threshold

source
fn MoonEmbedIndex::search_threshold(self : MoonEmbedIndex, query : Array[Double], k : Int, threshold : Double) -> SearchReport

Search a query and keep only hits at or above a score threshold.

#
MoonEmbedIndex::search_token

source
fn MoonEmbedIndex::search_token(self : MoonEmbedIndex, token : String, k : Int) -> SearchReport

#
MoonEmbedIndex::search_tokenized

source
fn MoonEmbedIndex::search_tokenized(self : MoonEmbedIndex, text : String, tokenizer : TextTokenizer, k : Int) -> SearchReport

#
PhraseQuery

source
pub(all) struct PhraseQuery {
  text : String
  tokens : Array[String]
  weights : Array[Double]
}

A phrase query configuration with deterministic token weighting.

#
PhraseQuery::is_empty

source
fn PhraseQuery::is_empty(self : PhraseQuery) -> Bool

#
PhraseQuery::new

source
fn PhraseQuery::new(text : String, tokenizer : TextTokenizer) -> PhraseQuery

#
PhraseQuery::size

source
fn PhraseQuery::size(self : PhraseQuery) -> Int

#
PhraseQuery::weight

source
fn PhraseQuery::weight(self : PhraseQuery, index : Int) -> Double

#
QueryAdmission

source
pub(all) struct QueryAdmission {
  accepted : Bool
  normalized : String
  token_count : Int
  known_token_count : Int
  reason : String
}

A reasoned admission decision for a query arriving from an application.

#
QueryAdmission::accepted

source
fn QueryAdmission::accepted(self : QueryAdmission) -> Bool

#
QueryAdmission::describe

source
fn QueryAdmission::describe(self : QueryAdmission) -> String

#
QueryAdmission::known_ratio

source
fn QueryAdmission::known_ratio(self : QueryAdmission) -> Double

#
QueryEvent

source
pub(all) struct QueryEvent {
  sequence : Int
  query : ApplicationQuery
  result_count : Int
  top_score : Double
  candidates : Int
}

Query history record used by CLI and embedded application shells.

#
QueryEvent::describe

source
fn QueryEvent::describe(self : QueryEvent) -> String

#
QueryPlan

source
pub(all) struct QueryPlan {
  mode : RetrievalMode
  k : Int
  threshold : Double?
  explain : Bool
}

#
QueryPlan::describe

source
fn QueryPlan::describe(self : QueryPlan) -> String

#
QueryPlan::new

source
fn QueryPlan::new(mode? : RetrievalMode, k? : Int, threshold? : Double, explain? : Bool) -> QueryPlan

#
QueryPlan::valid

source
fn QueryPlan::valid(self : QueryPlan) -> Bool

#
QuerySampler

source
pub(all) struct QuerySampler {
  queries : Array[Array[Double]]
  labels : Array[String]
  limit : Int
}

A deterministic reservoir of representative search queries.

#
QuerySampler::add

source
fn QuerySampler::add(self : QuerySampler, label : String, query : Array[Double]) -> Bool

#
QuerySampler::clear

source
fn QuerySampler::clear(self : QuerySampler) -> Unit

#
QuerySampler::evaluate

source
fn QuerySampler::evaluate(self : QuerySampler, index : MoonEmbedIndex, k : Int) -> RetrievalMetrics

#
QuerySampler::is_full

source
fn QuerySampler::is_full(self : QuerySampler) -> Bool

#
QuerySampler::label

source
fn QuerySampler::label(self : QuerySampler, index : Int) -> String?

#
QuerySampler::new

source
fn QuerySampler::new(limit : Int) -> QuerySampler

#
QuerySampler::query

source
fn QuerySampler::query(self : QuerySampler, index : Int) -> Array[Double]?

#
QuerySampler::size

source
fn QuerySampler::size(self : QuerySampler) -> Int

#
QuerySession

source
pub(all) struct QuerySession {
  name : String
  max_events : Int
  events : Array[QueryEvent]
  next_sequence : Int
}

A bounded query history with usage counters.

#
QuerySession::clear

source
fn QuerySession::clear(self : QuerySession) -> Unit

#
QuerySession::describe

source
fn QuerySession::describe(self : QuerySession) -> String

#
QuerySession::history

source
fn QuerySession::history(self : QuerySession) -> Array[QueryEvent]

#
QuerySession::last

source
fn QuerySession::last(self : QuerySession) -> QueryEvent?

#
QuerySession::new

source
fn QuerySession::new(name : String, max_events? : Int) -> QuerySession

#
QuerySession::record

source
fn QuerySession::record(self : QuerySession, query : ApplicationQuery, report : ApplicationSearchReport) -> Unit

#
QuerySession::size

source
fn QuerySession::size(self : QuerySession) -> Int

#
RankedDocument

source
pub(all) struct RankedDocument {
  id : String
  score : Double
  category : String
}

A ranked document result for applications that need stable ids.

#
RankedDocument::describe

source
fn RankedDocument::describe(self : RankedDocument) -> String

#
RankingSummary

source
pub(all) struct RankingSummary {
  total : Int
  nonempty : Int
  top_score : Double
  average_score : Double
}

#
RankingSummary::describe

source
fn RankingSummary::describe(self : RankingSummary) -> String

#
RetrievalCase

source
pub(all) struct RetrievalCase {
  name : String
  query : Array[Double]
  expected : Array[String]
}

A deterministic query case used by benchmark and regression reports.

#
RetrievalMetrics

source
pub(all) struct RetrievalMetrics {
  cases : Int
  passed : Int
  mean_recall : Double
  mean_candidates : Double
}

#
RetrievalMetrics::describe

source
fn RetrievalMetrics::describe(self : RetrievalMetrics) -> String

#
RetrievalMode

source
pub(all) enum RetrievalMode {
  Exact
  Approximate
  Auto
}

A query plan chooses exact or approximate retrieval explicitly.

#
RetrievalMode::label

source
fn RetrievalMode::label(self : RetrievalMode) -> String

#
SampleStats

source
pub(all) struct SampleStats {
  count : Int
  total : Double
  minimum : Double
  maximum : Double
}

A simple deterministic latency sample accumulator.

#
SampleStats::add

source
fn SampleStats::add(self : SampleStats, value : Double) -> Unit

#
SampleStats::describe

source
fn SampleStats::describe(self : SampleStats) -> String

#
SampleStats::mean

source
fn SampleStats::mean(self : SampleStats) -> Double

#
SampleStats::new

source

#
ScenarioMatrixReport

source
pub(all) struct ScenarioMatrixReport {
  scenarios : Int
  passed : Int
  total_documents : Int
  total_queries : Int
  total_rejected : Int
  total_skipped : Int
}

Aggregate the outcome of multiple independent acceptance scenarios.

#
ScenarioMatrixReport::all_passed

source
fn ScenarioMatrixReport::all_passed(self : ScenarioMatrixReport) -> Bool

#
ScenarioMatrixReport::describe

source
fn ScenarioMatrixReport::describe(self : ScenarioMatrixReport) -> String

#
ScenarioReport

source
pub(all) struct ScenarioReport {
  name : String
  ingested : Int
  rejected : Int
  skipped : Int
  queries : Int
  nonempty_queries : Int
  expected_matches : Int
  observed_matches : Int
  expected_rejected : Int
  expected_skipped : Int
}

Create a compact report for a reproducible application scenario.

#
ScenarioReport::describe

source
fn ScenarioReport::describe(self : ScenarioReport) -> String

#
ScenarioReport::passed

source
fn ScenarioReport::passed(self : ScenarioReport) -> Bool

#
ScoreComponents

source
pub(all) struct ScoreComponents {
  lexical : Double
  semantic : Double
  freshness : Double
  popularity : Double
}

A bounded, explainable component score.

#
ScoreComponents::clamp

source

#
ScoreComponents::combine

source
fn ScoreComponents::combine(self : ScoreComponents, profile : ScoreProfile) -> Double

#
ScoreComponents::describe

source
fn ScoreComponents::describe(self : ScoreComponents) -> String

#
ScoreProfile

source
pub(all) struct ScoreProfile {
  lexical_weight : Double
  semantic_weight : Double
  freshness_weight : Double
  popularity_weight : Double
}

A configurable score combiner for applications that need explainable ranking.

#
ScoreProfile::balanced

source
fn ScoreProfile::balanced() -> ScoreProfile

#
ScoreProfile::normalized

source
fn ScoreProfile::normalized(self : ScoreProfile) -> ScoreProfile

#
ScoreProfile::semantic_only

source
fn ScoreProfile::semantic_only() -> ScoreProfile

#
ScoreProfile::sum

source
fn ScoreProfile::sum(self : ScoreProfile) -> Double

#
SearchHit

source
pub(all) struct SearchHit {
  token : String
  score : Double
}

#
SearchHit::above

source
fn SearchHit::above(self : SearchHit, threshold : Double) -> Bool

#
SearchReport

source
pub(all) struct SearchReport {
  hits : Array[SearchHit]
  scanned : Int
  candidates : Int
}

#
SearchReport::apply_policy

source
fn SearchReport::apply_policy(self : SearchReport, policy : ThresholdPolicy) -> SearchReport

#
SearchReport::best_score

source
fn SearchReport::best_score(self : SearchReport) -> Double?

#
SearchReport::is_confident

source
fn SearchReport::is_confident(self : SearchReport, threshold : Double) -> Bool

#
SearchReport::tokens

source
fn SearchReport::tokens(self : SearchReport) -> Array[String]

#
SearchReport::unique_tokens

source
fn SearchReport::unique_tokens(self : SearchReport) -> Array[String]

#
SourceFormat

source
pub(all) enum SourceFormat {
  Word2VecText
  Word2VecBinary
  GloVeText
}

#
SourceFormat::label

source
fn SourceFormat::label(self : SourceFormat) -> String

#
TextReport

source
pub(all) struct TextReport {
  characters : Int
  raw_terms : Int
  retained_terms : Int
  unique_terms : Int
  stop_words : Int
}

A compact text preprocessing report for observability.

#
TextReport::describe

source
fn TextReport::describe(self : TextReport) -> String

#
TextToken

source
pub(all) struct TextToken {
  text : String
  position : Int
  original_length : Int
}

A token with its position and normalized text.

#
TextToken::describe

source
fn TextToken::describe(self : TextToken) -> String

#
TextTokenizer

source
pub(all) struct TextTokenizer {
  lowercase : Bool
  keep_numbers : Bool
  min_length : Int
  stop_words : Map[String, Bool]
}

A deterministic, dependency-free tokenizer for small local search systems.

#
TextTokenizer::contains

source
fn TextTokenizer::contains(self : TextTokenizer, text : String, token : String) -> Bool

#
TextTokenizer::count

source
fn TextTokenizer::count(self : TextTokenizer, text : String) -> Int

#
TextTokenizer::new

source
fn TextTokenizer::new(lowercase? : Bool, keep_numbers? : Bool, min_length? : Int, stop_words? : Map[String, Bool]) -> TextTokenizer

#
TextTokenizer::report

source
fn TextTokenizer::report(self : TextTokenizer, text : String) -> TextReport

#
TextTokenizer::tokenize

source
fn TextTokenizer::tokenize(self : TextTokenizer, text : String) -> Array[TextToken]

#
TextTokenizer::tokens

source
fn TextTokenizer::tokens(self : TextTokenizer, text : String) -> Array[String]

#
TextTokenizer::weighted_tokens

source
fn TextTokenizer::weighted_tokens(self : TextTokenizer, text : String) -> TokenWeights

#
ThresholdPolicy

source
pub(all) struct ThresholdPolicy {
  minimum_score : Double
  maximum_results : Int
  require_nonempty : Bool
}

A reusable score threshold policy.

#
ThresholdPolicy::accept

source
fn ThresholdPolicy::accept(self : ThresholdPolicy, score : Double) -> Bool

#
ThresholdPolicy::new

source
fn ThresholdPolicy::new(minimum_score? : Double, maximum_results? : Int, require_nonempty? : Bool) -> ThresholdPolicy

#
ThresholdPolicy::valid

source
fn ThresholdPolicy::valid(self : ThresholdPolicy) -> Bool

#
TokenSet

source
pub(all) struct TokenSet {
  values : Map[String, Bool]
  order : Array[String]
}

A list of token ids with stable insertion order and duplicate suppression.

#
TokenSet::add

source
fn TokenSet::add(self : TokenSet, token : String) -> Bool

#
TokenSet::contains

source
fn TokenSet::contains(self : TokenSet, token : String) -> Bool

#
TokenSet::difference

source
fn TokenSet::difference(self : TokenSet, other : TokenSet) -> TokenSet

#
TokenSet::intersection

source
fn TokenSet::intersection(self : TokenSet, other : TokenSet) -> TokenSet

#
TokenSet::new

source
fn TokenSet::new() -> TokenSet

#
TokenSet::remove

source
fn TokenSet::remove(self : TokenSet, token : String) -> Bool

#
TokenSet::size

source
fn TokenSet::size(self : TokenSet) -> Int

#
TokenSet::to_array

source
fn TokenSet::to_array(self : TokenSet) -> Array[String]

#
TokenSet::union

source
fn TokenSet::union(self : TokenSet, other : TokenSet) -> TokenSet

#
TokenWeights

source
pub(all) struct TokenWeights {
  values : Map[String, Double]
  total : Double
}

A weighted bag of tokens used for deterministic query expansion.

#
TokenWeights::add

source
fn TokenWeights::add(self : TokenWeights, token : String, weight : Double) -> Unit

#
TokenWeights::get

source
fn TokenWeights::get(self : TokenWeights, token : String) -> Double

#
TokenWeights::new

source

#
TokenWeights::normalize

source
fn TokenWeights::normalize(self : TokenWeights) -> TokenWeights

#
TokenWeights::size

source
fn TokenWeights::size(self : TokenWeights) -> Int

#
UsageCounters

source
pub(all) struct UsageCounters {
  ingestion_attempts : Int
  accepted_documents : Int
  rejected_documents : Int
  skipped_documents : Int
  query_attempts : Int
  empty_queries : Int
  returned_hits : Int
  scanned_candidates : Int
}

Counters exposed to a health endpoint or CLI status command.

#
UsageCounters::describe

source
fn UsageCounters::describe(self : UsageCounters) -> String

#
UsageCounters::new

source

#
UsageCounters::record_ingestion

source
fn UsageCounters::record_ingestion(self : UsageCounters, result : IngestionResult) -> Unit

#
UsageCounters::record_query

source
fn UsageCounters::record_query(self : UsageCounters, report : ApplicationSearchReport) -> Unit

#
ValidationFinding

source
pub(all) struct ValidationFinding {
  severity : ValidationSeverity
  code : String
  message : String
  token : String?
}

A structured validation finding that can be rendered by a CLI or CI job.

#
ValidationFinding::describe

source
fn ValidationFinding::describe(self : ValidationFinding) -> String

#
ValidationReport

source
pub(all) struct ValidationReport {
  findings : Array[ValidationFinding]
  checked_records : Int
  checked_dimensions : Int
}

A complete validation result with a stable error count.

#
ValidationReport::add

source
fn ValidationReport::add(self : ValidationReport, finding : ValidationFinding) -> Unit

#
ValidationReport::errors

source
fn ValidationReport::errors(self : ValidationReport) -> Int

#
ValidationReport::is_valid

source
fn ValidationReport::is_valid(self : ValidationReport) -> Bool

#
ValidationReport::messages

source
fn ValidationReport::messages(self : ValidationReport) -> Array[String]

#
ValidationReport::new

source

#
ValidationReport::summary

source
fn ValidationReport::summary(self : ValidationReport) -> String

#
ValidationReport::warnings

source
fn ValidationReport::warnings(self : ValidationReport) -> Int

#
ValidationSeverity

source
pub(all) enum ValidationSeverity {
  Info
  Warning
  Error
}

Severity of a corpus validation finding.

#
ValidationSeverity::label

source
fn ValidationSeverity::label(self : ValidationSeverity) -> String

#
all_application_scenarios_pass

source
fn all_application_scenarios_pass() -> Bool

#
application_operations_smoke

source
fn application_operations_smoke() -> Bool

Use the application operations as a deterministic smoke path.

#
compare_corpora

source
fn compare_corpora(left : EmbeddingCorpus, right : EmbeddingCorpus) -> CorpusCompatibility

#
corpus_health

source
fn corpus_health(corpus : EmbeddingCorpus) -> String

#
corpus_quantization_error

source
fn corpus_quantization_error(corpus : EmbeddingCorpus, levels : Int) -> Double

#
cosine_distance

source
fn cosine_distance(left : Array[Double], right : Array[Double]) -> Double

#
cosine_similarity

source
fn cosine_similarity(left : Array[Double], right : Array[Double]) -> Double

#
demo_corpus

source
fn demo_corpus() -> EmbeddingCorpus

#
demo_index

source
fn demo_index() -> MoonEmbedIndex

#
dequantize_coordinate

source
fn dequantize_coordinate(value : Int, levels : Int) -> Double

#
dequantize_vector

source
fn dequantize_vector(vector : Array[Int], levels : Int) -> Array[Double]

#
euclidean_distance

source
fn euclidean_distance(left : Array[Double], right : Array[Double]) -> Double

#
format_report

source
fn format_report(report : SearchReport) -> String

#
manhattan_distance

source
fn manhattan_distance(left : Array[Double], right : Array[Double]) -> Double

#
quantization_error

source
fn quantization_error(vector : Array[Double], levels : Int) -> Double

Estimate mean absolute error introduced by coordinate quantization.

#
quantize_coordinate

source
fn quantize_coordinate(value : Double, levels : Int) -> Int

Quantize a normalized coordinate into a small integer range for compact telemetry.

#
quantize_vector

source
fn quantize_vector(vector : Array[Double], levels : Int) -> Array[Int]

#
recall_at_k

source
fn recall_at_k(approx : SearchReport, exact : SearchReport, k : Int) -> Double

Compute recall against an exact result for a query.

#
run_application_scenarios

source
fn run_application_scenarios() -> Array[ScenarioReport]

Run all application scenarios used by the acceptance checklist.

#
run_documentation_scenario

source
fn run_documentation_scenario() -> ScenarioReport

Build a realistic local documentation search scenario.

#
run_ingestion_guard_scenario

source
fn run_ingestion_guard_scenario() -> ScenarioReport

Build a realistic regression scenario for invalid input and capacity policy.

#
run_scenario_matrix

source
fn run_scenario_matrix() -> ScenarioMatrixReport

#
run_support_scenario

source
fn run_support_scenario() -> ScenarioReport

#
scenario_operations_summary

source
fn scenario_operations_summary(knowledge : ApplicationKnowledgeBase) -> String

Build an operator-facing summary for a completed scenario.

#
standard_benchmark_suite

source
fn standard_benchmark_suite() -> BenchmarkSuite

#
summarize_reports

source
fn summarize_reports(reports : Array[SearchReport]) -> RankingSummary

#
support_knowledge_base

source
fn support_knowledge_base() -> ApplicationKnowledgeBase

Build a realistic product-support knowledge base with metadata filters.

#
validate_corpus

source
fn validate_corpus(corpus : EmbeddingCorpus) -> ValidationReport

Validate every record and identify duplicate or empty keys.

#
validate_query

source
fn validate_query(query : Array[Double], dimension : Int) -> ValidationReport

Validate a query before passing it to an index.

#
validate_vector

source
fn validate_vector(vector : Array[Double], expected_dimension : Int) -> ValidationReport

Validate a vector without throwing, for ingestion pipelines.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io