tinyquant-sys 0.0.0

/*
 * tinyquant.h — generated by cbindgen from tinyquant-sys.
 *
 * DO NOT EDIT BY HAND. Regenerate with:
 *   cargo build -p tinyquant-sys
 *
 * CI gate: `git diff --exit-code rust/crates/tinyquant-sys/include/tinyquant.h`.
 */
#define TINYQUANT_H_VERSION "0.1.0"



#ifndef TINYQUANT_H
#define TINYQUANT_H


/* Generated with cbindgen:0.27.0 */

/* WARNING: regenerate this file via `cargo build -p tinyquant-sys`. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Compression-policy discriminator over the C ABI.
 */
typedef enum {
    /**
     * Lossy compression through the TinyQuant codec.
     */
    TINY_QUANT_COMPRESSION_POLICY_COMPRESS = 0,
    /**
     * Store the FP32 vector verbatim (no compression).
     */
    TINY_QUANT_COMPRESSION_POLICY_PASSTHROUGH = 1,
    /**
     * Cast to FP16 without quantisation.
     */
    TINY_QUANT_COMPRESSION_POLICY_FP16 = 2,
} TinyQuantCompressionPolicy;

/**
 * Canonical error discriminants emitted by every `tq_*` entry point.
 *
 * Values are fixed for the lifetime of the crate's 0.x line so that C
 * consumers compiled against `tinyquant.h` do not have to recompile on
 * minor-version bumps. Adding a new variant is always allowed; changing
 * an existing discriminant is a breaking change.
 */
typedef enum {
    /**
     * Operation succeeded. `TinyQuantError::message` is guaranteed null.
     */
    TINY_QUANT_ERROR_KIND_OK = 0,
    /**
     * A handle argument was null or previously freed.
     */
    TINY_QUANT_ERROR_KIND_INVALID_HANDLE = 1,
    /**
     * Vector length / dimension mismatch (maps to Python
     * `DimensionMismatchError`).
     */
    TINY_QUANT_ERROR_KIND_DIMENSION_MISMATCH = 2,
    /**
     * `config_hash` of a compressed vector does not match the supplied
     * `CodecConfig` (maps to Python `ConfigMismatchError`).
     */
    TINY_QUANT_ERROR_KIND_CONFIG_MISMATCH = 3,
    /**
     * Codebook bit width does not match the config (maps to Python
     * `CodebookIncompatibleError`).
     */
    TINY_QUANT_ERROR_KIND_CODEBOOK_INCOMPATIBLE = 4,
    /**
     * Duplicate `vector_id` on a corpus insert (maps to Python
     * `DuplicateVectorError`).
     */
    TINY_QUANT_ERROR_KIND_DUPLICATE_VECTOR = 5,
    /**
     * I/O layer error — serialization / file / format issue.
     */
    TINY_QUANT_ERROR_KIND_IO = 6,
    /**
     * Caller passed a malformed argument (null where non-null required,
     * out-of-range integer, wrong buffer size, etc.).
     */
    TINY_QUANT_ERROR_KIND_INVALID_ARGUMENT = 7,
    /**
     * A panic crossed the `extern "C"` boundary. The wrapper captured
     * the payload and set `message` accordingly. No UB.
     */
    TINY_QUANT_ERROR_KIND_PANIC = 98,
    /**
     * An error kind the wrapper could not classify.
     */
    TINY_QUANT_ERROR_KIND_UNKNOWN = 99,
} TinyQuantErrorKind;

/**
 * Opaque handle for `tinyquant_core::codec::Codebook`.
 */
typedef struct {
    uint8_t _private[0];
} CodebookHandle;

/**
 * Opaque handle for `tinyquant_core::codec::CodecConfig`.
 *
 * The real object is a `Box<CodecConfig>`; pointers are minted with
 * `Box::into_raw`. Never dereferenced in this module.
 */
typedef struct {
    uint8_t _private[0];
} CodecConfigHandle;

/**
 * Out-pointer structure populated by every fallible `tq_*` entry point.
 *
 * The caller owns `message` and MUST free it with [`tq_error_free`] or
 * [`tq_error_free_message`]. A fresh `TinyQuantError` may be zero-initialised
 * on the C side with `{0}`; Rust callers use [`TinyQuantError::empty`].
 */
typedef struct {
    /**
     * Discriminant. `Ok` means `message` is guaranteed null.
     */
    TinyQuantErrorKind kind;
    /**
     * Owned NUL-terminated UTF-8 message; null when `kind == Ok`.
     */
    char *message;
} TinyQuantError;

/**
 * Opaque handle for `tinyquant_core::codec::CompressedVector`.
 */
typedef struct {
    uint8_t _private[0];
} CompressedVectorHandle;

/**
 * Opaque handle for `tinyquant_core::corpus::Corpus`.
 */
