valentinus-v1.3.1

Release Notes: Valentinus v1.3.1

Valentinus is a thread-safe vector database for model inference inside LMDB. Version 1.3.1 is a patch release focused on system-level performance optimizations and dependency updates.

🚀 Performance Optimizations

• Optimized Memory Queries: Refactored system memory polling by replacing System::new_all() with a more targeted query:
  System::new_with_specifics(RefreshKind::nothing().with_memory(MemoryRefreshKind::nothing().with_ram());
  This significantly reduces the overhead and execution time when determining available system memory (used to calculate the default LMDB_MAP_SIZE), as the application no longer needlessly queries CPUs, disks, and other irrelevant system components.

📦 Dependency Updates

• sysinfo: Updated the sysinfo crate to version 0.39.3 to leverage the latest system information parsing improvements and ensure compatibility with our new targeted memory queries.

---

Full Changelog: v1.3.0...v1.3.1

valentinus-v1.3.0

Valentinus v1.3.0 Release Notes

The Hexagonal Close Packing (HCP) Architecture Upgrade

We are thrilled to announce Valentinus v1.3.0. This release marks a fundamental shift in how Valentinus handles spatial indexing and high-dimensional vector search. By stepping away from computationally expensive floating-point algorithms (like KD-Trees) and migrating to a mathematically perfect geometric grid, we have drastically reduced CPU overhead while maintaining pinpoint semantic accuracy.

This makes Valentinus faster, leaner, and uniquely suited for local, edge, and off-grid deployments where computing resources and power are at a premium.

🚀 Major Features & Architectural Shifts

• O(1) Geometric Routing: We have completely bypassed iterative array scans and Euclidean distance calculations at query time. Valentinus now uses integer-based Hexagonal Cube Coordinates (q,r,s) to instantly bucket and retrieve vectors via O(1) Hash Map lookups.
• The vecpac Integration: Valentinus is now officially powered by the vecpac crate. This lightweight spatial indexer handles all fraction-to-integer quantization, ensuring every embedded vector snaps perfectly into the Seed of Life hexagonal grid.
• Dimensionality Reduction Pipeline: We implemented a deterministic, pseudo-random projection algorithm that gracefully compresses n-dimensional ONNX embeddings down to a 2D geometric "shadow" for indexing, entirely preserving local semantic neighborhoods without requiring heavy machine learning crates.
• IVF-Hex (Inverted File Hex-Indexing) & Fallback Routing: To combat the Curse of Dimensionality and sparse datasets, Valentinus now intelligently utilizes the Principle of Multiplicity. If a target hex bucket is empty, the engine instantly expands its search to the 6 equidistant neighboring buckets, falling back to a global cosine-similarity scan only when absolutely necessary.
• Zero-Overhead Serialization (The Tuple Trick): To maintain blazing-fast read/write speeds, the new geometric hash map is serialized using native (i32, i32, i32) tuples, entirely bypassing complex crate-to-crate trait inheritance while remaining fully compatible with wincode.

🛠 Improvements & Optimizations

• Insertion-Time Indexing: The heavy lifting has been shifted from query time to insertion time. Collections now pre-calculate and cache their geometric buckets natively, making nearest-neighbor queries near-instantaneous.
• Lower Power Footprint: By replacing floating-point iteration with pure integer math, the database requires significantly less active CPU time per query.

Full Changelog: v1.2.1...v1.3.0

valentinus-v1.2.1

Release Notes

What's Changed

• begin testing bincode migration by @kn0sys in #17
• Release 1.2.1 by @kn0sys in #18

Full Changelog: v1.2.0...v1.2.1

valentinus-v1.2.0

Valentinus v1.2.0 Release Notes

v1.2.0 brings a major architectural upgrade to the storage layer, replacing the legacy serialization engine with wincode for improved performance and type safety. This release also addresses critical security updates in core dependencies.

⚡ Highlights

• Migration to Wincode: We have completely replaced bincode with wincode for all internal database serialization. This change lays the groundwork for faster cold-starts and more efficient memory usage when loading large vector collections.
• Security Hardening: The bytes dependency has been upgraded to the latest secure version, addressing potential vulnerabilities in buffer handling.

⚠️ Breaking Changes

• Storage Format Incompatibility: Due to the migration to wincode, database files created with v1.1.x are not compatible with v1.2.0.
• Action Required: Users must re-index their collections or export/import their data using a raw format (CSV/JSON) when upgrading. Attempting to load a v1.1.x LMDB environment will result in deserialization errors (e.g., WincodeError).

🛠 Technical Improvements

• Refactored EmbeddingCollection: The internal structure for storing embeddings has been optimized. We replaced the direct serialization of ndarray::Array2 with a flattened Vec<f32> and shape tuple. This reduces overhead during the serialization process and eliminates complex custom adapters.
• Test Suite Reliability: Fixed race conditions in the full_etl_and_query_workflow tests by ensuring unique environment paths for parallel test runs.

📦 Dependency Updates

• wincode: Added as the primary serialization crate.
• bincode: Removed.
• bytes: Upgraded to latest version (Security Fix).

valentinus-v1.1.3

Release Notes

Synchronize the custom linfa-nn algorithms to ndarray 0.17 along with ort-2.0.0-rc.11.

valentinus-v1.1.2

Release notes

• Patch the multidimensional metadata filter for in operations. Add tests for valid filters.
• Fix a typo in sentence-transformers setup documentation

Full Changelog: v1.1.1...v.1.1.2

valentinus-v1.1.1

Release Notes

• bump sysinfo
• update documentation

Full Changelog: v1.1.0...v1.1.1

valentinus-v1.1.0

Valentinus v1.1.0 - The Resilience Update

Release Date: July 29, 2025

This is a landmark release for Valentinus, focusing entirely on making the database engine resilient, thread-safe, and production-ready. We've undertaken a significant architectural refactor to address core issues related to concurrency, performance, and data integrity.

---

🚀 Major Features & Architectural Changes

1. New Thread-Safe Architecture with Valentinus

The most significant change is the introduction of the new Valentinus struct. This struct is now the primary, thread-safe entry point for all database operations. It manages the database connection and a new in-memory cache, eliminating the need for global static locks and providing a clear, safe API for concurrent applications.

Old Way (Not Thread-Safe):

// Operations were scattered across static functions, relying on a global lock.
EmbeddingCollection::new(...);
EmbeddingCollection::save(...);
EmbeddingCollection::delete(...);

New Way (Thread-Safe):

// Create one shared instance and use its methods.
use std::sync::Arc;

let valentinus = Arc::new(Valentinus::new("production_env")?);

// All operations are now methods on the central struct.
valentinus.create_collection(...);
valentinus.cosine_query(...);
valentinus.delete_collection(...);

2. High-Performance In-Memory Caching

To dramatically improve query performance, Valentinus now implements a thread-safe, in-memory caching layer. When a collection is accessed for the first time, it is loaded from disk and cached. All subsequent queries for that collection will be served directly from memory, avoiding costly disk I/O and deserialization.

3. Atomic Database Operations

All operations that modify the database state—especially creating and deleting collections—are now performed within single, atomic LMDB transactions. This guarantees that the database indexes can never be left in a corrupt state, even if the application crashes mid-operation. The previous read-modify-write patterns have been completely replaced.

4. Rock-Solid Reliability and Error Handling

We have performed a complete audit to remove all .unwrap(), .expect(), and other panics from the core logic. All functions now return a Result, and errors are propagated cleanly, allowing applications to handle database issues gracefully instead of crashing.

🐛 Bug Fixes

Fixed: Database Deadlocks: Corrected a critical bug where nested write transactions would cause the entire application to hang when creating a collection.

Fixed: Data Integrity in Queries: Resolved a bug in cosine_query where incorrect metadata could be returned for documents with duplicate text content.

Fixed: Collection Lookup Failures: Eliminated an inconsistency in how collection view names were stored and retrieved, which previously caused CollectionNotFound errors immediately after creation.

⚠️ Breaking API Changes

This release introduces significant, necessary breaking changes to the public API to achieve production readiness.

All standalone functions like EmbeddingCollection::new, EmbeddingCollection::save, and EmbeddingCollection::delete have been removed.

All database interactions must now go through an instance of the Valentinus struct. Please update your application to initialize this struct once and share it via an Arc.

The database.rs module no longer contains public constants for keys and views; these are now internal implementation details of the embeddings.rs module.

We believe these changes provide a much safer, faster, and more ergonomic API for building powerful AI applications with Valentinus.

Full Changelog: v1.0.0...v1.1.0

v1.0.0

Release Notes

• first stable release
• bump sysinfo to 35.1
• bump ort to 2.0.0-rc.10

Full Changelog: v0.7.0...v1.0.0

valentinus-v0.7.0

Release Notes

• security patches
• bincode version 2 migration
• use token type ids for ort::inputs

Full Changelog: v0.6.0...v0.7.0