User Guide

from montycat import SemanticModel

# Enable semantic search DB-wide. Requires the Montycat Semantic server edition,
# where it is ON by default — call this only to enroll a keyspace that has none.
# model: MINI_LM | BGE_SMALL (default) | BGE_BASE | E5_SMALL
await connection.enable_semantic_search(model=SemanticModel.BGE_SMALL)

# {"status": True, "payload": None, "error": None}

# The chosen model is downloaded on first enable and cached locally. Every
# keyspace is embedded in the background as data is written.

# Enrolling one keyspace explicitly. A keyspace that is already enrolled is left
# untouched — this will not switch its model.
await connection.enable_semantic_search(
    model=SemanticModel.BGE_BASE, store="catalog", keyspace="products"
)

# Turn it off (vectors are kept, so re-enabling resumes instantly).
# Pass drop_vectors=True to also clear all stored vectors.
await connection.disable_semantic_search()

# {"status": True, "payload": None, "error": None}

from montycat import SemanticModel

# Read back what the server actually holds. Omit both arguments for the
# whole database, or narrow to one keyspace.
status = await connection.get_semantic_status(store="catalog", keyspace="products")

# {
#   "status": True,
#   "payload": {
#     "globally_enabled": True,
#     "default_model": "bge-small",
#     "default_field": None,
#     "keyspaces": {
#       "catalog/products": {
#         "enrolled": True,
#         "model": "bge-small",
#         "dimensions": 384,
#         "field": None,
#         "persistent": True,
#         "backfill_pending": False
#       }
#     }
#   },
#   "error": None
# }

# Replace the model of an already-enrolled keyspace. Drops its old vectors and
# starts a complete backfill in one atomic operation.
res = await connection.reembed_semantic_search(
    SemanticModel.MINI_LM, store="catalog", keyspace="products"
)

# {
#   "status": True,
#   "payload": {
#     "scope": "catalog/products",
#     "changed": True,
#     "previous_model": "bge-small",
#     "model": "minilm",
#     "dimensions": 384,
#     "field": None,
#     "backfill_started": True
#   },
#   "error": None
# }

from keyspaces import Employees #keyspaces.py

# Rank stored items by MEANING, not keywords. Two variants:
#   get_values -> each hit is {__key__, __score__, __value__}
#   get_keys   -> each hit is {__key__, __score__} (lighter; fetch a value later with get_bulk)

res = await Employees.semantic_search_get_values("engineers based near the coast", limit=5)

# {
#   "status": True,
#   "payload": [
#     {"__key__": "128222336824100726154851618391811195396", "__score__": 0.82,
#      "__value__": {"username": "Name", "location": "Location", "age": 21}}
#   ],
#   "error": None
# }

# Keys + scores only, with a cosine-similarity floor (range [-1, 1]):

keys = await Employees.semantic_search_get_keys("engineers based near the coast", limit=5, min_score=0.35)

# {
#   "status": True,
#   "payload": [{"__key__": "128222336824100726154851618391811195396", "__score__": 0.82}],
#   "error": None
# }

from keyspaces import Employees #keyspaces.py

# Rank by meaning, but only among records that match the structured filter.
# Filters use the same criteria shape as lookup_keys_where.

matching_keys = await Employees.semantic_search_get_keys_where(
    "works on distributed systems",
    {"location": "Location"},
    limit=5,
    min_score=0.35,
)

# {
#   "status": True,
#   "payload": [{"__key__": "128222336824100726154851618391811195396", "__score__": 0.82}],
#   "error": None
# }

matching_values = await Employees.semantic_search_get_values_where(
    "works on distributed systems",
    {"location": "Location"},
    limit=5,
)

# {
#   "status": True,
#   "payload": [
#     {"__key__": "128222336824100726154851618391811195396", "__score__": 0.82,
#      "__value__": {"username": "Name", "location": "Location", "age": 21}}
#   ],
#   "error": None
# }

from keyspaces import Employees #keyspaces.py

# Vectors produced elsewhere — another model, a batch pipeline, an existing
# vector store — are stored as-is and the server skips embedding.

res = await Employees.insert_value(
    {"username": "Name", "location": "Location", "age": 21},
    vector=my_embedding,          # list[float], omit for server-side embedding
)

# {"status": True, "payload": "128222336824100726154851618391811195396", "error": None}

# Bulk: vectors are paired with bulk_values BY POSITION.

res = await Employees.insert_bulk(
    bulk_values=[record_one, record_two],
    vectors=[embedding_one, embedding_two],
)

# Searching: a query vector bypasses text embedding, so the query may be empty.

hits = await Employees.semantic_search_get_values("", vector=my_query_embedding, limit=10)

# {
#   "status": True,
#   "payload": [
#     {"__key__": "128222336824100726154851618391811195396", "__score__": 0.82,
#      "__value__": {"username": "Name", "location": "Location", "age": 21}}
#   ],
#   "error": None
# }