@instruments/materialgraph 1.4.0 → 2.1.0

package/runs.js

@@ -1,198 +0,0 @@
-/**
- * The workflow Run + source-material calls — the agentic half of the SDK. These
- * functions take the shared {@link HttpTransport} and speak the hosted Run
- * lifecycle: upload source material, start and read a workflow's Runs, and
- * stream (or drain) their events. `mg.workflows` and `uploadSourceMaterial`
- * are thin wrappers over exactly these calls.
- */
-import { MaterialGraphError } from "./errors.js";
-import { findSdkOperation, operationPath } from "./operations.js";
-import { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
-import { readSseFrames } from "./sse.js";
-const hasSourceIdentity = (source) => typeof source === "object" &&
-    source !== null &&
-    "sourceId" in source &&
-    typeof source.sourceId === "string" &&
-    "role" in source &&
-    typeof source.role === "string" &&
-    "filename" in source &&
-    typeof source.filename === "string" &&
-    "mediaType" in source &&
-    typeof source.mediaType === "string";
-const hasSourceMeasurements = (source) => typeof source === "object" &&
-    source !== null &&
-    "sha256" in source &&
-    typeof source.sha256 === "string" &&
-    "bytes" in source &&
-    typeof source.bytes === "number" &&
-    "pages" in source &&
-    (source.pages === null || typeof source.pages === "number");
-const isSourceReceipt = (value) => typeof value === "object" &&
-    value !== null &&
-    "batchId" in value &&
-    typeof value.batchId === "string" &&
-    "sources" in value &&
-    Array.isArray(value.sources) &&
-    value.sources.every((source) => typeof source === "object" &&
-        source !== null &&
-        hasSourceIdentity(source) &&
-        hasSourceMeasurements(source));
-const isRunEvent = (value) => typeof value === "object" &&
-    value !== null &&
-    "sequence" in value &&
-    typeof value.sequence === "number" &&
-    "type" in value &&
-    typeof value.type === "string";
-const runOperation = (operationId) => {
-    const match = findSdkOperation(operationId);
-    if (!match) {
-        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
-    }
-    return { ...match, operationId };
-};
-/** Build a `Blob` from raw bytes, normalizing to an ArrayBuffer-backed view. */
-const bytesToBlob = (input) => {
-    const type = input.contentType !== undefined && input.contentType !== ""
-        ? { type: input.contentType }
-        : {};
-    if (input.data instanceof ArrayBuffer) {
-        return new Blob([input.data], type);
-    }
-    // A Uint8Array may be SharedArrayBuffer-backed; copy into a fresh view so the
-    // Blob part is unambiguously ArrayBuffer-backed (no cast needed).
-    const copy = new Uint8Array(input.data.byteLength);
-    copy.set(input.data);
-    return new Blob([copy], type);
-};
-/** Append one file to the multipart body, from either input form. */
-const appendFile = (form, field, input) => {
-    if (input instanceof Blob) {
-        if (input instanceof File) {
-            form.append(field, input, input.name);
-        }
-        else {
-            form.append(field, input);
-        }
-        return;
-    }
-    form.append(field, bytesToBlob(input), input.filename);
-};
-/**
- * Upload one atomic source-material batch (`POST /api/v1/source-material`).
- * Each entry of `{ files }` becomes one part of the repeatable multipart
- * `files` field.
- */
-export const uploadSourceMaterial = async (transport, input, signal) => {
-    const form = new FormData();
-    for (const file of input.files) {
-        appendFile(form, "files", file);
-    }
-    const url = transport.buildUrl(operationPath(runOperation("upload_source_material")));
-    // No Content-Type header: fetch sets multipart/form-data with the boundary.
-    const { parsed } = await transport.send({
-        body: form,
-        headers: transport.authHeaders(),
-        method: "POST",
-        signal,
-        url,
-    });
-    if (!isSourceReceipt(parsed)) {
-        throw MaterialGraphError.unexpected("MaterialGraph source-material upload returned an invalid receipt");
-    }
-    return parsed;
-};
-/** Start an asynchronous Run of one workflow (`POST /api/v1/workflows/{workflowId}/runs`). */
-export const startWorkflowRun = async (transport, workflowId, body, signal) => await transport.requestJson(runOperation("create_public_run"), {
-    body,
-    pathParams: { workflowId },
-    signal,
-});
-/** Get a Run's current state (`GET /api/v1/workflows/{workflowId}/runs/{runId}`). */
-export const getWorkflowRun = async (transport, workflowId, runId, signal) => await transport.requestJson(runOperation("get_public_run"), {
-    pathParams: { runId, workflowId },
-    signal,
-});
-/** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
-const decodeRunEvent = (data) => {
-    if (data.length === 0) {
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(data);
-    }
-    catch (cause) {
-        throw MaterialGraphError.unexpected(`MaterialGraph run-event stream sent an unparseable data frame: ${String(cause)}`);
-    }
-    return isRunEvent(parsed) ? parsed : null;
-};
-/**
- * Stream ordered Run events as an async iterator (`GET
- * /api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until the stream ends or
- * `signal` aborts. One connection is bounded server-side (~25s or a terminal
- * event); pass `after` to resume from the last observed sequence.
- * @yields {RunEvent} Each usable Run event from the stream.
- */
-export const streamRunEvents = async function* streamRunEvents(transport, workflowId, runId, options = {}) {
-    const body = await transport.openStream(runOperation("list_public_run_events"), {
-        pathParams: { runId, workflowId },
-        ...(options.after === undefined
-            ? {}
-            : { query: { after: options.after } }),
-        ...(options.signal ? { signal: options.signal } : {}),
-        accept: "text/event-stream",
-        subject: "run-event stream",
-    });
-    for await (const frame of readSseFrames(body, options.signal)) {
-        const event = decodeRunEvent(frame.data);
-        if (event) {
-            yield event;
-        }
-    }
-};
-/**
- * Collect Run events until a terminal event, the deadline, or the stream ends —
- * the bounded events-log pattern the console uses. A single pass over
- * {@link streamRunEvents}; the deadline is enforced by aborting the stream.
- *
- * The deadline abort is this drain's OWN, expected termination — not a failure.
- * Where it lands decides how {@link streamRunEvents} surfaces it: mid-read it
- * ends the iterator cleanly, but while the underlying `fetch` is still pending —
- * the common case for a poll whose upstream has flushed no bytes yet (no new
- * events after the cursor, so no immediate SSE frame) — it rejects with an
- * `aborted` {@link MaterialGraphError}. Both mean the same thing here, so the
- * self-inflicted abort is swallowed and the collected events returned. Any other
- * failure (a real 4xx/5xx or transport error) still propagates, keeping the
- * fail-fast surface for genuine upstream problems.
- */
-export const drainRunEvents = async (transport, workflowId, runId, options) => {
-    const collected = [];
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-        controller.abort();
-    }, options.deadlineMs);
-    try {
-        for await (const event of streamRunEvents(transport, workflowId, runId, {
-            after: options.after,
-            signal: controller.signal,
-        })) {
-            collected.push(event);
-            if (TERMINAL_RUN_EVENT_TYPES.has(event.type)) {
-                break;
-            }
-        }
-    }
-    catch (error) {
-        const causedByDeadline = controller.signal.aborted &&
-            error instanceof MaterialGraphError &&
-            error.kind === "aborted";
-        if (!causedByDeadline) {
-            throw error;
-        }
-    }
-    finally {
-        clearTimeout(timer);
-        controller.abort();
-    }
-    return collected;
-};

