C FFI: Embeddings & Search

Embeddings, vector search, and hybrid search through the C FFI. For the concepts behind each step see the guide pages on Embedding Models, Vector Search, and Hybrid & Lexical Search.

Every atelico_* call returns ATELICO_OK (0) on success; JSON results come back through an out-pointer that the engine owns (do not free it).

Embed text

const char *resp = NULL;
atelico_embed(engine,
    "{\"model\":\"in-memory::sentence-transformers/all-MiniLM-L6-v2\","
    "\"input\":[\"The guard saw a thief enter the keep at midnight.\"]}",
    &resp);
// Parse resp with your JSON lib -> data[0].embedding (384 floats).

// Direct cosine similarity between two strings:
float score = 0.0f;
atelico_embed_similarity(engine,
    "in-memory::sentence-transformers/all-MiniLM-L6-v2",
    "a knight's blade", "a warrior's sword", &score);

Create a store, insert, query

embed_dim must match the model (384 for MiniLM/bge-small, 768 for bge-base).

// 1. Create
uint64_t store_id = 0;
atelico_kvstore_create(engine,
    "{\"store_id\":\"npc-memory\",\"db_path\":\"./data/npc-memory\",\"embed_dim\":384}",
    &store_id);

// 2. Insert — key_embedding is the vector from atelico_embed (build the JSON
//    however you like: sprintf, your JSON library, etc.)
atelico_kvstore_insert(engine, "npc-memory", entries_json);
//   entries_json = [{"id":"mem-001",
//                    "key_text":"...",
//                    "key_embedding":[ ... 384 floats ... ],
//                    "facets":{"npc_id":"guard-01"},
//                    "priority":0.8}]

// 3. Query
const char *results = NULL;
atelico_kvstore_query(engine, "npc-memory", query_json, &results);
//   query_json = {"query_embedding":[ ... ],
//                 "facet_filters":{"npc_id":"guard-01"},
//                 "limit":5}
//   results = [{"id","key_text","similarity","priority","combined_score"}, ...]

uint64_t count = 0;
atelico_kvstore_count(engine, "npc-memory", "", &count);

Hybrid (vector + keyword) search

atelico_kvstore_create_fts_index(engine, "npc-memory", "key_text");

const char *response = NULL;
atelico_kvstore_hybrid_query(engine, "npc-memory", hybrid_json, &response);
//   hybrid_json = {"embeddings":[ ... ],"text":"thief keep",
//                  "fts_column":"key_text","limit":5,
//                  "vector_weight":0.6,"lexical_weight":0.4}

See Hybrid & Lexical Search for the scoring details and the lexical-only (atelico_kvstore_lexical_query) variant.