@absolutejs/absolute-rag-pinecone

@absolutejs/absolute-rag-pinecone

Pinecone adapter package for AbsoluteJS RAG workflows.

This package treats Pinecone as the backend boundary, similarly to how @absolutejs/absolute-rag-postgresql treats PostgreSQL. The @pinecone-database/pinecone SDK is the first (and currently only) implementation choice inside the package.

Public surface

import { createPineconeRAG } from "@absolutejs/absolute-rag-pinecone";

const rag = createPineconeRAG({
  apiKey: process.env.PINECONE_API_KEY,
  indexName: "absolute-rag-demo",
  namespace: "production",
  vector: {
    provider: "pinecone",
    dimensions: 1536,
    distanceMetric: "cosine",
  },
});

await rag.store.upsert({
  chunks: [
    {
      chunkId: "doc-1#0",
      text: "Pinecone stores vectors with attached metadata.",
      title: "Pinecone overview",
      source: "https://docs.pinecone.io",
      metadata: { tags: ["vector", "managed"] },
    },
  ],
});

const hits = await rag.collection.search({ query: "vector database", topK: 4 });

Package primitives

• createPineconeRAG(...) — full bundle: { store, collection, getCapabilities }
• createPineconeRAGCollection(...) — collection-level convenience helper
• createPineconeStore(...) — concrete RAGVectorStore implementation

Options

Field	Required	Notes
apiKey	when no client	Falls back to process.env.PINECONE_API_KEY if omitted.
indexName	when no client	Pinecone index must already exist with matching dimensions.
indexHost	optional	Pre-resolved index host endpoint; skips a describeIndex lookup.
namespace	optional	Logical partition inside the index; default is the empty namespace.
client	optional	Inject a pre-built Pinecone index client (e.g. for tests).
vector.dimensions	yes	Must match the dimensionality of the Pinecone index.
vector.distanceMetric	optional	"cosine" (default), "euclidean", or "dotproduct".
embedding	optional	Custom embed function. Defaults to a deterministic in-memory hash.

The Pinecone index itself is not auto-provisioned at runtime. Pinecone indexes are global resources that take 30–60s to create and have per-account limits and pricing implications, so the runtime path stays lazy. The distanceMetric here is informational and used for score normalization; the authoritative metric is the one configured on the index in Pinecone.

For explicit, opt-in provisioning, the package exports two helpers:

import {
  ensurePineconeIndex,
  describePineconeIndex,
} from "@absolutejs/absolute-rag-pinecone";

// Idempotent: creates the index if missing, validates it if present.
await ensurePineconeIndex({
  apiKey: process.env.PINECONE_API_KEY,
  indexName: "absolute-rag-demo",
  dimensions: 1536,
  metric: "cosine",
  spec: { serverless: { cloud: "aws", region: "us-east-1" } },
  waitUntilReady: true,
});

const description = await describePineconeIndex({
  apiKey: process.env.PINECONE_API_KEY,
  indexName: "absolute-rag-demo",
});

ensurePineconeIndex defaults to a serverless aws/us-east-1 spec, polls until the index reports ready (timeout configurable via waitTimeoutMs), and throws on dimension/metric mismatch when the index already exists.

Filter translation

The AbsoluteJS filter DSL is translated to Pinecone's metadata filter syntax:

AbsoluteJS	Pinecone
field: value	field: { $eq: value }
$eq, $ne, $gt, $gte, $lt, $lte	same
$in: [...]	$in: [...]
$exists: true	$exists: true (paid tier required)
$contains: x	$in: [x] (works for string-array fields)
$containsAny: [...]	$in: [...]
$containsAll: [a, b]	$and: [{ field: { $in: [a] } }, { field: { $in: [b] } }]
$and, $or	$and, $or

$not and dot-path keys (e.g. "profile.score") are not supported — Pinecone metadata is flat. Throws at filter-translation time if encountered.

Reserved metadata keys

The adapter stores chunk fields alongside user metadata at the top level of the Pinecone record's metadata so they round-trip correctly:

• chunkId
• text
• title
• source

These are reserved. Keys with the same name in user metadata are dropped during upsert.

Capabilities and known limits

Capability	Value	Notes
backend	custom	Pinecone is not in the closed RAGVectorStoreStatus.backend union, so the store omits getStatus.
persistence	external
nativeVectorSearch	true
serverSideFiltering	true	Subject to Pinecone's filter constraints.
streamingIngestStatus	false

• queryLexical is intentionally not implemented. Pinecone supports sparse-dense hybrid search, but it has a different shape and is not a drop-in for the framework's RAGLexicalQueryInput contract.
• count({ filter }) performs a query() capped at topK: 10000 and counts the matches; it will undercount above that ceiling.
• delete({ filter }) returns the count by issuing a count({ filter }) first, since Pinecone's deleteMany does not return a count.
• clear() calls deleteAll() on the configured namespace. On free-tier indexes this may not be supported.