> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

<Tabs>
  <Tab title="Embedded">
    ## DBConfig

    The `DBConfig` class specifies the storage location for the index, with options for in-memory storage or databases.

    ### Parameters

    | Parameter           | Type     | Default | Description                                                     |
    | ------------------- | -------- | ------- | --------------------------------------------------------------- |
    | `location`          | `string` | -       | DB location (`rocksdb`, `s3`, `memory`, `threadsafememory`)     |
    | `connection_string` | `string` | None    | *(Optional)* Connection string or path for the chosen location. |

    The supported `location` options are:

    * `"rocksdb"`: Use for persistent, on-disk key-value storage (recommended for embedded/local deployments).
    * `"s3"`: Use for AWS S3 or any S3-compatible object store (MinIO, Cloudflare R2). Connection string carries the URI and credentials.
    * `"memory"`: Use for temporary in-memory storage (for benchmarking and evaluation purposes).
    * `"threadsafememory"`: Use for thread-safe in-memory storage (for multi-threaded benchmarking).

    ### Example Usage

    ```python theme={null}
    from cyborgdb_core import DBConfig

    # RocksDB (persistent local storage)
    rocksdb_location = DBConfig(
        location="rocksdb",
        connection_string="/path/to/rocksdb"
    )

    # S3 (cloud-native)
    s3_location = DBConfig(
        location="s3",
        connection_string="s3://my-bucket?region=us-east-1"
    )

    # Memory configuration (for testing)
    memory_location = DBConfig(location="memory")

    # Thread-safe memory configuration (for multi-threaded testing)
    ts_memory_location = DBConfig(location="threadsafememory")
    ```

    ***

    ## Embeddings

    The Embedded LangChain integration accepts any LangChain `Embeddings` implementation:

    ### Supported Embedding Types

    | Type         | Description                             | Example                                         |
    | ------------ | --------------------------------------- | ----------------------------------------------- |
    | `Embeddings` | Any LangChain Embeddings implementation | `OpenAIEmbeddings()`, `HuggingFaceEmbeddings()` |

    ### Example Usage

    ```python theme={null}
    from langchain_openai import OpenAIEmbeddings
    from cyborgdb_core.integrations.langchain import CyborgVectorStore
    from cyborgdb_core import DBConfig

    # Using LangChain Embeddings
    store = CyborgVectorStore(
        index_name="docs",
        index_key=key,
        api_key="your-api-key",
        embedding=OpenAIEmbeddings(),
        index_location=DBConfig("memory"),
        config_location=DBConfig("memory")
    )
    ```

    ***

    ## DistanceMetric

    `DistanceMetric` is a string representing the distance metric used for the index. Options include:

    * `"cosine"`: Cosine similarity (recommended for normalized embeddings)
    * `"euclidean"`: Euclidean distance
    * `"squared_euclidean"`: Squared Euclidean distance

    ### Metric Characteristics

    | Metric              | Range   | Best Match | Use Case                            |
    | ------------------- | ------- | ---------- | ----------------------------------- |
    | `cosine`            | \[0, 2] | 0          | Text embeddings, normalized vectors |
    | `euclidean`         | \[0, ∞) | 0          | Raw feature vectors                 |
    | `squared_euclidean` | \[0, ∞) | 0          | When avoiding sqrt computation      |

    ***

    ## IndexType

    The index type determines the algorithm used for approximate nearest neighbor search.

    ### Available Index Types

    | Type        | Description                             | Speed | Recall  | Index Size |
    | ----------- | --------------------------------------- | ----- | ------- | ---------- |
    | `"ivfflat"` | Inverted file with flat storage         | Fast  | Highest | Biggest    |
    | `"ivfpq"`   | Inverted file with product quantization | Fast  | High    | Medium     |
    | `"ivfsq"`   | Inverted file with scalar quantization  | Fast  | High    | Small      |

    <Note>The default index type for the Embedded library is `"ivfsq"`.</Note>

    ### Example Usage

    ```python theme={null}
    from langchain_openai import OpenAIEmbeddings

    # IVFFlat index (highest recall)
    store = CyborgVectorStore(
        index_name="high_recall_index",
        index_key=key,
        api_key="your-api-key",
        embedding=OpenAIEmbeddings(),
        index_location=DBConfig("memory"),
        config_location=DBConfig("memory"),
        index_type="ivfflat",
        index_config_params={"n_lists": 1024}
    )

    # IVFPQ index (balanced performance)
    store = CyborgVectorStore(
        index_name="balanced_index",
        index_key=key,
        api_key="your-api-key",
        embedding=OpenAIEmbeddings(),
        index_location=DBConfig("memory"),
        config_location=DBConfig("memory"),
        index_type="ivfpq",
        index_config_params={
            "n_lists": 1024,
            "pq_dim": 64,
            "pq_bits": 8
        }
    )
    ```

    ***

    ## IndexConfigParams

    Optional parameters for configuring the index, passed as a dictionary.

    ### Parameters by Index Type

    #### IVFFlat

    | Parameter | Type  | Default | Description                         |
    | --------- | ----- | ------- | ----------------------------------- |
    | `n_lists` | `int` | 1024    | Number of inverted lists (clusters) |

    #### IVFPQ

    | Parameter | Type  | Default | Description                               |
    | --------- | ----- | ------- | ----------------------------------------- |
    | `n_lists` | `int` | 1024    | Number of inverted lists (clusters)       |
    | `pq_dim`  | `int` | 8       | Dimensionality after product quantization |
    | `pq_bits` | `int` | 8       | Bits per quantized dimension (1-16)       |

    #### IVFSQ

    | Parameter | Type  | Default | Description                         |
    | --------- | ----- | ------- | ----------------------------------- |
    | `n_lists` | `int` | 1024    | Number of inverted lists (clusters) |
    | `sq_bits` | `int` | 16      | Bits per scalar quantized value     |

    ### Tuning Guidelines

    <Tip>
      * **n\_lists**: Use √n where n is the expected number of vectors. Common values: 256, 512, 1024, 2048
      * **pq\_dim**: Should divide the embedding dimension evenly. Lower values = more compression
      * **pq\_bits / sq\_bits**: 8 bits provides good balance. Lower = more compression, higher = better accuracy
    </Tip>

    ***

    ## Document

    LangChain Document object used for storing text with metadata.

    ### Attributes

    | Attribute      | Type   | Description                                    |
    | -------------- | ------ | ---------------------------------------------- |
    | `page_content` | `str`  | The text content of the document               |
    | `metadata`     | `dict` | Optional metadata associated with the document |

    ### Example Usage

    ```python theme={null}
    from langchain_core.documents import Document

    # Create a document
    doc = Document(
        page_content="This is the content of my document",
        metadata={
            "source": "manual",
            "author": "John Doe",
            "timestamp": "2024-01-01"
        }
    )

    # Add to vector store
    store.add_documents([doc])
    ```

    ***

    ## Filter Format

    Metadata filters use a dictionary format for querying documents.

    ### Simple Filters

    ```python theme={null}
    # Exact match
    filter = {"category": "technology"}

    # Multiple conditions (AND)
    filter = {
        "category": "technology",
        "year": 2024
    }
    ```

    ### Advanced Filters

    ```python theme={null}
    # Range queries
    filter = {
        "price": {"$gte": 100, "$lte": 500}
    }

    # IN queries
    filter = {
        "tags": {"$in": ["python", "machine-learning"]}
    }

    # Nested fields
    filter = {
        "metadata.author": "John Doe"
    }
    ```

    ### Supported Operators

    | Operator | Description           | Example                                        |
    | -------- | --------------------- | ---------------------------------------------- |
    | `$eq`    | Equal to              | `{"age": {"$eq": 25}}`                         |
    | `$ne`    | Not equal to          | `{"status": {"$ne": "archived"}}`              |
    | `$gt`    | Greater than          | `{"price": {"$gt": 100}}`                      |
    | `$gte`   | Greater than or equal | `{"score": {"$gte": 0.8}}`                     |
    | `$lt`    | Less than             | `{"quantity": {"$lt": 10}}`                    |
    | `$lte`   | Less than or equal    | `{"rating": {"$lte": 5}}`                      |
    | `$in`    | In array              | `{"tags": {"$in": ["ai", "ml"]}}`              |
    | `$nin`   | Not in array          | `{"category": {"$nin": ["draft", "deleted"]}}` |

    ***

    ## Return Types

    ### Query Results

    Query operations return documents with optional scores:

    ```python theme={null}
    # similarity_search returns List[Document]
    docs = store.similarity_search("query", k=5)
    # Returns: [Document(...), Document(...), ...]

    # similarity_search_with_score returns List[Tuple[Document, float]]
    results = store.similarity_search_with_score("query", k=5)
    # Returns: [(Document(...), 0.95), (Document(...), 0.87), ...]
    ```

    ### Score Normalization

    Scores are normalized to \[0, 1] range where:

    * **1.0** = Perfect match
    * **0.0** = Worst match

    The normalization depends on the distance metric used.

    ***

    ## Async Support

    All methods have async variants prefixed with `a`:

    | Sync Method                     | Async Method                     |
    | ------------------------------- | -------------------------------- |
    | `add_texts`                     | `aadd_texts`                     |
    | `add_documents`                 | `aadd_documents`                 |
    | `similarity_search`             | `asimilarity_search`             |
    | `similarity_search_with_score`  | `asimilarity_search_with_score`  |
    | `similarity_search_by_vector`   | `asimilarity_search_by_vector`   |
    | `max_marginal_relevance_search` | `amax_marginal_relevance_search` |
    | `delete`                        | `adelete`                        |

    ### Example Usage

    ```python theme={null}
    import asyncio

    async def main():
        # Async text addition
        ids = await store.aadd_texts(["async text 1", "async text 2"])

        # Async search
        docs = await store.asimilarity_search("query", k=5)

        # Async deletion
        success = await store.adelete(ids)

    asyncio.run(main())
    ```
  </Tab>

  <Tab title="Python SDK">
    ## Connection Configuration

    The Python SDK connects to a running CyborgDB service instead of using `DBConfig` for storage locations.

    | Parameter    | Type   | Default | Description                                                                                           |
    | ------------ | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
    | `base_url`   | `str`  | -       | Base URL of the CyborgDB microservice endpoint                                                        |
    | `api_key`    | `str`  | -       | API key for authentication with the microservice                                                      |
    | `verify_ssl` | `bool` | `None`  | *(Optional)* SSL verification. When `None`, automatically disabled for `localhost` and `http://` URLs |

    <Note>`DBConfig` and `GPUConfig` are not applicable to the Python SDK. Storage configuration is managed by the CyborgDB service.</Note>

    ### Example Usage

    ```python theme={null}
    from cyborgdb.integrations.langchain import CyborgVectorStore

    store = CyborgVectorStore(
        index_name="my_documents",
        index_key=key,
        api_key="your-api-key",
        embedding="all-MiniLM-L6-v2",
        base_url="http://localhost:8000"
    )
    ```

    ***

    ## Embeddings

    The Python SDK supports the same embedding types as the Embedded library:

    | Type                  | Description                                | Example                                         |
    | --------------------- | ------------------------------------------ | ----------------------------------------------- |
    | `str`                 | Model name string for SentenceTransformers | `"sentence-transformers/all-MiniLM-L6-v2"`      |
    | `SentenceTransformer` | SentenceTransformer model instance         | `SentenceTransformer("all-MiniLM-L6-v2")`       |
    | `Embeddings`          | Any LangChain Embeddings implementation    | `OpenAIEmbeddings()`, `HuggingFaceEmbeddings()` |

    ***

    ## DistanceMetric

    Same as Embedded:

    * `"cosine"`: Cosine similarity (recommended for normalized embeddings)
    * `"euclidean"`: Euclidean distance
    * `"squared_euclidean"`: Squared Euclidean distance

    | Metric              | Range   | Best Match | Use Case                            |
    | ------------------- | ------- | ---------- | ----------------------------------- |
    | `cosine`            | \[0, 2] | 0          | Text embeddings, normalized vectors |
    | `euclidean`         | \[0, ∞) | 0          | Raw feature vectors                 |
    | `squared_euclidean` | \[0, ∞) | 0          | When avoiding sqrt computation      |

    ***

    ## IndexType

    Same as Embedded:

    | Type        | Description                             | Speed | Recall  | Index Size |
    | ----------- | --------------------------------------- | ----- | ------- | ---------- |
    | `"ivfflat"` | Inverted file with flat storage         | Fast  | Highest | Biggest    |
    | `"ivfpq"`   | Inverted file with product quantization | Fast  | High    | Medium     |
    | `"ivfsq"`   | Inverted file with scalar quantization  | Fast  | High    | Small      |

    ***

    ## Document

    LangChain Document object used for storing text with metadata.

    | Attribute      | Type   | Description                                    |
    | -------------- | ------ | ---------------------------------------------- |
    | `page_content` | `str`  | The text content of the document               |
    | `metadata`     | `dict` | Optional metadata associated with the document |

    ```python theme={null}
    from langchain_core.documents import Document

    doc = Document(
        page_content="This is the content of my document",
        metadata={"source": "manual", "author": "John Doe"}
    )
    ```

    ***

    ## Filter Format

    Same filter format as Embedded. Metadata filters use a dictionary format:

    ```python theme={null}
    # Exact match
    filter = {"category": "technology"}

    # Range queries
    filter = {"price": {"$gte": 100, "$lte": 500}}

    # IN queries
    filter = {"tags": {"$in": ["python", "machine-learning"]}}
    ```

    Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`

    ***

    ## Return Types

    Same as Embedded:

    ```python theme={null}
    # similarity_search returns List[Document]
    docs = store.similarity_search("query", k=5)

    # similarity_search_with_score returns List[Tuple[Document, float]]
    results = store.similarity_search_with_score("query", k=5)
    ```

    ***

    ## Async Support

    Same async variants as Embedded, prefixed with `a`:

    | Sync Method                    | Async Method                    |
    | ------------------------------ | ------------------------------- |
    | `add_texts`                    | `aadd_texts`                    |
    | `add_documents`                | `aadd_documents`                |
    | `similarity_search`            | `asimilarity_search`            |
    | `similarity_search_with_score` | `asimilarity_search_with_score` |
    | `similarity_search_by_vector`  | `asimilarity_search_by_vector`  |
    | `delete`                       | `adelete`                       |
  </Tab>

  <Tab title="JS/TS">
    ## CyborgVectorStoreConfig

    Configuration interface for constructing a `CyborgVectorStore` in JavaScript/TypeScript.

    ```typescript theme={null}
    interface CyborgVectorStoreConfig {
        baseUrl: string;
        apiKey: string;
        indexName: string;
        indexKey: Uint8Array;
        indexType?: "ivfflat" | "ivfpq" | "ivfsq";
        indexConfigParams?: Record<string, number>;
        dimension?: number;
        metric?: "cosine" | "euclidean" | "squared_euclidean";
        verifySsl?: boolean;
    }
    ```

    | Parameter           | Type                     | Default     | Description                                                      |
    | ------------------- | ------------------------ | ----------- | ---------------------------------------------------------------- |
    | `baseUrl`           | `string`                 | -           | Base URL of the CyborgDB microservice endpoint                   |
    | `apiKey`            | `string`                 | -           | API key for authentication                                       |
    | `indexName`         | `string`                 | -           | Name of the index                                                |
    | `indexKey`          | `Uint8Array`             | -           | 32-byte encryption key                                           |
    | `indexType`         | `string`                 | `"ivfflat"` | *(Optional)* Index algorithm type                                |
    | `indexConfigParams` | `Record<string, number>` | -           | *(Optional)* Additional index configuration parameters           |
    | `dimension`         | `number`                 | -           | *(Optional)* Embedding dimension (auto-inferred if not provided) |
    | `metric`            | `string`                 | `"cosine"`  | *(Optional)* Distance metric                                     |
    | `verifySsl`         | `boolean`                | `true`      | *(Optional)* SSL verification                                    |

    <Note>All parameters use camelCase convention, consistent with JavaScript/TypeScript standards.</Note>

    ***

    ## EmbeddingsInterface

    The JS/TS SDK accepts any LangChain `EmbeddingsInterface` implementation:

    ```typescript theme={null}
    import { OpenAIEmbeddings } from '@langchain/openai';
    import { HuggingFaceTransformersEmbeddings } from '@langchain/community/embeddings/hf_transformers';

    // OpenAI embeddings
    const embeddings = new OpenAIEmbeddings();

    // HuggingFace embeddings
    const embeddings = new HuggingFaceTransformersEmbeddings({
        model: "all-MiniLM-L6-v2"
    });
    ```

    <Note>Unlike the Python SDKs, the JS/TS SDK does not accept raw model name strings. You must pass a LangChain `EmbeddingsInterface` instance.</Note>

    ***

    ## DistanceMetric

    Same options as Python SDKs:

    * `"cosine"`: Cosine similarity (recommended for normalized embeddings)
    * `"euclidean"`: Euclidean distance
    * `"squared_euclidean"`: Squared Euclidean distance

    ***

    ## Document

    LangChain `Document` object:

    ```typescript theme={null}
    import { Document } from '@langchain/core/documents';

    const doc = new Document({
        pageContent: "This is the content of my document",
        metadata: { source: "manual", author: "John Doe" }
    });
    ```

    | Attribute     | Type                  | Description                                    |
    | ------------- | --------------------- | ---------------------------------------------- |
    | `pageContent` | `string`              | The text content of the document               |
    | `metadata`    | `Record<string, any>` | Optional metadata associated with the document |

    ***

    ## FilterType

    Metadata filters use an object format:

    ```typescript theme={null}
    // Exact match
    const filter = { category: "technology" };

    // Multiple conditions (AND)
    const filter = {
        category: "technology",
        year: 2024
    };
    ```

    Supports the same operators as the Python SDKs: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`.

    ***

    ## Return Types

    ```typescript theme={null}
    // similaritySearch returns Promise<Document[]>
    const docs = await store.similaritySearch("query", 5);

    // similaritySearchWithScore returns Promise<[Document, number][]>
    const results = await store.similaritySearchWithScore("query", 5);
    ```

    ***

    ## Async

    <Note>All JS/TS methods are natively async and return `Promise<...>`. There are no separate sync/async variants — every method uses `await`.</Note>
  </Tab>
</Tabs>