@spec add_docs(t(), String.t(), [Moss.DocumentInfo.t()], keyword()) ::
  {:ok, Moss.MutationResult.t()} | {:error, Moss.Error.t()}

Add documents to an existing cloud index.

Options:

• :upsert (boolean, default nil — use server default)

@spec close(t()) :: :ok

Close the client's index manager: send its final usage telemetry, unload its indexes and stop its process.

Waits until the telemetry is delivered or 2 seconds pass. Sessions are separate processes, so close each with Moss.Session.close/1. Cloud calls such as create_index/4 keep working afterwards; calls that need the manager exit.

@spec create_index(t(), String.t(), [Moss.DocumentInfo.t()], String.t()) ::
  {:ok, Moss.MutationResult.t()} | {:error, Moss.Error.t()}

Create a cloud index with initial documents.

@spec create_index_from_files(
  t(),
  String.t(),
  [map()],
  String.t(),
  map() | nil
) :: {:ok, Moss.MutationResult.t()} | {:error, Moss.Error.t()}

Create an index from raw files via the server-side parse pipeline.

Each file in files is a map with all three keys required:

• :path — filesystem path
• :name — filename sent to the server
• :content_type — MIME type

model_id defaults to "moss-minilm". Must be a built-in model. "custom" is not supported because the parse pipeline generates embeddings server-side.

At most 20 files per call.

parse_options is an optional map controlling extraction. Omitted keys use the server defaults:

• :ocr_mode: "auto_ocr" or "full_ocr". Use "full_ocr" for scanned documents with no text layer.
• :segmentation_method: "smart_layout_detection" or "page_by_page"
• :use_high_resolution: boolean, slower but better on dense tables
• :merge_tables: boolean, join tables split across a page break
• :chunk_size: integer, target length of each chunk in characters, 200 to 2000 (default 1200)
• :chunk_overlap: integer, characters shared by consecutive chunks, 0 to half of :chunk_size (default 200, capped at half of :chunk_size)

Supported content types: "application/pdf" and the DOCX MIME "application/vnd.openxmlformats-officedocument.wordprocessingml.document".

Example:

{:ok, result} = Moss.Client.create_index_from_files(
  client,
  "my-index",
  [
    %{
      name: "report.pdf",
      content_type: "application/pdf",
      path: "/docs/report.pdf"
    },
    %{
      name: "manual.docx",
      content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      path: "/docs/manual.docx"
    }
  ],
  "moss-minilm",
  %{ocr_mode: "full_ocr"}
)

@spec delete_docs(t(), String.t(), [String.t()]) ::
  {:ok, Moss.MutationResult.t()} | {:error, Moss.Error.t()}

Delete documents by IDs from a cloud index.

@spec delete_index(t(), String.t()) :: {:ok, boolean()} | {:error, Moss.Error.t()}

Delete a cloud index.

@spec get_docs(t(), String.t(), keyword()) ::
  {:ok, [Moss.DocumentInfo.t()]} | {:error, Moss.Error.t()}

Get documents from a cloud index.

Options:

• :doc_ids (list of strings) — if provided, only fetch those docs

@spec get_index(t(), String.t()) ::
  {:ok, Moss.IndexInfo.t()} | {:error, Moss.Error.t()}

Get metadata for a cloud index.

@spec get_index_info(t(), String.t()) ::
  {:ok, Moss.IndexInfo.t()} | {:error, Moss.Error.t()}

Get metadata for a loaded index.

@spec get_job_status(t(), String.t()) ::
  {:ok, Moss.JobStatusResponse.t()} | {:error, Moss.Error.t()}

Poll the status of an async job.

@spec has_index(t(), String.t()) :: boolean()

Check if an index is loaded.

@spec list_indexes(t()) :: {:ok, [Moss.IndexInfo.t()]} | {:error, Moss.Error.t()}

List all cloud indexes for this project.

@spec load_index(t(), String.t(), keyword()) ::
  {:ok, Moss.IndexInfo.t()} | {:error, Moss.Error.t()}

Load a cloud index into memory.

Options:

• :auto_refresh (boolean, default false)
• :polling_interval (integer seconds, default 600, minimum 1; 0 uses the default)

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

@spec load_indexes(t(), [String.t()], keyword()) :: {:ok, Moss.LoadIndexesResult.t()}

Bulk-load many indexes into memory. Best-effort: names that fail are reported in failed without rolling back the ones that loaded.

Options:

• :auto_refresh (boolean, default false)
• :polling_interval (integer seconds, default 600, minimum 1; 0 uses the default)

Returns {:ok, %Moss.LoadIndexesResult{loaded: [...], failed: %{name => reason}}}.

@spec new(String.t(), String.t(), keyword()) :: {:ok, t()} | {:error, Moss.Error.t()}

Create a new Moss.Client.

The index API URL is resolved from the MOSS_INDEX_URL environment variable (falls back to the default cloud endpoint). No URL option is needed.

Options:

• :cache_path (directory for the on-disk index cache used by load_index/3; <cache_path>/.moss-device-id is created when missing and adopted as the device id; sessions from this client save to <cache_path>/sessions/<project id>/ by default)

@spec query(t(), String.t(), String.t(), keyword()) ::
  {:ok, Moss.SearchResult.t()} | {:error, Moss.Error.t()}

Query a locally loaded index.

For built-in models, the query is embedded automatically. For indexes created with 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 query_multi_index(t(), [String.t()], String.t(), keyword()) ::
  {:ok, Moss.SearchResult.t()} | {:error, Moss.Error.t()}

Search several loaded indexes in one call and get the global top-k, each result tagged with its source index_name. All names must be loaded (load_index/3 or load_indexes/3) and share one embedding model.

:alpha works exactly as in query/4 (default 0.8): 1.0 is embedding-only, 0.0 is keyword-only, and values in between fuse both with Reciprocal Rank Fusion. Keyword scoring runs each index's own BM25 and merges hits by score before fusion. Keyword-only queries never embed the text, so they also work on custom-model indexes without :embedding.

Options:

• :top_k (integer, default 10; caps the merged result, not each index)
• :alpha (float, default 0.8)
• :filter (map, applied to every index)
• :embedding (list of floats, required for model_id: "custom" unless alpha: 0.0)

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

@spec refresh_index(t(), String.t()) ::
  {:ok, Moss.RefreshResult.t()} | {:error, Moss.Error.t()}

Install the cloud's snapshot of a loaded index when it is newer. A snapshot no newer than the loaded one, with the same model, downloads nothing and returns was_updated: false.

@spec session(t(), String.t(), keyword()) ::
  {:ok, GenServer.server()} | {:error, Moss.Error.t()}

Create or resume a local session index.

If a cloud index with index_name already exists, it is silently loaded into the session, and the session takes its model, even when the index has no documents. If not, the session starts empty. An explicit :model_id that the existing index does not use returns {:error, %Moss.Error{code: :invalid_argument}}.

With auto_load_on_init: false the session skips that load and starts empty with :model_id, so Moss.Session.load_from_disk/3 can restore it with no index download. Moss.Session.push_index/1 before any load replaces the cloud index with the session's documents.

Options:

• :model_id (String.t(), default "moss-minilm")
• :auto_load_on_init (boolean, default true): load an existing cloud index into the session before returning
• :server_name — GenServer name for the Session process

Returns {:ok, pid} on success.

@spec unload_index(t(), String.t()) :: {:ok, :ok} | {:error, Moss.Error.t()}

Unload an index from memory.

@spec unload_indexes(t(), [String.t()]) :: :ok

Bulk-unload indexes. Idempotent for names that are not loaded.