dataiku-sdk 3.2.0 → 3.3.0

package/dist/src/resources/datasets.js

@@ -712,6 +712,104 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/metadata`);
     }
+    /**
+     * Replace dataset metadata with the given object (faithful PUT per the DSS
+     * API contract: the caller GETs the metadata, edits it, and PUTs the full
+     * object back — no partial merge is applied client-side). `label`,
+     * `description`, `tags`, and `custom` are the documented writable fields;
+     * any additional server-provided metadata fields present in the object are
+     * preserved verbatim.
+     */
+    async updateMetadata(datasetName, metadata, projectKey) {
+        if (metadata === null || Array.isArray(metadata)) {
+            throw new ClientValidationError("metadata must be a JSON object.");
+        }
+        const dsEnc = encodeURIComponent(datasetName);
+        return this.client.put(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/metadata`, metadata);
+    }
+    /**
+     * Create a managed dataset through the dedicated
+     * `POST /projects/{projectKey}/datasets/managed` endpoint. DSS handles the
+     * format/storage details: you select the name, the connection, and optional
+     * type/format/partitioning options. The endpoint answers `204` with no
+     * body; the returned settings echo what was sent.
+     */
+    async createManaged(opts, projectKey) {
+        const name = typeof opts.name === "string" ? opts.name.trim() : "";
+        if (name === "") {
+            throw new ClientValidationError("name must be a non-empty dataset name.");
+        }
+        const connection = typeof opts.connection === "string" ? opts.connection.trim() : "";
+        if (connection === "") {
+            throw new ClientValidationError("connection must be a non-empty connection name.");
+        }
+        if (opts.partitioningOptionId !== undefined && opts.copyPartitioningFrom !== undefined) {
+            throw new ClientValidationError("Pass either partitioningOptionId or copyPartitioningFrom, not both.");
+        }
+        if (opts.copyPartitioningFrom !== undefined
+            && (typeof opts.copyPartitioningFrom.ref !== "string"
+                || opts.copyPartitioningFrom.ref.trim() === "")) {
+            throw new ClientValidationError("copyPartitioningFrom.ref must be a non-empty dataset or folder name.");
+        }
+        const pk = this.resolveProjectKey(projectKey);
+        const creationSettings = { connectionId: connection, };
+        if (opts.typeOptionId !== undefined)
+            creationSettings.typeOptionId = opts.typeOptionId;
+        if (opts.formatOptionId !== undefined || opts.partitioningOptionId !== undefined
+            || opts.copyPartitioningFrom !== undefined) {
+            const specificSettings = {};
+            if (opts.formatOptionId !== undefined) {
+                specificSettings.formatOptionId = opts.formatOptionId;
+            }
+            if (opts.partitioningOptionId !== undefined) {
+                specificSettings.partitioningOptionId = opts.partitioningOptionId;
+            }
+            else if (opts.copyPartitioningFrom !== undefined) {
+                const code = opts.copyPartitioningFrom.type === "FOLDER" ? "folder" : "dataset";
+                specificSettings.partitioningOptionId = `copy:${code}:${opts.copyPartitioningFrom.ref.trim()}`;
+            }
+            creationSettings.specificSettings = specificSettings;
+        }
+        await this.client.post(`/public/api/projects/${encodeURIComponent(pk)}/datasets/managed`, { name, creationSettings, });
+        return { datasetName: name, projectKey: pk, creationSettings, };
+    }
+    /**
+     * Get the full info object for a dataset (type, parameters, last build
+     * information, schema, etc.). The server returns a complex opaque object;
+     * it is surfaced without validation.
+     */
+    async info(datasetName, projectKey) {
+        const dsEnc = encodeURIComponent(datasetName);
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/info`);
+    }
+    /**
+     * Get the full column lineage (auto-computed and manual) of a column in
+     * this dataset. Relations with datasets from both local and foreign
+     * projects are included.
+     *
+     * Route per the official Python client:
+     * `GET /projects/{projectKey}/datasets/{datasetName}/column-lineage`
+     * with query `columnName` (required) and `maxDatasetCount` (optional,
+     * positive integer — the docs page renders a merged project-scoped path,
+     * but DSS's own client and route registry use this per-dataset form).
+     */
+    async getColumnLineage(datasetName, column, opts = {}) {
+        const trimmed = typeof column === "string" ? column.trim() : "";
+        if (trimmed === "") {
+            throw new ClientValidationError("column must be a non-empty column name.");
+        }
+        const maxDatasetCount = opts.maxDatasetCount;
+        if (maxDatasetCount !== undefined
+            && (!Number.isSafeInteger(maxDatasetCount) || maxDatasetCount <= 0)) {
+            throw new ClientValidationError("maxDatasetCount must be a positive integer.");
+        }
+        const dsEnc = encodeURIComponent(datasetName);
+        const params = [`columnName=${encodeURIComponent(trimmed)}`,];
+        if (maxDatasetCount !== undefined) {
+            params.push(`maxDatasetCount=${encodeURIComponent(String(maxDatasetCount))}`);
+        }
+        return this.client.get(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/column-lineage?${params.join("&")}`);
+    }
     /**
      * Download dataset rows as a gzipped (or .csv) file, capped at `limit` rows
      * (default 100k). Returns the written path, the number of data rows written,
@@ -746,7 +844,7 @@ export class DatasetsResource extends BaseResource {
             : undefined;
         const shouldGzip = filePath.endsWith(".gz");
         const stats = { rows: 0, truncated: false, };
-        const nodeStream = Readable.fromWeb(res.body);
+        const nodeStream = Readable.from(res.body, { objectMode: false, });
         const csvTransform = tsvToCsvTransform(limit, stats, onHeader, opts?.rawData !== true);
         fs.mkdirSync(nodePath.dirname(filePath), { recursive: true, });
         const fileOut = fs.createWriteStream(filePath);

package/dist/src/resources/futures.d.ts

@@ -5,10 +5,13 @@ export interface FutureWaitOptions {
     timeoutMs?: number;
 }
 export declare class FuturesResource extends BaseResource {
-    get(futureId: string): Promise<FutureState>;
+    get(futureId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<FutureState>;
     peek(futureId: string): Promise<FutureState>;
     state(futureId: string, opts?: {
         peek?: boolean;
+        timeoutMs?: number;
     }): Promise<FutureState>;
     abort(futureId: string): Promise<void>;
     wait(futureId: string, opts?: FutureWaitOptions): Promise<FutureWaitResult>;

package/dist/src/resources/futures.js

@@ -1,4 +1,5 @@
 import { FutureStateSchema, FutureWaitResultSchema, } from "../schemas.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
 import { BaseResource, } from "./base.js";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -23,8 +24,8 @@ function waitState(state) {
     return "RUNNING";
 }
 export class FuturesResource extends BaseResource {
-    async get(futureId) {
-        return this.state(futureId, { peek: false, });
+    async get(futureId, opts = {}) {
+        return this.state(futureId, { peek: false, timeoutMs: opts.timeoutMs, });
     }
     async peek(futureId) {
         return this.state(futureId, { peek: true, });
@@ -32,14 +33,18 @@ export class FuturesResource extends BaseResource {
     async state(futureId, opts = {}) {
         const params = new URLSearchParams();
         params.set("peek", String(opts.peek === true));
-        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`);
+        const raw = await this.client.get(`/public/api/futures/${encodeURIComponent(futureId)}?${params.toString()}`, { timeoutMs: opts.timeoutMs, });
         return this.client.safeParse(FutureStateSchema, raw, "futures.state");
     }
     async abort(futureId) {
         await this.client.del(`/public/api/futures/${encodeURIComponent(futureId)}`);
     }
     async wait(futureId, opts = {}) {
-        const baseIntervalMs = Math.max(1, opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        // Adaptive backoff is the default; an explicit pollIntervalMs is an
+        // exact contract the caller chose, so it is never adapted.
+        const explicitIntervalMs = opts.pollIntervalMs;
+        const baseIntervalMs = Math.max(1, explicitIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        const adaptiveEnabled = explicitIntervalMs === undefined;
         // A caller's budget is never rounded up to a whole poll interval: a 5ms
         // wait must answer in about 5ms. One state observation always happens
         // regardless, because the poll precedes the deadline check.
@@ -48,7 +53,29 @@ export class FuturesResource extends BaseResource {
         let pollCount = 0;
         while (true) {
             pollCount += 1;
-            const state = await this.get(futureId);
+            // One state observation always happens, even when the budget is
+            // already spent (the poll precedes the deadline check); only the
+            // requests issued while budget remains are bounded by the remaining
+            // time, so a stalled status endpoint can never defeat the deadline.
+            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            let state;
+            try {
+                state = await this.get(futureId, remainingMs > 0 ? { timeoutMs: remainingMs, } : undefined);
+            }
+            catch (error) {
+                // The poll budget ran out mid-request: report the structured
+                // timeout instead of letting the transport deadline error escape.
+                if (!isRequestDeadlineError(error, startedAt + timeoutMs))
+                    throw error;
+                return this.client.safeParse(FutureWaitResultSchema, {
+                    futureId,
+                    state: "RUNNING",
+                    elapsedMs: Date.now() - startedAt,
+                    pollCount,
+                    success: false,
+                    timedOut: true,
+                }, "futures.wait");
+            }
             const elapsedMs = Date.now() - startedAt;
             const status = waitState(state);
             if (isFinished(state)) {
@@ -85,7 +112,12 @@ export class FuturesResource extends BaseResource {
             }
             // Only the remaining budget is slept: a longer sleep would report an
             // elapsed time the caller never authorized.
-            await sleep(Math.min(baseIntervalMs, timeoutMs - elapsedMs));
+            const nextDelayMs = computeNextPollDelayMs({
+                pollCount,
+                baseIntervalMs,
+                adaptiveEnabled,
+            });
+            await sleep(Math.min(nextDelayMs, timeoutMs - elapsedMs));
         }
     }
 }

package/dist/src/resources/groups.d.ts

@@ -0,0 +1,47 @@
+import { BaseResource } from "./base.js";
+/**
+ * A DSS group as returned by the admin Security endpoints. The documented
+ * attributes below are stable; DSS may return undocumented extra attributes
+ * (per the API docs they must not be modified on update), so they are preserved
+ * under `Record<string, unknown>` and are never stripped by this SDK.
+ */
+export interface DssGroup extends Record<string, unknown> {
+    name?: string;
+    description?: string;
+    /** Whether this group gives administrative rights on DSS. */
+    admin?: boolean;
+    sourceType?: string;
+}
+/**
+ * Body of `POST /admin/groups` (create) and the editable subset of the PUT
+ * body. DSS requires `name` on create; `admin` and `description` are optional.
+ */
+export interface GroupCreateRequest extends Record<string, unknown> {
+    name: string;
+    description?: string;
+    admin?: boolean;
+}
+export declare class GroupsResource extends BaseResource {
+    /** Retrieves the list of DSS groups (Admin required). */
+    list(): Promise<DssGroup[]>;
+    /**
+     * Retrieves a Group object describing a DSS user group, used for access
+     * control on connections and projects (Admin required).
+     */
+    get(groupName: string): Promise<DssGroup>;
+    /**
+     * Creates a group (Admin required). DSS answers with
+     * `{msg: "Created group <name>"}`; the raw server record is returned as-is.
+     */
+    create(body: GroupCreateRequest): Promise<Record<string, unknown>>;
+    /**
+     * Updates a group (Admin required). Per the docs the body MUST have been
+     * obtained from a prior GET at the same URL; undocumented attributes should
+     * be passed through unmodified. DSS answers with `{msg: "Edited group ..."}`.
+     */
+    update(groupName: string, body: DssGroup): Promise<Record<string, unknown>>;
+    /** Deletes a DSS users group (Admin required). */
+    delete(groupName: string): Promise<{
+        deleted: string;
+    }>;
+}

