RAG Knowledge Base

divinci.rag is the server-side RAG pipeline: create a collection (vector index), upload documents into it, wait for chunking + embedding, then search. A Release that references the collection retrieves from it automatically during chat.

End-to-end flow

1. Create a collection

   const collection = await divinci.rag.createCollection({
     workspaceId: "ws_123",
     name: "Product docs",
   });

2. Upload a document (a Buffer or Blob plus a file name)

   import { readFileSync } from "node:fs";
   
   const file = readFileSync("./handbook.pdf");
   
   const doc = await divinci.rag.uploadDocument(
     "ws_123",
     collection.id,
     file,
     "handbook.pdf",
     { mimeType: "application/pdf" },
   );

3. Wait for processing (chunking + embedding is asynchronous)

   const ready = await divinci.rag.waitForProcessing(
     "ws_123",
     collection.id,
     doc.id,
     { timeout: 120_000, pollInterval: 5_000 },
   );

4. Search

   const results = await divinci.rag.search(
     "ws_123",
     collection.id,
     "What is the refund window?",
     { limit: 5 },
   );

Collections

await divinci.rag.listCollections("ws_123", { limit: 20 });
await divinci.rag.getCollection("ws_123", collection.id);
await divinci.rag.updateCollection("ws_123", collection.id, {
  settings: { similarityThreshold: 0.55, maxChunksPerQuery: 8 },
});
await divinci.rag.deleteCollection("ws_123", collection.id);

Renaming

updateCollection tunes retrieval settings; the platform does not support renaming a collection through this API, so a name passed here is ignored.

Tune retrieval behavior with updateCollectionSettings:

await divinci.rag.updateCollectionSettings("ws_123", collection.id, {
  minimumSimilarity: 0.72,
  contextPerMessage: 8,
  embeddingModel: "gemini-embedding-001@1536",
});

Choosing an embedding model

For large batch imports, prefer a high-RPM embedding model so parallel ingestion doesn’t hit rate limits. Don’t mix embedding models within one collection — vectors from different models live in incompatible spaces.

Documents

await divinci.rag.listDocuments("ws_123", collection.id, { limit: 50 });
await divinci.rag.getDocument("ws_123", collection.id, doc.id);
await divinci.rag.reprocessDocument("ws_123", collection.id, doc.id);
await divinci.rag.deleteDocument("ws_123", collection.id, doc.id);

Source URL backlinks

Every chunk of a document can link back to its source page on the chat context bubble. HTML-scraped pages get this automatically at ingestion; assign a URL to uploads and transcripts (or correct one) with setDocumentSourceUrl:

// Set — http(s) URLs only; anything else is rejected with a 400
await divinci.rag.setDocumentSourceUrl("ws_123", doc.id, "https://example.com/eat-to-live");

// Clear
await divinci.rag.setDocumentSourceUrl("ws_123", doc.id, null);

The stored value surfaces as sourceUrl on the document and as a clickable link on every chat citation that retrieves the document’s chunks.

Bulk upload

const docs = await divinci.rag.uploadDocuments("ws_123", collection.id, [
  { file: pdfA, fileName: "a.pdf" },
  { file: pdfB, fileName: "b.pdf", metadata: { team: "sales" } },
]);

Searching

// Single collection
const hits = await divinci.rag.search("ws_123", collection.id, "return policy", {
  limit: 5,
});

// Across multiple collections
const merged = await divinci.rag.searchMultiple(
  "ws_123",
  [collection.id, otherCollectionId],
  "return policy",
  { limit: 8 },
);

Each RagSearchResult carries the matched chunk text, source metadata, and a similarity score.

Realtime chunks (RTS API)

For low-latency append + search against a vector (mem0-backed), use the chunk API:

const appended = await divinci.rag.appendChunk("ws_123", "rag_vec_id", {
  text: "Orders ship within 2 business days.",
  metadata: { source: "policy" },
});

const found = await divinci.rag.searchChunks("ws_123", "rag_vec_id", {
  query: "how fast is shipping?",
  limit: 5,
  minScore: 0.7,
});

Large synchronous uploads

Synchronous embedding of very large files can exceed an edge proxy’s request timeout even though the work completes server-side. For files over a few hundred chunks, upload without blocking and poll the document’s status (or use waitForProcessing) rather than holding one long request.