### Install Dependencies and Run Development Server

Source: https://github.com/yarlabs/hyperspace-db/blob/main/dashboard/README.md

Install project dependencies using npm and start the development server. Ensure Node.js 18+ is installed.

```bash
npm install

npm run dev
```

--------------------------------

### Quick Start Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/crates/hyperspace-sdk/README.md

A basic example demonstrating how to connect to HyperspaceDB, create a collection, insert data, and perform a search.

```APIDOC
## Quick Start

```rust
use hyperspace_sdk::Client;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect(
        "http://localhost:50051".to_string(),
        Some("I_LOVE_HYPERSPACEDB".to_string()),
        None,
    ).await?;

    let collection = "docs_rust".to_string();
    let _ = client.delete_collection(collection.clone()).await;
    client.create_collection(collection.clone(), 3, "cosine".to_string()).await?;

    client.insert(
        1,
        vec![0.1, 0.2, 0.3],
        HashMap::new(),
        Some(collection.clone()),
    ).await?;

    let results = client.search(
        vec![0.1, 0.2, 0.3],
        10,
        Some(collection.clone()),
    ).await?;

    println!("results: {}", results.len());
    Ok(())
}
```
```

--------------------------------

### Initialize HyperspaceClient and Perform Operations

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/python.md

Quick start example demonstrating client initialization, inserting data with metadata, and performing a hybrid search.

```python
from hyperspace import HyperspaceClient

client = HyperspaceClient("localhost:50051", api_key="KEY")

# 1. Insert (id comes first)
client.insert(1, [0.1, 0.2], metadata={"tag": "demo"}, collection="docs")

# 2. Hybrid Search (Semantic + BM25)
results = client.search(
    vector=[0.1, 0.2],
    hybrid_query="autonomous robotics",
    hybrid_alpha=0.7,
    collection="docs"
)
```

--------------------------------

### Install hyperspace-sdk and Tokio

Source: https://github.com/yarlabs/hyperspace-db/blob/main/crates/hyperspace-sdk/README.md

Add hyperspace-sdk and tokio to your Cargo.toml to get started.

```toml
[dependencies]
hyperspace-sdk = "3.1.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

--------------------------------

### Setup Python SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/CONTRIBUTING.md

Sets up the Python SDK environment. This includes creating a virtual environment, activating it, installing dependencies, and generating protocol buffers.

```bash
cd sdks/python
python3 -m venv venv
source venv/bin/activate
pip install grpcio-tools grpcio protobuf
./generate_protos.sh
```

--------------------------------

### Setup LangChain Python Integration

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Clone the repository, navigate to the integration directory, and install the package in development mode. This also includes generating protobuf files.

```bash
git clone https://github.com/yourusername/hyperspace-db
cd hyperspace-db/integrations/langchain-python
pip install -e ".[dev]"
./generate_proto.sh
```

--------------------------------

### Install and Use Hyperspace Python SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/README.md

Install the HyperspaceDB Python SDK and connect to a local instance. Includes examples for creating collections, inserting documents, and searching.

```python
pip install hyperspacedb==3.1.0

from hyperspace import HyperspaceClient

# Connect to local instance
client = HyperspaceClient()

# Create a collection with proper Cognitive Metrics
client.create_collection(name="world_model", dimension=64, metric="poincare")

# Insert text document (you can provide your own embeddings)
client.insert(id=1, collection="world_model", document="Hyperspace is autonomous.")

# Search 
results = client.search(query_text="autonomous engine", top_k=5)
print(results)
```

--------------------------------

### Setup TypeScript SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/CONTRIBUTING.md

Sets up the TypeScript SDK environment by installing npm dependencies and building the project. This is necessary for using the TypeScript client.

```bash
cd sdks/ts
npm install
npm run build
```

--------------------------------

### Install Nightly Rust Toolchain

Source: https://github.com/yarlabs/hyperspace-db/blob/main/CONTRIBUTING.md

Installs and sets the Rust nightly toolchain for development. Ensure this is done before proceeding with other setup steps.

```bash
rustup toolchain install nightly
rustup default nightly
```

--------------------------------

### Start MCP Server for HyperspaceDB

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Starts an MCP server that connects to HyperspaceDB. This command requires Node.js and npm to be installed. The HYPERSPACE_HOST and HYPERSPACE_API_KEY environment variables must be set.

```bash
# Start MCP server (connects to HyperspaceDB at HYPERSPACE_HOST)
HYPERSPACE_HOST=localhost:50051 HYPERSPACE_API_KEY=my_key npx mcp-hyperspacedb@latest
```

--------------------------------

### Install macOS Dependencies

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/install.md

Installs the protobuf compiler using Homebrew on macOS.

```bash
brew install protobuf
```

--------------------------------

### Install HyperspaceDB Go SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/go/README.md

Use Go Modules to retrieve and install the HyperspaceDB Go SDK package.

```bash
go get github.com/yarlabs/hyperspace-sdk-go
```

--------------------------------

### Install Tauri CLI and Node Dependencies

Source: https://github.com/yarlabs/hyperspace-db/blob/main/examples/hivemind/README.md

Commands to install the Tauri CLI and Node.js dependencies for the HiveMind example.

```bash
cargo install tauri-cli

