@pipelex/sdk 0.17.0 → 0.18.0

package/dist/index.js

@@ -7,7 +7,7 @@
  * errors. Consumers should import everything they need from `@pipelex/sdk`.
  */
 /** Package version. Kept in sync with `package.json` — enforced by `tests/index.test.ts`. */
-export const SDK_VERSION = "0.17.0";
+export const SDK_VERSION = "0.18.0";
 // ── Pure MTHDS Protocol surface (re-exported from the `mthds/protocol` subpath) ──
 // The standard's interface, wire models, request/options surface, abstract domain
 // shapes, and the protocol-base `PipelineRequestError`. Re-exported so apps have a
@@ -19,6 +19,11 @@ export { PipelexApiClient, DEFAULT_API_BASE_URL } from "./client.js";
 export { methodSourceToContents } from "./method-source.js";
 // The blocking `execute()` result — a `DictRunResultExecute` with a resolved `.main_stuff`.
 export { PipelexExecuteResult } from "./execute-result.js";
+// ── Artifacts (the download twin of input preparation) ──────────────
+// `collectArtifacts` and `artifactFilename` are pure and standalone; the network
+// operations (`resolveArtifacts` / `fetchArtifact` / `downloadArtifacts`) are client
+// methods, and only their public types and bounds travel with the barrel.
+export { collectArtifacts, artifactFilename, PIPELEX_STORAGE_SCHEME, BULK_RESOLVE_MAX_URIS, DEFAULT_ARTIFACT_MAX_BYTES, DEFAULT_ARTIFACT_TIMEOUT_MS, DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES, DEFAULT_DOWNLOAD_CONCURRENCY, } from "./artifacts.js";
 // ── Offline codegen drift check (pure — no filesystem, no network, no key) ──
 // The CI half of the codegen trust chain: hand it a committed tree plus its
 // `codegen.lock` and it returns the structured drift verdict. Regeneration needs
@@ -26,6 +31,8 @@ export { PipelexExecuteResult } from "./execute-result.js";
 export { runCodegenCheck, isStampableArtifactPath, STAMPABLE_ARTIFACT_SUFFIXES, CodegenLockError, } from "./codegen-check.js";
 // ── Run lifecycle (hosted extension — NOT part of the protocol) ──────
 export { isTerminalRunStatus, isSuccessRunStatus } from "./runs.js";
+// ── Usage summary (pure — folds a run's usage pair into one null-aware reading) ──
+export { summarizeUsage } from "./usage.js";
 // ── Typed errors (PipelineRequestError rides the protocol re-export above) ──
-export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "./errors.js";
+export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAYrE,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA8E3D,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAiD5B,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWpE,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAYrE,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAY3D,uEAAuE;AACvE,iFAAiF;AACjF,qFAAqF;AACrF,0EAA0E;AAC1E,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAgFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAiD5B,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWpE,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/runs.d.ts

@@ -1,4 +1,4 @@
-import type { DictPipeOutput } from "./models.js";
+import type { DictPipeOutput, DictWorkingMemory } from "./models.js";
 /**
  * Run-lifecycle types + polling for the hosted polling surface (`/v1/runs/*`).
  *
@@ -131,12 +131,43 @@ export interface RunResults {
      * output to an object) and may be a valid falsy value (empty array, `0`); it is never absent.
      */
     main_stuff: unknown;
