Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/ruvector-collections/README.md

@@ -0,0 +1,196 @@
+# Ruvector Collections
+
+[![Crates.io](https://img.shields.io/crates/v/ruvector-collections.svg)](https://crates.io/crates/ruvector-collections)
+[![Documentation](https://docs.rs/ruvector-collections/badge.svg)](https://docs.rs/ruvector-collections)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Rust](https://img.shields.io/badge/rust-1.77%2B-orange.svg)](https://www.rust-lang.org)
+
+**High-performance collection management for Ruvector vector databases.**
+
+`ruvector-collections` provides multi-tenant collection support with isolated namespaces, schema management, and collection-level configuration. Part of the [Ruvector](https://github.com/ruvnet/ruvector) ecosystem.
+
+## Why Ruvector Collections?
+
+- **Multi-Tenant**: Isolated collections with separate namespaces
+- **Schema Support**: Define and enforce vector schemas
+- **Collection Configs**: Per-collection settings for dimensions, metrics
+- **Thread-Safe**: Concurrent access with DashMap
+- **Metadata Support**: Rich collection metadata and tagging
+
+## Features
+
+### Core Capabilities
+
+- **Collection CRUD**: Create, read, update, delete collections
+- **Namespace Isolation**: Logical separation between collections
+- **Schema Validation**: Enforce vector dimensions and types
+- **Metadata Management**: Tags, descriptions, custom properties
+- **Alias Support**: Human-readable names for collections
+
+### Advanced Features
+
+- **Collection Groups**: Organize collections hierarchically
+- **Access Control**: Collection-level permissions (planned)
+- **Versioning**: Collection schema versioning
+- **Migration**: Tools for collection migration
+- **Statistics**: Per-collection metrics and stats
+
+## Installation
+
+Add `ruvector-collections` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+ruvector-collections = "0.1.1"
+```
+
+## Quick Start
+
+### Create a Collection
+
+```rust
+use ruvector_collections::{CollectionManager, CollectionConfig, Schema};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create collection manager
+    let manager = CollectionManager::new()?;
+
+    // Define collection schema
+    let schema = Schema {
+        dimensions: 384,
+        distance_metric: DistanceMetric::Cosine,
+        vector_type: VectorType::Float32,
+    };
+
+    // Create collection with config
+    let config = CollectionConfig {
+        name: "documents".to_string(),
+        schema,
+        description: Some("Document embeddings".to_string()),
+        metadata: serde_json::json!({
+            "model": "text-embedding-3-small",
+            "created_by": "data-pipeline"
+        }),
+        ..Default::default()
+    };
+
+    let collection = manager.create_collection(config)?;
+    println!("Created collection: {}", collection.id);
+
+    Ok(())
+}
+```
+
+### Manage Collections
+
+```rust
+use ruvector_collections::CollectionManager;
+
+let manager = CollectionManager::new()?;
+
+// List all collections
+for collection in manager.list_collections()? {
+    println!("{}: {} vectors", collection.name, collection.count);
+}
+
+// Get collection by name
+let docs = manager.get_collection("documents")?;
+
+// Update collection metadata
+manager.update_collection("documents", |c| {
+    c.metadata["last_updated"] = serde_json::json!(chrono::Utc::now());
+})?;
+
+// Delete collection
+manager.delete_collection("old_collection")?;
+```
+
+### Collection Aliases
+
+```rust
+// Create alias for collection
+manager.create_alias("docs", "documents_v2")?;
+
+// Swap alias to new collection (zero-downtime migration)
+manager.swap_alias("docs", "documents_v3")?;
+
+// Access via alias
+let collection = manager.get_collection_by_alias("docs")?;
+```
+
+## API Overview
+
+### Core Types
+
+```rust
+// Collection configuration
+pub struct CollectionConfig {
+    pub name: String,
+    pub schema: Schema,
+    pub description: Option<String>,
+    pub metadata: serde_json::Value,
+    pub replicas: usize,
+    pub shards: usize,
+}
+
+// Vector schema
+pub struct Schema {
+    pub dimensions: usize,
+    pub distance_metric: DistanceMetric,
+    pub vector_type: VectorType,
+}
+
+// Collection info
+pub struct Collection {
+    pub id: Uuid,
+    pub name: String,
+    pub schema: Schema,
+    pub count: usize,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub metadata: serde_json::Value,
+}
+```
+
+### Manager Operations
+
+```rust
+impl CollectionManager {
+    pub fn new() -> Result<Self>;
+    pub fn create_collection(&self, config: CollectionConfig) -> Result<Collection>;
+    pub fn get_collection(&self, name: &str) -> Result<Option<Collection>>;
+    pub fn list_collections(&self) -> Result<Vec<Collection>>;
+    pub fn update_collection<F>(&self, name: &str, f: F) -> Result<Collection>;
+    pub fn delete_collection(&self, name: &str) -> Result<bool>;
+    pub fn create_alias(&self, alias: &str, collection: &str) -> Result<()>;
+    pub fn delete_alias(&self, alias: &str) -> Result<bool>;
+}
+```
+
+## Related Crates
+
+- **[ruvector-core](../ruvector-core/)** - Core vector database engine
+- **[ruvector-server](../ruvector-server/)** - REST API server
+- **[ruvector-filter](../ruvector-filter/)** - Metadata filtering
+
+## Documentation
+
+- **[Main README](../../README.md)** - Complete project overview
+- **[API Documentation](https://docs.rs/ruvector-collections)** - Full API reference
+- **[GitHub Repository](https://github.com/ruvnet/ruvector)** - Source code
+
+## License
+
+**MIT License** - see [LICENSE](../../LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Part of [Ruvector](https://github.com/ruvnet/ruvector) - Built by [rUv](https://ruv.io)**
+
+[![Star on GitHub](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
+
+[Documentation](https://docs.rs/ruvector-collections) | [Crates.io](https://crates.io/crates/ruvector-collections) | [GitHub](https://github.com/ruvnet/ruvector)
+
+</div>