cd examples/hivemind
npm install
```

--------------------------------

### Start Database Stack

Source: https://github.com/yarlabs/hyperspace-db/blob/main/benchmarks/README.md

Launches the necessary database services using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### Install HyperspaceDB Python SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/python.md

Install the HyperspaceDB Python client using pip.

```bash
pip install hyperspacedb
```

--------------------------------

### Install HyperspaceDB TypeScript SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/ts/README.md

Install the SDK using npm.

```bash
npm install hyperspace-sdk-ts
```

--------------------------------

### Quick Start: Initialize and Basic Operations

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/python/README.md

Initialize the HyperspaceClient, manage collections, insert a vector, and perform a search. Ensure the HyperspaceDB server is running.

```python
from hyperspace import HyperspaceClient

client = HyperspaceClient("localhost:50051", api_key="I_LOVE_HYPERSPACEDB")
collection = "docs_py"

client.delete_collection(collection)
client.create_collection(collection, dimension=3, metric="cosine")

# id is now the first argument
client.insert(
    id=1,
    vector=[0.1, 0.2, 0.3],
    metadata={"source": "demo"},
    collection=collection,
)

results = client.search(
    vector=[0.1, 0.2, 0.3],
    top_k=5,
    collection=collection,
)
print(results)

client.close()
```

--------------------------------

### Install Just Task Runner

Source: https://github.com/yarlabs/hyperspace-db/blob/main/CONTRIBUTING.md

Installs the 'just' command-line tool, which is used for managing development tasks. This is a prerequisite for running build and other commands.

```bash
cargo install just
```

--------------------------------

### Admin Usage Response Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON response for the /api/admin/usage endpoint, showing usage statistics per tenant.

```json
{
  "tenant_A": {
    "collection_count": 2,
    "vector_count": 1500,
    "disk_usage_bytes": 1048576
  }
}
```

--------------------------------

### Install LlamaIndex Hyperspace Integration

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/llamaindex-python/README.md

Install the necessary packages for the LlamaIndex Hyperspace integration and HyperspaceDB.

```bash
pip install llama-index-vector-stores-hyperspace hyperspacedb
```

--------------------------------

### Install Debian/Ubuntu Dependencies

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/install.md

Installs necessary build tools like protobuf-compiler and cmake on Debian-based systems.

```bash
sudo apt install protobuf-compiler cmake
```

--------------------------------

### System Metrics Response Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON response for system metrics, detailing CPU, RAM, disk usage, and collection/vector counts.

```json
{
    "cpu_usage_percent": 12,
    "ram_usage_mb": 512,
    "disk_usage_mb": 1024,
    "total_collections": 5,
    "total_vectors": 1000000
}
```

--------------------------------

### Run HyperspaceDB MCP Server with npx

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/mcp-hyperspacedb/README.md

Recommended way to run the server without local installation. Ensure Node.js 18+ is installed.

```bash
npx mcp-hyperspacedb
```

--------------------------------

### Install Dependencies

Source: https://github.com/yarlabs/hyperspace-db/blob/main/benchmarks/README.md

Installs project dependencies and the Hyperspace Python SDK using pip within a virtual environment.

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e ../sdks/python
```

--------------------------------

### Install LangChain Hyperspace Integration

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-js/README.md

Install the necessary packages for the LangChain Hyperspace integration. Ensure you have the core LangChain package as well.

```bash
npm install langchain-hyperspace hyperspace-sdk-ts @langchain/core
```

--------------------------------

### Start HyperspaceDB Leader Node

Source: https://github.com/yarlabs/hyperspace-db/blob/main/README.md

Command to start a HyperspaceDB server instance as a leader node, specifying the port and role.

```bash
./hyperspace-server --port 50051 --role leader
```

--------------------------------

### Start HyperspaceDB Server as Follower

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/distributed.md

Configure the server to act as a Follower by specifying the role and the leader's address.

```bash
./hyperspace-server --port 50052 --role follower --leader http://127.0.0.1:50051
```

--------------------------------

### Start HyperspaceDB Server as Leader

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/distributed.md

Run the hyperspace-server executable. By default, it assumes the Leader role.

