sqlodin 0.6.0__py3-none-any.whl

sqlodin/errors.py

@@ -0,0 +1,42 @@
+"""Errors distinguish rejected requests from writes whose outcome is unknown."""
+
+
+class Error(Exception):
+    """Base class for SQLodin client errors."""
+
+
+class ConnectionError(Error):
+    """No usable authenticated connection, or an invalid server response."""
+
+
+class QueryError(Error):
+    """The server rejected a SQL statement or its bounded result."""
+
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+
+class ConstraintError(QueryError):
+    """A constraint rejected and rolled back the entire transaction."""
+
+
+class SerializationError(QueryError):
+    """The read version changed; retry the complete transaction after rollback."""
+    sqlstate = "40001"
+
+
+class SessionError(QueryError):
+    """A session identity is stale, conflicted, or cannot be admitted."""
+
+
+class PendingWriteError(Error):
+    """Resolve the outstanding write before submitting another one."""
+
+
+class UnknownOutcome(Error):
+    """The write may have committed. Retry its identity, never a fresh write."""
+
+    def __init__(self, pending):
+        self.pending = pending
+        super().__init__("Write outcome unknown; call resolve_pending() to retry the same request")

sqlodin/parameters.py

@@ -0,0 +1,86 @@
+"""Bound values and qmark translation; values are never interpolated into SQL."""
+import math
+from collections.abc import Sequence
+from .vector import Vector
+
+Value = str | int | float | Vector | None
+
+
+def encode(value: Value) -> dict:
+    if isinstance(value, Vector):
+        return {"kind": "vector", "vector": list(value)}
+    if value is None:
+        return {"kind": "null"}
+    if isinstance(value, int):
+        if not -(2**63) <= value < 2**63:
+            raise ValueError("Integers must fit SQLite's signed 64-bit range")
+        return {"kind": "integer", "integer": int(value)}
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("Floating-point parameters must be finite")
+        return {"kind": "real", "real": value}
+    if isinstance(value, str):
+        if len(value.encode('utf-8')) > 256:
+            raise ValueError("Text parameters are limited to 256 UTF-8 bytes")
+        return {"kind": "text", "text": value}
+    raise TypeError("Parameters support str, int, float, Vector, and None")
+
+
+def prepare(sql: str, parameters: Sequence[Value], offset: int = 0) -> tuple[str, tuple[Value, ...]]:
+    if not isinstance(sql, str) or not sql.strip() or '\x00' in sql:
+        raise ValueError("SQL must be a nonempty string without NUL")
+    if isinstance(parameters, (str, bytes, dict)):
+        raise TypeError("Parameters must be a sequence of values")
+    values = tuple(parameters)
+    if offset + len(values) > 16:
+        raise ValueError("A request supports at most 16 parameters")
+    if sum(len(v) for v in values if isinstance(v, Vector)) > 384:
+        raise ValueError("A request supports at most 384 vector components in total")
+    for value in values:
+        encode(value)
+    # SQLite lexical quoting and comments; reject numbered/named bindings so a
+    # batch can assign one unambiguous global parameter tuple to all statements.
+    out, count, i = [], 0, 0
+    while i < len(sql):
+        char = sql[i]
+        if sql.startswith('--', i):
+            end = sql.find('\n', i)
+            end = len(sql) if end == -1 else end
+        elif sql.startswith('/*', i):
+            end = sql.find('*/', i + 2)
+            if end == -1:
+                raise ValueError("Unterminated SQL comment")
+            end += 2
+        elif char in "'\"`[":
+            closing = ']' if char == '[' else char
+            end = i + 1
+            while end < len(sql):
+                if sql[end] == closing:
+                    end += 1
+                    if closing != ']' and end < len(sql) and sql[end] == closing:
+                        end += 1
+                        continue
+                    break
+                end += 1
+            else:
+                raise ValueError("Unterminated SQL quote")
+        else:
+            if char == '?':
+                if i + 1 < len(sql) and sql[i + 1].isdigit():
+                    raise ValueError("Use plain ? placeholders, not numbered parameters")
+                count += 1
+                out.append(f'?{offset + count}')
+            elif char in ':@$':
+                raise ValueError("Use plain ? placeholders, not named parameters")
+            else:
+                out.append(char)
+            i += 1
+            continue
+        out.append(sql[i:end])
+        i = end
+    if count != len(values):
+        raise ValueError(f"SQL has {count} placeholders but received {len(values)} parameters")
+    text = ''.join(out)
+    if len(text.encode('utf-8')) > 4096:
+        raise ValueError("A SQL request is limited to 4096 UTF-8 bytes")
+    return text, values

