dataiku-sdk 3.1.0 → 3.3.0

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>;
+}

package/dist/src/resources/llms.js

@@ -0,0 +1,62 @@
+import { ClientValidationError, } from "../errors.js";
+import { BaseResource, requireNonEmpty, } from "./base.js";
+export class LlmsResource extends BaseResource {
+    /**
+     * List the LLMs available in a project, including Retrieval-Augmented
+     * Generation ones. Requires READ_CONF.
+     */
+    async list(options = {}) {
+        const params = new URLSearchParams();
+        if (options.purpose !== undefined) {
+            params.set("purpose", requireNonEmpty(options.purpose, "purpose"));
+        }
+        const query = params.size > 0 ? `?${params.toString()}` : "";
+        return this.client.get(`/public/api/projects/${this.enc(options.projectKey)}/llms/${query}`);
+    }
+    /**
+     * Perform completions on an LLM. This call is cost-bearing: it invokes an
+     * external LLM provider and may incur charges.
+     */
+    async completions(body, projectKey) {
+        const payload = validateLlmInferenceBody(body, "completions");
+        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/llms/completions`, payload);
+    }
+    /**
+     * Perform embeddings on an LLM. This call is cost-bearing: it invokes an
+     * external LLM provider and may incur charges.
+     */
+    async embeddings(body, projectKey) {
+        const payload = validateLlmInferenceBody(body, "embeddings");
+        return this.client.post(`/public/api/projects/${this.enc(projectKey)}/llms/embeddings`, payload);
+    }
+}
+/**
+ * Validate a completions/embeddings request body on the client boundary:
+ * `llmId` must be a non-empty string and `queries` a non-empty array of
+ * objects. Unknown documented fields pass through untouched.
+ */
+function validateLlmInferenceBody(body, action) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new ClientValidationError(`llms.${action} body must be an object with llmId and queries.`);
+    }
+    const llmId = requireNonEmpty(body.llmId, "llmId");
+    if (!Array.isArray(body.queries) || body.queries.length === 0) {
+        throw new ClientValidationError(`llms.${action} queries must be a non-empty array of query objects.`, "validation_failed", 'Pass at least one query, e.g. queries: [{ messages: [...] }] for completions or [{ text: "..." }] for embeddings.');
+    }
+    for (const [index, query,] of body.queries.entries()) {
+        if (query === null || typeof query !== "object" || Array.isArray(query)) {
+            throw new ClientValidationError(`llms.${action} queries[${index}] must be an object.`);
+        }
+    }
+    const payload = {
+        llmId,
+        queries: body.queries,
+    };
+    if (body.settings !== undefined) {
+        if (body.settings === null || typeof body.settings !== "object" || Array.isArray(body.settings)) {
+            throw new ClientValidationError("llms.completions settings must be an object.");
+        }
+        payload["settings"] = body.settings;
+    }
+    return payload;
+}

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

@@ -0,0 +1,121 @@
+import type { MacroDefinition, MacroRunStart, MacroState, MacroSummary, MacroWaitResult } from "../schemas.js";
+import { BaseResource } from "./base.js";
+export interface MacroRunOptions {
+    /**
+     * Server-side wait: when true the POST call blocks until the run finishes
+     * (docs: `POST /runnables/{runnableType}?wait=true`). Default false.
+     */
+    wait?: boolean;
+    projectKey?: string;
+    /**
+     * Macro parameter values keyed by the param names declared in the macro
+     * definition (`params` array). Sent as the POST body. Values must be
+     * JSON-serializable primitives or structures matching the declared types.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Admin-only parameter values keyed by the adminParams names declared in
+     * the macro definition. Sent as the POST body's adminParams entry.
+     */
+    adminParams?: Record<string, unknown>;
+}
+export interface MacroWaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    projectKey?: string;
+    /** Macro parameter values (see {@link MacroRunOptions.params}). */
+    params?: Record<string, unknown>;
+    /** Admin-only parameter values (see {@link MacroRunOptions.adminParams}). */
+    adminParams?: Record<string, unknown>;
+}
+export interface MacroResultOptions {
+    projectKey?: string;
+    /**
+     * Cap on the number of bytes buffered from the result body. Macro results
+     * can be arbitrary documents (HTML, text, JSON); the default 8 MiB guards
+     * against oversized bodies while remaining generous for typical reports.
+     */
+    maxBytes?: number;
+}
+/**
+ * Normalize a byte cap coming from user input (CLI `--max-bytes`) into the
+ * inclusive range [1, 2 GiB], rejecting non-integers before any DSS request.
+ */
+export declare function macroResultMaxBytes(maxBytes: number | undefined): number;
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Run result of {@link MacrosResource.run} when the caller opted into
+ * `wait: false` (the default): a run id for abort/state/result tracking.
+ */
+export type MacroRunHandle = MacroRunStart;
+/**
+ * When `wait: true`, DSS blocks server-side until the run finishes and then
+ * returns the run id plus the terminal poll state (resultType, errors, …).
+ */
+export type MacroRunWaitedResult = MacroRunStart & {
+    state?: MacroState;
+};
+/**
+ * Error payload surfaced by DSS on a failed macro run, from either
+ * `resultError` or `storedError` in the poll state.
+ */
+export interface MacroRunFailure {
+    source: "resultError" | "storedError";
+    details: unknown;
+}
+declare function macroRunFailure(state: Record<string, unknown>): MacroRunFailure | undefined;
+/**
+ * DSS Macros — the plugin "runnable" surface under
+ * `/public/api/projects/{pk}/runnables`.
+ *
+ * A macro run executes arbitrary plugin code on the DSS backend with
+ * side effects that DSS cannot predict; every method here that starts or
+ * stops a run is a write. Result bodies may be plain text or HTML rather
+ * than JSON, so {@link MacrosResource.result} returns the raw body.
+ */
+export declare class MacrosResource extends BaseResource {
+    /**
+     * List the macros (runnables) available in a project. The official client
+     * lists at `/runnables/` (trailing slash): the slashless path 404s on live
+     * DSS 15, while get/run/state/result stay slashless.
+     */
+    list(projectKey?: string): Promise<MacroSummary[]>;
+    /** Get the definition of a macro: params, result type, owning plugin. */
+    definition(runnableType: string, opts?: {
+        projectKey?: string;
+    }): Promise<MacroDefinition>;
+    /**
+     * Start a macro run. Executes arbitrary plugin code: classify as
+     * destructive. With `wait: true` the server call blocks until completion
+     * and the resolved state is attached to the returned run handle.
+     */
+    run(runnableType: string, opts?: MacroRunOptions): Promise<MacroRunHandle | MacroRunWaitedResult>;
+    /** Request abort of a running macro run (204 response). */
+    abort(runnableType: string, runId: string, projectKey?: string): Promise<void>;
+    /** Get the poll state of a macro run (running flag, progress, errors). */
+    state(runnableType: string, runId: string, opts?: {
+        projectKey?: string;
+        /**
+         * TOTAL duration budget in ms for this state GET, measured from
+         * call start (bounds fetch, retries, backoff, and body read).
+         * Polling loops pass their remaining wait budget so a stalled
+         * state endpoint cannot outlive the wait deadline.
+         */
+        timeoutMs?: number;
+    }): Promise<MacroState>;
+    /**
+     * Download the result of a macro run. Macro results are documents of the
+     * macro's declared `resultType` (HTML, text, JSON, …) and are frequently
+     * NOT JSON: the raw body is returned verbatim. JSON bodies are returned
+     * as parsed values so programmatic callers can read fields directly.
+     */
+    result(runnableType: string, runId: string, opts?: MacroResultOptions): Promise<unknown>;
+    /**
+     * Run a macro and poll its state until it finishes or times out, using a
+     * bounded client-side loop on the state endpoint. Returns
+     * `{ success: false, timedOut: true }` on timeout rather than throwing.
+     */
+    runAndWait(runnableType: string, opts?: MacroWaitOptions): Promise<MacroWaitResult>;
+    private base;
+}
+export { isRecord as isMacroStateRecord, macroRunFailure, };