```bash
./hyperspace-server --port 50051
```

--------------------------------

### RAG Example with HyperspaceDB

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Sets up a Retrieval-Augmented Generation (RAG) chain using HyperspaceVectorStore and an LLM. This example is suitable for building question-answering systems over your data.

```python
from langchain_hyperspace import HyperspaceVectorStore
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain.chains import RetrievalQA

# Setup
embeddings = OpenAIEmbeddings()
vectorstore = HyperspaceVectorStore(
    host="localhost",
    port=50051,
    collection_name="knowledge_base",
    embedding_function=embeddings
)

# Create RAG chain
llm = ChatOpenAI(model_name="gpt-4")
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(search_kwargs={"k": 3})
)

# Ask questions
response = qa_chain.run("What are the key features of HyperspaceDB?")
print(response)
```

--------------------------------

### Quick Start: HyperspaceDB Client Operations

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/ts/README.md

Initialize the client, manage collections, insert and delete vectors, and perform searches. Ensure the HyperspaceDB server is running.

```typescript
import { HyperspaceClient } from "hyperspace-sdk-ts";

async function main() {
  const client = new HyperspaceClient("localhost:50051", "I_LOVE_HYPERSPACEDB");
  const collection = "docs_ts";

  await client.deleteCollection(collection).catch(() => {});
  await client.createCollection(collection, 3, "cosine");

  await client.insert(1, [0.1, 0.2, 0.3], { source: "demo" }, collection);
  await client.insert(2, [0.2, 0.1, 0.4], { source: "demo" }, collection);

  // Delete vector by ID
  await client.delete(1);

  const results = await client.search([0.1, 0.2, 0.3], 5, collection);
  console.log(results);

  client.close();
}

main().catch(console.error);
```

--------------------------------

### Embedding Pipeline Setup

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/python/README.md

Configuration options for setting up embedding pipelines, including environment variables and client-side embedders.

```APIDOC
## Embedding Pipeline (Optional)

### Description
HyperspaceDB supports per-geometry embeddings, allowing each geometry type (e.g., `l2`, `cosine`, `poincare`, `lorentz`) to use its own backend independently. This can be configured via environment variables or using client-side embedders.

### Quick Setup via Environment Variables

Set the `HYPERSPACE_EMBED` environment variable to `true` to enable embeddings. Then, configure providers for specific geometries:

```bash
export HYPERSPACE_EMBED=true

# Cosine geometry → OpenAI API
export HS_EMBED_COSINE_PROVIDER=openai
export HS_EMBED_COSINE_EMBED_MODEL=text-embedding-3-small
export HS_EMBED_COSINE_API_KEY=sk-...

# Poincaré geometry → HuggingFace Hub
export HS_EMBED_POINCARE_PROVIDER=huggingface
export HS_EMBED_POINCARE_HF_MODEL_ID=your-org/cde-spatial-poincare-128d
export HS_EMBED_POINCARE_DIM=128
export HF_TOKEN=hf_...  # Optional: for gated models

# Lorentz geometry → Local ONNX file
export HS_EMBED_LORENTZ_PROVIDER=local
export HS_EMBED_LORENTZ_MODEL_PATH=./models/lorentz_128d.onnx
export HS_EMBED_LORENTZ_TOKENIZER_PATH=./models/lorentz_128d_tokenizer.json
export HS_EMBED_LORENTZ_DIM=129
```

### Client-Side Embedder

The Python SDK also provides client-side embedders, eliminating the need for server-side configuration.

```python
from hyperspace.embedder import OpenAIEmbedder, LocalOnnxEmbedder, HuggingFaceEmbedder
```
```

--------------------------------

### HyperspaceClient SDK Demo (TypeScript)

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Demonstrates various functionalities of the Hyperspace TypeScript SDK, including collection management, data insertion (single, typed metadata, batch), searching (ANN with filters, hybrid BM25, text search, batch search), graph traversal, CDC event subscription, and hyperbolic math operations. Ensure the SDK is installed via 'npm install hyperspace-sdk-ts'.