-    /** Method graph spec (`graphspec.json`); null if missing mid-write or on the bare-runner path. */
+    /**
+     * The run's working memory — every named stuff of the run (`{ root, aliases }`), the inputs it
+     * was given and the intermediates it produced as well as the main output, each stuff carried as
+     * its concept ref and its content. It reads the same on both paths: the hosted path relays the
+     * `working_memory.json` artifact verbatim, and on the blocking path the SDK lifts it off
+     * `pipe_output`. `main_stuff` is the content of one of its entries, already resolved. Null on the
+     * hosted path when the artifact was not yet written. `DictWorkingMemory` mirrors the MTHDS
+     * standard's `DictWorkingMemory` field for field. A run delivered by a runtime older than
+     * pipelex 0.60.0 carries each `concept` as the concept object instead, and a stored artifact is
+     * relayed as written, never migrated: the type stays the standard's `string`, so read `concept`
+     * as `unknown` when a run may predate that release. See `docs/run-results.md`.
+     */
+    working_memory?: DictWorkingMemory | null;
+    /**
+     * The executed graph — the same document a local run writes as `graphspec.json`: `meta.mode`
+     * `"live"`, one node per pipe with its status, its timings and its own usage. It reaches the client on both
+     * paths: the hosted path relays the `graphspec.json` artifact verbatim, and on the blocking path
+     * the SDK lifts it off `pipe_output`. Null when the runner assembled no graph (see
+     * `graph_assembly_error`) or, on the hosted path, when the artifact was not yet written. Typed
+     * `unknown` on purpose — the canonical declaration is `GraphSpec` in `@pipelex/mthds-ui`, which
+     * carries a React peer dependency this server-side SDK does not take. See `docs/run-results.md`.
+     */
     graph_spec?: unknown;
     /**
-     * Bare runner's native pipe output — the full working memory (`{ root, aliases }`),
-     * blocking-execute path only; null on the hosted path. Supplementary to `main_stuff`,
-     * which is already resolved out of it; kept for consumers that need the whole working memory.
+     * Non-null when the runner's graph assembly failed for the run — the graph's twin of
+     * `usage_assembly_error`, and the only thing that separates "the graph broke" from "this run
+     * produced no graph". Lifted off `pipe_output` on the blocking path; the hosted results body
+     * carries nothing of the kind yet, so on that path the field is absent until the platform writes
+     * and relays it.
+     */
+    graph_assembly_error?: string | null;
+    /**
+     * Bare runner's native pipe output, blocking-execute path only; absent on the hosted path, whose
+     * results body carries no such key, so it reads `undefined` there. Supplementary: `main_stuff`,
+     * `working_memory`, the graph pair and the usage pair are all lifted out of it onto their own
+     * fields, which read the same on both paths. Read `working_memory` for the run's named stuffs;
+     * `pipe_output` is the runner's output as it arrived, extension fields included.
      */
     pipe_output?: DictPipeOutput | null;
     /**

package/dist/runs.js.map

@@ -1 +1 @@
-{"version":3,"file":"runs.js","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}

package/dist/usage.d.ts

@@ -0,0 +1,87 @@
+import type { RunResults } from "./runs.js";
+/**
+ * `summarizeUsage` — one run-level reading of a run's usage pair.
+ *
+ * A completed run reports usage as `RunResults.tokens_usages` (one record per inference call)
+ * beside `RunResults.usage_assembly_error`, and the wire carries no run-level aggregate. This
+ * module folds the pair into a single summary under the rules `docs/run-usage.md` states, so
+ * every consumer reads the same totals instead of re-deriving them:
+ *
+ * - a `null` cost is unrated (the model has no rate table), a `0` cost is priced at zero;
+ * - `input` and `output` are the only additive token categories (`input_cached` is a subset of
+ *   `input`, and summing every category double-counts);
+ * - a null list means usage is unavailable, and only `usage_assembly_error` says it broke;
+ * - an empty list is a run that did no inference, which costs `0`, not `null`.
+ *
+ * Pure: no I/O, no client, and the input is never mutated.
+ */
+/**
+ * Which of the three readings of `tokens_usages` the summary describes:
+ * - `records` — a non-empty list: the totals are folded from it.
+ * - `no_inference` — `[]`: usage assembly ran and no inference happened, so the cost is `0`
+ *   and the token totals are zero.
+ * - `unavailable` — the list is null or absent: usage assembly was off, it broke (then
+ *   `assembly_error` is non-null), or on the hosted path the run was delivered before the
+ *   usage artifact existed. Nothing is known, so the cost and the token totals are `null`.
+ */
+export type UsageSummaryState = "records" | "no_inference" | "unavailable";
+/**
+ * The two additive token totals. Each is the sum of that category over the records that
+ * reported it, and `null` when no record reported it at all — which is different from a
+ * reported `0`.
+ */
+export interface UsageTokenTotals {
+    input: number | null;
+    output: number | null;
+}
+/** One pipe's share of a run's usage — the same fold as the run level, over its calls only. */
+export interface PipeUsageSummary {
+    /** The pipe that made the calls; `null` groups the calls the runtime did not attribute. */
+    pipe_code: string | null;
+    /** Sum of the priced calls' costs in USD; `null` when none of this pipe's calls was priced. */
+    total_cost_usd: number | null;
+    /** True when this pipe mixes priced and unrated calls, so `total_cost_usd` is a lower bound. */
+    cost_partial: boolean;
+    tokens: UsageTokenTotals;
+    /** Number of inference calls this pipe made. */
+    calls: number;
+}
+/** A run's usage pair folded into one null-aware reading. */
+export interface UsageSummary {
+    state: UsageSummaryState;
+    /**
+     * Sum of the priced calls' costs in USD. `0` for `no_inference`. `null` for `records` when no
+     * call was priced (unrated), and for `unavailable`, where nothing is known — read `state`
+     * first to tell the two apart.
+     */
+    total_cost_usd: number | null;
+    /**
+     * True when priced and unrated calls are mixed, so `total_cost_usd` covers the priced calls
+     * only and is a lower bound. Never true outside `records`.
+     */
+    cost_partial: boolean;
+    tokens: UsageTokenTotals;
+    /** Number of usage records summarized — one per inference call; `0` outside `records`. */
+    calls: number;
+    /**
+     * `usage_assembly_error` as relayed: non-null when the runner's usage assembly failed, which
+     * is the only thing that separates a broken assembly from an `unavailable` one that was off.
+     */
+    assembly_error: string | null;
+    /**
+     * Per-pipe rollup, most expensive first: priced pipes by cost descending, then unrated pipes,
+     * with ties broken by call count (descending) and then by pipe code. Empty outside `records`.
+     */
+    by_pipe: PipeUsageSummary[];
+}
+/** The part of `RunResults` the summary reads — a whole `RunResults` is accepted as is. */
+export type RunUsagePair = Pick<RunResults, "tokens_usages" | "usage_assembly_error">;
+/**
+ * Fold a run's usage pair into one summary: run totals, the call count, the assembly error and
+ * a per-pipe rollup. See `docs/run-usage.md` for the rules it applies.
+ *
+ * Pre-contract records, relayed verbatim from artifacts written before the usage contract,
+ * carry no `cost` and no `pipe_code`: they count as unrated and unattributed. The legacy
+ * `job_metadata` / `unit_costs` fields are relics and are never read.
+ */
+export declare function summarizeUsage(results: RunUsagePair): UsageSummary;

