@instruments/materialgraph 0.26.0 → 0.27.1

package/slot-pool-types.d.ts

@@ -1,372 +0,0 @@
-/**
- * Hand-mirrored wire types for the slot-pool surface
- * (`POST /api/v1/schemes/pools`, operation `slot_pools`, MG-1301). Like the rest
- * of the SDK these interfaces carry NO runtime dependency on any
- * `@materialgraph/*` package — they mirror the `SlotPoolsRequest` /
- * `SlotPoolsResponse` shapes in `apps/web/public/openapi.yaml`.
- *
- * THE QUESTION IT ANSWERS: "for each of these slots, what should I be choosing
- * between?" One call, up to 24 slots, one ranked and gated pool each. There is
- * no project and no run — the request is self-contained and the ownership of the
- * work stays with you.
- *
- * THREE THINGS TO READ CORRECTLY, because getting them wrong turns a careful
- * answer into a false one:
- *  1. A pool with a `shortfall` of kind `search-failed` was NOT answered. The
- *     other pools in the same response were. Never read that empty pool as
- *     "nothing matched".
- *  2. `not_evaluated` and `missing` are not `failed`. The first means the engine
- *     did not check the criterion at the tier that ran; the second means the
- *     material holds no accepted value for it. Only `failed` means a value
- *     exists and does not satisfy the ask.
- *  3. `eligible: false` does not mean "bad". It means this candidate cannot be
- *     placed automatically — read `flags` for which of the reasons applies.
- *
- * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
- * so a new server value still type-checks; objects are read structurally.
- */
-import type { VerdictCitation } from "./citation-types.js";
-import type { VariantId } from "./identifiers.js";
-import type { OpenEnum } from "./types.js";
-/**
- * One requirement or preference. Request-side, so this is a STRICT union.
- * `attribute` asks for a canonical term, `attribute-presence` merely that the
- * attribute is recorded, `attribute-numeric` a one-sided bound. `unresolved`
- * carries brief language nothing bound to — it is never a filter and never
- * blamed for a coverage shortfall.
- */
-export type SlotPoolCriterion = {
-    kind: "attribute";
-    attributeId: string;
-    term: string;
-    raw: string;
-} | {
-    kind: "attribute-presence";
-    attributeId: string;
-    raw: string;
-} | {
-    kind: "attribute-numeric";
-    attributeId: string;
-    comparator: "at-least" | "at-most";
-    value: number;
-    unit?: string;
-    raw: string;
-} | {
-    kind: "unresolved";
-    raw: string;
-    suggestion?: {
-        attributeId: string;
-        term?: string;
-    };
-    coverageNote?: string;
-};
-/** A colour cue for a slot. Colours rerank within the retrieved set; they never admit. */
-export type SlotPoolColourCue = {
-    /** `#rrggbb`. */
-    hex: string;
-    name?: string;
-};
-/**
- * What to do with a candidate the catalogue no longer lists. Neither value ever
- * marks such a candidate eligible — the policy decides only whether it is
- * returned at all.
- */
-export type SlotPoolAvailabilityPolicy = "flag-unavailable" | "exclude-unavailable";
-/** One slot of work. Self-contained: nothing in it identifies a project. */
-export type SlotPoolTask = {
-    /**
-     * YOUR key for this task, opaque to MaterialGraph and returned verbatim on the
-     * matching pool. This is how you correlate 24 results; it is never parsed,
-     * normalised or reused as a server id. Must be unique within a request.
-     */
-    taskKey: string;
-    /**
-     * The catalog category. OMITTING IT yields an empty pool with a `no-category`
-     * shortfall — category is the only cross-kind gate, and retrieval will not
-     * rank an ungated corpus.
-     */
-    category?: string;
-    /** A short VISUAL description of the material wanted — not a keyword list. */
-    intent?: string;
-    required?: SlotPoolCriterion[];
-    preferred?: SlotPoolCriterion[];
-    colours?: SlotPoolColourCue[];
-    /** Rank this task around an already-chosen variant. Ids are opaque tokens. */
-    anchorSeed?: {
-        variantId: VariantId;
-    };
-    exclude?: {
-        variantIds?: VariantId[];
-        brandSlugs?: string[];
-    };
-    availability?: SlotPoolAvailabilityPolicy;
-    /** Candidates returned for this task. Max 48, default 12. */
-    limit?: number;
-};
-/** Body for `POST /api/v1/schemes/pools` ({@link MaterialGraphClient.slotPools}). */
-export type SlotPoolsRequest = {
-    /** Up to 24 tasks. Each is independent: one failing costs that one. */
-    tasks: SlotPoolTask[];
-    /**
-     * Include the co-specification evidence among the returned candidates
-     * (default true). One bounded read — never one request per candidate.
-     */
-    coSpecification?: boolean;
-};
-/** The six live verdict states, plus the two legacy tokens older rows carry. */
-export type SlotPoolVerdictState = OpenEnum<"matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated">;
-/** One cell of a candidate's report card against one criterion. */
-export type SlotPoolVerdictCell = {
-    attributeId: string;
-    state: SlotPoolVerdictState;
-    strength: OpenEnum<"required" | "preferred">;
-    baseline: {
-        kind: "term";
-        term: string;
-    } | {
-        kind: "presence";
-    } | {
-        kind: "seed";
-        variantId: VariantId;
-    } | {
-        kind: "image";
-        source: OpenEnum<"variant" | "vector">;
-        variantId: VariantId | null;
-    };
-    /** The candidate's OWN accepted value, or null when it holds none. */
-    value: string | null;
-    deviation: {
-        direction: OpenEnum<"above" | "below" | "other">;
-        delta: number | null;
-        unit: string | null;
-        label: string;
-    } | null;
-    confidence: number | null;
-    /**
-     * WHERE the value came from — it ranks the SOURCE, not the accuracy. It says
-     * nothing about whether the value is right.
-     */
-    sourceBasis: string | null;
-    trustGap: OpenEnum<"below_confidence" | "basis_unmet" | "proposed"> | null;
-    citation?: VerdictCitation;
-};
-/** Why a candidate is labelled. An eligible candidate carries none of these. */
-export type SlotPoolFlag = OpenEnum<"below-floor" | "required-not-applied" | "discontinued" | "superseded" | "unverified-value">;
-export type SlotPoolAvailability = OpenEnum<"available" | "discontinued" | "superseded" | "unknown">;
-/** The declared successor of a withdrawn material, one hop only. */
-export type SlotPoolSuccessor = {
-    variantId: VariantId;
-    brandSlug: string;
-    productId: string;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    availability: SlotPoolAvailability;
-};
-/**
- * The features a composer scores on. Colours are EXTRACTED FROM PRODUCT IMAGERY
- * — visual likeness, never a declared colour specification. An empty `palette`
- * or `attributes` means nothing is on record, never that the material has none.
- */
-export type SlotPoolCandidateFeatures = {
-    colour: {
-        dominantHex: string | null;
-        hsl: {
-            h: number;
-            s: number;
-            l: number;
-        } | null;
-        oklab: {
-            l: number;
-            a: number;
-            b: number;
-        } | null;
-        chroma: number | null;
-        vibrancy: number | null;
-        sourceBasis?: string;
-    };
-    palette: {
-        hex: string;
-        proportion: number;
-        name?: string | null;
-        oklab?: {
-            l: number;
-            a: number;
-            b: number;
-        };
-    }[];
-    attributes: {
-        attributeId: string;
-        term: string;
-    }[];
-    dimensions: Record<string, unknown>[] | null;
-};
-export type SlotPoolCandidate = {
-    variantId: VariantId;
-    productId: string;
-    brandSlug: string;
-    brand: string;
-    product: string;
-    variant: string;
-    category: string | null;
-    materialBankId: string | null;
-    imageUrl: string | null;
-    availability: SlotPoolAvailability;
-    supersededBy: SlotPoolSuccessor | null;
-    /**
-     * True only when every required criterion was applied, the catalogue still
-     * lists the material, and no exclusion touched it. Anything else needs a
-     * human decision — read `flags` for which reason.
-     */
-    eligible: boolean;
-    flags: SlotPoolFlag[];
-    score: {
-        /** Normalised to [0,1] against the best score on THIS pool's page. */
-        retrieval: number;
-        /** `unverified` + `not_evaluated` cells. A soft penalty, not a failure count. */
-        unknownCount: number;
-        verdictCounts: {
-            matched: number;
-            deviated: number;
-            failed: number;
-            unverified: number;
-            missing: number;
-            notEvaluated: number;
-        };
-    };
-    verdict: {
-        cells: SlotPoolVerdictCell[];
-        grade: OpenEnum<"meets_all" | "close" | "hard_no">;
-        minConfidence: number | null;
-    };
-    features: SlotPoolCandidateFeatures;
-};
-/**
- * Why a pool is short. Four different facts, and none of them is "nothing in
- * the catalogue matches your brief".
- */
-export type SlotPoolShortfall = {
-    kind: "no-category";
-} | {
-    kind: "category-coverage";
-    category: string;
-    attributeIds: string[];
-    gaps?: ({
-        level: "attribute";
-        attributeId: string;
-    } | {
-        level: "value";
-        attributeId: string;
-        term: string;
-    })[];
-} | {
-    kind: "search-failed";
-    detail: string;
-} | {
-    kind: "no-match";
-    tier: string;
-    consideredCount: number;
-};
-export type SlotPool = {
-    /** Your own key, verbatim. */
-    taskKey: string;
-    category: string | null;
-    /** The relaxation rung the returned candidates were drawn at. */
-    retrievalTier: OpenEnum<"strict" | "presence" | "category-only">;
-    /**
-     * HOW the candidates were retrieved. DERIVED from the retrieval plan and the
-     * pool's receipt — MaterialGraph does not report an arm per candidate.
-     *
-     * It is constant across the relaxation rungs, so it cannot tell you how far
-     * the ladder went. `retrievalTier` beside it names the rung the pool settled
-     * on: the arm says how, the tier says how strictly.
-     */
-    arm: OpenEnum<"visual-text" | "image-similarity" | "none">;
-    candidates: SlotPoolCandidate[];
-    /** How much retrieval scored before this task's own `limit` trimmed the page. */
-    consideredCount: number;
-    returnedCount: number;
-    excludedCount: number;
-    unavailableDroppedCount: number;
-    /**
-     * The criteria nothing on this page could be graded on — a statement about
-     * catalogue COVERAGE, never about the candidates.
-     */
-    unknownCoverage: {
-        evaluatedCriteria: number;
-        /** Every returned candidate graded `not_evaluated` on these. */
-        uncheckedCriteria: string[];
-        /** Every returned candidate graded `missing` on these. */
-        unheldCriteria: string[];
-    };
-    shortfall: SlotPoolShortfall | null;
-    seededFrom: {
-        variantId: VariantId;
-    } | null;
-    warnings: string[];
-};
-/**
- * The sparse pairing graph among the returned candidates. Each unordered pair
- * appears ONCE and the relation is symmetric. An empty `edges` under a null
- * `datasetSessionId` means the dataset is absent, NOT that these materials are
- * never specified together.
- */
-export type SlotPoolCoSpecification = {
-    edges: {
-        from: VariantId;
-        to: VariantId;
-        projectCount: number;
-    }[];
-    coverage: {
-        candidateCount: number;
-        coveredCount: number;
-        truncated: boolean;
-        datasetSessionId: string | null;
-        window: string;
-        signal: string;
-    };
-};
-/** The `200` body from `POST /api/v1/schemes/pools`. */
-export type SlotPoolsResponse = {
-    versions: {
-        contract: string;
-        retrieval: string;
-        evaluator: string;
-        dataset: {
-            coSpecificationSessionId: string | null;
-        };
-    };
-    /** One pool per task, in request order. Correlate by `taskKey`, not by index. */
-    pools: SlotPool[];
-    coSpecification: SlotPoolCoSpecification | null;
-    summary: {
-        tasks: number;
-        eligibleCandidates: number;
-        flaggedCandidates: number;
-        tasksWithEligibleCandidates: number;
-        tasksWithoutEligibleCandidates: number;
-        /** Non-zero means some tasks were NOT answered; their pools say so. */
-        searchFailed: number;
-        noCategory: number;
-        categoryCoverage: number;
-        noMatch: number;
-    };
-    /**
-     * CALL VOLUME — how many of each bounded operation the request performed.
-     *
-     * Never a cost or token figure. Slot retrieval is database and embedding work
-     * and does not go through the model-call path that carries token and spend
-     * accounting, so no such figure exists for it. Do not render these as usage
-     * or spend.
-     */
-    calls: {
-        searchesRun: number;
-        searchesFailed: number;
-        candidatesConsidered: number;
-        candidatesReturned: number;
-        hydrationBatches: number;
-        coSpecificationQueries: number;
-    };
-    warnings: string[];
-};

package/slot-pool-types.js

@@ -1 +0,0 @@
-export {};