```typescript
import { HyperspaceClient, CognitiveMath, TribunalContext, DurabilityLevel } from 'hyperspace-sdk-ts';

const client = new HyperspaceClient('localhost:50051', 'my_secret_key', 'tenant_42');

async function demo() {
    // Collection management
    await client.createCollection('docs', 1536, 'cosine');
    const collections = await client.listCollections();
    // [{name: 'docs', count: 0, dimension: 1536, metric: 'cosine'}]

    // Insert with typed metadata
    await client.insert(
        1,
        new Array(1536).fill(0.1),
        { source: 'web' },           // string metadata
        'docs',
        DurabilityLevel.BATCH,
        { score: 0.95, year: 2024 }  // typed metadata
    );

    // Server-side text insert
    await client.insertText(2, 'Hyperbolic geometry in AI', { topic: 'math' }, 'docs');

    // Batch insert
    await client.batchInsert(
        Array.from({ length: 100 }, (_, i) => ({
            id: i + 10,
            vector: new Array(1536).fill(i / 100),
            typedMetadata: { rank: i }
        })),
        'docs'
    );

    // ANN search with filters and hybrid BM25
    const results = await client.search(
        new Array(1536).fill(0.1),
        10,
        'docs',
        {
            filters: [{ range: { key: 'score', gte: 0.8, lte: 1.0 } }],
            hybridQuery: 'geometry AI',
            hybridAlpha: 0.7,
            bm25: { method: 'bm25plus', language: 'english', fusionMethod: 'rrf' }
        }
    );
    // [{id: 1, distance: 0.02, metadata: {source: 'web'}, typedMetadata: {score: 0.95}}, ...]

    // Text search (server-side vectorization)
    const textResults = await client.searchText('hyperbolic embeddings', 5, 'docs');

    // Batch search (multiple query vectors in one RPC)
    const batch = await client.searchBatch(
        [new Array(1536).fill(0.1), new Array(1536).fill(0.2)],
        5,
        'docs'
    );

    // Graph traversal
    const node      = await client.getNode(1, 0, 'docs');
    const neighbors = await client.getNeighbors(1, 0, 32, 0, 'docs');
    const subgraph  = await client.traverse(1, 0, 3, 256, 'docs');
    const clusters  = await client.findSemanticClusters(0, 3, 16, 5000, 'docs');

    // CDC event stream
    client.subscribeToEvents(
        { types: ['insert', 'delete'], collection: 'docs' },
        (event) => console.log('CDC event:', event.toObject())
    );

    // Hyperbolic math (built into the SDK)
    const x = [0.1, 0.2, 0.0], y = [0.3, 0.1, 0.0];
    const z    = CognitiveMath.mobiusAdd(x, y);
    const mean = CognitiveMath.frechetMean([x, y]);
    const { delta, recommendation } = CognitiveMath.analyzeDeltaHyperbolicity(
        Array.from({ length: 200 }, () => [Math.random(), Math.random(), Math.random()])
    );
    console.log(`Delta: ${delta.toFixed(4)}, use: ${recommendation}`);

    client.close();
}
demo().catch(console.error);
```

--------------------------------

### Start a Single HyperspaceDB Instance

Source: https://github.com/yarlabs/hyperspace-db/blob/main/DockerHub.md

Run a detached HyperspaceDB container and expose the default gRPC port (50051).

```bash
docker run -d \
  --name hyperspace \
  -p 50051:50051 \
  glukhota/hyperspace-db:latest

```

--------------------------------

### gRPC: Range Filter Examples

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Illustrates how to define range filters for numeric metadata, including compatibility integer and recommended decimal thresholds.

```protobuf
Filter {
  range: {
    key: "depth",
    gte: 2,
    lte: 10
  }
}

// Decimal threshold (recommended for typed numeric metadata)
Filter {
  range: {
    key: "energy",
    gte_f64: 0.8,
    lte_f64: 1.0
  }
}

```

--------------------------------

### Start Single HyperspaceDB Instance

Source: https://github.com/yarlabs/hyperspace-db/blob/main/README.md

Run a single instance of HyperspaceDB using Docker. Exposes gRPC on port 50051 and the dashboard on port 50050.

```bash
docker run -d \
  --name hyperspace \
  -p 50051:50051 \
  -p 50050:50050 \
  glukhota/hyperspace-db:latest
```

--------------------------------

### Go SDK: Full Example

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Demonstrates various operations using the Go SDK, including client initialization, collection management, data insertion (single, text, batch), ANN and hybrid search, text vectorization, delta synchronization, and deletion.

