Moss.
Copy Markdown
Local in-session index — index documents in memory during a session and query them with no cloud round trips.
Sessions are opened via Moss.Client.session/3, which handles credentials
and auto-loading from the cloud:
{:ok, session} = Moss.Client.session(client, "session-abc", model_id: "moss-minilm")
docs = [%Moss.DocumentInfo{id: "1", text: "hello"}]
{:ok, {1, 0}} = Moss.Session.add_docs(session, docs)
{:ok, result} = Moss.Session.query(session, "hello")
{:ok, push_result} = Moss.Session.push_index(session)For model_id: "custom", each document must have .embedding set and
query/3 requires embedding: [...] in opts.
Call close/1 when done, so the final usage telemetry is delivered and the
session's memory freed.
Summary
Functions
Add documents to the session index.
Close the session: send its final usage telemetry and stop its process.
Delete documents by IDs. Returns the count deleted.
Number of documents in the session index.
Get documents from the index.
Restore a session saved by save_to_disk/2 from <cache_path>/<name>/.
Load an existing cloud index into this session.
The embedding model the session uses, or "custom".
The index name.
Push the local session index to the cloud.
Query the session index.
Save the session under <cache_path>/<name>/, so a later session with the
same name can restore it with load_from_disk/3. Open that session with
auto_load_on_init: false so the restore downloads no index.
Functions
@spec add_docs(GenServer.server(), list(), keyword()) :: {:ok, {non_neg_integer(), non_neg_integer()}} | {:error, Moss.Error.t()}
Add documents to the session index.
For built-in models ("moss-minilm", "moss-mediumlm"), embeddings are
computed automatically in Rust. For model_id: "custom", each document must
have .embedding set.
Options:
:upsert(boolean, default true)
Returns {:ok, {added, updated}} or {:error, reason}.
@spec close(GenServer.server()) :: :ok
Close the session: send its final usage telemetry and stop its process.
Waits until the telemetry is delivered or 2 seconds pass. Closing a session that
already stopped returns :ok. A supervisor shutting the session down, or the exit
of the process that started it with start_link/1, closes it the same way.
@spec delete_docs(GenServer.server(), [String.t()]) :: non_neg_integer()
Delete documents by IDs. Returns the count deleted.
@spec doc_count(GenServer.server()) :: non_neg_integer()
Number of documents in the session index.
@spec get_docs( GenServer.server(), keyword() ) :: [Moss.DocumentInfo.t()]
Get documents from the index.
Options:
:doc_ids(list of strings)
@spec load_from_disk(GenServer.server(), String.t(), keyword()) :: {:ok, non_neg_integer()} | {:error, Moss.Error.t()}
Restore a session saved by save_to_disk/2 from <cache_path>/<name>/.
The snapshot replaces this session's documents and model, so add_docs/3 and
query/3 need embeddings after loading a custom-model snapshot. A missing or
damaged snapshot returns {:error, %Moss.Error{code: :deserialization}} and
leaves the session as it was.
A snapshot saved for a built-in model by an older core carries no model
artifact identity, so the core can only restore it as a custom-model session.
With rebuild_legacy: true (the default), a session opened with the same
built-in model rebuilds such a snapshot instead: the stored documents are
re-embedded with the current model and the upgraded snapshot is saved back, in
one call, so the rebuild happens once per device. It needs the model, so the
cloud must be reachable. When the model cannot be loaded the call returns
{:error, %Moss.Error{code: :model_unavailable}} and changes nothing, so retry
later instead of discarding the snapshot. Custom-model sessions and snapshots of
another model load without a rebuild.
Options:
:rebuild_legacy(boolean, default true)
Returns {:ok, doc_count} or {:error, reason}.
@spec load_index(GenServer.server(), String.t()) :: {:ok, non_neg_integer()} | {:error, Moss.Error.t()}
Load an existing cloud index into this session.
The index replaces this session's documents and model, so add_docs/3 and
query/3 need embeddings after a custom-model index loads.
Returns {:ok, doc_count} or {:error, reason}.
@spec model_id(GenServer.server()) :: String.t()
The embedding model the session uses, or "custom".
A load moves the session to the loaded model, so after a
custom-model load add_docs/3 and query/3 need embeddings.
@spec name(GenServer.server()) :: String.t()
The index name.
@spec push_index(GenServer.server()) :: {:ok, Moss.PushIndexResult.t()} | {:error, Moss.Error.t()}
Push the local session index to the cloud.
Returns {:ok, Moss.PushIndexResult.t()} or {:error, reason}.
@spec query(GenServer.server(), String.t(), keyword()) :: {:ok, Moss.SearchResult.t()} | {:error, Moss.Error.t()}
Query the session index.
For built-in models, the query is embedded automatically in Rust. For
model_id: "custom", pass the query embedding via embedding: [...].
Options:
:top_k(integer, default 5):alpha(float, default 0.8):filter(map):embedding(list of floats, required formodel_id: "custom")
Returns {:ok, Moss.SearchResult.t()} or {:error, reason}.
@spec save_to_disk(GenServer.server(), String.t()) :: :ok | {:error, Moss.Error.t()}
Save the session under <cache_path>/<name>/, so a later session with the
same name can restore it with load_from_disk/3. Open that session with
auto_load_on_init: false so the restore downloads no index.
A failed or interrupted save leaves the last saved snapshot loadable. For a built-in model the snapshot records the model id and the exact model artifact.
Returns :ok or {:error, reason}.