Pinecone

Import from @anvia/pinecone.

PineconeVectorStoreConnectOptions

type PineconeVectorStoreConnectOptions = {
  client?: PineconeClientLike;
  indexName: string;
  namespace?: string;
  createIfMissing?: boolean;
  metric?: "cosine" | "euclidean" | "dotproduct";
};

Purpose: connection options for a Pinecone index.

Return behavior: consumed by PineconeVectorStore.connect(...).

Notable errors: index lookup fails when createIfMissing is false and the index does not exist.

Design note: connect(...) optionally creates a serverless index, then resolves a namespace handle. This keeps constructors synchronous and side-effect free while ensuring the index exists before ingestion or search.

PineconeVectorStore

class PineconeVectorStore<T, Metadata extends VectorMetadata = VectorMetadata> {
  static connect<T, Metadata extends VectorMetadata = VectorMetadata>(
    options: PineconeVectorStoreConnectOptions,
  ): Promise<PineconeVectorStore<T, Metadata>>;
  upsertDocuments(documents: Array<EmbeddedDocument<T, Metadata>>): Promise<void>;
  index(model: EmbeddingModel): PineconeVectorIndex<T, Metadata>;
}

Purpose: Pinecone-backed document storage.

Return behavior: connect(...) resolves a store; index(...) binds it to an embedding model.

Notable errors: connection and upsert calls reject on Pinecone errors; upsertDocuments(...) throws when a document has no embeddings.

PineconeVectorIndex

class PineconeVectorIndex<T, Metadata extends VectorMetadata = VectorMetadata>
  implements VectorSearchIndex<T, Metadata> {
  search(request: VectorSearchRequest): Promise<Array<VectorSearchResult<T, Metadata>>>;
  searchIds(request: VectorSearchRequest): Promise<Array<{ score: number; id: string }>>;
  asTool(options: VectorSearchToolOptions): Tool<{ query: string; topK?: number }, unknown>;
}

Purpose: query-time Pinecone search adapter.

Return behavior: embeds the query, queries Pinecone with metadata, deduplicates multi-embedding document IDs, and returns normalized results.

Notable errors: embedding or Pinecone query failures reject.

filterToPineconeFilter

function filterToPineconeFilter(filter: VectorFilter | undefined): unknown;

Purpose: convert Anvia vector filters to Pinecone filter objects.

Return behavior: returns undefined when no filter is supplied.

Notable errors: none directly.

PineconeMetric

type PineconeMetric = "cosine" | "euclidean" | "dotproduct";

Purpose: distance metric for a Pinecone index.

PineconeIndexLike

type PineconeIndexLike = {
  namespace(namespace: string): PineconeNamespaceLike;
};

Purpose: duck-typed interface for a Pinecone index handle.

PineconeNamespaceLike

type PineconeNamespaceLike = {
  upsert(vectors: Array<Record<string, unknown>>): Promise<unknown>;
  query(options: Record<string, unknown>): Promise<unknown>;
};

Purpose: duck-typed interface for a Pinecone namespace.