sqlodin/results.py

@@ -0,0 +1,67 @@
+"""Owned, immutable results: iteration, named columns, and explicit cardinality."""
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, overload
+
+
+@dataclass(frozen=True)
+class Row(Mapping[str, Any]):
+    _columns: tuple[str, ...]
+    _values: tuple[Any, ...]
+
+    def __getitem__(self, key: str | int) -> Any:
+        if isinstance(key, int):
+            return self._values[key]
+        try:
+            return self._values[self._columns.index(key)]
+        except ValueError:
+            raise KeyError(key) from None
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(dict.fromkeys(self._columns))
+
+    def __len__(self) -> int:
+        return len(set(self._columns))
+
+    def as_tuple(self) -> tuple[Any, ...]:
+        return self._values
+
+
+@dataclass(frozen=True)
+class Rows(Sequence[Row]):
+    columns: tuple[str, ...]
+    _rows: tuple[Row, ...]
+    applied: int
+    node: int
+
+    @overload
+    def __getitem__(self, index: int) -> Row: ...
+    @overload
+    def __getitem__(self, index: slice) -> tuple[Row, ...]: ...
+    def __getitem__(self, index):
+        return self._rows[index]
+
+    def __len__(self) -> int:
+        return len(self._rows)
+
+    def first(self) -> Row | None:
+        return self._rows[0] if self._rows else None
+
+    def one(self) -> Row:
+        if len(self) != 1:
+            raise ValueError(f"Expected exactly one row, received {len(self)}")
+        return self._rows[0]
+
+    def scalar(self) -> Any:
+        row = self.one()
+        if len(self.columns) != 1:
+            raise ValueError(f"Expected one column, received {len(self.columns)}")
+        return row[0]
+
+
+@dataclass(frozen=True)
+class WriteResult:
+    changes: int
+    applied: int
+    node: int
+    sequence: int

sqlodin/search.py