package/dist/src/resources/groups.js

@@ -0,0 +1,56 @@
+import { ClientValidationError, } from "../errors.js";
+import { BaseResource, requireArrayResponse, requireNonEmpty, } from "./base.js";
+function validateGroupBody(body, method) {
+    if (body === null || body === undefined || typeof body !== "object" || Array.isArray(body)) {
+        throw new ClientValidationError(`${method}: body must be a Group object.`);
+    }
+    const record = body;
+    if (record.admin !== undefined && typeof record.admin !== "boolean") {
+        throw new ClientValidationError(`${method}: admin must be a boolean.`);
+    }
+    return record;
+}
+export class GroupsResource extends BaseResource {
+    /** Retrieves the list of DSS groups (Admin required). */
+    async list() {
+        const raw = await this.client.get("/public/api/admin/groups");
+        return requireArrayResponse(raw, "groups.list");
+    }
+    /**
+     * Retrieves a Group object describing a DSS user group, used for access
+     * control on connections and projects (Admin required).
+     */
+    async get(groupName) {
+        const enc = requireNonEmpty(groupName, "groupName").trim();
+        return this.client.get(`/public/api/admin/groups/${encodeURIComponent(enc)}`);
+    }
+    /**
+     * Creates a group (Admin required). DSS answers with
+     * `{msg: "Created group <name>"}`; the raw server record is returned as-is.
+     */
+    async create(body) {
+        if (body === null || body === undefined || typeof body !== "object" || Array.isArray(body)
+            || typeof body.name !== "string"
+            || body.name.trim().length === 0) {
+            throw new ClientValidationError("groups.create: body.name is required.");
+        }
+        validateGroupBody(body, "groups.create");
+        return this.client.post("/public/api/admin/groups", body);
+    }
+    /**
+     * Updates a group (Admin required). Per the docs the body MUST have been
+     * obtained from a prior GET at the same URL; undocumented attributes should
+     * be passed through unmodified. DSS answers with `{msg: "Edited group ..."}`.
+     */
+    async update(groupName, body) {
+        const enc = requireNonEmpty(groupName, "groupName").trim();
+        const validated = validateGroupBody(body, "groups.update");
+        return this.client.put(`/public/api/admin/groups/${encodeURIComponent(enc)}`, validated);
+    }
+    /** Deletes a DSS users group (Admin required). */
+    async delete(groupName) {
+        const enc = requireNonEmpty(groupName, "groupName").trim();
+        await this.client.del(`/public/api/admin/groups/${encodeURIComponent(enc)}`);
+        return { deleted: enc, };
+    }
+}

