import { APIResource } from "../../core/resource.mjs";
import * as VectorStoresAPI from "./vector-stores.mjs";
import * as CompletionsAPI from "../chat/completions.mjs";
import * as VectorsAPI from "./vectors.mjs";
import { VectorDocument, VectorDocumentsCursorPageVectors, VectorListParams, VectorRetrieveParams, Vectors } from "./vectors.mjs";
import { APIPromise } from "../../core/api-promise.mjs";
import { CursorPageByName, type CursorPageByNameParams, PagePromise } from "../../core/pagination.mjs";
import { RequestOptions } from "../../internal/request-options.mjs";
export declare class VectorStores extends APIResource {
    vectors: VectorsAPI.Vectors;
    /**
     * Create a new vector store for storing and querying document embeddings.
     *
     * The vector store name must be unique within your account and follow naming
     * conventions (3-63 characters, alphanumeric with hyphens/underscores). Once
     * created, the embedding configuration and dimensions are immutable and cannot be
     * changed. To use a different model, you must create a new vector store.
     *
     * **Embedding Configuration:** Provide `embedding_config` (for base or custom
     * model deployments), `embedding_model` (shorthand for a base model), or
     * `dimensions` only (raw embeddings).
     *
     * - With `embedding_config` or `embedding_model`: dimensions are auto-derived, and
     *   documents can be upserted with text content (auto-embedded) or with
     *   pre-computed embeddings.
     * - With `dimensions` only: the store accepts only pre-computed embeddings.
     *   Semantic/hybrid queries are not supported (lexical search only).
     *
     * **Indexed Fields:** Optionally specify metadata fields to index at creation
     * time. Only indexed fields can be used for filtering -- indexing is required, not
     * just a performance optimization. Additional indexed fields can be added later
     * using the configure endpoint, but cannot be removed once added. Keep in mind
     * that each indexed field increases write latency and storage overhead, so only
     * index fields you actively filter on.
     */
    create(body: VectorStoreCreateParams, options?: RequestOptions): APIPromise<VectorStore>;
    /**
     * Retrieve detailed configuration and metadata for a specific vector store.
     *
     * Returns the store's embedding model, dimensions, indexed metadata field
     * definitions, creation timestamp, and last update timestamp. Use this to verify
     * store settings before performing operations or to display store information in
     * your application.
     */
    retrieve(vectorStoreName: string, options?: RequestOptions): APIPromise<VectorStore>;
    /**
     * List all vector stores in your account with pagination.
     *
     * Returns vector stores sorted by creation date (newest first). Each store
     * includes its configuration, embedding model, dimensions, indexed fields, and
     * timestamps.
     */
    list(query?: VectorStoreListParams | null | undefined, options?: RequestOptions): PagePromise<VectorStoresCursorPageByName, VectorStore>;
    /**
     * Delete documents from a vector store by document IDs or metadata filter
     * criteria.
     *
     * **Delete by IDs:** Provide an array of document IDs to delete specific
     * documents. Non-existent documents are silently skipped.
     *
     * **Delete by Filter:** Use metadata filters to delete all documents matching the
     * specified criteria (e.g., delete all documents where `status: "archived"`). The
     * filter must specify at least one condition and cannot be empty. To delete all
     * documents, use the drop endpoint instead.
     *
     * **Filter Operators:** Supports MongoDB-style operators including equality
     * (`{"field": "value"}`), comparison (`$gt`, `$gte`, `$lt`, `$lte`, `$eq`, `$ne`),
     * logical (`$and`, `$or`, `$not`), and membership (`$in`, `$nin`). Only indexed
     * metadata fields can be used for filtering.
     *
     * **Best Practice:** Use the count endpoint with the same filter to preview the
     * number of documents that will be deleted before executing the deletion
     * operation.
     */
    delete(vectorStoreName: string, body: VectorStoreDeleteParams, options?: RequestOptions): APIPromise<VectorStoreDeleteResponse>;
    /**
     * Update the indexed metadata fields configuration for a vector store.
     *
     * This replaces the current set of indexed metadata fields. Only indexed fields
     * can be used for filtering during query, list, and count operations; non-indexed
     * fields are still stored and returned, but cannot be filtered on.
     *
     * **Field Types:** Only STRING, NUMBER, and BOOLEAN fields can be indexed (maximum
     * 20 fields). OBJECT and LIST types are stored but cannot be indexed for
     * filtering.
     *
     * **Adding Fields:** New indexed fields can be added at any time. They are indexed
     * for documents upserted after the change; to make existing documents filterable
     * on a new field, re-upsert them.
     *
     * **Removing Fields:** Omitting a field removes it from this configuration, so it
     * can no longer be filtered on. The underlying index is append-only, so removal
     * does not reclaim storage or reduce write overhead; the field stays in the
     * physical index until the store is recreated. Prefer indexing only the fields you
     * filter on.
     *
     * **Note:** The `name` and `embedding_config` are immutable after creation.
     */
    configure(vectorStoreName: string, body: VectorStoreConfigureParams, options?: RequestOptions): APIPromise<VectorStore>;
    /**
     * Count documents in a vector store, optionally filtered by metadata.
     *
     * **Use Cases:**
     *
     * - Monitor vector store size and growth over time
     * - Preview the number of documents matching a filter before deletion
     * - Validate data ingestion by comparing expected versus actual document counts
     * - Analyze document distribution across metadata categories
     *
     * **Filtering:** Apply the same metadata filter syntax as delete and list
     * operations. Only indexed fields can be used for filtering. An empty filter
     * counts all documents in the store.
     */
    count(vectorStoreName: string, body?: VectorStoreCountParams | null | undefined, options?: RequestOptions): APIPromise<VectorStoreCountResponse>;
    /**
     * Permanently delete a vector store and all its contents.
     *
     * **⚠️ WARNING:** This is a destructive operation that cannot be undone. All
     * documents, embeddings, metadata, and index configurations will be permanently
     * deleted. Data recovery is not possible after deletion.
     */
    drop(vectorStoreName: string, options?: RequestOptions): APIPromise<VectorStoreDropResponse>;
    /**
     * Query documents using similarity search with optional reranking.
     *
     * Primary endpoint for semantic search, question-answering, and RAG
     * (Retrieval-Augmented Generation) applications. Returns documents ranked by
     * relevance to the query text with similarity scores.
     *
     * **Query Types:**
     *
     * - `semantic` (default): Approximate nearest-neighbor search using HNSW over
     *   cosine similarity of document embeddings. Optimal for question-answering,
     *   conceptual search, and finding semantically related content without requiring
     *   exact keyword matches.
     * - `lexical`: Keyword-based text search (BM25 algorithm). Optimal for exact
     *   phrase matching, proper nouns, and scenarios where keyword presence is more
     *   important than semantic similarity.
     * - `hybrid`: Combines semantic and lexical approaches with weighted scoring.
     *   Provides maximum recall by identifying documents matching either semantically
     *   or lexically.
     *
     * **Metadata Filtering:** Narrow the search scope by applying metadata filters
     * (e.g., search only documents where `category: "technical"`). Only indexed fields
     * can be used for filtering. Filters are applied before similarity search for
     * optimal efficiency.
     *
     * **Reranking (Advanced):** Optionally enhance result quality using a
     * cross-encoder reranking model. The reranker rescores the initial results using a
     * more sophisticated model that evaluates the complete query-document pair (not
     * solely embeddings). This adds 100-500ms latency but significantly improves
     * precision for high-stakes applications.
     *
     * **Reranking Strategy:** Set `top_k` higher than the desired final count
     * (e.g., 50) to retrieve more candidates from the initial search. Then configure
     * `rerank_top_n` to the desired final count (e.g., 10) to return only the most
     * relevant documents after reranking. This two-stage approach maximizes both
     * recall and precision.
     *
     * **Performance Metrics:** The response includes detailed timing breakdowns
     * (embedding generation time, index query time, reranking time) to facilitate
     * search pipeline optimization and latency analysis.
     *
     * **Similarity Scores:** Each result includes a `score` field indicating
     * relevance. Higher scores indicate greater relevance. Score ranges and semantics
     * vary by query type (semantic scores use cosine similarity, lexical scores use
     * BM25, hybrid scores combine both approaches).
     */
    query(vectorStoreName: string, body: VectorStoreQueryParams, options?: RequestOptions): APIPromise<VectorStoreQueryResponse>;
    /**
     * Insert new documents or update existing documents in a vector store.
     *
     * **Upsert Behavior:** If a document ID already exists, it will be completely
     * replaced with the new content and metadata. The previous document's text,
     * embedding, and all metadata fields are discarded. If the ID does not exist, a
     * new document is created.
     *
     * **Document Content:** Each document supports several modes:
     *
     * - `content` only: text is automatically embedded using the store's configured
     *   model.
     * - `embedding` only: pre-computed embedding vector is used directly. Dimension
     *   must match the store's configuration.
     * - Both `content` and `embedding`: the pre-computed embedding is stored and text
     *   is kept for retrieval/search.
     * - Neither (metadata-only): only metadata is updated on an existing document
     *   without re-embedding. If the document does not exist, it will appear as a
     *   failure in the batch response.
     *
     * A store created without an embedding model (dimensions-only) only accepts
     * documents with pre-computed `embedding`.
     *
     * **Batch Operations:** This endpoint supports batch operations with partial
     * success handling and mixed document types (some with raw embeddings, some with
     * content) in the same call.
     *
     * **Metadata:** Supports nested metadata with string, number, boolean, object, and
     * array types. Null values are not permitted—omit the field or use an empty string
     * instead.
     */
    upsert(vectorStoreName: string, body: VectorStoreUpsertParams, options?: RequestOptions): APIPromise<VectorStoreUpsertResponse>;
}
export type VectorStoresCursorPageByName = CursorPageByName<VectorStore>;
export type EmbeddingConfig = EmbeddingConfigModelsAPI | EmbeddingConfigBase;
export interface EmbeddingConfigBase {
    /**
     * The name of the base embedding model to use. Either a known base model
     * (EmbeddingModelName) or, in ray-serve deployments with
     * NATIVE_OPENAI_EMBEDDING_GATEWAY enabled, any model id served by the
     * OpenAI-compatible inference proxy (e.g. 'nomic-embed-text-v1.5'). For fully
     * custom deployments, use type 'models_api' with a model_deployment_id.
     */
    embedding_model: EmbeddingModelName | (string & {});
    /**
     * The type of the embedding configuration.
     */
    type?: 'base';
}
export interface EmbeddingConfigModelsAPI {
    /**
     * The ID of the deployment of the created model in the Models API V3.
     */
    model_deployment_id: string;
    /**
     * The type of the embedding configuration.
     */
    type: 'models_api';
}
export type EmbeddingModelName = 'sentence-transformers/all-MiniLM-L12-v2' | 'sentence-transformers/multi-qa-distilbert-cos-v1' | 'openai/text-embedding-ada-002' | 'openai/text-embedding-3-small' | 'openai/text-embedding-3-large' | 'embed-english-v3.0' | 'embed-english-light-v3.0' | 'embed-multilingual-v3.0' | 'gemini/text-embedding-005' | 'gemini/text-multilingual-embedding-002' | 'gemini/gemini-embedding-001';
/**
 * Text content for documents.
 */