package/samplize-catalog-types.d.ts

@@ -1,98 +0,0 @@
-export type SamplizeCatalogOptions = {
-    limit?: number;
-    /** Continue with unchanged filters and sourceVersion; omit when filters change. */
-    after?: string;
-    /** Exact canonical identities, at most 100. Unknown/ineligible IDs are omitted; no substitution. Combined filters intersect. */
-    variantIds?: string[];
-    /** Pin every subsequent page to the version returned by the first page. */
-    sourceVersion?: string;
-};
-export type SamplizeCatalogProduct = {
-    variantId: string;
-    productId: string;
-    name: string;
-    code: string;
-    brand: {
-        slug: string;
-        name: string;
-    };
-    hex: string;
-    hexSource: {
-        publisher: string;
-        url: string | null;
-        source: "resolved_variant";
-        valueSource: string | null;
-    };
-    lrv: number | null;
-    lrvSource: SamplizeLrvObservation | null;
-    lrvObservations: SamplizeLrvObservation[];
-    /** The primary sample variant count, never an aggregate of product orders. */
-    demand: SamplizeDemand | null;
-    collectionMemberships: SamplizeCollectionMembership[];
-    colorAnalysis: Record<string, unknown>;
-    oklab: {
-        L: number;
-        a: number;
-        b: number;
-    };
-    sourceProductId: string | null;
-    url: string | null;
-    sizeVariants: {
-        sourceVariantId: string;
-        sku: string | null;
-        title: string | null;
-        price: number | null;
-        inventoryAvailable: boolean;
-        demand: SamplizeDemand | null;
-    }[];
-    publishedHexes: SamplizeHexObservation[];
-    hexObservations: SamplizeHexObservation[];
-};
-export type SamplizeCatalogPage = {
-    schemaVersion: 2;
-    searchCatalogSubset: "samplizeCatalog";
-    sourceVersion: string;
-    source: Record<string, unknown>;
-    /** Number of eligible records matching the supplied filters. */
-    total: number;
-    unavailableFields: string[];
-    items: SamplizeCatalogProduct[];
-    nextCursor: string | null;
-    /** True on the final page; completeness requires collecting total unique IDs. */
-    complete: boolean;
-};
-export type SamplizeHexObservation = {
-    hex: string;
-    publisher: string;
-    source: string;
-    sourceUrl: string | null;
-    valueSource: string;
-    observedAt: string | null;
-    differsFromSelected: boolean;
-};
-export type SamplizePublicationSource = {
-    publisher: "Samplize";
-    source: "algolia_shopify_products";
-    sourceUrl: string;
-    observedAt: string | null;
-};
-export type SamplizeLrvObservation = {
-    field: string;
-    value: number;
-} & SamplizePublicationSource;
-export type SamplizeDemand = {
-    field: "recently_ordered_count";
-    sourceVariantId: string;
-    defaultAttributeLevel: "shopify_variant";
-    recentlyOrderedCount: number;
-    /** The publisher does not supply the time window. */
-    window: null;
-} & SamplizePublicationSource;
-export type SamplizeCollectionMembership = {
-    sourceCollectionId: string;
-    handle: string;
-    url: string;
-    publisher: "Samplize";
-    source: "algolia_shopify_products";
-    observedAt: string | null;
-};