package/dist/usage.js

@@ -0,0 +1,121 @@
+/**
+ * Fold a run's usage pair into one summary: run totals, the call count, the assembly error and
+ * a per-pipe rollup. See `docs/run-usage.md` for the rules it applies.
+ *
+ * Pre-contract records, relayed verbatim from artifacts written before the usage contract,
+ * carry no `cost` and no `pipe_code`: they count as unrated and unattributed. The legacy
+ * `job_metadata` / `unit_costs` fields are relics and are never read.
+ */
+export function summarizeUsage(results) {
+    const records = results.tokens_usages;
+    const assemblyError = results.usage_assembly_error ?? null;
+    if (records == null) {
+        return {
+            state: "unavailable",
+            total_cost_usd: null,
+            cost_partial: false,
+            tokens: { input: null, output: null },
+            calls: 0,
+            assembly_error: assemblyError,
+            by_pipe: [],
+        };
+    }
+    if (records.length === 0) {
+        return {
+            state: "no_inference",
+            total_cost_usd: 0,
+            cost_partial: false,
+            tokens: { input: 0, output: 0 },
+            calls: 0,
+            assembly_error: assemblyError,
+            by_pipe: [],
+        };
+    }
+    return {
+        state: "records",
+        ...foldRecords(records),
+        calls: records.length,
+        assembly_error: assemblyError,
+        by_pipe: rollUpByPipe(records),
+    };
+}
+/** Null-aware totals over a non-empty set of records. */
+function foldRecords(records) {
+    let pricedSum = 0;
+    let anyPriced = false;
+    let anyUnrated = false;
+    let inputSum = null;
+    let outputSum = null;
+    for (const record of records) {
+        // `typeof` rather than `!= null`: artifacts are relayed unvalidated, and a non-numeric `cost`
+        // on a malformed one must count as unrated, not turn the sum into string concatenation.
+        if (typeof record.cost === "number") {
+            pricedSum += record.cost;
+            anyPriced = true;
+        }
+        else {
+            anyUnrated = true;
+        }
+        const byCategory = record.nb_tokens_by_category;
+        if (byCategory != null) {
+            // Only the two joined totals are additive; every other category is a subset of one.
+            const input = byCategory["input"];
+            const output = byCategory["output"];
+            if (typeof input === "number")
+                inputSum = (inputSum ?? 0) + input;
+            if (typeof output === "number")
+                outputSum = (outputSum ?? 0) + output;
+        }
+    }
+    return {
+        total_cost_usd: anyPriced ? pricedSum : null,
+        cost_partial: anyPriced && anyUnrated,
+        tokens: { input: inputSum, output: outputSum },
+    };
+}
+/** Group the records by `pipe_code` (a `null` key gathers the unattributed calls) and sort. */
+function rollUpByPipe(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const pipeCode = typeof record.pipe_code === "string" ? record.pipe_code : null;
+        const group = groups.get(pipeCode);
+        if (group === undefined) {
+            groups.set(pipeCode, [record]);
+        }
+        else {
+            group.push(record);
+        }
+    }
+    const rows = [];
+    for (const [pipeCode, pipeRecords] of groups) {
+        const fold = foldRecords(pipeRecords);
+        rows.push({
+            pipe_code: pipeCode,
+            total_cost_usd: fold.total_cost_usd,
+            cost_partial: fold.cost_partial,
+            tokens: fold.tokens,
+            calls: pipeRecords.length,
+        });
+    }
+    return rows.sort(comparePipeRows);
+}
+/** Cost descending with unrated pipes last, then calls descending, then pipe code (null last). */
+function comparePipeRows(a, b) {
+    if (a.total_cost_usd !== b.total_cost_usd) {
+        if (a.total_cost_usd === null)
+            return 1;
+        if (b.total_cost_usd === null)
+            return -1;
+        return b.total_cost_usd - a.total_cost_usd;
+    }
+    if (a.calls !== b.calls)
+        return b.calls - a.calls;
+    if (a.pipe_code === b.pipe_code)
+        return 0;
+    if (a.pipe_code === null)
+        return 1;
+    if (b.pipe_code === null)
+        return -1;
+    return a.pipe_code < b.pipe_code ? -1 : 1;
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "TypeScript SDK for the Pipelex hosted API — execute methods, manage runs, and call the product surface.",
   "license": "MIT",
   "repository": {
@@ -60,6 +60,7 @@
   },
   "dependencies": {
     "mthds": "^0.25.0",
-    "smol-toml": "^1.6.0"
+    "smol-toml": "^1.6.0",
+    "undici": "^7.29.1"
   }
 }