@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() | nil | keyword(), keyword()) ::
  {:ok, non_neg_integer()} | {:error, Moss.Error.t()}

Restore a session saved by save_to_disk/2 from <cache_path>/<name>/. Without cache_path, or with only options, it reads the directory that save_to_disk/2 picks when called without one.

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 for model_id: "custom")

Returns {:ok, Moss.SearchResult.t()} or {:error, reason}.

@spec save_to_disk(GenServer.server(), String.t() | nil) ::
  :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.

Without cache_path the snapshot goes in sessions/<project id>/ under the client's :cache_path, else under the MOSS_SESSION_CACHE_PATH environment variable, which only session snapshots read, else under moss in the default cache directory (~/.cache on macOS and Linux, %LOCALAPPDATA% on Windows). A relative cache_path resolves against the current working directory, and ~ is not expanded. The core reads MOSS_SESSION_CACHE_PATH from the environment the VM started with, so System.put_env/2 does not change it; set the client's :cache_path instead.

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}.