> ## 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">
    ## StorageConfig

    The `StorageConfig` class specifies where the index data is stored. Build it with one of the static factories:

    | Factory | Description |
    | - | - |
    | `StorageConfig.disk(path, *, cache_vectors=False, cache_metadata=False, cache_ids=False, cache_metadata_index=False)` | Persistent local storage at `path` (recommended for embedded/local deployments). |
    | `StorageConfig.s3(bucket, *, region=None, endpoint=None, prefix="", credentials=None)` | AWS S3 or any S3-compatible object store (MinIO, Cloudflare R2). Uses the AWS default credential chain unless `credentials` is set. |

    ### Example Usage

    ```python theme={null}
    from cyborgdb_core import StorageConfig, S3Credentials

    # Local disk (persistent local storage)
    disk_storage = StorageConfig.disk("/path/to/data")

    # S3 (cloud-native)
    s3_storage = StorageConfig.s3("my-bucket", region="us-east-1")

    # S3-compatible store with explicit credentials
    minio_storage = StorageConfig.s3(
        "my-bucket",
        endpoint="http://localhost:9000",
        credentials=S3Credentials(access_key="minioadmin", secret_key="minioadmin"),
    )
    ```

    ***

    ## Embeddings

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

    ### Supported Embedding Types

    | Type | Description | Example |
    | - | - | - |
    | `str` | Name of a built-in embedding model | `"all-MiniLM-L6-v2"` |
    | `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 StorageConfig

    # Using LangChain Embeddings
    store = CyborgVectorStore(
        index_name="docs",
        index_key=key,
        api_key="your-api-key",
        embedding=OpenAIEmbeddings(),
        storage_config=StorageConfig.disk("/tmp/cyborgdb-langchain")
    )
    ```

    ***

    ## 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 |

    ***

    ## 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 a `StorageConfig`.

    | 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>`StorageConfig` 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 |

    ***

    ## 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;
        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 |
    | `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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.