export interface TextContent {
    /**
     * Text content to be embedded
     */
    text: string;
    /**
     * Content type identifier
     */
    type?: 'text';
}
/**
 * Response model for vector store operations.
 */
export interface VectorStore {
    /**
     * The unique identifier of the vector store
     */
    id: string;
    /**
     * Timestamp of creation
     */
    created_at: string;
    /**
     * Dimensionality of the embedding vectors
     */
    embedding_dimensions: number;
    /**
     * The name of the vector store
     */
    name: string;
    /**
     * Timestamp of last update
     */
    updated_at: string;
    /**
     * Embedding configuration identifying the model and its type. None for
     * raw-embedding-only stores.
     */
    embedding_config?: EmbeddingConfig;
    /**
     * Dictionary mapping metadata field names to their types
     */
    indexed_metadata_fields?: {
        [key: string]: 'string' | 'number' | 'boolean';
    };
}
/**
 * Response for delete operation.
 */
export interface VectorStoreDeleteResponse {
    /**
     * Number of documents deleted
     */
    deleted_count: number;
}
/**
 * Response for count operation.
 */
export interface VectorStoreCountResponse {
    /**
     * Number of documents matching the criteria
     */
    count: number;
}
/**
 * Response for vector store deletion.
 */
export interface VectorStoreDropResponse {
    /**
     * The name of the deleted vector store
     */
    name: string;
}
/**
 * Response for query operation.
 */
