### Complete Runnable CyborgDB Python Example

Source: https://docs.cyborg.co/versions/v0.12.x/intro/using-docs

A full, runnable Python example demonstrating client initialization with in-memory configuration and adding vectors to an index. This serves as a practical starting point for using CyborgDB.

```python
# Complete working example
from cyborgdb_core import Client, DBConfig

client = Client(
    api_key="your-api-key",
    index_location=DBConfig("memory"),
    config_location=DBConfig("memory")
)

# Create index and add vectors
index = client.create_index("my-index", dimension=384)
index.add_vectors([1, 2, 3, ...], metadata={"doc": "example"})
```

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

### Configure CyborgDB Service HTTPS with Let's Encrypt Certificates

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

This example guides users on setting up HTTPS for the CyborgDB service using certificates generated by Let's Encrypt. It includes commands to install `certbot`, generate a certificate for a specified domain, and then export the paths to these Let's Encrypt certificates as environment variables before starting the service.

```bash
# Install certbot (Ubuntu/Debian)
sudo apt-get install certbot

# Generate certificate for your domain
sudo certbot certonly --standalone -d your-domain.com

# Set environment variables to Let's Encrypt certificates
export SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
export SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem

# Start service with HTTPS
cyborgdb-service
```

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

### Install CyborgDB Core and Lite (Python, C++)

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/guides/intro/quickstart

Instructions for installing CyborgDB using pip for Python and Conan for C++. Includes commands for creating virtual environments and adding Conan remotes. Note that a token is required for the private repository.

```python
# Ensure that Python 3.9 - 3.13 is installed
# Or create a virtual environment with Python 3.9 - 3.13:
conda create -n cyborg-env python=3.12

# Activate the virtual environment:
conda activate cyborg-env

# Install CyborgDB:
pip install cyborgdb-core -i https://dl.cloudsmith.io/<token>/cyborg/cyborgdb/python/simple/

# Or install CyborgDB Lite for evaluation/non-commercial use:
pip install cyborgdb-lite

# For automatic embedding generation, install with:
pip install cyborgdb-core[embeddings] -i https://dl.cloudsmith.io...
pip install cyborgdb-lite[embeddings]
```

```cpp
# Ensure that Conan is installed

# Add the repository to your Conan remotes:
conan remote add cyborgdb https://dl.cloudsmith.io/<token>/cyborg/cyborgdb/conan
conan remote login cyborgdb -p <token> cyborg

# Install CyborgDB:
conan install cyborgdb_core -r cyborgdb
```

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

### Create CyborgDB Client (Python, C++)

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/guides/intro/quickstart

Code examples for creating a CyborgDB client in Python and C++. Demonstrates configuring storage locations (memory, redis, postgres) and initializing the client with an API key. Replace 'your_api_key_here' with your actual key.

```python
import cyborgdb_core as cyborgdb
# or import cyborgdb_lite as cyborgdb
import secrets

# Using `memory` storage for this example
# `redis` and `postgres` are also supported

index_location = cyborgdb.DBConfig("memory")  # Where encrypted index is stored (for queries)
config_location = cyborgdb.DBConfig("memory") # Where encrypted index config is stored (for config/loading)
items_location = cyborgdb.DBConfig("memory")  # Where item contents are stored (for upsert/get)

# Get your API key
api_key = "your_api_key_here"  # Replace with your actual API key

# Create a client
client = cyborgdb.Client(
    api_key=api_key, 
    index_location=index_location, 
    config_location=config_location, 
    items_location=items_location
)
```

```cpp
#include "cyborgdb_core/client.hpp"
#include "cyborgdb_core/encrypted_index.hpp"
#include <array>
#include <string>
#include <openssl/rand.h>

// Using `memory` storage for this example
// `redis` and `postgres` are also supported

cyborg::DBConfig index_location(cyborg::Location::kMemory);  // Where encrypted index is stored (for queries)
cyborg::DBConfig config_location(cyborg::Location::kMemory); // Where encrypted index config is stored (for config/loading)
cyborg::DBConfig items_location(cyborg::Location::kMemory);  // Where item contents are stored (for upsert/get)

// Get your API key
std::string api_key = "your_api_key_here";  // Replace with your actual API key

// Create a client
cyborg::Client client(api_key, index_location, config_location, items_location, 0, false);
```

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

### Install and Run CyborgDB Service

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/introduction

Provides commands to install and run the CyborgDB service, which is a prerequisite for using the Python SDK. It covers installation via pip and Docker, along with starting the service locally or via a container. Ensure the service is running before connecting the SDK.

```bash
# Install the CyborgDB service
pip install cyborgdb-service
```

```bash
# Or pull the Docker image
docker pull cyborginc/cyborgdb-service
```

```bash
# Start the service
cyborgdb-service
```