@@ -0,0 +1,110 @@
+"""FTS5 and exact vector retrieval over one atomically maintained search index."""
+import re
+from .vector import Vector
+
+
+def identifier(name: str) -> str:
+    if not isinstance(name, str) or not re.fullmatch(r'[A-Za-z][A-Za-z0-9_]{0,63}', name):
+        raise ValueError('Index names need 1..64 ASCII letters, digits or underscores, starting with a letter')
+    if name.lower().startswith('sqlite_'):
+        raise ValueError('Reserved index name')
+    return '"' + name + '"'
+
+
+def bound(value, name, maximum=100):
+    if type(value) is not int or not 1 <= value <= maximum:
+        raise ValueError(f'{name} must be an integer in 1..{maximum}')
+    return value
+
+
+class SearchIndex:
+    def __init__(self, connection, name: str, *, dimensions: int):
+        self.connection, self.name = connection, name
+        if not isinstance(name, str) or len(name) > 60:
+            raise ValueError("Search index names must be at most 60 characters")
+        self.table, self.fts = identifier(name), identifier(name + '_fts')
+        self.dimensions = bound(dimensions, 'dimensions', 384)
+
+    def create(self):
+        """Fail if either table exists; never silently accept a different schema."""
+        return self.connection.execute(
+            f'CREATE TABLE {self.table}(id INTEGER PRIMARY KEY,title TEXT NOT NULL,body TEXT NOT NULL,'
+            f'embedding BLOB NOT NULL CHECK(length(embedding)={self.dimensions * 4}));'
+            f'CREATE VIRTUAL TABLE {self.fts} USING fts5(title,body);')
+
+    def _vector(self, value):
+        value = value if isinstance(value, Vector) else Vector(value)
+        if len(value) != self.dimensions:
+            raise ValueError(f'Expected {self.dimensions} vector dimensions, received {len(value)}')
+        return value
+
+    def put(self, id: int, *, title: str, body: str, vector):
+        """Atomically insert/update the content, embedding, and FTS document."""
+        if type(id) is not int or not 1 <= id < 2**63 - 1:
+            raise ValueError('Document ID must be a positive integer below SQLite maximum rowid')
+        value = self._vector(vector)
+        with self.connection.transaction() as tx:
+            tx.execute(f'INSERT INTO {self.table}(id,title,body,embedding) VALUES(?,?,?,?) '
+                       'ON CONFLICT(id) DO UPDATE SET title=excluded.title,body=excluded.body,'
+                       'embedding=excluded.embedding', (id, title, body, value))
+            tx.execute(f'DELETE FROM {self.fts} WHERE rowid=?', (id,))
+            tx.execute(f'INSERT INTO {self.fts}(rowid,title,body) VALUES(?,?,?)', (id, title, body))
+        return tx.result
+
+    def delete(self, id: int):
+        if type(id) is not int or not 1 <= id < 2**63 - 1:
+            raise ValueError('Invalid document ID')
+        with self.connection.transaction() as tx:
+            tx.execute(f'DELETE FROM {self.fts} WHERE rowid=?', (id,))
+            tx.execute(f'DELETE FROM {self.table} WHERE id=?', (id,))
+        return tx.result
+
+    def full_text(self, text: str, *, limit: int = 20):
+        """FTS5 query syntax; lower BM25 score is better. SQL values stay bound."""
+        bound(limit, 'limit')
+        return self.connection.query(
+            f'SELECT d.id,d.title,d.body,bm25({self.fts}) AS score '
+            f'FROM {self.fts} JOIN {self.table} AS d ON d.id={self.fts}.rowid '
+            f'WHERE {self.fts} MATCH ? ORDER BY score,d.id LIMIT ?', (text, limit))
+
+    def nearest(self, vector, *, limit: int = 20, metric: str = 'l2'):
+        """Exact distance scan, not an ANN index. Lower distance is better."""
+        function = self._metric(metric)
+        value = self._vector(vector)
+        if metric == 'cosine' and not any(value):
+            raise ValueError('Cosine distance requires a nonzero query vector')
+        bound(limit, 'limit')
+        return self.connection.query(
+            f'SELECT id,title,body,{function}(embedding,?) AS distance FROM {self.table} '
+            'ORDER BY distance,id LIMIT ?', (value, limit))
+
+    @staticmethod
+    def _metric(metric):
+        if metric not in ('l2', 'cosine'):
+            raise ValueError("Metric must be 'l2' or 'cosine'")
+        return 'vec_distance_' + metric
+
+    def hybrid(self, text: str, vector, *, limit: int = 20, candidates: int = 50,
+               rank_constant: int = 60, metric: str = 'l2'):
+        """Reciprocal-rank fusion of FTS and vector candidates in one fenced snapshot."""
+        bound(limit, 'limit')
+        bound(candidates, 'candidates')
+        bound(rank_constant, 'rank_constant', 1000)
+        if candidates < limit:
+            raise ValueError('Candidates must be at least limit')
+        function = self._metric(metric)
+        value = self._vector(vector)
+        if metric == 'cosine' and not any(value):
+            raise ValueError('Cosine distance requires a nonzero query vector')
+        sql = f'''WITH
+          ft AS MATERIALIZED (SELECT rowid AS id,bm25({self.fts}) AS score FROM {self.fts}
+            WHERE {self.fts} MATCH ? ORDER BY score,id LIMIT ?),
+          vt AS MATERIALIZED (SELECT id,{function}(embedding,?) AS distance FROM {self.table}
+            ORDER BY distance,id LIMIT ?),
+          ranks AS (SELECT id,ROW_NUMBER() OVER(ORDER BY score,id) AS rank FROM ft
+            UNION ALL SELECT id,ROW_NUMBER() OVER(ORDER BY distance,id) AS rank FROM vt),
+          fused AS (SELECT id,SUM(1.0 / (? + rank)) AS score FROM ranks GROUP BY id)
+          SELECT d.id,d.title,d.body,f.score FROM fused AS f JOIN {self.table} AS d ON d.id=f.id
+          ORDER BY f.score DESC,d.id LIMIT ?'''
+        return self.connection.query(sql, (text, candidates, value, candidates,
+                                           rank_constant, limit))

sqlodin/sqlalchemy.py