export interface VectorStoreQueryResponse {
    /**
     * Query execution metadata
     */
    metadata: VectorStoreQueryResponse.Metadata;
    /**
     * Array of matching documents
     */
    vectors: Array<VectorStoreQueryResponse.Vector>;
}
export declare namespace VectorStoreQueryResponse {
    /**
     * Query execution metadata
     */
    interface Metadata {
        /**
         * Type of search performed (semantic, lexical, hybrid)
         */
        search_type: string;
        /**
         * Total end-to-end query execution time in milliseconds
         */
        total_query_time_ms: number;
        /**
         * Embedding configuration used for query vectorization. None for lexical queries
         * on model-less stores.
         */
        embedding_config?: VectorStoresAPI.EmbeddingConfig;
        /**
         * Time spent generating embeddings in milliseconds (None for lexical queries)
         */
        embedding_time_ms?: number;
        /**
         * Time spent querying the vector index (OpenSearch) in milliseconds
         */
        index_query_time_ms?: number;
        /**
         * Reranking model used (None if reranking not enabled)
         */
        reranking_model?: string;
        /**
         * Time spent reranking results in milliseconds (None if reranking not enabled)
         */
        reranking_time_ms?: number;
    }
    /**
     * A document in query/search responses with similarity score.
     *
     * Extends VectorDocumentResponse to add a similarity score field for ranked search
     * results.
     */
    interface Vector {
        /**
         * Document ID
         */
        id: string;
        /**
         * Similarity score indicating relevance
         */
        score: number;
        /**
         * Text content for documents.
         */
        content?: VectorStoresAPI.TextContent;
        /**
         * Key-value metadata
         */
        metadata?: {
            [key: string]: unknown;
        };
        /**
         * Embedding vector (if requested)
         */
        vector?: Array<number>;
    }
}
/**
 * Response for batch insert/upsert operations.
 */