package/dist/src/resources/jobs.d.ts

@@ -1,6 +1,13 @@
 import type { BuildMode, JobSummary, JobWaitResult } from "../schemas.js";
 import { BaseResource } from "./base.js";
-export type JobBuildTargetType = "DATASET" | "MANAGED_FOLDER";
+/**
+ * Buildable target kinds. DATASET and MANAGED_FOLDER are user-selectable;
+ * MODEL_EVALUATION_STORE appears as a recipe output role and is a valid job
+ * target per the official client (recipe.run object_type_map maps
+ * COMPUTABLE_MODEL_EVALUATION_STORE to MODEL_EVALUATION_STORE before
+ * JobDefinition.with_output).
+ */
+export type JobBuildTargetType = "DATASET" | "MANAGED_FOLDER" | "MODEL_EVALUATION_STORE";
 export type JobLogFilter = "stdout" | "stderr" | "user" | "errors";
 export interface JobLogProgress {
     lastProgressLine?: string;
@@ -46,17 +53,6 @@ export interface JobBuildAndWaitOptions extends JobBuildOptions {
     logId?: string;
     summary?: boolean;
 }
-interface ComputeNextPollDelayMsOptions {
-    pollCount: number;
-    baseIntervalMs: number;
-    adaptiveEnabled: boolean;
-}
-/**
- * Compute the next poll delay.
- * When adaptive polling is enabled, the interval doubles every 3 polls,
- * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
- */
-export declare function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }: ComputeNextPollDelayMsOptions): number;
 export declare function parseJobLogProgress(log: string, elapsedMs?: number): JobLogProgress | undefined;
 export declare class JobsResource extends BaseResource {
     /** List jobs in a project. */
@@ -146,4 +142,3 @@ export declare class JobsResource extends BaseResource {
     /** Request a job abort. */
     abort(jobId: string, projectKey?: string): Promise<void>;
 }
-export {};

package/dist/src/resources/jobs.js

@@ -1,8 +1,8 @@
 import { DataikuError, } from "../errors.js";
 import { JobSummaryArraySchema, } from "../schemas.js";
+import { computeNextPollDelayMs, isRequestDeadlineError, } from "../utils/polling.js";
 import { BaseResource, } from "./base.js";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const MAX_POLL_INTERVAL_MS = 10_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_LOG_LINES = 500;
 /**
@@ -26,19 +26,6 @@ function isTerminalState(state) {
 function isSuccessfulTerminalState(state) {
     return (state ?? "").toUpperCase() === "DONE";
 }
-/**
- * Compute the next poll delay.
- * When adaptive polling is enabled, the interval doubles every 3 polls,
- * capped at MAX_POLL_INTERVAL_MS (or baseIntervalMs if it's larger).
- */
-export function computeNextPollDelayMs({ pollCount, baseIntervalMs, adaptiveEnabled, }) {
-    if (!adaptiveEnabled) {
-        return baseIntervalMs;
-    }
-    const step = Math.max(0, Math.floor((pollCount - 1) / 3));
-    const interval = baseIntervalMs * 2 ** step;
-    return Math.min(interval, Math.max(baseIntervalMs, MAX_POLL_INTERVAL_MS));
-}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -48,7 +35,10 @@ function jobBuildOutput(target, defaultProjectKey, defaultPartition, defaultTarg
     const projectKey = target.projectKey ?? defaultProjectKey;
     const partition = target.partition ?? defaultPartition;
     const output = { projectKey, id: target.id, type: targetType, };
-    if (targetType === "DATASET") {
+    if (targetType === "DATASET" || targetType === "MODEL_EVALUATION_STORE") {
+        // MES targets follow the plain {projectKey, id, type} shape (official
+        // JobDefinition.with_output sends the name/id plus object type, with no
+        // managed-folder indirection).
         if (partition !== undefined)
             output.partition = partition;
     }
@@ -294,12 +284,47 @@ export class JobsResource extends BaseResource {
         const jobEnc = encodeURIComponent(jobId);
         const baseIntervalMs = Math.max(1, opts?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
         const adaptivePolling = opts?.pollIntervalMs === undefined;
+        // Pre-existing contract: the effective budget is never below one poll
+        // interval, so a single observation always fits inside it.
         const timeout = Math.max(baseIntervalMs, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
         const startedAt = Date.now();
         let pollCount = 0;
         while (true) {
             pollCount += 1;
-            const j = await this.client.get(`/public/api/projects/${projectEnc}/jobs/${jobEnc}/`);
+            // One status observation always happens, even when the budget is
+            // already spent (the poll precedes the deadline check); only the
+            // requests issued while budget remains are bounded by the remaining
+            // time, so a stalled status endpoint can never defeat the deadline.
+            const elapsedBefore = Date.now() - startedAt;
+            const remainingMs = timeout - elapsedBefore;
+            let j;
+            try {
+                j = await this.client.get(`/public/api/projects/${projectEnc}/jobs/${jobEnc}/`, remainingMs > 0
+                    ? { timeoutMs: remainingMs, }
+                    : undefined);
+            }
+            catch (error) {
+                // The poll budget ran out mid-request: report the documented
+                // structured timeout instead of letting the transport deadline
+                // error escape the loop.
+                if (!isRequestDeadlineError(error, startedAt + timeout))
+                    throw error;
+                return {
+                    success: false,
+                    jobId,
+                    state: "unknown",
+                    type: "unknown",
+                    elapsedMs: Date.now() - startedAt,
+                    pollCount,
+                    timedOut: true,
+                    progress: {
+                        done: 0,
+                        failed: 0,
+                        running: 0,
+                        total: null,
+                    },
+                };
+            }
             const bs = j.baseStatus ?? {};
             const def = bs.def ?? {};
             const gs = j.globalState ?? {};

package/dist/src/resources/knowledge-banks.d.ts

@@ -0,0 +1,58 @@
+import { BaseResource } from "./base.js";
+/** Search algorithm for knowledge-bank search, per the DSS 15 REST schema. */
+export type KnowledgeBankSearchType = "SIMILARITY" | "SIMILARITY_THRESHOLD" | "MMR" | "HYBRID" | (string & {});
+/**
+ * Optional search parameters, documented in the DSS 15 REST reference for
+ * `POST /projects/{projectKey}/knowledge-banks/{knowledgeBankId}/search`.
+ * Which knobs apply depends on the backing vector store.
+ */
+export interface KnowledgeBankSearchParams {
+    /** Maximum number of documents to return (default 10). */
+    maxDocuments?: number;
+    /** Search algorithm. Defaults to SIMILARITY. */
+    searchType?: KnowledgeBankSearchType;
+    /** Similarity threshold; only applied for SIMILARITY_THRESHOLD. */
+    similarityThreshold?: number;
+    /** Documents considered before selection; only applied for MMR. */
+    mmrK?: number;
+    /** 0..1 balance of diversity (0) vs relevancy (1); only applied for MMR. */
+    mmrDiversity?: number;
+    /** Proprietary rerankers; only valid for Azure AI and ElasticSearch stores. */
+    useAdvancedReranking?: boolean;
+    /** Weight of lower-ranked documents; only valid for ElasticSearch stores. */
+    rrfRankConstant?: number;
+    /** Documents considered per search type; only valid for ElasticSearch stores. */
+    rrfRankWindowSize?: number;
+    [key: string]: unknown;
+}
+/** Request body for knowledge-bank search. */
+export interface KnowledgeBankSearchBody {
+    query: string;
+    params?: KnowledgeBankSearchParams;
+}
+/** One retrieved knowledge-bank document. Metadata is server-defined. */
+export interface KnowledgeBankDocument extends Record<string, unknown> {
+    /** Document text content. */
+    text?: string;
+    /** Arbitrary server-defined metadata map. */
+    metadata?: Record<string, unknown>;
+    /** Relevance score in [0, 1] as returned by the backend. */
+    score?: number;
+}
+/** Response envelope of the knowledge-bank search endpoint. */
+export interface KnowledgeBankSearchResult extends Record<string, unknown> {
+    documents?: KnowledgeBankDocument[];
+}
+export declare class KnowledgeBanksResource extends BaseResource {
+    /**
+     * Search a knowledge bank for documents matching a query string.
+     * Requires READ_CONF.
+     */
+    search(knowledgeBankId: string, body: KnowledgeBankSearchBody, projectKey?: string): Promise<KnowledgeBankSearchResult>;
+    /**
+     * Clear all data from a knowledge bank. DESTRUCTIVE: the stored knowledge
+     * bank content is removed and cannot be recovered from this call. Requires
+     * WRITE_CONF.
+     */
+    clear(knowledgeBankId: string, projectKey?: string): Promise<void>;
+}

package/dist/src/resources/knowledge-banks.js

@@ -0,0 +1,61 @@
+import { ClientValidationError, } from "../errors.js";
+import { BaseResource, requireNonEmpty, } from "./base.js";
+export class KnowledgeBanksResource extends BaseResource {
+    /**
+     * Search a knowledge bank for documents matching a query string.
+     * Requires READ_CONF.
+     */
+    async search(knowledgeBankId, body, projectKey) {
+        const id = encodeURIComponent(requireNonEmpty(knowledgeBankId, "knowledgeBankId"));
+        const payload = validateKnowledgeBankSearchBody(body);
+        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/knowledge-banks/${id}/search`, payload);
+    }
+    /**
+     * Clear all data from a knowledge bank. DESTRUCTIVE: the stored knowledge
+     * bank content is removed and cannot be recovered from this call. Requires
+     * WRITE_CONF.
+     */
+    async clear(knowledgeBankId, projectKey) {
+        const id = encodeURIComponent(requireNonEmpty(knowledgeBankId, "knowledgeBankId"));
+        await this.client.post(`/public/api/projects/${this.enc(projectKey)}/knowledge-banks/${id}/clear`, {});
+    }
+}
+/**
+ * Validate a knowledge-bank search body on the client boundary: `query` must
+ * be a non-empty string and `params`, when present, an object. Documented
+ * params are checked for type; unknown fields pass through untouched.
+ */
+function validateKnowledgeBankSearchBody(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new ClientValidationError("knowledgeBanks.search body must be an object with a query string.");
+    }
+    const query = requireNonEmpty(body.query, "query");
+    const payload = { query, };
+    const params = body.params;
+    if (params !== undefined) {
+        if (params === null || typeof params !== "object" || Array.isArray(params)) {
+            throw new ClientValidationError("knowledgeBanks.search params must be an object.");
+        }
+        const searchParams = { ...params, };
+        validateSearchParamNumber(searchParams, "maxDocuments");
+        validateSearchParamNumber(searchParams, "similarityThreshold");
+        validateSearchParamNumber(searchParams, "mmrK");
+        validateSearchParamNumber(searchParams, "mmrDiversity");
+        validateSearchParamNumber(searchParams, "rrfRankConstant");
+        validateSearchParamNumber(searchParams, "rrfRankWindowSize");
+        const reranking = searchParams["useAdvancedReranking"];
+        if (reranking !== undefined && typeof reranking !== "boolean") {
+            throw new ClientValidationError("knowledgeBanks.search params.useAdvancedReranking must be a boolean.");
+        }
+        payload["params"] = searchParams;
+    }
+    return payload;
+}
+function validateSearchParamNumber(params, name) {
+    const value = params[name];
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new ClientValidationError(`knowledgeBanks.search params.${name} must be a finite number.`);
+    }
+}

package/dist/src/resources/llms.d.ts

@@ -0,0 +1,92 @@
+import { BaseResource } from "./base.js";
+/**
+ * Usage purpose of an LLM as documented in the DSS 15 REST reference
+ * (`GET /projects/{projectKey}/llms/{?purpose}`). The list is open: DSS
+ * versions may add purposes, so unknown server-provided values stay usable.
+ */
+export type LlmPurpose = "GENERIC_COMPLETION" | "TEXT_EMBEDDING_EXTRACTION" | "IMAGE_GENERATION" | (string & {});
+/** One entry of the LLM list endpoint. The rest of the object is server-defined. */
+export interface LlmDescriptor extends Record<string, unknown> {
+    /** Fully-qualified LLM id, e.g. `openai:openai1:gpt-4`. Contains colons. */
+    id?: string;
+    /** Backend type, e.g. `OPENAI`, `BEDROCK`, `HUGGINGFACE_TRANSFORMER_LOCAL`. */
+    type?: string;
+    /** DSS connection backing the LLM, e.g. `openai1`. */
+    connection?: string;
+    /** Model name as configured on the connection. */
+    model?: string;
+    /** True when the LLM supports prompt-based interactions. */
+    promptDriven?: boolean;
+}
+/** Per-query settings block documented for the completions endpoint. */
+export interface LlmCompletionSettings {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    [key: string]: unknown;
+}
+/**
+ * One completions query. The documented shape is a chat `messages` array; the
+ * full documented request field set (roles, contents) is server-defined, so
+ * the object is left open rather than fake-strictly modeled.
+ */
+export interface LlmCompletionQuery extends Record<string, unknown> {
+    messages?: Array<Record<string, unknown>>;
+}
+/** One embeddings query. `text` is the documented input field. */
+export interface LlmEmbeddingQuery extends Record<string, unknown> {
+    text?: string;
+}
+/** One completion result. Fields are the documented stable set plus extras. */
+export interface LlmCompletionResponse extends Record<string, unknown> {
+    ok?: boolean;
+    text?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    /** Cost estimate in cost units, per DSS LLM Mesh accounting. */
+    estimatedCost?: number;
+}
+/** One embedding result. Fields are the documented stable set plus extras. */
+export interface LlmEmbeddingResponse extends Record<string, unknown> {
+    ok?: boolean;
+    /** Embedding vector as returned by the backend. */
+    embedding?: number[];
+    promptTokens?: number;
+    estimatedCost?: number;
+}
+/** Response envelope of the completions endpoint. */
+export interface LlmCompletionsResult extends Record<string, unknown> {
+    responses?: LlmCompletionResponse[];
+}
+/** Response envelope of the embeddings endpoint. */
+export interface LlmEmbeddingsResult extends Record<string, unknown> {
+    responses?: LlmEmbeddingResponse[];
+}
+export declare class LlmsResource extends BaseResource {
+    /**
+     * List the LLMs available in a project, including Retrieval-Augmented
+     * Generation ones. Requires READ_CONF.
+     */
+    list(options?: {
+        purpose?: LlmPurpose;
+        projectKey?: string;
+    }): Promise<LlmDescriptor[]>;
+    /**
+     * Perform completions on an LLM. This call is cost-bearing: it invokes an
+     * external LLM provider and may incur charges.
+     */
+    completions(body: {
+        llmId: string;
+        queries: LlmCompletionQuery[];
+        settings?: LlmCompletionSettings;
+    }, projectKey?: string): Promise<LlmCompletionsResult>;
+    /**
+     * Perform embeddings on an LLM. This call is cost-bearing: it invokes an
+     * external LLM provider and may incur charges.
+     */
+    embeddings(body: {
+        llmId: string;
+        queries: LlmEmbeddingQuery[];
+    }, projectKey?: string): Promise<LlmEmbeddingsResult>;
+}