package/samplize-colorvec.d.ts

@@ -1,70 +0,0 @@
-export declare const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
-export declare const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = "oklch-anchor-quantiles-v12";
-export type SamplizeColorVecPaint = {
-    variantId: string;
-    hex: string;
-    brand: string;
-    oklab: {
-        L: number;
-        a: number;
-        b: number;
-    };
-    family: string;
-    lightness: string;
-    intensity: string;
-    vector: number[] | string;
-};
-export type SamplizeColorVecCache = {
-    sourceVersion: string;
-    dictionaryVersion: string;
-    embeddingVersion: string;
-    rankingVersion: string;
-    generatedAt: string;
-    paints: SamplizeColorVecPaint[];
-};
-export type SamplizeColorVecInput = {
-    hex?: string;
-    reference?: string;
-    palette?: {
-        hex: string;
-        proportion: number;
-    }[];
-    direction?: "similar" | "lighter" | "darker" | "muted";
-    brand?: string[];
-    family?: string[];
-    lightness?: string[];
-    intensity?: string[];
-    lightnessMin?: number;
-    lightnessMax?: number;
-    temperatureMin?: number;
-    temperatureMax?: number;
-    limit?: number;
-};
-export declare const samplizeSolidColorVector: (hex: string) => number[];
-/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
-export declare const selectSamplizeEligiblePaints: <T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput) => {
-    counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
-    eligible: T[];
-    reference: T | undefined;
-};
-/** Official portable MG ranking over its complete versioned sampling-channel projection. */
-export declare const createSamplizeColorVecIndex: (cache: SamplizeColorVecCache) => {
-    search(input: SamplizeColorVecInput): {
-        countBasis: "complete-catalog";
-        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
-        dictionaryVersion: string;
-        eligibleCount: number;
-        embeddingVersion: string;
-        groups: {
-            hex: string;
-            ids: string[];
-            proportion: number;
-            quota: number;
-            shortfall: number;
-        }[];
-        ids: string[];
-        limited: boolean;
-        rankingVersion: string;
-        sourceVersion: string;
-    };
-};

package/samplize-colorvec.js

