diff --git a/docs/website/content/docs/ai-capabilities/rag.mdx b/docs/website/content/docs/ai-capabilities/rag.mdx index 9a7a98cb24..07eadb42a9 100644 --- a/docs/website/content/docs/ai-capabilities/rag.mdx +++ b/docs/website/content/docs/ai-capabilities/rag.mdx @@ -36,8 +36,12 @@ For how to use each function, see [SDK β€” API reference](/reference/api/). Create your RAG pipeline using [text embeddings](/ai-capabilities/text-embeddings), the functions above, and [completion](/ai-capabilities/text-generation). Regarding vector storage, you may use: +- **External vector DB:** use [`embed()`](/reference/api#embed) to generate vectors and store them wherever you want (e.g., MongoDB, LanceDB, ChromaDB, SQLite-Vector). Choose this when you need custom persistence, filtering, or integration with an existing database. - **Built-in vector store:** use the RAG workspace functions ([`ragIngest()`](/reference/api#ragingest), [`ragSearch()`](/reference/api#ragsearch), etc.). QVAC persists the vectors for you, so this is the simplest path. -- **External vector DB:** use the embedding primitives ([`ragChunk()`](/reference/api#ragchunk), [`embed()`](/reference/api#embed)) and store the vectors wherever you want (e.g., MongoDB, LanceDB, ChromaDB, SQLite-Vector). Choose this when you need custom persistence, filtering, or integration with an existing database. + + +**Built-in vector store is not production grade** and is intended for prototypes only. For production workloads, use one of the external vector DB paths shown below (MongoDB, SQLite, LanceDB, Chroma, etc.). + **Important:** when using an external vector DB, make sure its schema matches the embedding dimensionality produced by your model (e.g., GTE Large embeddings used in the example are 1024‑dimensional). @@ -47,6 +51,10 @@ Regarding vector storage, you may use: ### Built-in vector store + +**Prototype only** β€” for production, prefer an external vector DB (below). + + The following script shows how to ingest documents into a built-in RAG workspace with `ragIngest()` and query them with `ragSearch()`, without setting up an external vector DB: diff --git a/docs/website/content/docs/reference/api/index.mdx b/docs/website/content/docs/reference/api/index.mdx index 2401c87e3a..1809bdaa0d 100644 --- a/docs/website/content/docs/reference/api/index.mdx +++ b/docs/website/content/docs/reference/api/index.mdx @@ -906,6 +906,8 @@ const chunks = await ragChunk({ ### `ragCloseWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance). **Workspace lifecycle:** Workspaces are implicitly opened. @@ -935,6 +937,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true }); ### `ragDeleteEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes document embeddings from the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. @@ -961,6 +965,8 @@ await ragDeleteEmbeddings({ ### `ragDeleteWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes a RAG workspace and all its data. The workspace must not be currently loaded/in-use. @@ -983,6 +989,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" }); ### `ragIngest` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Ingests documents into the RAG vector database. Full pipeline: chunk β†’ embed β†’ save @@ -1023,6 +1031,8 @@ const result = await ragIngest({ ### `ragListWorkspaces` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Lists all RAG workspaces with their open status. Returns all workspaces that exist on disk. The `open` field indicates whether @@ -1049,6 +1059,8 @@ const workspaces = await ragListWorkspaces(); ### `ragReindex` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Reindexes the RAG database to optimize search performance. For HyperDB, this rebalances centroids using k-means clustering. @@ -1094,6 +1106,8 @@ const result = await ragReindex({ ### `ragSaveEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Saves pre-embedded documents to the RAG vector database. Part of the segregated flow: chunk() β†’ embed() β†’ saveEmbeddings() @@ -1131,6 +1145,8 @@ const result = await ragSaveEmbeddings({ ### `ragSearch` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Searches for similar documents in the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. If the workspace diff --git a/docs/website/content/docs/reference/api/v0.16.x.mdx b/docs/website/content/docs/reference/api/v0.16.x.mdx index 44e46aa09a..daffa2260f 100644 --- a/docs/website/content/docs/reference/api/v0.16.x.mdx +++ b/docs/website/content/docs/reference/api/v0.16.x.mdx @@ -887,6 +887,8 @@ const chunks = await ragChunk({ ### `ragCloseWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance). **Workspace lifecycle:** Workspaces are implicitly opened. @@ -916,6 +918,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true }); ### `ragDeleteEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes document embeddings from the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. @@ -942,6 +946,8 @@ await ragDeleteEmbeddings({ ### `ragDeleteWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes a RAG workspace and all its data. The workspace must not be currently loaded/in-use. @@ -964,6 +970,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" }); ### `ragIngest` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Ingests documents into the RAG vector database. Full pipeline: chunk β†’ embed β†’ save @@ -1004,6 +1012,8 @@ const result = await ragIngest({ ### `ragListWorkspaces` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Lists all RAG workspaces with their open status. Returns all workspaces that exist on disk. The `open` field indicates whether @@ -1030,6 +1040,8 @@ const workspaces = await ragListWorkspaces(); ### `ragReindex` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Reindexes the RAG database to optimize search performance. For HyperDB, this rebalances centroids using k-means clustering. @@ -1075,6 +1087,8 @@ const result = await ragReindex({ ### `ragSaveEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Saves pre-embedded documents to the RAG vector database. Part of the segregated flow: chunk() β†’ embed() β†’ saveEmbeddings() @@ -1112,6 +1126,8 @@ const result = await ragSaveEmbeddings({ ### `ragSearch` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Searches for similar documents in the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. If the workspace diff --git a/docs/website/content/docs/reference/api/v0.17.x.mdx b/docs/website/content/docs/reference/api/v0.17.x.mdx index 4de5537f80..241e7cb730 100644 --- a/docs/website/content/docs/reference/api/v0.17.x.mdx +++ b/docs/website/content/docs/reference/api/v0.17.x.mdx @@ -889,6 +889,8 @@ const chunks = await ragChunk({ ### `ragCloseWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance). **Workspace lifecycle:** Workspaces are implicitly opened. @@ -918,6 +920,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true }); ### `ragDeleteEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes document embeddings from the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. @@ -944,6 +948,8 @@ await ragDeleteEmbeddings({ ### `ragDeleteWorkspace` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Deletes a RAG workspace and all its data. The workspace must not be currently loaded/in-use. @@ -966,6 +972,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" }); ### `ragIngest` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Ingests documents into the RAG vector database. Full pipeline: chunk β†’ embed β†’ save @@ -1006,6 +1014,8 @@ const result = await ragIngest({ ### `ragListWorkspaces` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Lists all RAG workspaces with their open status. Returns all workspaces that exist on disk. The `open` field indicates whether @@ -1032,6 +1042,8 @@ const workspaces = await ragListWorkspaces(); ### `ragReindex` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Reindexes the RAG database to optimize search performance. For HyperDB, this rebalances centroids using k-means clustering. @@ -1077,6 +1089,8 @@ const result = await ragReindex({ ### `ragSaveEmbeddings` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Saves pre-embedded documents to the RAG vector database. Part of the segregated flow: chunk() β†’ embed() β†’ saveEmbeddings() @@ -1114,6 +1128,8 @@ const result = await ragSaveEmbeddings({ ### `ragSearch` +> πŸ§ͺ **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + Searches for similar documents in the RAG vector database. **Workspace lifecycle:** This operation requires an existing workspace. If the workspace diff --git a/docs/website/scripts/api-docs/extract.ts b/docs/website/scripts/api-docs/extract.ts index 467cb665e8..50e588367e 100644 --- a/docs/website/scripts/api-docs/extract.ts +++ b/docs/website/scripts/api-docs/extract.ts @@ -528,6 +528,7 @@ function buildApiFunction( examples: string[]; throws: Array<{ error: string; description: string }>; deprecated?: string; + prototype?: string; label?: string; }; const rawOverloads: RawOverload[] = overloadSigs.map((s, idx) => { @@ -588,8 +589,15 @@ function buildApiFunction( const deprecated = depTag ? extractComment(depTag.content) || "This overload is deprecated." : undefined; + // @prototype on a specific overload β€” surfaces a "Prototype only" + // callout scoped to this overload. Mirrors @deprecated. + const protoTag = sigBlockTags.find((t: any) => t.tag === "@prototype"); + const prototype = protoTag + ? extractComment(protoTag.content) || + "This overload is a prototype and is not production grade." + : undefined; - return { signature: sigText, description, examples, throws, deprecated, label }; + return { signature: sigText, description, examples, throws, deprecated, prototype, label }; }); // De-dupe identical overload signatures (TypeDoc sometimes emits the @@ -619,6 +627,7 @@ function buildApiFunction( if (ov.throws.length > 0) entry.throws = ov.throws; if (ov.examples.length > 0) entry.examples = ov.examples; if (ov.deprecated) entry.deprecated = ov.deprecated; + if (ov.prototype) entry.prototype = ov.prototype; if (ov.label) entry.label = ov.label; return entry; }) @@ -762,6 +771,16 @@ function buildApiFunction( if (comment?.isDeprecated) return "This function is deprecated."; return undefined; })(), + prototype: (() => { + const protoTag = blockTags.find((tag: any) => tag.tag === "@prototype"); + if (protoTag) { + return ( + extractComment(protoTag.content) || + "This function is a prototype and is not production grade." + ); + } + return undefined; + })(), }; } diff --git a/docs/website/scripts/api-docs/templates/single-page.njk b/docs/website/scripts/api-docs/templates/single-page.njk index 694c777873..be69fa18a4 100644 --- a/docs/website/scripts/api-docs/templates/single-page.njk +++ b/docs/website/scripts/api-docs/templates/single-page.njk @@ -13,7 +13,7 @@ description: One-page reference of all public functions and objects exported by > For per-parameter and per-field details, hover symbols in your IDE or open > `node_modules/@qvac/sdk/dist`. This page is intentionally a high-level index. > -> **Fields shown**: description, signature, throws, examples, deprecation. +> **Fields shown**: description, signature, throws, examples, deprecation, prototype. > **Fields intentionally omitted**: parameter descriptions, return field descriptions > (covered by IDE hover and `.d.ts` declarations). > @@ -29,6 +29,10 @@ description: One-page reference of all public functions and objects exported by {% if fn.deprecated %} > ⚠️ **Deprecated**: {{ fn.deprecated }} +{% endif %} +{% if fn.prototype %} +> πŸ§ͺ **Prototype only**: {{ fn.prototype }} + {% endif %} {% if fn.overloads and fn.overloads.length > 1 %} Has {{ fn.overloads.length }} overloads. @@ -39,6 +43,10 @@ Has {{ fn.overloads.length }} overloads. {% if ov.deprecated %} > ⚠️ **Deprecated**: {{ ov.deprecated }} +{% endif %} +{% if ov.prototype %} +> πŸ§ͺ **Prototype only**: {{ ov.prototype }} + {% endif %} {% if ov.description %} {{ ov.description }} diff --git a/docs/website/scripts/api-docs/types.ts b/docs/website/scripts/api-docs/types.ts index f103b53194..9f5d9a610f 100644 --- a/docs/website/scripts/api-docs/types.ts +++ b/docs/website/scripts/api-docs/types.ts @@ -69,6 +69,13 @@ export interface ApiFunction { throws?: Array<{ error: string; description: string }>; examples?: string[]; deprecated?: string; + /** + * Prototype marker (`@prototype ` in TSDoc). Mirrors `deprecated` + * in shape and rendering: when set, the single-page renderer emits a + * "Prototype only" blockquote above the description, warning consumers + * that the function is not production grade. + */ + prototype?: string; /** * When the function declares multiple overloads, this is a per-overload * breakdown produced by the extractor (one entry per unique signature). @@ -84,6 +91,8 @@ export interface ApiOverload { throws?: Array<{ error: string; description: string }>; examples?: string[]; deprecated?: string; + /** See `ApiFunction.prototype`. Scoped to a single overload. */ + prototype?: string; /** Optional human-friendly label, e.g. "Single text" or "Run / start". */ label?: string; } diff --git a/docs/website/tests/__snapshots__/api-docs-rendering.test.ts.snap b/docs/website/tests/__snapshots__/api-docs-rendering.test.ts.snap index b46529b80d..c15d43eb2b 100644 --- a/docs/website/tests/__snapshots__/api-docs-rendering.test.ts.snap +++ b/docs/website/tests/__snapshots__/api-docs-rendering.test.ts.snap @@ -11,7 +11,7 @@ description: One-page reference of all public functions and objects exported by > For per-parameter and per-field details, hover symbols in your IDE or open > \`node_modules/@qvac/sdk/dist\`. This page is intentionally a high-level index. > -> **Fields shown**: description, signature, throws, examples, deprecation. +> **Fields shown**: description, signature, throws, examples, deprecation, prototype. > **Fields intentionally omitted**: parameter descriptions, return field descriptions > (covered by IDE hover and \`.d.ts\` declarations). > diff --git a/docs/website/tests/api-docs-rendering.test.ts b/docs/website/tests/api-docs-rendering.test.ts index 5aa0253bf8..054d0d9166 100644 --- a/docs/website/tests/api-docs-rendering.test.ts +++ b/docs/website/tests/api-docs-rendering.test.ts @@ -277,4 +277,22 @@ describe('single-page template', () => { expect(mdx).toContain('### `oldThing`') expect(mdx).toContain('> ⚠️ **Deprecated**: Use newThing() instead.') }) + + it('renders a prototype callout for prototype-only functions', () => { + const prototypeFn: ApiFunction = { + ...minimalFn, + name: 'earlyThing', + prototype: 'Not production grade; use foo() instead in production.', + } + const mdx = env + .render('single-page.njk', { + ...renderArgs, + functions: [prototypeFn], + }) + .trim() + expect(mdx).toContain('### `earlyThing`') + expect(mdx).toContain( + '> πŸ§ͺ **Prototype only**: Not production grade; use foo() instead in production.', + ) + }) }) diff --git a/packages/sdk/src/client/api/rag.ts b/packages/sdk/src/client/api/rag.ts index 81ba461298..a7248b7318 100644 --- a/packages/sdk/src/client/api/rag.ts +++ b/packages/sdk/src/client/api/rag.ts @@ -86,6 +86,8 @@ export async function ragChunk(params: RagChunkParams, options?: RPCOptions): Pr // ============== Ingest ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Ingests documents into the RAG vector database. * Full pipeline: chunk β†’ embed β†’ save * @@ -191,6 +193,8 @@ async function runRagIngest( // ============== SaveEmbeddings ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Saves pre-embedded documents to the RAG vector database. * Part of the segregated flow: chunk() β†’ embed() β†’ saveEmbeddings() * @@ -284,6 +288,8 @@ async function runRagSaveEmbeddings( // ============== Search ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Searches for similar documents in the RAG vector database. * * **Workspace lifecycle:** This operation requires an existing workspace. If the workspace @@ -340,6 +346,8 @@ export async function ragSearch( // ============== Delete Embeddings ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Deletes document embeddings from the RAG vector database. * * **Workspace lifecycle:** This operation requires an existing workspace. @@ -385,6 +393,8 @@ export async function ragDeleteEmbeddings( // ============== Reindex ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Reindexes the RAG database to optimize search performance. * For HyperDB, this rebalances centroids using k-means clustering. * @@ -486,6 +496,8 @@ async function runRagReindex( // ============== List Workspaces ============== /** + * @prototype The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide). + * * Lists all RAG workspaces with their open status. * * Returns all workspaces that exist on disk. The `open` field indicates whether @@ -528,6 +540,8 @@ export async function ragListWorkspaces(options?: RPCOptions): Promise