Skip to main content
Elixir SDK / Moss.Session

​
Moss.Session

A local, in-session index backed by the Rust core. Index documents in memory during a live workflow (voice AI agents, chat) and query them with no cloud round trips, then push the index to the cloud when done. Sessions are opened with Moss.Client.session/3, which handles credentials and auto-loads from the cloud if an index with the given name already exists. The functions below take the session reference returned by that call. For built-in models ("moss-minilm", "moss-mediumlm"), embeddings are computed automatically in the Rust core. For model_id: "custom", each document must set .embedding, and query/3 requires an :embedding option.

​
Example

{:ok, client} = Moss.Client.new("project-id", "project-key")
{:ok, session} = Moss.Client.session(client, "session-abc")

docs = [
  %Moss.DocumentInfo{id: "turn-1", text: "Customer: I need to cancel my subscription"},
  %Moss.DocumentInfo{id: "turn-2", text: "Agent: I can help with that. Can I ask why?"}
]

{:ok, {2, 0}} = Moss.Session.add_docs(session, docs)
{:ok, result} = Moss.Session.query(session, "subscription cancellation", top_k: 2)
{:ok, push_result} = Moss.Session.push_index(session)

​
Methods

​
add_docs(session, docs, opts)

Add or update documents in the session index, embedding them in the Rust core. Returns the counts of documents added (new IDs) and updated (existing IDs). For built-in models embeddings are computed automatically. For model_id: "custom", each document must have .embedding set.

​
Parameters

  • session (GenServer.server())
  • docs (list of Moss.DocumentInfo)
  • opts (keyword() = []): supports :upsert (boolean, default true).

​
Returns

{:ok, {added, updated}} or {:error, String.t()} 
{:ok, {2, 0}} = Moss.Session.add_docs(session, docs)

​
delete_docs(session, doc_ids)

Delete documents from the session index by their IDs. Returns the number of documents actually deleted (missing IDs are ignored).

​
Parameters

  • session (GenServer.server())
  • doc_ids (list of String.t())

​
Returns

non_neg_integer() 
deleted = Moss.Session.delete_docs(session, ["turn-1"])

​
get_docs(session, opts)

Retrieve documents from the session index.

​
Parameters

  • session (GenServer.server())
  • opts (keyword() = []): supports :doc_ids (list of strings). When provided, only those documents are returned; otherwise all documents are returned.

​
Returns

[Moss.DocumentInfo.t()] 
docs = Moss.Session.get_docs(session, doc_ids: ["turn-1"])

​
query(session, query_text, opts)

Run a semantic similarity search against the session index. For built-in models the query is embedded automatically in the Rust core. For model_id: "custom", pass the query embedding via the :embedding option. Metadata filtering is supported.

​
Parameters

  • session (GenServer.server())
  • query_text (String.t())
  • opts (keyword() = []): supports :top_k (integer, default 5), :alpha (float, default 0.8), :filter (map), and :embedding (list of floats, required for model_id: "custom").

​
Returns

{:ok, Moss.SearchResult.t()} or {:error, String.t()} 
{:ok, result} = Moss.Session.query(session, "subscription cancellation", top_k: 2, alpha: 0.6)
alpha tunes the hybrid blend: 1.0 is pure semantic, 0.0 is pure keyword, and the default 0.8 is semantic-heavy.

​
load_index(session, index_name)

Load an existing cloud index into this session. Returns the document count loaded. After loading, the session behaves as a local index: subsequent add, delete, and query operations run in memory without hitting the network.

​
Parameters

  • session (GenServer.server())
  • index_name (String.t())

​
Returns

{:ok, non_neg_integer()} or {:error, String.t()} 
{:ok, doc_count} = Moss.Session.load_index(session, "faqs")

​
push_index(session)

Push the local session index to the cloud, creating or replacing the server-side index. Returns a Moss.PushIndexResult with a job_id; poll it with Moss.Client.get_job_status/2 until the status is ready.

​
Parameters

  • session (GenServer.server())

​
Returns

{:ok, Moss.PushIndexResult.t()} or {:error, String.t()} 
{:ok, push_result} = Moss.Session.push_index(session)