```bash
# Or run the Docker container
docker run -p 8000:8000 cyborginc/cyborgdb-service
```

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

### Install Go SDK for CyborgDB

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

This command installs the CyborgDB Go SDK. Ensure you have Go installed and configured on your system. This is a prerequisite for using the Go SDK.

```bash
go get github.com/cyborginc/cyborgdb-go
```

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

### CyborgDB Service Production Deployment with Gunicorn and Systemd

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

Provides commands for deploying the CyborgDB service in a production environment. It includes instructions for installing and running the service with `gunicorn`, a Python WSGI HTTP Server, and for enabling and starting the service using `systemd` on Linux systems.

```bash
# Using gunicorn (install separately)
pip install gunicorn
gunicorn cyborgdb_service.main:app --port 8000

# Using systemd service (Linux)
sudo systemctl enable cyborgdb-service
sudo systemctl start cyborgdb-service
```

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

### Install CyborgDB Client SDKs

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-docker

Commands to install the CyborgDB client SDKs for various programming languages. These SDKs facilitate integration with the CyborgDB service from different application environments.

```bash
pip install cyborgdb
```

```bash
npm install cyborgdb
```

```bash
npm install cyborgdb
```

```bash
go get github.com/cyborginc/cyborgdb-go
```

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

### LangChain Integration with CyborgDB (Python)

Source: https://docs.cyborg.co/versions/v0.12.x/intro/quickstart

Demonstrates how to integrate CyborgDB into a LangChain application by initializing a CyborgVectorStore. This allows for a drop-in replacement of existing vector stores, leveraging CyborgDB's encrypted vector search capabilities. Requires the cyborgdb_core library and a specified embedding model.

```python
from cyborgdb_core.integrations.langchain import CyborgVectorStore

store = CyborgVectorStore.from_texts(
    texts=["hello world", "goodbye world"],
    embedding="all-MiniLM-L6-v2",
    index_key=CyborgVectorStore.generate_key(),
    # ... other config
)
```

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

### Start CyborgDB Service

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/introduction

Starts the CyborgDB service. This command assumes the service has been installed (e.g., via pip) and is required before the JavaScript/TypeScript SDK can establish a connection and perform operations.

```bash
cyborgdb-service
```

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

### Mixed Database Configuration Example

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/advanced/env-vars

Demonstrates an advanced configuration for using different database types for various components. This example uses PostgreSQL for indexes and configurations, and Redis for items, specifying distinct connection strings for each.

```bash
# Main configuration
CYBORGDB_API_KEY="cyborg_your_api_key_here"

# Use PostgreSQL for indexes and configs
INDEX_LOCATION="postgres"
CONFIG_LOCATION="postgres"
INDEX_CONNECTION_STRING="host=postgres.example.com port=5432 dbname=cyborgdb user=cyborgdb password=password1"
CONFIG_CONNECTION_STRING="host=postgres.example.com port=5432 dbname=cyborgdb user=cyborgdb password=password1"

# Use Redis for items (faster access)
ITEMS_LOCATION="redis"
ITEMS_CONNECTION_STRING="host=redis.example.com,port=6379,db=0,password=redis_password"
```

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

### Docker Run Example with SSL

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-docker

This example demonstrates how to run the CyborgDB service using a Docker command, configuring it for PostgreSQL, setting an API key, and enabling HTTPS by mounting a local certificates directory to the container. It also maps ports and sets necessary environment variables.

```bash
sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=postgres \
  -e CYBORGDB_CONNECTION_STRING="host=host.docker.internal port=5432 dbname=postgres user=postgres password=your_password" \
  -e SSL_CERT_PATH=/certs/server.crt \
  -e SSL_KEY_PATH=/certs/server.key \
  -v /host/path/to/certs:/certs \
  cyborginc/cyborgdb-service:latest
```

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

### Install CyborgDB Client SDKs for Python and JavaScript/TypeScript

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

Provides instructions for installing the CyborgDB client Software Development Kits (SDKs) for different programming languages. It includes commands for Python using `pip` and for JavaScript/TypeScript using `npm`, enabling developers to interact with the CyborgDB service.

```bash
pip install cyborgdb
```

```bash
npm install cyborgdb
```

```bash
npm install cyborgdb
```

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

### Create Encrypted Index (Python, C++)

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/guides/intro/quickstart

Examples for creating an encrypted index using the CyborgDB client in Python and C++. This involves generating a 32-byte encryption key and calling the `create_index` method.

```python
# ... Continuing from the previous step

# Generate an encryption key for the index
index_key = secrets.token_bytes(32)

# Create an encrypted index
index = client.create_index(
    index_name="my_index", 
    index_key=index_key
)
```

```cpp
/// ... Continuing from the previous step

// Generate a 32-byte random encryption key
std::array<uint8_t, 32> index_key;
if (RAND_bytes(index_key.data(), index_key.size()) != 1) {
    throw std::runtime_error("Failed to generate secure random key");
}

// Create an encrypted index
auto index = client.CreateIndex("my_index", index_key);
```

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

