@askdb/studio 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/client/index.html

@@ -6,8 +6,8 @@
     <title>AskDB Studio</title>
     <link rel="icon" type="image/png" media="(prefers-color-scheme: light)" href="/assets/brand/light-icon.png" />
     <link rel="icon" type="image/png" media="(prefers-color-scheme: dark)" href="/assets/brand/dark-icon.png" />
-    <script type="module" crossorigin src="/assets/index-Bn3ZXmWq.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Bsn2S5X2.css">
+    <script type="module" crossorigin src="/assets/index-B4TrMaCm.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CCT1sMLb.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { createServer } from "node:http";
+import { createPgvectorStore } from "@askdb/rag";
 import { type Workspace } from "@askdb/enrich";
 import type { StudioWorkspaceDto } from "./shared/api.js";
 export type StudioOptions = {
@@ -7,6 +8,7 @@ export type StudioOptions = {
     port?: number;
 };
 export type StudioServer = ReturnType<typeof createServer>;
+export declare function setStudioPgvectorStoreFactoryForTests(factory: typeof createPgvectorStore | undefined): void;
 export declare function createStudioServer(options: StudioOptions): StudioServer;
 export declare function serializeWorkspace(workspace: Workspace): StudioWorkspaceDto;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AAgCpF,OAAO,EAYL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAOV,kBAAkB,EAEnB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAyC3D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAkEvE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,CAuC3E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AAsBpF,OAAO,EAOL,mBAAmB,EAOpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAaL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAOV,kBAAkB,EAEnB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAyD3D,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,OAAO,mBAAmB,GAAG,SAAS,GAC9C,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAwEvE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,CAqC3E"}

package/dist/server.js

@@ -4,16 +4,17 @@ import { extname, relative, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateText as defaultGenerateText } from "ai";
 import { getAskDbRuntimeConfig } from "@askdb/config";
-import { ask, askDbAiKeyMissingMessage, createAskDbEmbeddingModel, createAskDbLanguageModelFromEnv, loadSchema, resolveAskDbAiConfig, resolveAskDbEmbeddingConfig, suggestEnrichment, } from "@askdb/core";
-import { postgresDialect } from "@askdb/postgres";
-import { buildSchemaIndex, chunkContentHash, chunkSchema, createRetriever, loadChunkerSourcesFromDir, } from "@askdb/rag";
-import { createAiSdkEmbedder } from "@askdb/rag/embedders/ai-sdk";
-import { createFileStore } from "@askdb/rag/stores/file";
-import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveTable, } from "@askdb/enrich";
+import { ask, askDbAiKeyMissingMessage, createAskDbEmbeddingModel, createAskDbLanguageModelFromEnv, isBuiltInDialectId, loadSchema, resolveAskDbAiConfig, resolveAskDbEmbeddingConfig, suggestEnrichment, } from "@askdb/core";
+import { buildSchemaIndex, chunkContentHash, chunkSchema, createAiSdkEmbedder, createFileStore, createMemoryStore, createPgvectorStore, createRetriever, loadChunkerSourcesFromDir, } from "@askdb/rag";
+import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveConcepts, saveTable, } from "@askdb/enrich";
 const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
 const STUDIO_RAG_MOCK_DIMENSIONS = 64;
 const STUDIO_RAG_MOCK_EMBEDDER_ID = `studio:mock-lexical-${STUDIO_RAG_MOCK_DIMENSIONS}`;
 const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+let studioPgvectorStoreFactoryForTests;