```go
package main

import (
    "context"
    "fmt"
    "log"
    hyperspace "github.com/yarlabs/hyperspace-sdk-go"
    pb "github.com/yarlabs/hyperspace-sdk-go/proto"
)

func main() {
    ctx := context.Background()

    client, err := hyperspace.NewClient("localhost:50051", "my_secret_key")
    if err != nil { log.Fatal(err) }
    defer client.Close()

    // Create collection
    if err := client.CreateCollection(ctx, "docs", 1536, "cosine"); err != nil {
        log.Fatal(err)
    }

    // Insert vector
    vec := make([]float64, 1536)
    for i := range vec { vec[i] = 0.1 }
    if err := client.Insert(ctx, 1, vec, "docs"); err != nil { log.Fatal(err) }

    // Server-side text insert
    if err := client.InsertText(ctx, 2, "hyperbolic geometry in AI", "docs"); err != nil {
        log.Fatal(err)
    }

    // Batch insert
    ids     := []uint32{10, 11, 12}
    vectors := [][]float64{vec, vec, vec}
    if err := client.BatchInsert(ctx, ids, vectors, "docs"); err != nil { log.Fatal(err) }

    // ANN search
    results, err := client.Search(ctx, vec, 5, "docs", nil)
    if err != nil { log.Fatal(err) }
    for _, r := range results {
        fmt.Printf("id=%d dist=%.4f\n", r.Id, r.Distance)
    }

    // Hybrid BM25 + vector search
    hybridQuery := "AI memory systems"
    hybridAlpha := float32(0.7)
    results, err = client.Search(ctx, vec, 10, "docs", &hyperspace.SearchParams{
        HybridQuery: hybridQuery,
        HybridAlpha: hybridAlpha,
        BM25Options: &pb.Bm25Options{Method: "bm25plus", Language: "english"},
    })

    // SearchText (server-side vectorization)
    textResults, err := client.SearchText(ctx, "autonomous agents", 5, "docs", 0.0, nil)
    if err != nil { log.Fatal(err) }
    fmt.Printf("Text results: %d\n", len(textResults))

    // Vectorize text
    embedding, err := client.Vectorize(ctx, "Poincaré ball model", "cosine")
    fmt.Printf("Embedding dim: %d\n", len(embedding))

    // Delta sync
    buckets := make([]uint64, 256) // local bucket hashes
    syncResp, err := client.SyncHandshake(ctx, "docs", buckets, 0, 0)
    if err != nil { log.Fatal(err) }
    fmt.Printf("In sync: %v, diff buckets: %d\n", syncResp.InSync, len(syncResp.DiffBuckets))

    if !syncResp.InSync {
        diffIdx := make([]uint32, len(syncResp.DiffBuckets))
        for i, b := range syncResp.DiffBuckets { diffIdx[i] = uint32(b.BucketIndex) }
        stream, err := client.SyncPull(ctx, "docs", diffIdx)
        if err != nil { log.Fatal(err) }
        for {
            item, err := stream.Recv()
            if err != nil { break }
            fmt.Printf("Pulled vector id=%d\n", item.Id)
        }
    }

    // Delete
    client.Delete(ctx, 1, "docs")
}
```

--------------------------------

### Rust Zero-Cost Abstraction Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/articles/rust-64x-compression.md

Compares high-level iterator-based code with its low-level equivalent, demonstrating Rust's zero-cost abstractions that compile to efficient assembly.

```rust
// High-level code
vectors.iter().map(|v| v.norm()).sum()

// Compiles to same assembly as:
let mut sum = 0.0;
for v in vectors {
    sum += v.norm();
}
```

--------------------------------

### Clone HyperspaceDB Repository

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Clone the HyperspaceDB repository from GitHub to get started.

```bash
git clone https://github.com/yourusername/hyperspace-db
cd hyperspace-db
```

--------------------------------

### Basic Client Initialization and Search

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Demonstrates how to initialize the Hyperspace client using a context manager and perform a basic search operation.

```python
with HyperspaceClient("localhost:50051") as c:
    c.search(vector=[0.0] * 64, top_k=3, collection="world_model")
```

--------------------------------

### Get Collection Statistics API Request

Source: https://github.com/yarlabs/hyperspace-db/blob/main/dashboard/README.md

Example of how to retrieve statistics for a specific collection. Requires an API key in the headers.

```http
GET /api/collections/{name}/stats
Headers: { 'x-api-key': 'YOUR_KEY' }
```

--------------------------------

### Quick Start: Connect, Create, Insert, and Search

Source: https://github.com/yarlabs/hyperspace-db/blob/main/crates/hyperspace-sdk/README.md

Demonstrates basic client connection, collection management, inserting a vector, and performing a search. Ensure HyperspaceDB is running on http://localhost:50051.

```rust
use hyperspace_sdk::Client;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect(
        "http://localhost:50051".to_string(),
        Some("I_LOVE_HYPERSPACEDB".to_string()),
        None,
    ).await?;

    let collection = "docs_rust".to_string();
    let _ = client.delete_collection(collection.clone()).await;
    client.create_collection(collection.clone(), 3, "cosine".to_string()).await?;

    client.insert(
        1,
        vec![0.1, 0.2, 0.3],
        HashMap::new(),
        Some(collection.clone()),
    ).await?;

    let results = client.search(
        vec![0.1, 0.2, 0.3],
        10,
        Some(collection.clone()),
    ).await?;

    println!("results: {}", results.len());
    Ok(())
}
```

