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

Add documents to an existing cloud index.

Options:

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

@spec create_index(t(), String.t(), [Moss.DocumentInfo.t()], String.t()) ::
  {:ok, Moss.MutationResult.t()} | {:error, String.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, String.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

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, String.t()}

Delete documents by IDs from a cloud index.

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

Delete a cloud index.

@spec get_docs(t(), String.t(), keyword()) ::
  {:ok, [Moss.DocumentInfo.t()]} | {:error, String.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, String.t()}

Get metadata for a cloud index.

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

Get metadata for a loaded index.

@spec get_job_status(t(), String.t()) ::
  {:ok, Moss.JobStatusResponse.t()} | {:error, String.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, String.t()}

List all cloud indexes for this project.

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

Load a cloud index into memory.

Options:

• :auto_refresh (boolean, default false)
• :polling_interval (integer seconds, default 600)

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)

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

@spec new(String.t(), String.t(), keyword()) :: {:ok, t()} | {:error, String.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)

@spec query(t(), String.t(), String.t(), keyword()) ::
  {:ok, Moss.SearchResult.t()} | {:error, String.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, String.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, String.t()}

Force an immediate refresh of a loaded index from the cloud.

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

Create or resume a local session index.

If a cloud index with index_name already exists, it is silently loaded into the session. If not, the session starts empty.

Options:

• :model_id (String.t(), default "moss-minilm")
• :server_name — GenServer name for the Session process

Returns {:ok, pid} on success.

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

Unload an index from memory.

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

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