### Install cyborgdb-core Package

Source: https://docs.cyborg.co/versions/v0.12.x/intro/using-docs

This command installs the core CyborgDB Python package using pip. It's a prerequisite for using the CyborgDB Python client.

```bash
# Terminal commands are shown in code blocks like this
pip install cyborgdb-core
```

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

### Install CyborgDB with LangChain Support (Python Client SDK)

Source: https://docs.cyborg.co/versions/v0.12.x/integrations/langchain/introduction

Installs the CyborgDB Python client package with the necessary extras for LangChain integration. This command ensures all required dependencies for using CyborgDB with LangChain are installed.

```bash
pip install cyborgdb[langchain]
```

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

### CyborgDB LangChain Vector Store Usage Example (Python)

Source: https://docs.cyborg.co/versions/v0.12.x/integrations/langchain/introduction

An example demonstrating how to initialize and use the CyborgVectorStore with LangChain. It shows adding texts, configuring the index, and performing a similarity search.

```python
from cyborgdb_core.integrations.langchain import CyborgVectorStore
from cyborgdb_core import DBConfig

store = CyborgVectorStore.from_texts(
    texts=["hello world", "goodbye world"],
    embedding="all-MiniLM-L6-v2",  # sentence-transformer name
    index_key=CyborgVectorStore.generate_key(),
    api_key="your-api-key",
    index_location=DBConfig("memory"),
    config_location=DBConfig("memory"),
    index_type="ivfflat",
    metric="cosine"
)

docs = store.similarity_search("hello")
```

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

### Install CyborgDB Python SDK

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/introduction

Installs the CyborgDB Python SDK using pip. This is the primary step to begin using the SDK in your Python projects. No specific dependencies are required beyond a working Python environment.

```bash
pip install cyborgdb
```

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

### GET /v1/vectors/get (cURL Example)

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/data-operations/get-items

This endpoint retrieves specific items from an encrypted index by their IDs. You can specify which fields to include in the response, such as 'contents' and 'metadata'.

