@spec attach_file_references(
  t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Appends uploaded file references from request options to a text or content-part query.

Supports :file_id, :file_ids, :file_reference, and :file_references. File references can be strings, keyword lists, or maps with :file_id/"file_id" plus optional :media_type, :filename, :metadata, :title, :context, or :citations.

Returns an explicit unsupported error when the active ReqLLM version does not expose ReqLLM.Message.ContentPart.file_id/3.

@spec content_part?(term()) :: boolean()

Returns true when a term is a ReqLLM content part or compatible content-part map.

@spec schema(keyword()) :: Zoi.schema()

Returns a Zoi schema that accepts text or a non-empty list of ReqLLM content parts.

@spec summarize(t()) :: String.t()

Builds a text summary for event metadata without discarding the original query.

@spec validate_content_parts(
  term(),
  keyword()
) :: :ok | {:error, String.t()}

Validates that a parsed multimodal query is a non-empty list of content parts.