@@ -0,0 +1,138 @@
+"""SQLAlchemy 2.0 dialect with optimistic serializable ORM transactions."""
+from sqlalchemy import create_engine as sa_create_engine
+from sqlalchemy.dialects import registry
+from sqlalchemy.dialects.sqlite.base import SQLiteDialect
+from sqlalchemy.types import UserDefinedType
+
+from . import dbapi
+from .vector import Vector
+
+
+class SQLodinDialect(SQLiteDialect):
+    name = 'sqlodin'
+    driver = 'native'
+    supports_statement_cache = True
+    insert_returning = update_returning = delete_returning = False
+    use_insertmanyvalues = False
+    postfetch_lastrowid = True
+    # Preview returns sqlite3_changes for the outer statement, excluding triggers.
+    supports_sane_rowcount = True
+    supports_sane_multi_rowcount = True
+    supports_default_values = True
+
+    def __init__(self, **kwargs):
+        # SQLite's constructor assumes a local sqlite3 module. This remote driver
+        # obtains the actual server version after connecting instead.
+        module = kwargs.pop('dbapi', None)
+        super().__init__(dbapi=None, **kwargs)
+        self.dbapi = module
+
+    @classmethod
+    def import_dbapi(cls): return dbapi
+
+    def create_connect_args(self, url):
+        if url.host or url.database or url.username or url.password or url.query:
+            raise ValueError('Use sqlodin:// with explicit connect_args for endpoints, cluster and TLS')
+        return [], {}
+
+    def _get_server_version_info(self, connection):
+        value = connection.exec_driver_sql('SELECT sqlite_version()').scalar()
+        return tuple(map(int, value.split('.')))
+
+    def _get_default_schema_name(self, connection): return 'main'
+    def get_default_isolation_level(self, connection): return 'SERIALIZABLE'
+    def get_isolation_level(self, connection): return 'AUTOCOMMIT' if connection.autocommit else 'SERIALIZABLE'
+    def get_isolation_level_values(self, connection): return ['SERIALIZABLE', 'AUTOCOMMIT']
+    def detect_autocommit_setting(self, connection): return connection.autocommit
+
+    def set_isolation_level(self, connection, level):
+        if level not in ('SERIALIZABLE', 'AUTOCOMMIT'):
+            raise dbapi.NotSupportedError('Supported isolation levels: SERIALIZABLE and AUTOCOMMIT')
+        connection.autocommit = level == 'AUTOCOMMIT'
+
+    def do_savepoint(self, connection, name):
+        connection.connection.dbapi_connection.savepoint(name)
+
+    def do_rollback_to_savepoint(self, connection, name):
+        connection.connection.dbapi_connection.rollback_savepoint(name)
+
+    def do_release_savepoint(self, connection, name):
+        connection.connection.dbapi_connection.release_savepoint(name)
+
+    def do_begin_twophase(self, connection, xid):
+        raise dbapi.NotSupportedError('Two-phase transactions are unsupported')
+
+    def do_execute(self, cursor, statement, parameters, context=None):
+        cursor.execute(statement, parameters)
+
+    def do_executemany(self, cursor, statement, parameters, context=None):
+        cursor.executemany(statement, parameters)
+
+    def has_table(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, 'main'): return False
+        return bool(connection.exec_driver_sql(
+            "SELECT 1 FROM sqlite_schema WHERE name=? AND type IN ('table','view')", (table_name,)).first())
+
+    def get_table_names(self, connection, schema=None, **kw):
+        if schema not in (None, 'main'): return []
+        return [r[0] for r in connection.exec_driver_sql(
+            "SELECT name FROM sqlite_schema WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_sqlodin_%' ORDER BY name")]
+
+    def get_columns(self, *args, **kw):
+        raise NotImplementedError('Schema reflection is not supported; declare SQLAlchemy tables explicitly')
+
+    def get_foreign_keys(self, *args, **kw):
+        raise NotImplementedError('Foreign-key reflection is not supported')
+
+    def get_indexes(self, *args, **kw):
+        raise NotImplementedError('Index reflection is not supported')
+
+    def get_pk_constraint(self, *args, **kw):
+        raise NotImplementedError('Primary-key reflection is not supported')
+
+
+class VectorType(UserDefinedType):
+    """SQLite BLOB storage with typed network float32 bindings and Vector results."""
+    cache_ok = True
+
+    def __init__(self, dimensions: int):
+        if type(dimensions) is not int or not 1 <= dimensions <= 384:
+            raise ValueError('Vector dimensions must be in 1..384')
+        self.dimensions = dimensions
+
+    def get_col_spec(self, **kw): return 'BLOB'
+
+    def bind_processor(self, dialect):
+        def process(value):
+            if value is None: return None
+            value = value if isinstance(value, Vector) else Vector(value)
+            if len(value) != self.dimensions: raise ValueError('Vector dimension mismatch')
+            return value
+        return process
+
+    def result_processor(self, dialect, coltype):
+        def process(value):
+            if value is None: return None
+            vector = Vector.from_bytes(value)
+            if len(vector) != self.dimensions: raise ValueError('Stored vector dimension mismatch')
+            return vector
+        return process
+
+
+registry.register('sqlodin', 'sqlodin.sqlalchemy', 'SQLodinDialect')
+
+
+def create_engine(endpoints, *, cluster, tls, autocommit=False, timeout=10, **options):
+    """Create an ORM/Core engine with SERIALIZABLE transactions by default.
+
+    Writes are provisional until commit. Concurrent application writes cause a
+    serialization error; roll back and retry the entire transaction. Explicit
+    autocommit=True opts into independently committed statements.
+    """
+    if type(autocommit) is not bool: raise ValueError('autocommit must be bool')
+    if 'connect_args' in options or 'isolation_level' in options:
+        raise ValueError('Connection arguments and isolation are set by this helper')
+    return sa_create_engine('sqlodin://', isolation_level='AUTOCOMMIT' if autocommit else 'SERIALIZABLE',
+                            connect_args=dict(endpoints=endpoints, cluster=cluster, tls=tls,
+                                              timeout=timeout, autocommit=autocommit), **options)