```APIDOC
## POST /v1/vectors/get

### Description
Retrieves specific items from an encrypted index by their IDs. Allows specifying which fields to include in the response.

### Method
POST

### Endpoint
`/v1/vectors/get`

### Parameters
#### Query Parameters
None

#### Request Body
- **index_name** (string) - Required - The name of the index.
- **index_key** (string) - Required - The 64-character hex key for the index.
- **ids** (array of strings) - Required - A list of item IDs to retrieve.
- **include** (array of strings) - Optional - Fields to include in the response. Options: `vector`, `contents`, `metadata`. Defaults to `["vector", "contents", "metadata"]`.

### Request Example
```json
{
  "index_name": "my_index",
  "index_key": "your_64_character_hex_key_here",
  "ids": ["item_20", "item_11"],
  "include": ["contents", "metadata"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the retrieved item.
- **contents** (bytes/Buffer/[]byte) - The content of the item, always returned as bytes.
- **metadata** (object) - Associated metadata for the item.
- **vector** (array of floats) - The vector data for the item.

#### Response Example
```json
[
  {"id": "item_20", "contents": b"Hello, World!", "metadata": {"type": "txt"}},
  {"id": "item_11", "contents": b"Hello, Cyborg!", "metadata": {"type": "md"}}
]
```
```

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

### Example: Create IVFFlat Index with Embedding Model (TypeScript)

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/client/create-index

Illustrates creating an `EncryptedIndex` with a specific `IndexIVFFlat` configuration and enabling server-side embedding generation using a specified model. This example includes necessary imports, client setup, key generation, `IndexIVFFlat` instantiation, and the `createIndex` call with the `embeddingModel` parameter.

```typescript
import { Client, IndexIVFFlat } from 'cyborgdb';

const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

const indexName = "semantic_search_index";
const indexKey: Uint8Array = client.generateKey();

const indexConfig: IndexIVFFlat = new IndexIVFFlat();

try {
    const index = await client.createIndex({
        indexName,
        indexKey,
        indexConfig,
        embeddingModel: 'all-MiniLM-L6-v2'  // Embedding model
    });
    
    console.log('IVFPQ index with embeddings created successfully');
} catch (error) {
    console.error('Index creation failed:', error.message);
}
```

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

### Development Environment Configuration

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/advanced/env-vars

Provides examples for setting up the development environment using environment variables and a .env file. This configuration includes API key, database type, and connection string for PostgreSQL.

```bash
export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE="postgres"
export CYBORGDB_CONNECTION_STRING="host=localhost port=5432 dbname=cyborgdb user=cyborgdb password=secure_password"
```

```dotenv
CYBORGDB_API_KEY=cyborg_your_api_key_here
CYBORGDB_DB_TYPE=postgres
CYBORGDB_CONNECTION_STRING=host=localhost port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
```

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

### Get Index Name - Python

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/getters

Retrieves the unique name identifier of the encrypted index. This is a read-only property. Example usage demonstrates accessing and printing the index name.

```python
@property
index_name: str

# Example Usage
index_name = index.index_name
print(f'Index name: {index_name}')
```

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

### Retrieve Items Post-Query

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/guides/data-operations/query

Retrieves and decrypts items that match a previous query. This is particularly useful in RAG applications and complements the `upsert()` function. Further details are available in the 'Get Items' guide.

```python
# Example usage assumes 'retrieved_item_id' is obtained from a query
retrieved_item = index.get(id=retrieved_item_id)
```

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

### Create CyborgDB Client Instance (Go)

Source: https://docs.cyborg.co/versions/v0.12.x/service/go-sdk/client/client

Initializes a new CyborgDB Client. Requires the base URL of the microservice and an API key for authentication. Optionally accepts a boolean to control SSL verification. Handles potential errors during client creation.

```go
func NewClient(baseURL, apiKey string, verifySSL ...bool) (*Client, error)
```

```go
package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client with API key
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
    
    // Test the connection
    ctx := context.Background()
    health, err := client.GetHealth(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Service health: %+v\n", health)
}
```

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

### Get Index Configuration - Python

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/getters

Retrieves the index configuration as a dictionary. The structure of this dictionary varies based on the index type. Example usage shows accessing common and type-specific configuration properties.

```python
@property
index_config: Dict[str, Any]

# Example Usage
config = index.index_config
print(f'Index configuration: {config}')

# Access common properties
print(f"Dimension: {config.get('dimension')}")
print(f"Metric: {config.get('metric')}")
print(f"Number of lists: {config.get('n_lists')}")

# Type-specific properties
if config.get('type') == 'ivfpq':
    print(f"PQ dimension: {config.get('pq_dim')}")
    print(f"PQ bits: {config.get('pq_bits')}")
```

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

### Initialize cyborg::Client with Storage and Acceleration Options (C++)

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/cpp/client/client

Initializes a new instance of the cyborg::Client class. This constructor requires an API key, configurations for index, configuration, and item storage locations, the number of CPU threads to utilize, and a flag for GPU acceleration. It throws exceptions for invalid parameters or unavailable resources.

```cpp
#include "cyborgdb_core/client.hpp"

std::string api_key = "your_api_key_here";
cyborg::DBConfig index_location(Location::kMemory);
cyborg::DBConfig config_location(Location::kRedis, "index_metadata", "redis://localhost");
cyborg::DBConfig items_location(Location::kNone); // No item storage
int cpu_threads = 4;
bool use_gpu = true;

cyborg::Client client(api_key, index_location, config_location, items_location, cpu_threads, use_gpu);
```

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

### Get Index Type - Python

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/getters

Returns the type of the index, such as 'ivf', 'ivfpq', or 'ivfflat'. This property helps in understanding the index's characteristics and optimizing operations. Example usage shows how to retrieve and conditionally use the index type.

```python
@property
index_type: str

# Example Usage
index_type = index.index_type
print(f'Index type: {index_type}')

if index_type == 'ivfpq':
    print('Using IVFPQ index for memory efficiency')
elif index_type == 'ivfflat':
    print('Using IVFFlat index for high accuracy')
```

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

### Example JSON Response for Vector Retrieval

Source: https://docs.cyborg.co/versions/v0.12.x/service/rest-api/encrypted-index/get

This JSON structure represents the successful response when retrieving vectors. It contains a 'results' array, where each object corresponds to a requested ID and includes the 'id', 'vector', 'contents', and 'metadata' if they were requested and available. IDs not found are omitted.

```json
{
  "results": [
    {
      "id": "item_1",
      "vector": [0.1, 0.2, 0.3, 0.4],
      "contents": "Hello world!",
      "metadata": {"category": "greeting", "language": "en"}
    },
    {
      "id": "item_2",
      "vector": [0.5, 0.6, 0.7, 0.8],
      "contents": "Bonjour monde!",
      "metadata": {"category": "greeting", "language": "fr"}
    }
  ]
}
```

```json
{
  "results": [
    {
      "id": "doc_1",
      "contents": "First document content here..."
    },
    {
      "id": "doc_2",
      "contents": "Second document content here..."
    },
    {
      "id": "doc_3",
      "contents": "Third document content here..."
    }
  ]
}
```

```json
{
  "results": [
    {
      "id": "user_1",
      "metadata": {
        "name": "Alice Smith",
        "role": "admin",
        "department": "engineering",
        "created": "2024-01-01"
      }
    },
    {
      "id": "user_2",
      "metadata": {
        "name": "Bob Johnson",
        "role": "user",
        "department": "marketing",
        "created": "2024-01-02"
      }
    }
  ]
}
```

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

### Initialize CyborgDB Python Client

Source: https://docs.cyborg.co/versions/v0.12.x/intro/using-docs

Demonstrates how to initialize the CyborgDB Python client using an API key. This is the first step for interacting with CyborgDB services programmatically.

```python
# Python code examples use syntax highlighting
from cyborgdb_core import Client
client = Client(api_key="your-key")
```

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

### Get Total Number of Vectors in Index (C++)

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/cpp/getters

Returns the total count of vectors stored in the encrypted index as a size_t. It throws std::runtime_error if the index is not created/loaded or if an error occurs during retrieval. Example usage demonstrates how to obtain and use this count.

```cpp
size_t NumVectors();
```

```cpp
// Get the number of vectors in the index
size_t vector_count = index->NumVectors();
std::cout << "Index contains " << vector_count << " vectors" << std::endl;

// Use count for validation or progress reporting
if (vector_count == 0) {
    std::cout << "Index is empty, consider adding vectors" << std::endl;
}
```

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

### Run CyborgDB with Docker (PostgreSQL Backend)

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-docker

Starts the CyborgDB service using Docker with a PostgreSQL backend. Requires environment variables for database connection and API key. Platform differences for Linux and macOS network configuration are noted.

```bash
sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=postgres \
  -e "CYBORGDB_CONNECTION_STRING=host=localhost port=5432 dbname=postgres user=postgres password=your_password" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest
```

```bash
sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=postgres \
  -e 'CYBORGDB_CONNECTION_STRING=host=host.docker.internal port=5432 dbname=postgres user=postgres password=your_password' \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest
```

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

### Retrieve Vectors with Specific Fields (Bash cURL)

Source: https://docs.cyborg.co/versions/v0.12.x/service/rest-api/encrypted-index/get

This example shows how to use cURL to retrieve specific fields (contents and metadata) for a list of vector IDs. It highlights the use of the 'include' parameter to customize the response, making it efficient for targeted data retrieval. Authentication is handled via the 'X-API-Key' header.

```bash
curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": ["doc_1", "doc_2", "doc_3"],
       "include": ["contents"]
     }'
```

```bash
curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": ["user_1", "user_2"],
       "include": ["metadata"]
     }'