--------------------------------

### Quick Start with HyperspaceDB Client

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/dart/README.md

Initialize the HyperspaceClient, create a collection, insert data, and perform a search. Ensure the client is properly configured with host, port, and API key.

```dart
import 'package:hyperspacedb/hyperspacedb.dart';

void main() async {
  final client = HyperspaceClient('localhost', 50051, apiKey: 'I_LOVE_HYPERSPACEDB');
  
  await client.createCollection('docs_dart', 128, 'cosine');
  
  await client.insert(1, [0.1, 0.2, 0.3], collection: 'docs_dart');
  
  final results = await client.search([0.1, 0.2, 0.3], 5, collection: 'docs_dart');
  print(results);
}
```

--------------------------------

### Initialize HyperspaceDB Client and Perform Basic Operations

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/go/README.md

Connect to the HyperspaceDB server, create a collection, insert text for server-side vectorization, perform a hybrid search, and list collections.

```go
package main

import (
	"context"
	"log"

	"github.com/yarlabs/hyperspace-sdk-go"
)

func main() {
	client, err := hyperspace.NewHyperspaceClient("localhost:50051", "I_LOVE_HYPERSPACEDB")
	if err != nil {
		log.Fatalf("failed to connect: %v", err)
	}
	defer client.Close()

	ctx := context.Background()
	collection := "docs_go"

	// Create collection
	_ = client.CreateCollection(ctx, collection, 1024, "cosine")

	// Insert text (server-side vectorization)
	err = client.InsertText(ctx, 1, "HyperspaceDB is awesome!", collection)
	if err != nil {
		log.Fatalf("Insert failed: %v", err)
	}
    
	// Hybrid Search (Semantic + BM25 Lexical)
	results, err := client.SearchText(ctx, "What is HyperspaceDB?", 5, collection, 0.7, &pb.Bm25Options{
		Method:   "bm25plus",
		Language: "english",
	})
	if err != nil {
		log.Fatalf("Search failed: %v", err)
	}

	log.Printf("Found %d vectors via hybrid search", len(results))

	// List collections with metadata
	collections, err := client.ListCollections(ctx)
	if err == nil {
		for _, col := range collections {
			log.Printf("Collection: %s, Count: %d, Dim: %d, Metric: %s", col.Name, col.Count, col.Dimension, col.Metric)
		}
	}
}
```

--------------------------------

### Install LlamaIndex Hyperspace Package

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/llamaindex-js/README.md

Install the necessary packages for the LlamaIndex Hyperspace integration.

```bash
npm install llamaindex-hyperspace llamaindex hyperspace-sdk-ts
```

--------------------------------

### Connect and Search with HyperspaceDB C++ SDK

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/cpp/README.md

Demonstrates connecting to HyperspaceDB, performing a basic search, and setting search parameters like top_k and metric. Includes example of adding authorization metadata.

```cpp
#include "proto/hyperspace.grpc.pb.h"
#include <grpcpp/grpcpp.h>

// Connect and Search
auto channel = grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials());
auto stub = hyperspace::Database::NewStub(channel);

hyperspace::SearchRequest request;
request.set_collection("robots_memory");
request.add_vector(0.12);
request.add_vector(-0.45);
request.set_top_k(10);
request.set_use_wasserstein(false); // Enable for 1D CFM (Wasserstein Metric)

hyperspace::SearchResponse response;
grpc::ClientContext context;
context.AddMetadata("authorization", "Bearer I_LOVE_HYPERSPACEDB");

grpc::Status status = stub->Search(&context, request, &response);
```

--------------------------------

### Build and Run HyperspaceDB Server

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Instructions for building the HyperspaceDB server from source or running it via Docker. Includes options for custom ports and cluster setup.

```bash
# Build from source (requires Rust nightly + just)
cargo build --release
./target/release/hyperspace-server
# gRPC on :50051, HTTP dashboard on :50050

# Or with custom ports
./target/release/hyperspace-server --port 50051 --http-port 50050

# Docker (persisting data)
docker run -d --name hyperspace \
  -p 50051:50051 -p 50050:50050 \
  -v $(pwd)/hs_data:/app/data \
  -e HYPERSPACE_API_KEY=my_secret_key \
  glukhota/hyperspace-db:latest

# Cluster: start leader, then follower
./hyperspace-server --port 50051 --role leader
./hyperspace-server --port 50052 --role follower --leader http://127.0.0.1:50051
```

--------------------------------

### Basic HyperspaceDB Usage with LangChain

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Demonstrates initializing the HyperspaceVectorStore, loading and splitting documents, adding them to the store, and performing a similarity search. Ensure you have OpenAI embeddings set up and a document file at the specified path.