@@ -1,222 +0,0 @@
-import { EMBEDDING_VERSION, EMBEDDING_VECTOR_SIZE, embeddingCosineSimilarity, paletteToEmbedding, } from "@materialinstruments/colorscope/embedding";
-export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
-export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
-const decodeVector = (encoded) => {
-    const bytes = Uint8Array.from(atob(encoded), (c) => {
-        const codePoint = c.codePointAt(0);
-        if (codePoint === undefined) {
-            throw new Error("Missing encoded vector byte.");
-        }
-        return codePoint;
-    });
-    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4) {
-        throw new Error("Invalid color vector size.");
-    }
-    const view = new DataView(bytes.buffer);
-    return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
-};
-const facets = ["brand", "family", "lightness", "intensity"];
-const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-export const samplizeSolidColorVector = (hex) => {
-    if (!/^#[0-9a-f]{6}$/iu.test(hex)) {
-        throw new Error("A six-digit published color is required.");
-    }
-    return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
-};
-const findReferencePaint = (paints, input) => {
-    const reference = input.reference !== undefined && input.reference !== ""
-        ? paints.find((p) => p.variantId === input.reference)
-        : undefined;
-    if (input.reference !== undefined && input.reference !== "" && !reference) {
-        throw new Error("The reference is absent from this catalog version.");
-    }
-    return reference;
-};
-/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
-export const selectSamplizeEligiblePaints = (paints, input) => {
-    const reference = findReferencePaint(paints, input);
-    const low = input.lightnessMin ?? 0;
-    const high = input.lightnessMax ?? 1;
-    const cool = input.temperatureMin ?? -0.4;
-    const warm = input.temperatureMax ?? 0.4;
-    if (![low, high, cool, warm].every(Number.isFinite) ||
-        low > high ||
-        cool > warm) {
-        throw new Error("Appearance ranges must be finite and ordered.");
-    }
-    const candidates = paints.filter((p) => {
-        if (!reference) {
-            return true;
-        }
-        if (p.variantId === reference.variantId) {
-            return false;
-        }
-        if (input.direction === "lighter") {
-            return p.oklab.L > reference.oklab.L;
-        }
-        if (input.direction === "darker") {
-            return p.oklab.L < reference.oklab.L;
-        }
-        if (input.direction === "muted") {
-            return (Math.hypot(p.oklab.a, p.oklab.b) <
-                Math.hypot(reference.oklab.a, reference.oklab.b));
-        }
-        return true;
-    });
-    const matches = (p, omit) => p.oklab.L >= low &&
-        p.oklab.L <= high &&
-        p.oklab.b >= cool &&
-        p.oklab.b <= warm &&
-        facets.every((f) => f === omit ||
-            input[f] === undefined ||
-            input[f].length === 0 ||
-            input[f].includes(p[f]));
-    const counts = {
-        brand: {},
-        family: {},
-        intensity: {},
-        lightness: {},
-    };
-    for (const p of candidates) {
-        for (const f of facets) {
-            if (matches(p, f)) {
-                counts[f][p[f]] = (counts[f][p[f]] ?? 0) + 1;
-            }
-        }
-    }
-    const eligible = candidates.filter((p) => matches(p));
-    return { counts, eligible, reference };
-};
-const searchPalette = (input, reference) => {
-    const palette = (input.palette !== undefined && input.palette.length > 0
-        ? input.palette
-        : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
-        .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
-        .toSorted((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
-    if (palette.length > 12 ||
-        palette.some((p) => !Number.isFinite(p.proportion) || p.proportion <= 0 || p.proportion > 1)) {
-        throw new Error("Supply up to twelve positive image color shares.");
-    }
-    return palette;
-};
-const searchSamplizePaints = (cache, paints, input, vectorFor) => {
-    const limit = input.limit ?? 48;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
-        throw new Error("Choose between 1 and 100 suggestions.");
-    }
-    const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
-    const palette = searchPalette(input, reference);
-    const total = palette.reduce((sum, p) => sum + p.proportion, 0);
-    const buckets = palette.map((p, position) => {
-        const bucketPaints = [];
-        return {
-            ...p,
-            paints: bucketPaints,
-            position,
-            quota: Math.floor((limit * p.proportion) / total),
-            remainder: ((limit * p.proportion) / total) % 1,
-            vector: vectorFor(p.hex),
-        };
-    });
-    let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
-    for (const p of [...buckets].toSorted((a, b) => b.remainder - a.remainder || a.position - b.position)) {
-        if (remaining-- > 0) {
-            p.quota++;
-        }
-    }
-    for (const paint of eligible) {
-        let best = buckets[0];
-        if (best === undefined) {
-            throw new Error("Missing first palette bucket.");
-        }
-        let score = embeddingCosineSimilarity(paint.vector, best.vector);
-        for (let i = 1; i < buckets.length; i++) {
-            const candidate = buckets[i];
-            if (candidate === undefined) {
-                throw new Error("Missing palette bucket.");
-            }
-            const next = embeddingCosineSimilarity(paint.vector, candidate.vector);
-            if (next > score) {
-                best = candidate;
-                score = next;
-            }
-        }
-        best.paints.push({ id: paint.variantId, score });
-    }
-    const groups = buckets
-        .toSorted((a, b) => b.proportion - a.proportion || a.position - b.position)
-        .map((p) => {
-        const ids = p.paints
-            .toSorted((a, b) => b.score - a.score || identityOrder(a.id, b.id))
-            .slice(0, p.quota)
-            .map((paint) => paint.id);
-        return {
-            hex: p.hex,
-            ids,
-            proportion: p.proportion,
-            quota: p.quota,
-            shortfall: p.quota - ids.length,
-        };
-    });
-    const ids = groups.flatMap((p) => p.ids);
-    return {
-        countBasis: "complete-catalog",
-        counts,
-        dictionaryVersion: cache.dictionaryVersion,
-        eligibleCount: eligible.length,
-        embeddingVersion: cache.embeddingVersion,
-        groups,
-        ids,
-        limited: eligible.length > ids.length,
-        rankingVersion: cache.rankingVersion,
-        sourceVersion: cache.sourceVersion,
-    };
-};
-/** Official portable MG ranking over its complete versioned sampling-channel projection. */
-export const createSamplizeColorVecIndex = (cache) => {
-    if (cache.embeddingVersion !== EMBEDDING_VERSION ||
-        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION) {
-        throw new Error("The color cache uses an incompatible embedding or ranking version. Refresh it before searching.");
-    }
-    if (!cache.sourceVersion ||
-        !cache.dictionaryVersion ||
-        !Number.isFinite(Date.parse(cache.generatedAt))) {
-        throw new Error("The color cache is missing its provenance.");
-    }
-    const paints = cache.paints.map((p) => ({
-        ...p,
-        vector: typeof p.vector === "string" ? decodeVector(p.vector) : p.vector,
-    }));
-    const identities = new Set();
-    for (const paint of paints) {
-        if (identities.has(paint.variantId) ||
-            paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
-            !paint.vector.every(Number.isFinite) ||
-            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite)) {
-            throw new Error("The color cache contains invalid or duplicate paint records.");
-        }
-        identities.add(paint.variantId);
-    }
-    const vectors = new Map();
-    const vectorFor = (hex) => {
-        const key = hex.toLowerCase();
-        let value = vectors.get(key);
-        if (!value) {
-            value = samplizeSolidColorVector(hex);
-            if (vectors.size >= 512) {
-                const oldest = vectors.keys().next().value;
-                if (oldest === undefined) {
-                    throw new Error("Missing oldest cached color vector.");
-                }
-                vectors.delete(oldest);
-            }
-            vectors.set(key, value);
-        }
-        return value;
-    };
-    return {
-        search(input) {
-            return searchSamplizePaints(cache, paints, input, vectorFor);
-        },
-    };
-};

package/sse.d.ts

@@ -1,36 +0,0 @@
-/**
- * A minimal, dependency-free Server-Sent Events reader — the primitive behind
- * {@link WorkflowsClient.streamRunEvents}. Hand-rolled (no `eventsource`,
- * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
- * Node route handlers, where `fetch` yields a byte `ReadableStream`.
- *
- * The parser follows the WHATWG event-stream tokenizer closely enough for the
- * `/api/v1/workflows/{workflowId}/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
- * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
- * optional leading space after the field colon. Frames split across network
- * chunks are held in an internal buffer until their terminating blank line.
- */
-/** One dispatched SSE frame. `data` is the joined data lines (no trailing newline). */
-export type SseFrame = {
-    id?: string;
-    event?: string;
-    data: string;
-};
-/**
- * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
- * returns any frames completed by that text. Call {@link flush} once the stream
- * ends to dispatch a final frame that had data but no terminating blank line.
- */
-export declare class SseDecoder {
-    #private;
-    push(text: string): SseFrame[];
-    /** Dispatch a trailing frame that had fields but no closing blank line. */
-    flush(): SseFrame[];
-}
-/**
- * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
- * or `signal` aborts (mid-read abort rejections are swallowed once the signal
- * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
- * @yields {SseFrame} Each completed frame containing fields.
- */
-export declare const readSseFrames: (body: ReadableStream<Uint8Array>, signal?: AbortSignal) => AsyncGenerator<SseFrame, void, unknown>;