```

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

### Client Constructor

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/python/client/client

Initializes a new CyborgDB Client instance. This client is the main entry point for creating, loading, listing, and deleting indexes.

```APIDOC
## Client Constructor

### Description
Initializes a new CyborgDB `Client` instance. This client provides access to functionalities for managing indexes within CyborgDB.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

**Parameters**
- `api_key` (str) - Required - API key for your CyborgDB account.
- `index_location` (DBConfig) - Required - Configuration for index storage location. Use a dictionary with keys `location`, `table_name`, and `connection_string`.
- `config_location` (DBConfig) - Required - Configuration for index metadata storage. Uses the same dictionary structure as `index_location`.
- `items_location` (DBConfig) - Optional - Configuration for encrypted item storage. Uses the same dictionary structure as `index_location`.
- `cpu_threads` (int) - Optional - Number of CPU threads to use for computations (defaults to `0` = all cores).
- `gpu_accelerate` (bool) - Optional - Indicates whether to use GPU acceleration (defaults to `False`).

### Exceptions
- `ValueError`: Throws if the `cpu_threads` parameter is less than `0`, if any `DBConfig` is invalid, or if the GPU is not available when `gpu_accelerate` is `True`.
- `RuntimeError`: Throws if the backing store is not available or if the Client could not be initialized.

### Request Example
```python
import cyborgdb_core as cyborgdb

api_key = "your_api_key_here"
index_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
config_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
items_location = cyborgdb.DBConfig(location='postgres', table_name="items", connection_string="host=localhost dbname=postgres")

client = cyborgdb.Client(
    api_key=api_key,
    index_location=index_location,
    config_location=config_location,
    items_location=items_location,
    cpu_threads=4,
    gpu_accelerate=True
)
```

### Response
#### Success Response (200)
- `Client` (object) - The initialized CyborgDB client object.

#### Response Example
(Constructor does not return a typical response body, it initializes an object.)
```

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

### Initialize CyborgDB Client

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/python/client/client

Constructs a new CyborgDB Client instance with specified API key and database configurations. Supports optional CPU thread count and GPU acceleration. Ensure all DBConfig parameters are valid to avoid ValueErrors. The backing store must be available for successful initialization.

```python
import cyborgdb_core as cyborgdb

api_key = "your_api_key_here"
index_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
config_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
items_location = cyborgdb.DBConfig(location='postgres', table_name="items", connection_string="host=localhost dbname=postgres")