```python
from langchain_hyperspace import HyperspaceVectorStore
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import CharacterTextSplitter
from langchain.document_loaders import TextLoader

# Initialize embeddings
embeddings = OpenAIEmbeddings()

# Create vector store
vectorstore = HyperspaceVectorStore(
    host="localhost",
    port=50051,
    collection_name="my_documents",
    embedding_function=embeddings,
    api_key="your_api_key"  # Optional
)

# Load and split documents
loader = TextLoader("path/to/document.txt")
documents = loader.load()
text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0)
docs = text_splitter.split_documents(documents)

# Add documents to vector store
vectorstore.add_documents(docs)

# Search for similar documents
query = "What is the main topic?"
results = vectorstore.similarity_search(query, k=4)

for doc in results:
    print(doc.page_content)
```

--------------------------------

### Install Tribunal Router Node Executable

Source: https://github.com/yarlabs/hyperspace-db/blob/main/sdks/ros2/ros2_hyperspace_node/CMakeLists.txt

Installs the compiled tribunal_router_node executable to the appropriate library directory.

```cmake
install(TARGETS
  tribunal_router_node
  DESTINATION lib/${PROJECT_NAME})

ament_package())
```

--------------------------------

### Build and Run Hyperspace Server

Source: https://github.com/yarlabs/hyperspace-db/blob/main/README.md

Build the release binary for the Hyperspace server and run it. Custom ports can be specified.

```bash
cargo build --release

./target/release/hyperspace-server

# Or with custom ports
./target/release/hyperspace-server --port 50051 --http-port 50050
```

--------------------------------

### List Collections Response Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON response for the /api/collections endpoint, listing active collections with their metadata.

```json
[
  {
    "name": "my_docs",
    "count": 1500,
    "dimension": 1536,
    "metric": "l2"
  }
]
```

--------------------------------

### Basic Search with Context Manager

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Demonstrates how to use the HyperspaceClient within a context manager for basic search operations.

```APIDOC
## Basic Search with Context Manager

### Description
This snippet shows how to initialize and use the `HyperspaceClient` with a context manager for performing searches.

### Method
`HyperspaceClient` context manager and `search` method.

### Endpoint
N/A (SDK usage)

### Parameters
- `vector` (list[float]): The query vector.
- `top_k` (int): The number of nearest neighbors to retrieve.
- `collection` (str): The name of the collection to search within.

### Request Example
```python
from hyperspace import HyperspaceClient

with HyperspaceClient("localhost:50051") as c:
    c.search(vector=[0.0] * 64, top_k=3, collection="world_model")
```

### Response
(Details not provided in source)
```

--------------------------------

### Cluster Status Response Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON response for cluster status, indicating node role and connectivity.

```json
{
  "node_id": "uuid...",
  "role": "Leader", // or "Follower"
  "upstream_peer": null,
  "downstream_peers": []
}
```

--------------------------------

### Install langchain-hyperspace

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Install the HyperspaceDB integration package for LangChain. This command is used to set up the necessary libraries for using HyperspaceDB with LangChain.

```bash
pip install langchain-hyperspace
```

--------------------------------

### Build and Run HyperspaceDB Server

Source: https://github.com/yarlabs/hyperspace-db/blob/main/integrations/langchain-python/README.md

Build the HyperspaceDB server in release mode and run it using an API key.

```bash
cargo build --release
HYPERSPACE_API_KEY=your_secret_key ./target/release/hyperspace-server
```

--------------------------------

### HyperspaceClient Initialization

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Instantiate the HyperspaceClient to connect to the HyperspaceDB server. Optional parameters include API key and user ID for authentication and multi-tenancy.

```APIDOC
## HyperspaceClient Initialization

### Description
Instantiate the HyperspaceClient to connect to the HyperspaceDB server. Optional parameters include API key and user ID for authentication and multi-tenancy.

### Method
`HyperspaceClient(host: str, api_key: Optional[str] = None, user_id: Optional[str] = None)`

### Parameters
- **host** (str) - Required - The host and port of the HyperspaceDB server (e.g., "localhost:50051").
- **api_key** (Optional[str]) - Optional - The API key for authentication.
- **user_id** (Optional[str]) - Optional - The user ID for multi-tenant access.

### Request Example
```python
from hyperspace import HyperspaceClient

client = HyperspaceClient(
    host="localhost:50051",
    api_key="my_secret_key",
    user_id="tenant_42"
)
```
```

--------------------------------

### Swarm Peers Response Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON response for the /api/swarm/peers endpoint, showing gossip protocol status and peer count.

```json
{
  "gossip_enabled": true,
  "peer_count": 2,
  "peers": [...] 
}
```

