@spec chebyshev(vector(), vector()) :: {:ok, float()} | {:error, term()}

Chebyshev/L-infinity distance over any supported representation.

@spec chebyshev(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Chebyshev/L-infinity distance with per-call compute options.

@spec convert(vector(), target_representation()) ::
  {:ok, raw_vector()} | {:error, term()}

Converts between list, f32-binary, and optional Nx representations.

@spec cosine(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Cosine similarity, with the same normalization options as Vettore.Distance.cosine/3.

@spec dimensions(vector()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the flattened coordinate count.

@spec dot_product(vector(), vector()) :: {:ok, float()} | {:error, term()}

Compatibility alias for inner_product/2.

@spec dot_product(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Compatibility alias for inner_product/3.

@spec from_nx(term(), :list | :f32_binary) :: {:ok, raw_vector()} | {:error, term()}

Converts an Nx tensor into a validated Vettore representation.

@spec hamming(vector(), vector()) :: {:ok, float()} | {:error, term()}

Hamming distance using Vettore's non-zero coordinate semantics.

@spec hamming(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Hamming distance with per-call compute options.

@spec inner_product(vector(), vector()) :: {:ok, float()} | {:error, term()}

Inner/dot product over any supported representation.

@spec inner_product(vector(), vector(), keyword()) ::
  {:ok, float()} | {:error, term()}

Inner/dot product with per-call compute options.

@spec jaccard(vector(), vector()) :: {:ok, float()} | {:error, term()}

Jaccard distance using Vettore's non-zero coordinate semantics.

@spec jaccard(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Jaccard distance with per-call compute options.

@spec l2(vector(), vector()) :: {:ok, float()} | {:error, term()}

L2/Euclidean distance over any supported representation.

@spec l2(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

L2/Euclidean distance with per-call compute options.

@spec l2_squared(vector(), vector()) :: {:ok, float()} | {:error, term()}

Squared L2 distance over any supported representation.

@spec l2_squared(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Squared L2 distance with per-call compute options.

@spec manhattan(vector(), vector()) :: {:ok, float()} | {:error, term()}

Manhattan/L1 distance over any supported representation.

@spec manhattan(vector(), vector(), keyword()) :: {:ok, float()} | {:error, term()}

Manhattan/L1 distance with per-call compute options.

@spec matrix_shape_f32(binary(), pos_integer()) ::
  {:ok, {non_neg_integer(), pos_integer()}} | {:error, term()}

Returns the row/column shape of a row-major little-endian f32 matrix.

@spec mean_pool(
  [vector()],
  keyword()
) :: {:ok, raw_vector()} | {:error, term()}

Mean-pools a non-empty list of equally sized vectors.

@spec mean_pool_f32(binary(), pos_integer(), [non_neg_integer()], keyword()) ::
  {:ok, raw_vector()} | {:error, term()}

Mean-pools selected rows from a row-major little-endian f32 matrix.

The result defaults to :f32_binary; pass as: :list or as: :nx when a different interchange representation is needed. Repeated indices are counted repeatedly, matching token-sequence pooling semantics.

@spec metric(vector(), vector(), metric(), keyword()) ::
  {:ok, float()} | {:error, term()}

Computes one named metric over any pair of supported representations.

@spec negative_inner_product(vector(), vector()) :: {:ok, float()} | {:error, term()}

Negative inner product over any supported representation.

@spec negative_inner_product(vector(), vector(), keyword()) ::
  {:ok, float()} | {:error, term()}

Negative inner product with per-call compute options.

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

Builds a dimensioned vector wrapper in the requested representation.

@spec normalize(vector(), normalization(), keyword()) ::
  {:ok, raw_vector()} | {:error, term()}

Normalizes a vector while allowing the result representation to be selected.

@spec representation(term()) :: representation() | :unknown

Returns the storage representation used by a supported vector value.

@spec reshape(vector(), tuple(), keyword()) :: {:ok, t()} | {:error, term()}

Returns a wrapper with new shape metadata, without changing coordinate order.

@spec shape(vector()) :: {:ok, tuple()} | {:error, term()}

Returns the original tensor shape, or a one-dimensional shape for flat values.

@spec stack(
  [vector()],
  keyword()
) :: {:ok, term()} | {:error, term()}

Stacks equally sized vectors into a row-major matrix representation.

@spec take_rows_f32(binary(), pos_integer(), [non_neg_integer()], keyword()) ::
  {:ok, term()} | {:error, term()}

Selects rows from a row-major f32 matrix without mean pooling them.

@spec to_f32_binary(vector()) :: {:ok, binary()} | {:error, term()}

Converts any supported vector to a validated little-endian f32 binary.

@spec to_list(vector()) :: {:ok, [float()]} | {:error, term()}

Converts any supported vector to a validated flat float list.

@spec to_nx(
  vector(),
  keyword()
) :: {:ok, term()} | {:error, term()}

Converts a vector to an Nx tensor, preserving shape and accepting a host backend.

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

Checks the vector representation, finite f32 values, and wrapper metadata.

@spec valid_matrix_f32?(term(), term()) :: boolean()

Returns whether a complete row-major f32 matrix is structurally valid and finite.

@spec validate_matrix_f32(binary(), pos_integer()) ::
  {:ok, {non_neg_integer(), pos_integer()}} | {:error, term()}

Validates a complete f32 matrix and returns its shape.