# `Zvex`
[🔗](https://github.com/edlontech/zvex/blob/main/lib/zvex.ex#L1)

Elixir bindings for **zvec**, an in-process vector database.

This module manages the zvec library lifecycle: initialization,
shutdown, and version introspection. For collection operations, use
the dedicated modules:

| Module | Purpose |
|---|---|
| `Zvex.Collection` | Collection lifecycle and CRUD |
| `Zvex.Collection.Schema` | Schema builder |
| `Zvex.Document` | Typed document construction |
| `Zvex.Query` | Fluent vector query builder |
| `Zvex.Vector` | Vector packing/unpacking |
| `Zvex.Config` | Library configuration |

## Quick Start

    alias Zvex.{Collection, Document, Query, Vector}
    alias Zvex.Collection.Schema

    # Initialize the library
    :ok = Zvex.initialize()

    # Define a schema
    schema =
      Schema.new("products")
      |> Schema.add_field("id", :string, primary_key: true)
      |> Schema.add_field("embedding", :vector_fp32,
           dimension: 128,
           index: [type: :hnsw, metric: :cosine])
      |> Schema.add_field("name", :string)

    # Create a collection and insert a document
    {:ok, coll} = Collection.create("/tmp/products", schema)

    doc =
      Document.new()
      |> Document.put_pk("prod-1")
      |> Document.put("name", "Widget")
      |> Document.put("embedding", Vector.from_list(List.duplicate(0.1, 128), :fp32))

    {:ok, _} = Collection.insert(coll, doc)

    # Query nearest neighbors
    query_vec = Vector.from_list(List.duplicate(0.1, 128), :fp32)

    {:ok, results} =
      Query.new()
      |> Query.field("embedding")
      |> Query.vector(query_vec)
      |> Query.top_k(5)
      |> Query.execute(coll)

    :ok = Collection.close(coll)
    :ok = Zvex.shutdown()

## Error Handling

Every fallible function comes in two flavours:

- `fun/n` returns `{:ok, result}` or `{:error, %Zvex.Error{}}`.
- `fun!/n` returns the unwrapped result or raises.

See `Zvex.Error` for the full error hierarchy.

# `compatible?`

```elixir
@spec compatible?(non_neg_integer(), non_neg_integer(), non_neg_integer()) ::
  boolean()
```

Checks if the linked zvec library is compatible with the given version.

Returns `true` if the library version is >= the requested version.

## Examples

    iex> Zvex.compatible?(0, 0, 1)
    true

# `initialize`

Initializes the zvec library with default configuration.

# `initialize`

Initializes the zvec library with the given configuration.

# `initialize!`

Initializes the zvec library. Raises on error.

# `initialize!`

Initializes the zvec library with the given configuration. Raises on error.

# `initialized?`

Returns whether the zvec library is initialized.

# `shutdown`

Shuts down the zvec library.

# `shutdown!`

Shuts down the zvec library. Raises on error.

# `version`

Returns the zvec library version.

## Examples

    iex> version = Zvex.version()
    iex> is_integer(version.major) and is_integer(version.minor) and is_integer(version.patch)
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*