+export function setStudioPgvectorStoreFactoryForTests(factory) {
+    studioPgvectorStoreFactoryForTests = factory;
+}
 export function createStudioServer(options) {
     const schemaDir = resolve(options.schema);
     if (!existsSync(schemaDir)) {
@@ -42,6 +43,12 @@ export function createStudioServer(options) {
                 saveDraft(state, tableId, draft);
                 return writeJson(res, 200, serializeWorkspace(state.workspace));
             }
+            if (req.method === "POST" && url.pathname === "/api/concepts") {
+                const body = await readJson(req);
+                const concepts = parseConceptsBody(body);
+                saveConceptsDraft(state, concepts);
+                return writeJson(res, 200, serializeWorkspace(state.workspace));
+            }
             if (req.method === "POST" && url.pathname === "/api/suggest") {
                 const body = await readJson(req);
                 const source = parseSuggestSource(body);
@@ -49,22 +56,22 @@ export function createStudioServer(options) {
                 return writeJson(res, 200, { candidates });
             }
             if (req.method === "GET" && url.pathname === "/api/rag/status") {
-                return writeJson(res, 200, getRagStatus(state.schemaDir));
+                return writeJson(res, 200, await getRagStatus(state));
             }
             if (req.method === "POST" && url.pathname === "/api/rag/index") {
-                const result = await indexRag(state.schemaDir);
+                const result = await indexRag(state);
                 return writeJson(res, 200, result);
             }
             if (req.method === "POST" && url.pathname === "/api/rag/query") {
                 const body = await readJson(req);
                 const query = parseRagQuery(body);
-                const result = await queryRag(state.schemaDir, query);
+                const result = await queryRag(state, query);
                 return writeJson(res, 200, result);
             }
             if (req.method === "POST" && url.pathname === "/api/ask") {
                 const body = await readJson(req);
                 const options = parseAskBody(body);
-                const result = await askSampleQuestion(state.schemaDir, options);
+                const result = await askSampleQuestion(state, options);
                 return writeJson(res, 200, result);
             }
             if (req.method === "GET" && !url.pathname.startsWith("/api/")) {
@@ -84,9 +91,7 @@ export function serializeWorkspace(workspace) {
     const rt = getAskDbRuntimeConfig();
     const aiConfig = (() => {
         try {
-            return resolveAskDbAiConfig(rt.ai.aiEnv, {
-                modelEnvVar: rt.ai.studioModel ? "ASKDB_STUDIO_MODEL" : undefined,
-            });
+            return resolveAskDbAiConfig(rt.ai.aiEnv);
         }
         catch {
             // A misconfigured AI env (e.g. azure without resourceName) shouldn't crash the workspace
@@ -116,6 +121,10 @@ export function serializeWorkspace(workspace) {
         concepts: workspace.concepts?.frontmatter.concepts ?? [],
     };
 }
+function saveConceptsDraft(state, concepts) {
+    saveConcepts(state.workspace, { concepts });
+    state.workspace = loadWorkspace(state.schemaDir);
+}
 function saveDraft(state, tableId, draft) {
     const table = state.workspace.tables.find((candidate) => candidate.physical.id === tableId);
     if (!table)
@@ -135,43 +144,39 @@ function saveDraft(state, tableId, draft) {
 }
 async function suggestForSource(workspace, source) {
     const rt = getAskDbRuntimeConfig();
-    const modelEnvVar = rt.ai.studioModel
-        ? "ASKDB_STUDIO_MODEL"
-        : rt.ai.tuiModel
-            ? "ASKDB_TUI_MODEL"
-            : undefined;
-    const model = await createAskDbLanguageModelFromEnv(rt.ai.aiEnv, {
-        modelEnvVar,
-    });
+    const model = await createAskDbLanguageModelFromEnv(rt.ai.aiEnv);
     if (!model) {
         throw new StudioHttpError(400, askDbAiKeyMissingMessage("AI enrichment suggestions"));
     }
     const candidates = await suggestEnrichment(buildSuggestionTarget(workspace, source), buildSuggestionContext(workspace, source.tableId), model);
     return candidates.map((candidate) => ({ text: candidate.text }));
 }
-async function askSampleQuestion(schemaDir, options) {
+async function askSampleQuestion(state, options) {
     const rt = getAskDbRuntimeConfig();
     const mockSql = rt.dev.mockSql;
     const aiConfig = mockSql ? undefined : resolveAskDbAiConfig(rt.ai.aiEnv);
     if (!mockSql && !aiConfig) {
         throw new StudioHttpError(400, `${askDbAiKeyMissingMessage("Sample NL-to-SQL generation")} Set ASKDB_MOCK_SQL to bypass the live model.`);
     }
-    const schema = loadSchema(schemaDir);
+    const schema = loadSchema(state.schemaDir);
     const retrievedChunks = [];
     const usage = createRequestUsageCollector();
     const ragIndex = options.useRag
-        ? await createCurrentStudioRagIndex(schemaDir, "using RAG for sample generation", usage)
+        ? await createCurrentStudioRagIndex(state, "using RAG for sample generation", usage)
         : undefined;
     const model = mockSql
         ? undefined
-        : (await createAskDbLanguageModelFromEnv(rt.ai.aiEnv, {
-            modelEnvVar: rt.ai.studioModel ? "ASKDB_STUDIO_MODEL" : undefined,
-        }));
+        : (await createAskDbLanguageModelFromEnv(rt.ai.aiEnv));
+    const schemaProvider = "provider" in schema && typeof schema.provider === "string"
+        ? schema.provider
+        : undefined;
+    const dialect = rt.nlToSql.dialect ??
+        (schemaProvider && isBuiltInDialectId(schemaProvider) ? schemaProvider : "postgres");
     const result = await ask({
         question: options.question,
         schema,
         model,
-        dialect: postgresDialect,
+        dialect,
         explain: true,
         ...(ragIndex
             ? {
@@ -181,7 +186,7 @@ async function askSampleQuestion(schemaDir, options) {
                         results = await ragIndex.retriever(params);
                     }
                     catch (error) {
-                        throw formatStudioRagEmbeddingError(error, ragIndex.config);
+                        throw formatStudioRagOperationError(error, ragIndex.config);
                     }
                     retrievedChunks.splice(0, retrievedChunks.length, ...results);
                     return results;
@@ -198,6 +203,8 @@ async function askSampleQuestion(schemaDir, options) {
             : {
                 generateText: createTrackedGenerateText(usage),
             },
+    }).finally(async () => {
+        await ragIndex?.dispose();
     });
     return {
         sql: result.sql,
@@ -210,87 +217,104 @@ async function askSampleQuestion(schemaDir, options) {
         usage: usage.toDto(),
     };
 }
-function getRagStatus(schemaDir) {
+async function getRagStatus(state) {
     const config = resolveStudioRagEmbedderConfig();
-    const sources = loadChunkerSourcesFromDir(schemaDir);
+    const sources = loadChunkerSourcesFromDir(state.schemaDir);
     const chunkResult = chunkSchema(sources);
-    const lockPath = join(schemaDir, "schema.lock.json");
-    const embeddingsJsonPath = join(schemaDir, "schema.embeddings.json");
-    const embeddingsBinPath = join(schemaDir, "schema.embeddings.bin");
+    const lockPath = join(state.schemaDir, "schema.lock.json");
     const lock = readOptionalJson(lockPath);
-    const embeddings = readOptionalJson(embeddingsJsonPath);
     const currentHashes = Object.fromEntries(chunkResult.chunks.map((chunk) => [chunk.id, chunkContentHash(chunk.text)]));
     const lockHashes = lock?.hashes ?? {};
     const hashIds = Object.keys(currentHashes);
-    const stale = !lock ||
-        !existsSync(embeddingsJsonPath) ||
-        !existsSync(embeddingsBinPath) ||
-        lock.embedderId !== config.embedderId ||
-        embeddings?.dimensions !== config.dimensions ||
-        Object.keys(lockHashes).length !== hashIds.length ||
-        hashIds.some((id) => lockHashes[id] !== currentHashes[id]);
-    return {
-        schemaId: sources.schema.schemaId,
-        embedder: {
-            kind: config.kind,
-            label: config.label,
-            configured: config.configured,
-            expectedId: config.embedderId,
-            indexedId: lock?.embedderId ?? null,
-            provider: config.kind === "ai-sdk" ? config.provider : null,
-            model: config.kind === "ai-sdk" ? config.model : null,
-            baseUrl: config.kind === "ai-sdk" ? config.baseUrl ?? null : null,
-        },
-        embedderId: lock?.embedderId ?? config.embedderId,
-        expectedEmbedderId: config.embedderId,
-        hasIndex: Boolean(lock && existsSync(embeddingsJsonPath) && existsSync(embeddingsBinPath)),
-        stale,
-        updatedAt: lock?.updatedAt ?? null,
-        chunksTotal: chunkResult.chunks.length,
-        chunksIndexed: Array.isArray(embeddings?.records) ? embeddings.records.length : 0,
-        dimensions: typeof embeddings?.dimensions === "number" ? embeddings.dimensions : config.dimensions,
-        expectedDimensions: config.dimensions,
-        sensitiveExcluded: chunkResult.stats.sensitiveExcluded,
-        sensitiveIncluded: chunkResult.stats.sensitiveIncluded,
-        files: {
-            lock: existsSync(lockPath),
-            embeddingsJson: existsSync(embeddingsJsonPath),
-            embeddingsBin: existsSync(embeddingsBinPath),
-        },
-    };
+    const store = await openStudioRagStore(state, config.dimensions);
+    try {
+        const chunksIndexed = await countStudioRagStoreChunks(store, sources.schema.schemaId);
+        const stale = !lock ||
+            lock.embedderId !== config.embedderId ||
+            Object.keys(lockHashes).length !== hashIds.length ||
+            hashIds.some((id) => lockHashes[id] !== currentHashes[id]) ||
+            chunksIndexed !== hashIds.length;
+        const fileArtifacts = store.kind === "file" && store.basePath
+            ? {
+                lock: existsSync(lockPath),
+                embeddingsJson: existsSync(`${store.basePath}.embeddings.json`),
+                embeddingsBin: existsSync(`${store.basePath}.embeddings.bin`),
+            }
+            : {
+                lock: existsSync(lockPath),
+                embeddingsJson: false,
+                embeddingsBin: false,
+            };
+        return {
+            schemaId: sources.schema.schemaId,
+            store: {
+                kind: store.kind,
+                basePath: store.basePath ?? null,
+                table: store.table ?? null,
+                indexStrategy: store.indexStrategy ?? null,
+            },
+            embedder: {
+                kind: config.kind,
+                label: config.label,
+                configured: config.configured,
+                expectedId: config.embedderId,
+                indexedId: lock?.embedderId ?? null,
+                provider: config.kind === "ai-sdk" ? config.provider : null,
+                model: config.kind === "ai-sdk" ? config.model : null,
+                baseUrl: config.kind === "ai-sdk" ? config.baseUrl ?? null : null,
+            },
+            embedderId: lock?.embedderId ?? config.embedderId,
+            expectedEmbedderId: config.embedderId,
+            hasIndex: Boolean(lock && chunksIndexed > 0),
+            stale,
+            updatedAt: lock?.updatedAt ?? null,
+            chunksTotal: chunkResult.chunks.length,
+            chunksIndexed,
+            dimensions: config.dimensions,
+            expectedDimensions: config.dimensions,
+            sensitiveExcluded: chunkResult.stats.sensitiveExcluded,
+            sensitiveIncluded: chunkResult.stats.sensitiveIncluded,
+            files: fileArtifacts,
+        };
+    }
+    finally {
+        await store.dispose();
+    }
 }
-async function indexRag(schemaDir) {
+async function indexRag(state) {
     const config = resolveStudioRagEmbedderConfig();
     if (!config.configured) {
         throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage());
     }
     const usage = createRequestUsageCollector();
-    clearIncompatibleRagStore(schemaDir, config);
-    const sources = loadChunkerSourcesFromDir(schemaDir);
-    const store = createFileStore({ basePath: join(schemaDir, "schema") });
+    clearIncompatibleRagStore(state, config);
+    const sources = loadChunkerSourcesFromDir(state.schemaDir);
+    const store = await openStudioRagStore(state, config.dimensions);
     let result;
     try {
         result = await buildSchemaIndex({
             schema: sources,
             embedder: await createStudioRagEmbedder(config, usage),
-            store,
+            store: store.store,
             embedderId: config.embedderId,
-            lockFilePath: join(schemaDir, "schema.lock.json"),
+            lockFilePath: join(state.schemaDir, "schema.lock.json"),
         });
     }
     catch (error) {
-        throw formatStudioRagEmbeddingError(error, config);
+        throw formatStudioRagOperationError(error, config);
+    }
+    finally {
+        await store.dispose();
     }
-    store.flush();
     return {
-        status: getRagStatus(schemaDir),
+        status: await getRagStatus(state),
         stats: result.stats,
         usage: usage.toDto(),
     };
 }
-async function queryRag(schemaDir, query) {
+async function queryRag(state, query) {
     const usage = createRequestUsageCollector();
-    const ragIndex = await createCurrentStudioRagIndex(schemaDir, "querying chunks", usage);
+    const ragIndex = await createCurrentStudioRagIndex(state, "querying chunks", usage);
     let results;
     try {
         results = await ragIndex.retriever({
@@ -303,7 +327,10 @@ async function queryRag(schemaDir, query) {
         });
     }
     catch (error) {
-        throw formatStudioRagEmbeddingError(error, ragIndex.config);
+        throw formatStudioRagOperationError(error, ragIndex.config);
+    }
+    finally {
+        await ragIndex.dispose();
     }
     return {
         question: query.question,
@@ -312,12 +339,12 @@ async function queryRag(schemaDir, query) {
         usage: usage.toDto(),
     };
 }
-async function createCurrentStudioRagIndex(schemaDir, action, usage) {
+async function createCurrentStudioRagIndex(state, action, usage) {
     const config = resolveStudioRagEmbedderConfig();
     if (!config.configured) {
         throw new StudioHttpError(400, studioRagAiSdkKeyMissingMessage());
     }
-    const status = getRagStatus(schemaDir);
+    const status = (await getRagStatus(state));
     if (!status.hasIndex) {
         throw new StudioHttpError(400, `Build the RAG index before ${action}.`);
     }
@@ -327,6 +354,7 @@ async function createCurrentStudioRagIndex(schemaDir, action, usage) {
     if (!status.schemaId || typeof status.chunksTotal !== "number") {
         throw new StudioHttpError(500, "Studio RAG status is missing schema metadata.");
     }
+    const store = await openStudioRagStore(state, config.dimensions);
     return {
         config,
         status: {
@@ -335,10 +363,85 @@ async function createCurrentStudioRagIndex(schemaDir, action, usage) {
         },
         retriever: createRetriever({
             embedder: await createStudioRagEmbedder(config, usage),
-            store: createFileStore({ basePath: join(schemaDir, "schema") }),
+            store: store.store,
         }),
+        dispose: async () => {
+            await store.dispose();
+        },
     };
 }
+function resolveStudioRagStoreConfig(state) {
+    const rt = getAskDbRuntimeConfig();
+    const kind = rt.structured.rag.store;
+    if (kind === "memory")
+        return { kind };
+    if (kind === "file") {
+        const basePath = rt.structured.rag.storeConfig.file?.basePath?.trim();
+        return { kind, basePath: basePath ? resolve(basePath) : join(state.schemaDir, "schema") };
+    }
+    const connectionString = pickFlat(rt.flat, "ASKDB_PGVECTOR_URL");
+    return {
+        kind,
+        connectionString,
+        table: rt.structured.rag.storeConfig.pgvector?.table?.trim() || undefined,
+        indexStrategy: pickFlat(rt.flat, "ASKDB_PGVECTOR_INDEX_STRATEGY"),
+    };
+}
+async function openStudioRagStore(state, dimensions) {
+    const config = resolveStudioRagStoreConfig(state);
+    if (config.kind === "memory") {
+        state.ragMemoryStore ??= createMemoryStore();
+        return {
+            kind: "memory",
+            store: state.ragMemoryStore,
+            dispose: async () => { },
+        };
+    }
+    if (config.kind === "file") {
+        const store = createFileStore({ basePath: config.basePath });
+        return {
+            kind: "file",
+            store,
+            basePath: config.basePath,
+            dispose: async () => {
+                store.flush();
+            },
+        };
+    }
+    if (!config.connectionString) {
+        throw new StudioHttpError(400, 'Studio pgvector RAG requires `ASKDB_PGVECTOR_URL` via `askdb.config.ts`.');
+    }
+    const pgvectorFactory = studioPgvectorStoreFactoryForTests ?? createPgvectorStore;
+    const store = pgvectorFactory({
+        connectionString: config.connectionString,
+        table: config.table,
+        dimensions,
+        ...(config.indexStrategy ? { indexStrategy: config.indexStrategy } : {}),
+    });
+    await store.ensureSchema();
+    return {
+        kind: "pgvector",
+        store,
+        table: config.table,
+        indexStrategy: config.indexStrategy,
+        dispose: async () => {
+            await store.close();
+        },
+    };
+}
+async function countStudioRagStoreChunks(store, schemaId) {
+    if (typeof store.store.count === "function") {
+        return store.store.count({ schemaId });
+    }
+    if (typeof store.store.size === "function") {
+        return store.store.size();
+    }
+    return 0;
+}
+function pickFlat(flat, key) {
+    const value = flat[key];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
 function pickEnv(env, key) {
     const v = env[key];
     return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
@@ -346,7 +449,7 @@ function pickEnv(env, key) {
 function resolveStudioRagEmbedderConfig() {
     const rt = getAskDbRuntimeConfig();
     const base = rt.ai.aiEnv;
-    const explicitKind = pickEnv(base, "ASKDB_RAG_EMBEDDER") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER");
+    const explicitKind = pickEnv(base, "ASKDB_RAG_EMBEDDER");
     const kind = explicitKind?.toLowerCase();
     if (kind === "mock") {
         return {
@@ -362,7 +465,7 @@ function resolveStudioRagEmbedderConfig() {
     }
     const env = buildStudioRagEmbeddingEnv(kind, base);
     const aiConfig = resolveAskDbEmbeddingConfig(env, {
-        modelEnvVar: "ASKDB_STUDIO_RAG_EMBEDDER_MODEL",
+        modelEnvVar: "ASKDB_RAG_EMBEDDER_MODEL",
         modelDefault: DEFAULT_EMBEDDING_MODEL,
     });
     if (!aiConfig && kind === undefined) {
@@ -376,8 +479,7 @@ function resolveStudioRagEmbedderConfig() {
     }
     const provider = aiConfig?.provider ?? fallbackStudioRagProvider(kind, base);
     const model = aiConfig?.model ?? DEFAULT_EMBEDDING_MODEL;
-    const dimensionOverride = readPositiveIntegerEnv(pickEnv(base, "ASKDB_RAG_EMBEDDER_DIMENSIONS") ??
-        pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_DIMENSIONS"));
+    const dimensionOverride = readPositiveIntegerEnv(pickEnv(base, "ASKDB_RAG_EMBEDDER_DIMENSIONS"));
     const dimensions = dimensionOverride ?? defaultEmbeddingDimensions(model);
     return {
         kind: "ai-sdk",
@@ -393,14 +495,12 @@ function resolveStudioRagEmbedderConfig() {
     };
 }
 function buildStudioRagEmbeddingEnv(kind, base) {
-    const apiKeyOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_API_KEY") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_API_KEY");
-    const modelOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_MODEL") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_MODEL");
-    const baseUrlOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_BASE_URL") ?? pickEnv(base, "ASKDB_STUDIO_RAG_EMBEDDER_BASE_URL");
+    const apiKeyOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_API_KEY");
+    const baseUrlOverride = pickEnv(base, "ASKDB_RAG_EMBEDDER_BASE_URL");
     return {
         ...base,
         ...(kind === "openai" ? { ASKDB_AI_PROVIDER: "openai" } : {}),
         ...(apiKeyOverride ? { ASKDB_AI_API_KEY: apiKeyOverride } : {}),
-        ...(modelOverride ? { ASKDB_STUDIO_RAG_EMBEDDER_MODEL: modelOverride } : {}),
         ...(baseUrlOverride ? { ASKDB_AI_BASE_URL: baseUrlOverride } : {}),
     };
 }
@@ -437,11 +537,16 @@ async function createStudioRagEmbedder(config, usage) {
         },
     });
 }
-function formatStudioRagEmbeddingError(error, config) {
+function formatStudioRagOperationError(error, config) {
+    if (error instanceof StudioHttpError)
+        return error;
     if (config.kind === "mock") {
         return new StudioHttpError(500, error instanceof Error ? error.message : String(error));
     }
     const apiError = findApiCallError(error);
+    if (!apiError) {
+        return new StudioHttpError(500, error instanceof Error ? error.message : String(error));
+    }
     const parts = [
         `Studio RAG embedding request failed for provider ${config.provider}, model ${config.model}.`,
     ];
@@ -484,15 +589,18 @@ function truncateForMessage(value) {
         return undefined;
     return trimmed.length > 500 ? `${trimmed.slice(0, 500)}...` : trimmed;
 }
-function clearIncompatibleRagStore(schemaDir, config) {
-    const embeddingsJsonPath = join(schemaDir, "schema.embeddings.json");
+function clearIncompatibleRagStore(state, config) {
+    const store = resolveStudioRagStoreConfig(state);
+    if (store.kind !== "file")
+        return;
+    const embeddingsJsonPath = `${store.basePath}.embeddings.json`;
     const embeddings = readOptionalJson(embeddingsJsonPath);
     if (embeddings?.dimensions === undefined || embeddings.dimensions === config.dimensions)
         return;
     for (const path of [
-        join(schemaDir, "schema.embeddings.json"),
-        join(schemaDir, "schema.embeddings.bin"),
-        join(schemaDir, "schema.lock.json"),
+        `${store.basePath}.embeddings.json`,
+        `${store.basePath}.embeddings.bin`,
+        join(state.schemaDir, "schema.lock.json"),
     ]) {
         rmSync(path, { force: true });
     }
@@ -552,6 +660,17 @@ function readOptionalJson(path) {
         return undefined;
     }
 }
+function parseConceptsBody(body) {
+    if (!isRecord(body) || !Array.isArray(body.concepts)) {
+        throw new StudioHttpError(400, "`concepts` array is required.");
+    }
+    for (const concept of body.concepts) {
+        if (!isRecord(concept) || typeof concept.id !== "string" || typeof concept.label !== "string") {
+            throw new StudioHttpError(400, "Each concept requires a string `id` and `label`.");
+        }
+    }
+    return body.concepts;
+}
 function parseTableDraftBody(body) {
     if (!isRecord(body) || !isRecord(body.draft)) {
         throw new StudioHttpError(400, "`draft` is required.");