typedef struct {
    uint8_t _private[0];
} CorpusHandle;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Free a byte buffer previously returned by
 * [`tq_compressed_vector_to_bytes`].
 *
 * # Safety
 *
 * `ptr` / `len`, if `ptr` is non-null, must be the exact pair produced
 * by `tq_compressed_vector_to_bytes`.
 */
void tq_bytes_free(uint8_t *ptr, uintptr_t len);

/**
 * Return the bit width of a codebook. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codebook_train`].
 */
uint8_t tq_codebook_bit_width(const CodebookHandle *handle);

/**
 * Free a codebook handle. Accepts null.
 *
 * # Safety
 *
 * See [`tq_codec_config_free`].
 */
void tq_codebook_free(CodebookHandle *handle);

/**
 * Train a [`Codebook`] from `training_vectors` (row-major, `rows × cols`).
 *
 * # Safety
 *
 * - `training_vectors` must point to at least `rows * cols` `f32`s.
 * - `config`, `out`, `err` must satisfy the usual pointer contracts.
 */
TinyQuantErrorKind tq_codebook_train(const float *training_vectors,
                                     uintptr_t rows,
                                     uintptr_t cols,
                                     const CodecConfigHandle *config,
                                     CodebookHandle **out,
                                     TinyQuantError *err);

/**
 * Compress a single vector.
 *
 * # Safety
 *
 * - `vector` must point to at least `vector_len` `f32`s.
 * - `config`, `codebook`, `out`, `err` must satisfy the usual contracts.
 */
TinyQuantErrorKind tq_codec_compress(const CodecConfigHandle *config,
                                     const CodebookHandle *codebook,
                                     const float *vector,
                                     uintptr_t vector_len,
                                     CompressedVectorHandle **out,
                                     TinyQuantError *err);

/**
 * Return the bit width embedded in a config handle. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codec_config_new`].
 */
uint8_t tq_codec_config_bit_width(const CodecConfigHandle *handle);

/**
 * Return the dimension embedded in a config handle. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codec_config_new`].
 */
uint32_t tq_codec_config_dimension(const CodecConfigHandle *handle);

/**
 * Free a handle returned by [`tq_codec_config_new`]. Accepts null.
 *
 * # Safety
 *
 * - `handle`, if non-null, must be a pointer previously returned by
 *   [`tq_codec_config_new`] and not yet freed.
 */
void tq_codec_config_free(CodecConfigHandle *handle);

/**
 * Return the borrowed NUL-terminated SHA-256 `config_hash`.
 *
 * Pointer is valid until the handle is freed. Returns null on null input.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codec_config_new`].
 */
const char *tq_codec_config_hash(const CodecConfigHandle *handle);

/**
 * Construct a new [`CodecConfig`] and return an opaque handle through
 * `out`.
 *
 * On success, `*out` owns the handle; the caller must pair every
 * successful `tq_codec_config_new` call with a `tq_codec_config_free`.
 *
 * # Errors
 *
 * - `InvalidArgument` if `out` or `err` is null.
 * - `InvalidArgument` for unsupported `bit_width` or zero `dimension`.
 *
 * # Safety
 *
 * - `out`, if non-null, must point to a writable `*mut CodecConfigHandle`.
 * - `err`, if non-null, must point to a valid `TinyQuantError` slot.
 */
TinyQuantErrorKind tq_codec_config_new(uint8_t bit_width,
                                       uint64_t seed,
                                       uint32_t dimension,
                                       bool residual_enabled,
                                       CodecConfigHandle **out,
                                       TinyQuantError *err);

/**
 * Return whether residual correction is enabled. Returns false on null.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codec_config_new`].
 */
bool tq_codec_config_residual_enabled(const CodecConfigHandle *handle);

/**
 * Return the seed embedded in a config handle. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live pointer from [`tq_codec_config_new`].
 */
uint64_t tq_codec_config_seed(const CodecConfigHandle *handle);

/**
 * Decompress a [`CompressedVector`] into the caller-supplied buffer
 * (length must equal `config.dimension()`).
 *
 * # Safety
 *
 * - `out` must point to a writable buffer of `out_len` `f32`s.
 * - Handles must satisfy the usual contracts.
 */
TinyQuantErrorKind tq_codec_decompress(const CodecConfigHandle *config,
                                       const CodebookHandle *codebook,
                                       const CompressedVectorHandle *compressed,
                                       float *out,
                                       uintptr_t out_len,
                                       TinyQuantError *err);

/**
 * Return the bit width of a compressed vector. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live `CompressedVectorHandle`.
 */
uint8_t tq_compressed_vector_bit_width(const CompressedVectorHandle *handle);

/**
 * Return the dimension of a compressed vector. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live `CompressedVectorHandle`.
 */
uint32_t tq_compressed_vector_dimension(const CompressedVectorHandle *handle);