sqlodin/transaction.py

@@ -0,0 +1,49 @@
+"""Atomic buffered transaction bodies, without misleading live SQL transactions."""
+from .errors import PendingWriteError
+from .parameters import prepare
+
+
+class Transaction:
+    def __init__(self, connection):
+        self.connection = connection
+        self.result = None
+        self._statements = []
+        self._parameters = []
+        self._active = False
+        self._used = False
+
+    def __enter__(self):
+        db = self.connection
+        db._lock.acquire()
+        try:
+            db._ready()
+            if self._used or db.pending is not None:
+                raise PendingWriteError("Transaction already used or a write needs resolution")
+            self._active = self._used = db._transaction = True
+            return self
+        except BaseException:
+            db._lock.release()
+            raise
+
+    def execute(self, sql, parameters=()):
+        if not self._active:
+            raise PendingWriteError("Use transaction.execute() inside its with block")
+        if len(self._statements) >= 8:
+            raise ValueError("A transaction supports at most eight statements")
+        text, values = prepare(sql, parameters, offset=len(self._parameters))
+        # A newline terminates any trailing -- comment before our separator.
+        body = '\n;\n'.join([*self._statements, text + '\n'])
+        if len(body.encode('utf-8')) > 4096:
+            raise ValueError("A transaction is limited to 4096 UTF-8 bytes")
+        self._statements.append(text + '\n')
+        self._parameters.extend(values)
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        db = self.connection
+        try:
+            self._active = db._transaction = False
+            if exc_type is None and self._statements:
+                self.result = db._execute_prepared('\n;\n'.join(self._statements), tuple(self._parameters))
+        finally:
+            db._lock.release()

sqlodin/transport.py