client = cyborgdb.Client(
    api_key=api_key,
    index_location=index_location,
    config_location=config_location,
    items_location=items_location,
    cpu_threads=4,
    gpu_accelerate=True
)
```

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

### Docker Compose for CyborgDB with PostgreSQL

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-docker

Defines a Docker Compose setup for the CyborgDB service with a PostgreSQL backend. Includes service definitions for both CyborgDB and PostgreSQL, with environment variables and volumes configured.

```yaml
version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_DB_TYPE=postgres
      - CYBORGDB_CONNECTION_STRING=host=postgres port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
      - CYBORGDB_API_KEY=cyborg_your_api_key_here
    depends_on:
      - postgres
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=cyborgdb
      - POSTGRES_USER=cyborgdb
      - POSTGRES_PASSWORD=secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:
```

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

### List Indexes Across Multiple SDKs and cURL

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/encrypted-indexes/list-indexes

This snippet demonstrates how to list available encrypted indexes using different client libraries and direct API calls. It includes examples for Python, JavaScript, TypeScript, Go, and cURL. Ensure you have the respective SDKs installed and replace placeholders like `http://localhost:8000` and `your-api-key` with your actual CyborgDB instance details.

```python
from cyborgdb import Client

# Create a client
client = Client(
    base_url='http://localhost:8000', 
    api_key='your-api-key'
)

# List all available indexes
indexes = client.list_indexes()

print(indexes)
# Example output:
# ["index_one", "index_two", "index_three"]
```

```javascript
import { Client } from 'cyborgdb';

// Create a client
const client = new Client({
    baseUrl: 'http://localhost:8000', 
    apiKey: 'your-api-key' 
});

// List all available indexes
const indexes = await client.listIndexes();

console.log(indexes);
# Example output:
# ["index_one", "index_two", "index_three"]
```

```typescript
import { Client } from 'cyborgdb';

// Create a client
const client = new Client({
    baseUrl: 'http://localhost:8000', 
    apiKey: 'your-api-key' 
});

// List all available indexes
const indexes: string[] = await client.listIndexes();

console.log(indexes);
# Example output:
# ["index_one", "index_two", "index_three"]
```

```go
package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

// Create client
client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
if err != nil {
    log.Fatal(err)
}

// List all indexes
ctx := context.Background()
indexes, err := client.ListIndexes(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Println(indexes)
# Example output: ["index_one", "index_two", "index_three"]
```

```bash
curl -X GET "http://localhost:8000/v1/indexes/list" \
     -H "X-API-Key: your-api-key"

# Response:
# {
#   "indexes": ["index_one", "index_two", "index_three"]
# }
```

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

### Production Environment Configuration

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/advanced/env-vars

Illustrates the configuration for a production environment using environment variables and a .env file. It includes settings for API key, database type, connection string, port, and SSL certificate paths.

```bash
export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE="postgres"
export CYBORGDB_CONNECTION_STRING="host=db.example.com port=5432 dbname=cyborgdb user=cyborgdb password=secure_password"
export PORT="8443"
export SSL_CERT_PATH="/etc/ssl/certs/cyborgdb.crt"
export SSL_KEY_PATH="/etc/ssl/private/cyborgdb.key"
export WORKERS="16"
```

```dotenv
CYBORGDB_API_KEY=cyborg_your_api_key_here
CYBORGDB_DB_TYPE=postgres
CYBORGDB_CONNECTION_STRING=host=db.example.com port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
PORT=8443
SSL_CERT_PATH=/etc/ssl/certs/cyborgdb.crt
SSL_KEY_PATH=/etc/ssl/private/cyborgdb.key
WORKERS=16
```

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

### Install CyborgDB Service via Docker

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/introduction

Installs and runs the CyborgDB service using a Docker container. This provides an alternative to pip installation and is necessary for the JavaScript/TypeScript SDK to function.

```bash
docker pull cyborginc/cyborgdb-service

docker run -p 8000:8000 cyborginc/cyborgdb-service
```

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

### Run CyborgDB with Docker (Redis Backend)

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-docker

Starts the CyborgDB service using Docker with a Redis backend. Requires environment variables for database connection and API key. Platform differences for Linux and macOS network configuration are noted.

```bash
sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=redis \
  -e "CYBORGDB_CONNECTION_STRING=host=localhost,port=6379,db=0" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest
```

```bash
sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=redis \
  -e 'CYBORGDB_CONNECTION_STRING=host=host.docker.internal,port=6379,db=0' \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest
```

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

### CyborgDB Get Response Item Structure

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/encrypted-index/get

Illustrates the structure of a single item returned by the CyborgDB 'get' method when all fields are included. The 'contents' field is consistently returned as a Buffer.