/**
 * Free a compressed vector handle. Accepts null.
 *
 * # Safety
 *
 * `handle`, if non-null, must be a pointer previously returned by
 * [`tq_codec_compress`] or [`tq_compressed_vector_from_bytes`].
 */
void tq_compressed_vector_free(CompressedVectorHandle *handle);

/**
 * Deserialise bytes into a [`CompressedVector`]. Returns a new handle.
 *
 * # Safety
 *
 * - `data` must point to at least `data_len` bytes.
 * - `out`, `err` must satisfy the usual contracts.
 */
TinyQuantErrorKind tq_compressed_vector_from_bytes(const uint8_t *data,
                                                   uintptr_t data_len,
                                                   CompressedVectorHandle **out,
                                                   TinyQuantError *err);

/**
 * Serialise a [`CompressedVector`] to the wire format.
 *
 * On success, `*out_bytes` holds a freshly allocated buffer owned by
 * Rust; release it with [`tq_bytes_free`].
 *
 * # Safety
 *
 * - `handle` must be a live compressed-vector handle.
 * - `out_bytes` and `out_len` must be writable.
 */
TinyQuantErrorKind tq_compressed_vector_to_bytes(const CompressedVectorHandle *handle,
                                                 uint8_t **out_bytes,
                                                 uintptr_t *out_len,
                                                 TinyQuantError *err);

/**
 * Return `true` iff `vector_id` is present in the corpus.
 *
 * # Safety
 *
 * `handle` must be null or a live corpus handle. `vector_id` must be a
 * NUL-terminated UTF-8 string.
 */
bool tq_corpus_contains(const CorpusHandle *handle, const char *vector_id);

/**
 * Free a corpus handle. Accepts null.
 *
 * # Safety
 *
 * `handle`, if non-null, must be a pointer previously returned by
 * [`tq_corpus_new`].
 */
void tq_corpus_free(CorpusHandle *handle);

/**
 * Insert a vector into the corpus with a given NUL-terminated id.
 *
 * # Safety
 *
 * - `handle` must be a live corpus handle.
 * - `vector_id` must be a valid NUL-terminated UTF-8 string.
 * - `vector` must point to at least `vector_len` `f32`s.
 */
TinyQuantErrorKind tq_corpus_insert(CorpusHandle *handle,
                                    const char *vector_id,
                                    const float *vector,
                                    uintptr_t vector_len,
                                    int64_t timestamp,
                                    TinyQuantError *err);

/**
 * Construct a new [`Corpus`] handle.
 *
 * `corpus_id` is a borrowed NUL-terminated UTF-8 string; the corpus
 * copies it internally.
 *
 * # Safety
 *
 * - `corpus_id` must be a valid pointer to a NUL-terminated UTF-8
 *   string or null (treated as `"corpus"`).
 * - `config`, `codebook` must be live handles.
 * - `out`, `err` must satisfy the usual contracts.
 */
TinyQuantErrorKind tq_corpus_new(const char *corpus_id,
                                 const CodecConfigHandle *config,
                                 const CodebookHandle *codebook,
                                 TinyQuantCompressionPolicy policy,
                                 CorpusHandle **out,
                                 TinyQuantError *err);

/**
 * Return the number of vectors in the corpus. Returns 0 on null.
 *
 * # Safety
 *
 * `handle` must be null or a live corpus handle.
 */
uintptr_t tq_corpus_vector_count(const CorpusHandle *handle);

/**
 * Free the `message` pointer owned by a [`TinyQuantError`] and reset the
 * struct to `Ok`.
 *
 * Idempotent — calling more than once on the same struct is safe.
 * Accepts a null `err` pointer as a no-op.
 *
 * # Safety
 *
 * - `err`, if non-null, must point to a `TinyQuantError` populated by a
 *   TinyQuant entry point or zero-initialised by the caller.
 * - The `message` field must not have been freed by any allocator other
 *   than this function.
 */
void tq_error_free(TinyQuantError *err);

/**
 * Free a `message` pointer extracted from a [`TinyQuantError`].
 *
 * Useful when the caller wants to extract the `message`, print it, then
 * release the allocation without touching the surrounding struct.
 *
 * # Safety
 *
 * `message`, if non-null, must have originated from a `TinyQuantError`
 * populated by a TinyQuant entry point (i.e. a Rust `CString::into_raw`
 * allocation).
 */
void tq_error_free_message(char *message);

/**
 * Return the crate version as a borrowed NUL-terminated C string.
 *
 * The returned pointer points into a `'static` string literal with an
 * embedded NUL terminator, so it is safe to share across threads and
 * lives for the program's lifetime.
 *
 * # Safety
 *
 * The function itself is safe to call; it is declared `unsafe extern`
 * only to match the ABI convention documented in the module header.
 */
const char *tq_version(void);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* TINYQUANT_H */