@@ -0,0 +1,97 @@
+"""TLS 1.3 framed transport with a single absolute deadline per operation."""
+import json
+import socket
+import ssl
+import struct
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ConnectionError
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    address: str
+    server_name: str
+
+    def socket_address(self) -> tuple[str, int]:
+        host, port = self.address.rsplit(':', 1)
+        return host, int(port)
+
+
+@dataclass(frozen=True)
+class TLS:
+    ca: str | Path
+    cert: str | Path
+    key: str | Path
+
+    def context(self) -> ssl.SSLContext:
+        ctx = ssl.create_default_context(cafile=str(self.ca))
+        ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+        ctx.maximum_version = ssl.TLSVersion.TLSv1_3
+        ctx.hostname_checks_common_name = False
+        ctx.load_cert_chain(str(self.cert), str(self.key))
+        return ctx
+
+
+def remaining(deadline: float) -> float:
+    seconds = deadline - time.monotonic()
+    if seconds <= 0:
+        raise TimeoutError("SQLodin operation deadline expired")
+    return seconds
+
+
+class Transport:
+    def __init__(self, tls: TLS):
+        self.context = tls.context()
+        self.socket = None
+        self.endpoint = None
+
+    def close(self):
+        if self.socket is not None:
+            self.socket.close()
+        self.socket = self.endpoint = None
+
+    def exchange(self, endpoint: Endpoint, request: dict, deadline: float) -> dict:
+        body = json.dumps(request, separators=(',', ':'), allow_nan=False).encode('utf-8')
+        if len(body) > 65536:
+            raise ValueError("Encoded request exceeds 64 KiB")
+        try:
+            if self.endpoint != endpoint or self.socket is None:
+                self.close()
+                raw = socket.create_connection(endpoint.socket_address(), timeout=remaining(deadline))
+                try:
+                    raw.settimeout(remaining(deadline))
+                    raw.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+                    self.socket = self.context.wrap_socket(raw, server_hostname=endpoint.server_name)
+                    sans = self.socket.getpeercert().get('subjectAltName', ())
+                    if ('DNS', endpoint.server_name) not in sans:
+                        raise ssl.CertificateError("Server certificate requires an exact DNS SAN")
+                    self.endpoint = endpoint
+                except BaseException:
+                    raw.close()
+                    self.close()
+                    raise
+            self.socket.settimeout(remaining(deadline))
+            self.socket.sendall(struct.pack('<I', len(body)) + body)
+            size = struct.unpack('<I', self._receive(4, deadline))[0]
+            if not 0 < size <= 1024 * 1024:
+                raise ConnectionError("Invalid response frame length")
+            result = json.loads(self._receive(size, deadline))
+            if not isinstance(result, dict):
+                raise ConnectionError("Invalid response object")
+            return result
+        except (OSError, ValueError, ConnectionError) as exc:
+            self.close()
+            raise ConnectionError(str(exc)) from exc
+
+    def _receive(self, size, deadline):
+        data = bytearray()
+        while len(data) < size:
+            self.socket.settimeout(remaining(deadline))
+            chunk = self.socket.recv(size - len(data))
+            if not chunk:
+                raise ConnectionError("Server closed the connection")
+            data.extend(chunk)
+        return data

sqlodin/vector.py

@@ -0,0 +1,47 @@
+"""Immutable, finite float32 vectors with explicit dimensional bounds."""
+import math
+import struct
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, init=False)
+class Vector(Sequence[float]):
+    values: tuple[float, ...]
+
+    def __init__(self, values: Iterable[float]):
+        if isinstance(values, (str, bytes, bytearray)):
+            raise TypeError('Vector expects numeric components; use Vector.from_bytes for a BLOB')
+        normalized = []
+        for value in values:
+            if len(normalized) == 384:
+                raise ValueError('A vector supports at most 384 dimensions')
+            try:
+                number = float(value)
+                number = struct.unpack('<f', struct.pack('<f', number))[0]
+            except (TypeError, ValueError, OverflowError, struct.error) as exc:
+                raise ValueError('Vector components must fit finite float32') from exc
+            if not math.isfinite(number):
+                raise ValueError('Vector components must be finite')
+            normalized.append(number)
+        if not normalized:
+            raise ValueError('A vector must have at least one dimension')
+        object.__setattr__(self, 'values', tuple(normalized))
+
+    def __len__(self) -> int:
+        return len(self.values)
+
+    def __getitem__(self, index):
+        return self.values[index]
+
+    def __iter__(self) -> Iterator[float]:
+        return iter(self.values)
+
+    def to_bytes(self) -> bytes:
+        return struct.pack(f'<{len(self)}f', *self.values)
+
+    @classmethod
+    def from_bytes(cls, value: bytes) -> 'Vector':
+        if not value or len(value) % 4 or len(value) > 384 * 4:
+            raise ValueError('A float32 vector BLOB needs 1..384 four-byte components')
+        return cls(struct.unpack(f'<{len(value) // 4}f', value))