--------------------------------

### Build and Run HyperspaceDB Server

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/quickstart.md

Compile the HyperspaceDB server in release mode and then run the executable. Ensure the server is running before proceeding with client interactions.

```bash
cargo build --release
./target/release/hyperspace-server
```

--------------------------------

### Collection Search Request Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/api.md

Example JSON payload for the /api/collections/{name}/search endpoint, used for manual testing and dashboard integration.

```json
{
  "vector": [0.1, 0.2, 0.3],
  "top_k": 5
}
```

--------------------------------

### Run Hyperspace Server

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/install.md

Executes the HyperspaceDB server after building it from source.

```bash
./target/release/hyperspace-server
```

--------------------------------

### Start MCP Server with npx

Source: https://github.com/yarlabs/hyperspace-db/blob/main/README.md

Initiate the Model Context Protocol (MCP) server using npx. This allows agents like Claude Desktop and Cursor to connect to HyperspaceDB.

```bash
npx mcp-hyperspacedb@latest
```

--------------------------------

### Initialize DB from Empty

Source: https://github.com/yarlabs/hyperspace-db/blob/main/examples/wasm-demo/index.html

Handles the click event for the 'Init New (Empty)' button to initialize the WASM module and create an empty database.

```javascript
document.getElementById('initBtn').onclick = async () => {
  if (await initWasm()) {
    statusEl.innerHTML = '<span class="success">Ready (Empty)</span>';
    enableButtons();
  }
};
```

--------------------------------

### TypeScript Hybrid Search Example

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/hybrid.md

Execute a hybrid search using TypeScript, specifying the query, alpha for weighting, and BM25 method. This example demonstrates the client's search method with hybrid search parameters.

```typescript
const results = await client.search(vector, 10, "collection", {
  hybridQuery: "apple macbook",
  hybridAlpha: 0.7,
  bm25: { method: "bm25plus" }
});
```

--------------------------------

### Get Collection Statistics

Source: https://github.com/yarlabs/hyperspace-db/blob/main/dashboard/README.md

Retrieves statistics for a specific collection.

```APIDOC
## GET /api/collections/{name}/stats

### Description
Retrieves statistics for a given collection.

### Method
GET

### Endpoint
/api/collections/{name}/stats

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the collection to get statistics for.

### Headers
- **x-api-key** (string) - Required - Your API key for authentication.
```

--------------------------------

### LangChain Integration with HyperspaceVectorStore

Source: https://context7.com/yarlabs/hyperspace-db/llms.txt

Demonstrates initializing HyperspaceVectorStore, adding documents, performing similarity and filtered searches, setting up a RAG chain with GPT-4, and ingesting large batches of data. Ensure `langchain-hyperspace` and `langchain-openai` are installed.

```python
from langchain_hyperspace import HyperspaceVectorStore
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain.chains import RetrievalQA
from langchain.document_loaders import TextLoader
from langchain.text_splitter import CharacterTextSplitter

# Initialize
embeddings  = OpenAIEmbeddings()
vectorstore = HyperspaceVectorStore(
    host="localhost",
    port=50051,
    collection_name="knowledge_base",
    embedding_function=embeddings,
    api_key="my_secret_key",
    dimension=1536,
    metric="cosine",
    enable_deduplication=True  # SHA-256 content-based dedup
)

# Add documents
loader   = TextLoader("docs/manual.txt")
docs     = loader.load()
splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=100)
chunks   = splitter.split_documents(docs)
vectorstore.add_documents(chunks)

# Similarity search
results = vectorstore.similarity_search("How does HNSW indexing work?", k=4)
for doc in results:
    print(doc.page_content[:200])

# Filter search
results = vectorstore.similarity_search(
    "robotics memory",
    k=5,
    filter={"category": "robotics"}
)

# RAG chain with GPT-4
llm      = ChatOpenAI(model_name="gpt-4")
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(search_kwargs={"k": 3})
)
answer = qa_chain.run("What are the key advantages of hyperbolic embeddings?")
print(answer)

# Sync / state verification
digest = vectorstore.get_digest()
print(f"State clock={digest['logical_clock']} count={digest['count']}")

# Large batch ingest
vectorstore.add_texts(
    texts=[f"Document {i} content" for i in range(10000)],
    metadatas=[{"index": i} for i in range(10000)]
)
```

--------------------------------

### Clone HyperspaceDB and Build from Source

Source: https://github.com/yarlabs/hyperspace-db/blob/main/docs/book/src/install.md

Clones the HyperspaceDB repository and builds the release version of the server.

```bash
git clone https://github.com/yarlabs/hyperspace-db
cd hyperspace-db
cargo build --release
```