```json
[
    {
        "id": "doc1",
        "vector": [0.1, 0.2, 0.3, 0.4],
        "contents": Buffer, // Always returned as Buffer (bytes)
        "metadata": {
            "title": "Document 1",
            "category": "research",
            "date": "2024-01-15"
        }
    },
    {
        "id": "doc2",
        "vector": [0.4, 0.5, 0.6, 0.7],
        "contents": Buffer, // Always returned as Buffer (bytes)
        "metadata": {
            "title": "Document 2",
            "category": "tutorial",
            "date": "2024-01-16"
        }
    }
]
```

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

### GET /websites/cyborg_co_versions_v0_12_x

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/encrypted-index/get

Retrieves vectors from the encrypted index by their IDs. Allows specifying which fields to include in the results.

```APIDOC
## GET /websites/cyborg_co_versions_v0_12_x

### Description
Retrieves vectors from the encrypted index by their IDs, with options to specify which fields to include in the results.

### Method
GET

### Endpoint
/websites/cyborg_co_versions_v0_12_x

### Parameters
#### Query Parameters
- **ids** (string[]) - Required - Array of vector IDs to retrieve from the index.
- **include** (string[]) - Optional - Fields to include in the response. Default: `["vector", "contents", "metadata"]`. Valid options: `"vector"`, `"contents"`, `"metadata"`

### Request Example
```json
{
  "ids": ["doc1", "doc2"],
  "include": ["vector", "contents", "metadata"]
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the vector.
- **vector** (number[]) - The vector data (included if `"vector"` in `include` array).
- **contents** (Buffer) - The content data as Buffer (bytes), always returned as bytes (included if `"contents"` in `include` array).
- **metadata** (any) - Associated metadata object (included if `"metadata"` in `include` array).

#### Response Example
```json
[
    {
        "id": "doc1",
        "vector": [0.1, 0.2, 0.3, 0.4],
        "contents": Buffer.from('This is the first document content'),
        "metadata": {
            "title": "Document 1",
            "category": "research",
            "date": "2024-01-15"
        }
    }
]
```

### Errors
- **API Request Failure**: Throws if the API request fails due to network connectivity issues.
- **Authentication Failure**: Throws if authentication fails (invalid API key).
- **Invalid Encryption Key**: Throws if the encryption key is invalid for the specified index.
- **Internal Server Errors**: Throws if there are internal server errors preventing the retrieval.
- **Validation Errors**: Throws if the `ids` parameter is null, undefined, or empty, or if the `include` parameter contains invalid field names.
```

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

### Initialize CyborgDB Client

Source: https://docs.cyborg.co/versions/v0.12.x/embedded/python/client

Demonstrates how to instantiate the `Client` class for CyborgDB. Requires an API key and configuration details for index, metadata, and optional item storage. Supports CPU thread count and GPU acceleration configuration.

```python
import cyborgdb_core as cyborgdb
# or import cyborgdb_lite as cyborgdb

api_key = "your_api_key_here"
index_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
config_location = cyborgdb.DBConfig(location='redis', connection_string="redis://localhost")
items_location = cyborgdb.DBConfig(location='postgres', table_name="items", connection_string="host=localhost dbname=postgres")

# Construct the Client object
client = cyborgdb.Client(
    api_key=api_key,
    index_location=index_location,
    config_location=config_location,
    items_location=items_location,
    cpu_threads=4,
    gpu_accelerate=True
)

# Proceed with further operations

```

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

### GET /health

Source: https://docs.cyborg.co/versions/v0.12.x/service/go-sdk/client/get-health

Checks the health status of the CyborgDB service. This endpoint is useful for readiness/liveness checks and connectivity diagnostics.

```APIDOC
## GET /health

### Description
Checks the health status of the CyborgDB service. Useful for readiness/liveness checks and connectivity diagnostics.

### Method
GET

### Endpoint
/health

### Parameters
#### Query Parameters
None

#### Path Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Current health status of the service (typically "healthy")
- **api_version** (string) - Version of the API interface (e.g., "v1")
- **version** (string) - Version of the CyborgDB application/service

#### Response Example
```json
{
  "status": "healthy",
  "api_version": "v0.12.x",
  "version": "1.2.3"
}
```

### Exceptions
- Throws if the health check request fails due to network connectivity issues.
- Throws if the server is unreachable or times out.
- Throws if the CyborgDB service is unavailable or unreachable.
- Throws if there are internal server errors on the CyborgDB service.
```

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

### Complete CyborgDB Production Example with SSL and Environment Variables

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

This example demonstrates setting all required environment variables, including those for API key, database type, connection string, and SSL certificate paths, to launch the CyborgDB service with HTTPS enabled. It assumes a PostgreSQL database and valid SSL certificate paths.

```bash
# Set all required environment variables including SSL
export CYBORGDB_API_KEY=cyborg_your_api_key_here
export CYBORGDB_DB_TYPE=postgres
export CYBORGDB_CONNECTION_STRING="host=localhost port=5432 dbname=postgres user=postgres password=your_password"
export SSL_CERT_PATH=/etc/ssl/certs/server.crt
export SSL_KEY_PATH=/etc/ssl/private/server.key

# Start service (will automatically use HTTPS)
cyborgdb-service
```

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

### Initialize CyborgDB Client with API Key

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/client/client

Demonstrates how to initialize a new CyborgDB Client instance using the base URL of the microservice and an API key for authentication. Ensure you have a valid API key obtained from the CyborgDB Admin Dashboard.

```python
from cyborgdb import Client

# Create client with API key
client = Client(base_url='http://localhost:8000', api_key='your-api-key')
```

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

### GET /websites/cyborg_co_versions_v0_12_x

Source: https://docs.cyborg.co/versions/v0.12.x/service/python-sdk/encrypted-index/get

Retrieves vectors from the encrypted index by their IDs. You can specify which fields to include in the results. The 'contents' field is always returned as bytes.

```APIDOC
## GET /websites/cyborg_co_versions_v0_12_x

### Description
Retrieves vectors from the encrypted index by their IDs, with options to specify which fields to include in the results.

### Method
GET

### Endpoint
/websites/cyborg_co_versions_v0_12_x

### Parameters
#### Query Parameters
- **ids** (List[str]) - Required - List of vector IDs to retrieve.
- **include** (List[str]) - Optional - Fields to include in the response. Defaults to `["vector", "contents", "metadata"]`.

### Response
#### Success Response (200)
- **id** (str) - Vector identifier (always included).
- **vector** (List[float]) - Vector data (if included).
- **contents** (bytes) - Vector contents as bytes (if included, always returned as bytes).
- **metadata** (Dict) - Vector metadata (if included).

#### Response Example
```json
[
  {
    "id": "doc1",
    "vector": [0.1, 0.2, 0.3, ...],
    "contents": "base64_encoded_content",
    "metadata": {"source": "document.pdf"}
  },
  {
    "id": "doc2",
    "vector": [0.4, 0.5, 0.6, ...]
  }
]
```

### Exceptions
#### Error
- Throws if the API request fails due to network connectivity issues.
- Throws if authentication fails (invalid API key).
- Throws if the encryption key is invalid for the specified index.
- Throws if there are internal server errors preventing the retrieval.

#### Validation Errors
- Throws if the `ids` parameter is null, undefined, or empty.
- Throws if the `include` parameter contains invalid field names.
```

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

### NewClient Constructor

Source: https://docs.cyborg.co/versions/v0.12.x/service/go-sdk/client/client

Creates a new CyborgDB Client instance for connecting to a CyborgDB microservice. It takes the base URL, API key, and an optional SSL verification flag.

```APIDOC
## NewClient Constructor

### Description
Creates a new CyborgDB `Client` instance for connecting to a CyborgDB microservice.

### Method
`func NewClient(baseURL, apiKey string, verifySSL ...bool) (*Client, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client with API key
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
    
    // Test the connection
    ctx := context.Background()
    health, err := client.GetHealth(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Service health: %+v\n", health)
}
```

### Response
#### Success Response (200)
The `NewClient` function returns a pointer to a `Client` struct and an error. If successful, the error will be nil.

- ***Client** (**Client*) - A pointer to the initialized CyborgDB client.
- **error** (*error*) - An error object if initialization fails, otherwise nil.

#### Response Example
```json
{
  "client": "<*cyborgdb.Client>",
  "error": null
}
```

### Remarks
- The `baseURL` should be the endpoint of your CyborgDB microservice.
- An `apiKey` is required for authentication. You can obtain this from the CyborgDB Admin Dashboard.
- `verifySSL` is an optional boolean. If omitted, SSL verification is auto-detected based on the URL.
```

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

### Configure CyborgDB Service HTTPS using .env File

Source: https://docs.cyborg.co/versions/v0.12.x/service/guides/intro/quickstart-python

This snippet shows how to configure the CyborgDB service with HTTPS by creating a `.env` file containing all necessary environment variables, including database connection details and SSL certificate paths. The service is then started, automatically utilizing the configurations from the `.env` file.

```bash
# Create a .env file with SSL configuration
cat > .env << EOF
CYBORGDB_API_KEY=cyborg_your_api_key_here
CYBORGDB_DB_TYPE=postgres
CYBORGDB_CONNECTION_STRING=host=localhost port=5432 dbname=postgres user=postgres password=your_password
SSL_CERT_PATH=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key
EOF

# Start service
cyborgdb-service
```

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

### Install CyborgDB via npm

Source: https://docs.cyborg.co/versions/v0.12.x/service/js-ts-sdk/introduction

Installs the CyborgDB JavaScript/TypeScript SDK using npm. This is the primary method for incorporating the SDK into your Node.js or browser-based projects.

```bash
npm install cyborgdb
```