export interface VectorStoreUpsertResponse {
    /**
     * Number of failed documents
     */
    failure_count: number;
    /**
     * Number of successfully processed documents
     */
    success_count: number;
    /**
     * Failed documents with their error messages
     */
    failed?: Array<VectorStoreUpsertResponse.Failed>;
    /**
     * IDs of successfully processed documents
     */
    succeeded?: Array<string>;
}
export declare namespace VectorStoreUpsertResponse {
    /**
     * A document that failed during a batch upsert operation.
     */
    interface Failed {
        /**
         * Document ID
         */
        id: string;
        /**
         * Error message describing why the document failed
         */
        error: string;
    }
}
export interface VectorStoreCreateParams {
    /**
     * A unique name for the vector store within the account
     */
    name: string;
    /**
     * Dimension size of embedding vectors. Required when neither 'embedding_config'
     * nor 'embedding_model' is set. Automatically derived when an embedding model is
     * provided.
     */
    dimensions?: number;
    /**
     * The embedding configuration. Either 'base' type with an embedding_model, or
     * 'models_api' type with a model_deployment_id for custom models.
     */
    embedding_config?: EmbeddingConfig;
    /**
     * The base embedding model to use. Shorthand for embedding_config with type
     * 'base'. Provide either embedding_config or embedding_model, not both.
     */
    embedding_model?: EmbeddingModelName;
    /**
     * Dictionary mapping metadata field names to their types for efficient filtering.
     * Only STRING, NUMBER, and BOOLEAN types can be indexed.
     */
    indexed_metadata_fields?: {
        [key: string]: 'string' | 'number' | 'boolean';
    };
}
export interface VectorStoreListParams extends CursorPageByNameParams {
    sort_by?: string;
    sort_order?: CompletionsAPI.SortOrder;
}
export interface VectorStoreDeleteParams {
    /**
     * Metadata filter expression for deletion
     */
    filter?: {
        [key: string]: unknown;
    };
    /**
     * Array of document IDs to delete
     */
    ids?: Array<string>;
}
export interface VectorStoreConfigureParams {
    /**
     * Dictionary mapping metadata field names to their types. Only STRING, NUMBER, and
     * BOOLEAN types can be indexed.
     */
    indexed_metadata_fields: {
        [key: string]: 'string' | 'number' | 'boolean';
    };
}
export interface VectorStoreCountParams {
    /**
     * Metadata filter expression
     */
    filter?: {
        [key: string]: unknown;
    };
}
export interface VectorStoreQueryParams {
    /**
     * Text content for documents.
     */
    content: TextContent;
    /**
     * Metadata filter expression
     */
    filter?: {
        [key: string]: unknown;
    };
    /**
     * Include embedding vectors in response
     */
    include_vectors?: boolean;
    /**
     * Query type: semantic, lexical, or hybrid
     */
    query_type?: 'semantic' | 'lexical' | 'hybrid';
    /**
     * [Deprecated: use rerank_config] Enable reranking of search results
     */
    rerank?: boolean;
    /**
     * Reranking configuration. Presence enables reranking; omit to disable. Pass an
     * empty object ({}) to enable reranking with system defaults.
     */
    rerank_config?: VectorStoreQueryParams.RerankConfig;
    /**
     * [Deprecated: use rerank_config.instruction] Custom instruction for reranker
     */
    rerank_instruction?: string;
    /**
     * [Deprecated: use rerank_config.model] Reranking model to use
     */
    rerank_model?: string;
    /**
     * [Deprecated: use rerank_config.top_n] Number of results after reranking
     */
    rerank_top_n?: number;
    /**
     * Number of search results to return
     */
    top_k?: number;
}
export declare namespace VectorStoreQueryParams {
    /**
     * Reranking configuration. Presence enables reranking; omit to disable. Pass an
     * empty object ({}) to enable reranking with system defaults.
     */
    interface RerankConfig {
        /**
         * Custom instruction for the reranking model (e.g., 'Given a medical question,
         * retrieve relevant clinical passages'). Only applies to instruction-following
         * rerankers like Qwen3.
         */
        instruction?: string;
        /**
         * Reranking model to use (uses system default if not specified). Supported values
         * depend on the selected provider: Launch cross-encoder names (e.g.
         * 'cross-encoder/ms-marco-MiniLM-L-12-v2'), Vertex semantic-ranker names (e.g.
         * 'semantic-ranker-default-004') when provider='vertex', or any model id the
         * inference proxy serves when provider='proxy'.
         */
        model?: string;
        /**
         * Reranking provider to use. When omitted, the deployment default is used
         * ('launch', or 'proxy' on ray-serve deployments configured for the
         * OpenAI-compatible inference proxy). Set explicitly (e.g. 'vertex') to route to a
         * specific provider on a deployment that has more than one configured. Requesting
         * a provider that is not configured on the deployment returns a 400.
         */
        provider?: 'launch' | 'vertex' | 'proxy';
        /**
         * Number of results to keep after reranking (defaults to top_k)
         */
        top_n?: number;
        /**
         * Reranking configuration type. Currently only 'base' is supported.
         */
        type?: 'base';
    }
}
export interface VectorStoreUpsertParams {
    /**
     * Array of documents to upsert
     */
    vectors: Array<VectorStoreUpsertParams.Vector>;
}
export declare namespace VectorStoreUpsertParams {
    /**
     * A document for upsert operations.
     *
     * Documents support several modes:
     *
     * - `content` only: text is embedded and all fields are replaced.
     * - `embedding` only: pre-computed embedding vector is used directly.
     * - Both `content` and `embedding`: the pre-computed embedding is used and text is
     *   stored for retrieval but not re-embedded.
     * - Neither (metadata-only): only metadata is updated on an existing document
     *   without re-embedding. Omitting both on a document that does not exist yet will
     *   return a per-item failure in the batch response.
     */
    interface Vector {
        /**
         * Unique document ID
         */
        id: string;
        /**
         * Text content for documents.
         */
        content?: VectorStoresAPI.TextContent;
        /**
         * Pre-computed embedding vector
         */
        embedding?: Array<number>;
        /**
         * Key-value metadata
         */
        metadata?: {
            [key: string]: unknown;
        };
    }
}
export declare namespace VectorStores {
    export { type EmbeddingConfig as EmbeddingConfig, type EmbeddingConfigBase as EmbeddingConfigBase, type EmbeddingConfigModelsAPI as EmbeddingConfigModelsAPI, type EmbeddingModelName as EmbeddingModelName, type TextContent as TextContent, type VectorStore as VectorStore, type VectorStoreDeleteResponse as VectorStoreDeleteResponse, type VectorStoreCountResponse as VectorStoreCountResponse, type VectorStoreDropResponse as VectorStoreDropResponse, type VectorStoreQueryResponse as VectorStoreQueryResponse, type VectorStoreUpsertResponse as VectorStoreUpsertResponse, type VectorStoresCursorPageByName as VectorStoresCursorPageByName, type VectorStoreCreateParams as VectorStoreCreateParams, type VectorStoreListParams as VectorStoreListParams, type VectorStoreDeleteParams as VectorStoreDeleteParams, type VectorStoreConfigureParams as VectorStoreConfigureParams, type VectorStoreCountParams as VectorStoreCountParams, type VectorStoreQueryParams as VectorStoreQueryParams, type VectorStoreUpsertParams as VectorStoreUpsertParams, };
    export { Vectors as Vectors, type VectorDocument as VectorDocument, type VectorDocumentsCursorPageVectors as VectorDocumentsCursorPageVectors, type VectorRetrieveParams as VectorRetrieveParams, type VectorListParams as VectorListParams, };
}
//# sourceMappingURL=vector-stores.d.mts.map