@samesake/core 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @samesake/core
 
-Config-as-code DSL for commerce search and entity resolution. Declare `collection()` and `entity()` with compile-time validation.
+Config-as-code DSL for Samesake, a TypeScript-first visual-commerce search engine compiler starting with fashion. Declare `collection()` for multi-space commerce search and `entity()` for entity resolution, both with compile-time validation.
 
 ```bash
 bun add @samesake/core

package/dist/index.cjs

@@ -28,7 +28,13 @@ __export(index_exports, {
   collection: () => collection,
   entity: () => entity,
   f: () => f,
+  fashionAttributeSchema: () => fashionAttributeSchema,
+  fashionAttributes: () => fashionAttributes,
+  fashionEnrichmentPreset: () => fashionEnrichmentPreset,
+  fashionSearchPreset: () => fashionSearchPreset,
   fields: () => fields,
+  isCollectionDef: () => isCollectionDef,
+  isEntityDef: () => isEntityDef,
   pipeline: () => pipeline,
   s: () => s,
   sources: () => sources,
@@ -72,6 +78,22 @@ function assertNoIdentCollisions(names, kind) {
 }
 
 // src/index.ts
+var DEF_KIND = /* @__PURE__ */ Symbol.for("@samesake/core.defKind");
+function brandDef(def, kind) {
+  Object.defineProperty(def, DEF_KIND, {
+    value: kind,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return def;
+}
+function isEntityDef(value) {
+  return !!value && typeof value === "object" && value[DEF_KIND] === "entity";
+}
+function isCollectionDef(value) {
+  return !!value && typeof value === "object" && value[DEF_KIND] === "collection";
+}
 var fields = {
   text(opts = {}) {
     return { type: "text", ...opts };
@@ -110,7 +132,7 @@ function entity(name, def) {
   assertIdent(name, "entity");
   for (const s2 of def.scopes ?? []) assertIdent(s2, "scope");
   assertNoIdentCollisions(Object.keys(def.fields ?? {}), "field");
-  return { ...def, name };
+  return brandDef({ ...def, name }, "entity");
 }
 var f = {
   text(opts = {}) {
@@ -186,7 +208,7 @@ function collection(name, def) {
   if (def.spaces && Object.keys(def.spaces).length > 0) {
     validateSpaceDims(def.spaces);
   }
-  return { ...def, name };
+  return brandDef({ ...def, name }, "collection");
 }
 function stage(name, def) {
   return { name, ...def };
@@ -194,6 +216,176 @@ function stage(name, def) {
 function pipeline(...stages) {
   return { stages };
 }
+var fashionAttributes = {
+  categories: [
+    "dresses",
+    "tops",
+    "bottoms",
+    "outerwear",
+    "ethnic",
+    "activewear",
+    "footwear",
+    "bags",
+    "jewelry",
+    "accessories",
+    "kids",
+    "other"
+  ],
+  colors: [
+    "black",
+    "white",
+    "ivory",
+    "beige",
+    "brown",
+    "tan",
+    "grey",
+    "red",
+    "pink",
+    "purple",
+    "blue",
+    "navy",
+    "green",
+    "yellow",
+    "orange",
+    "multicolor"
+  ],
+  materials: [
+    "cotton",
+    "linen",
+    "denim",
+    "silk",
+    "satin",
+    "chiffon",
+    "knit",
+    "polyester",
+    "leather",
+    "wool",
+    "blend",
+    "unknown"
+  ],
+  patterns: ["solid", "floral", "striped", "checked", "embroidered", "graphic", "other"],
+  fit: ["slim", "regular", "relaxed", "oversized", "tailored", "unknown"],
+  occasions: ["everyday", "office", "party", "wedding guest", "festive", "beach", "gym", "evening"],
+  seasons: ["spring", "summer", "fall", "winter", "all-season"],
+  formality: ["casual", "smart-casual", "formal", "occasion"],
+  modesty: ["modest", "moderate", "revealing"],
+  genders: ["women", "men", "unisex", "kids"],
+  styles: ["casual", "formal", "bohemian", "minimalist", "streetwear", "romantic", "classic", "sporty"]
+};
+function fashionAttributeSchema() {
+  return {
+    type: "OBJECT",
+    properties: {
+      category: { type: "STRING", enum: fashionAttributes.categories },
+      silhouette: { type: "STRING" },
+      colors: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.colors } },
+      material: { type: "STRING", enum: fashionAttributes.materials },
+      pattern: { type: "STRING", enum: fashionAttributes.patterns },
+      fit: { type: "STRING", enum: fashionAttributes.fit },
+      sleeve_length: { type: "STRING" },
+      neckline: { type: "STRING" },
+      length: { type: "STRING" },
+      occasions: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.occasions } },
+      season: { type: "STRING", enum: fashionAttributes.seasons },
+      formality: { type: "STRING", enum: fashionAttributes.formality },
+      modesty: { type: "STRING", enum: fashionAttributes.modesty },
+      gender: { type: "STRING", enum: fashionAttributes.genders },
+      style_archetypes: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.styles } },
+      search_document: { type: "STRING" },
+      confidence: { type: "NUMBER" },
+      uncertain_fields: { type: "ARRAY", items: { type: "STRING" } }
+    },
+    required: ["category", "colors", "search_document", "confidence"]
+  };
+}
+function fashionEnrichmentPreset(opts = {}) {
+  const imageField = opts.imageField ?? "image_url";
+  const titleField = opts.titleField ?? "title";
+  const descriptionField = opts.descriptionField ?? "description";
+  return pipeline(
+    stage("fashion_attributes", {
+      model: opts.model,
+      images: (ctx) => {
+        const url = ctx.data[imageField];
+        return typeof url === "string" && url ? [url] : [];
+      },
+      prompt: (ctx) => [
+        "Extract structured fashion catalog attributes for visual search.",
+        `Title: ${String(ctx.data[titleField] ?? "")}`,
+        `Description: ${String(ctx.data[descriptionField] ?? "").slice(0, 1200)}`,
+        "Prefer observable image evidence, use allowed enum values, and write a concise shopper-facing search_document."
+      ].join("\n"),
+      schema: () => fashionAttributeSchema()
+    })
+  );
+}
+function fashionSearchPreset(opts) {
+  const fieldsMap = {
+    title: opts.fields?.title ?? "title",
+    brand: opts.fields?.brand ?? "brand",
+    price: opts.fields?.price ?? "price",
+    availability: opts.fields?.availability ?? "available",
+    imageUrl: opts.fields?.imageUrl ?? "image_url",
+    category: opts.fields?.category ?? "category"
+  };
+  const spaces = {
+    intent: s.text({
+      source: "$enriched.search_document $title",
+      model: opts.textModel,
+      dim: opts.textDim,
+      taskType: "RETRIEVAL_DOCUMENT"
+    }),
+    price: s.number({ field: "price", mode: "closer", dims: 8, min: 0, max: 1e5, scale: "log" })
+  };
+  if (opts.enableVisual !== false && opts.imageModel && opts.imageDim) {
+    spaces.visual = s.image({
+      source: `$${fieldsMap.imageUrl}`,
+      model: opts.imageModel,
+      dim: opts.imageDim,
+      taskType: "RETRIEVAL_DOCUMENT"
+    });
+  }
+  return collection(opts.name ?? "products", {
+    fields: {
+      title: f.text({ searchable: true, path: fieldsMap.title }),
+      brand: f.text({ filterable: true, facet: true, path: fieldsMap.brand }),
+      price: f.number({ filterable: true, facet: "range", budget: true, path: fieldsMap.price }),
+      available: f.boolean({ filterable: true, facet: true, path: fieldsMap.availability }),
+      category: f.text({ filterable: true, facet: true, path: fieldsMap.category }),
+      colors: f.array(f.enum(fashionAttributes.colors), { filterable: true, soft: true, path: "enriched.colors" }),
+      material: f.enum(fashionAttributes.materials, { filterable: true, soft: true, path: "enriched.material" }),
+      fit: f.enum(fashionAttributes.fit, { filterable: true, soft: true, path: "enriched.fit" }),
+      styles: f.array(f.enum(fashionAttributes.styles), { filterable: true, soft: true, path: "enriched.style_archetypes" })
+    },
+    enrich: fashionEnrichmentPreset({ model: opts.enrichmentModel, imageField: fieldsMap.imageUrl, titleField: fieldsMap.title }),
+    embeddings: {
+      intent: {
+        source: "$enriched.search_document $title",
+        model: opts.textModel,
+        dim: opts.textDim,
+        taskType: "RETRIEVAL_DOCUMENT"
+      }
+    },
+    spaces,
+    search: {
+      channels: [
+        Channels.fts({ fields: ["title"], weight: 1 }),
+        Channels.cosine({ embedding: "intent", weight: 1 }),
+        Channels.spaces({ weight: 1 })
+      ],
+      combiner: "rrf",
+      defaultSpaceWeights: {
+        intent: 1,
+        price: 0.4,
+        ...spaces.visual ? { visual: 1.2 } : {}
+      },
+      nlq: {
+        semanticRewrite: true,
+        schema: fashionAttributeSchema()
+      }
+    }
+  });
+}
 var sources = {
   shopifyFeed(opts) {
     return {
@@ -235,7 +427,13 @@ var sources = {
   collection,
   entity,
   f,
+  fashionAttributeSchema,
+  fashionAttributes,
+  fashionEnrichmentPreset,
+  fashionSearchPreset,
   fields,
+  isCollectionDef,
+  isEntityDef,
   pipeline,
   s,
   sources,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { FtsChannel, CosineChannel, RecencyChannel, SpacesChannel, CosineScorer, TrigramScorer, PhoneticEqScorer, PhoneExactScorer, AliasHitScorer, InternalCodeExactScorer, SizeUnitGateScorer, BrandGateScorer, CollectionFieldDef, CollectionEmbeddingDef, SpaceDef, PipelineDef, ConnectorDef, TypedSearchChannel, CollectionDef, FieldDef, EmbeddingDef, PhoneticDef, ParseDef, TypedScorer, EntityDef, CollectionTextFieldDef, CollectionNumberFieldDef, CollectionBooleanFieldDef, CollectionEnumFieldDef, CollectionArrayFieldDef, StageDef, TextSpaceDef, ImageSpaceDef, NumberSpaceDef, RecencySpaceDef, CategoricalSpaceDef } from './types.cjs';
-export { CollectionSearchDef, ProjectConfig, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, StageContext } from './types.cjs';
+import { FtsChannel, CosineChannel, RecencyChannel, SpacesChannel, CosineScorer, TrigramScorer, PhoneticEqScorer, PhoneExactScorer, AliasHitScorer, InternalCodeExactScorer, SizeUnitGateScorer, BrandGateScorer, CollectionFieldDef, CollectionEmbeddingDef, SpaceDef, PipelineDef, ConnectorDef, TypedSearchChannel, SchemaInput, CollectionDef, FieldDef, EmbeddingDef, PhoneticDef, ParseDef, TypedScorer, EntityDef, CollectionTextFieldDef, CollectionNumberFieldDef, CollectionBooleanFieldDef, CollectionEnumFieldDef, CollectionArrayFieldDef, StageDef, TextSpaceDef, ImageSpaceDef, NumberSpaceDef, RecencySpaceDef, CategoricalSpaceDef } from './types.cjs';
+export { AgentImageInput, AgentToolDescriptor, CollectionSearchDef, ConstraintFieldType, ConstraintOperator, ConstraintPlan, ConstraintPredicate, ConstraintTrace, ConstraintTraceItem, ConstraintTraceKind, ConstraintTraceSource, ConstraintVerification, FashionPersonalizationContext, FashionRankingPolicy, FashionSearchExplanation, FashionSearchImageInput, FashionSearchRequest, FashionSearchResponse, FindProductsRequest, FindProductsResponse, GroundedProductCandidate, ProductVariantAvailability, ProjectConfig, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, StageContext } from './types.cjs';
 export { MatchCandidate, MatchComponents, MatchResult, ResolvedMatch } from './schemas.cjs';
 import 'zod';
 
@@ -9,6 +9,8 @@ declare class IdentError extends Error {
 declare function assertIdent(name: string, kind: string): void;
 declare function assertNoIdentCollisions(names: readonly string[], kind: string): void;
 
+declare function isEntityDef(value: unknown): value is EntityDef;
+declare function isCollectionDef(value: unknown): value is CollectionDef;
 declare const fields: {
     readonly text: (opts?: {
         required?: boolean;
@@ -121,7 +123,7 @@ type CollectionInput<TFields extends Record<string, CollectionFieldDef>, TEmbedd
             instructions?: string;
             semanticRewrite?: boolean;
             enable?: boolean;
-            schema?: Record<string, unknown>;
+            schema?: SchemaInput;
             model?: string;
         };
     };
@@ -131,6 +133,47 @@ declare function collection<const TFields extends Record<string, CollectionField
 };
 declare function stage(name: string, def: Omit<StageDef, "name">): StageDef;
 declare function pipeline(...stages: StageDef[]): PipelineDef;
+declare const fashionAttributes: {
+    readonly categories: readonly ["dresses", "tops", "bottoms", "outerwear", "ethnic", "activewear", "footwear", "bags", "jewelry", "accessories", "kids", "other"];
+    readonly colors: readonly ["black", "white", "ivory", "beige", "brown", "tan", "grey", "red", "pink", "purple", "blue", "navy", "green", "yellow", "orange", "multicolor"];
+    readonly materials: readonly ["cotton", "linen", "denim", "silk", "satin", "chiffon", "knit", "polyester", "leather", "wool", "blend", "unknown"];
+    readonly patterns: readonly ["solid", "floral", "striped", "checked", "embroidered", "graphic", "other"];
+    readonly fit: readonly ["slim", "regular", "relaxed", "oversized", "tailored", "unknown"];
+    readonly occasions: readonly ["everyday", "office", "party", "wedding guest", "festive", "beach", "gym", "evening"];
+    readonly seasons: readonly ["spring", "summer", "fall", "winter", "all-season"];
+    readonly formality: readonly ["casual", "smart-casual", "formal", "occasion"];
+    readonly modesty: readonly ["modest", "moderate", "revealing"];
+    readonly genders: readonly ["women", "men", "unisex", "kids"];
+    readonly styles: readonly ["casual", "formal", "bohemian", "minimalist", "streetwear", "romantic", "classic", "sporty"];
+};
+declare function fashionAttributeSchema(): Record<string, unknown>;
+declare function fashionEnrichmentPreset(opts?: {
+    model?: string;
+    imageField?: string;
+    titleField?: string;
+    descriptionField?: string;
+}): PipelineDef;
+declare function fashionSearchPreset(opts: {
+    name?: string;
+    textModel: string;
+    textDim: number;
+    imageModel?: string;
+    imageDim?: number;
+    enableVisual?: boolean;
+    enrichmentModel?: string;
+    fields?: {
+        title?: string;
+        brand?: string;
+        price?: string;
+        variants?: string;
+        availability?: string;
+        imageUrl?: string;
+        category?: string;
+        rawTags?: string;
+    };
+}): CollectionDef & {
+    name: string;
+};
 declare const sources: {
     readonly shopifyFeed: (opts: {
         domain: string;
@@ -150,4 +193,4 @@ declare const sources: {
     }) => ConnectorDef;
 };
 
-export { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, Channels, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, IdentError, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, RecencyChannel, RecencySpaceDef, Scorers, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel, assertIdent, assertNoIdentCollisions, collection, entity, f, fields, pipeline, s, sources, stage };
+export { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, Channels, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, IdentError, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, RecencyChannel, RecencySpaceDef, SchemaInput, Scorers, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel, assertIdent, assertNoIdentCollisions, collection, entity, f, fashionAttributeSchema, fashionAttributes, fashionEnrichmentPreset, fashionSearchPreset, fields, isCollectionDef, isEntityDef, pipeline, s, sources, stage };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { FtsChannel, CosineChannel, RecencyChannel, SpacesChannel, CosineScorer, TrigramScorer, PhoneticEqScorer, PhoneExactScorer, AliasHitScorer, InternalCodeExactScorer, SizeUnitGateScorer, BrandGateScorer, CollectionFieldDef, CollectionEmbeddingDef, SpaceDef, PipelineDef, ConnectorDef, TypedSearchChannel, CollectionDef, FieldDef, EmbeddingDef, PhoneticDef, ParseDef, TypedScorer, EntityDef, CollectionTextFieldDef, CollectionNumberFieldDef, CollectionBooleanFieldDef, CollectionEnumFieldDef, CollectionArrayFieldDef, StageDef, TextSpaceDef, ImageSpaceDef, NumberSpaceDef, RecencySpaceDef, CategoricalSpaceDef } from './types.js';
-export { CollectionSearchDef, ProjectConfig, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, StageContext } from './types.js';
+import { FtsChannel, CosineChannel, RecencyChannel, SpacesChannel, CosineScorer, TrigramScorer, PhoneticEqScorer, PhoneExactScorer, AliasHitScorer, InternalCodeExactScorer, SizeUnitGateScorer, BrandGateScorer, CollectionFieldDef, CollectionEmbeddingDef, SpaceDef, PipelineDef, ConnectorDef, TypedSearchChannel, SchemaInput, CollectionDef, FieldDef, EmbeddingDef, PhoneticDef, ParseDef, TypedScorer, EntityDef, CollectionTextFieldDef, CollectionNumberFieldDef, CollectionBooleanFieldDef, CollectionEnumFieldDef, CollectionArrayFieldDef, StageDef, TextSpaceDef, ImageSpaceDef, NumberSpaceDef, RecencySpaceDef, CategoricalSpaceDef } from './types.js';
+export { AgentImageInput, AgentToolDescriptor, CollectionSearchDef, ConstraintFieldType, ConstraintOperator, ConstraintPlan, ConstraintPredicate, ConstraintTrace, ConstraintTraceItem, ConstraintTraceKind, ConstraintTraceSource, ConstraintVerification, FashionPersonalizationContext, FashionRankingPolicy, FashionSearchExplanation, FashionSearchImageInput, FashionSearchRequest, FashionSearchResponse, FindProductsRequest, FindProductsResponse, GroundedProductCandidate, ProductVariantAvailability, ProjectConfig, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, StageContext } from './types.js';
 export { MatchCandidate, MatchComponents, MatchResult, ResolvedMatch } from './schemas.js';
 import 'zod';
 
@@ -9,6 +9,8 @@ declare class IdentError extends Error {
 declare function assertIdent(name: string, kind: string): void;
 declare function assertNoIdentCollisions(names: readonly string[], kind: string): void;
 
+declare function isEntityDef(value: unknown): value is EntityDef;
+declare function isCollectionDef(value: unknown): value is CollectionDef;
 declare const fields: {
     readonly text: (opts?: {
         required?: boolean;
@@ -121,7 +123,7 @@ type CollectionInput<TFields extends Record<string, CollectionFieldDef>, TEmbedd
             instructions?: string;
             semanticRewrite?: boolean;
             enable?: boolean;
-            schema?: Record<string, unknown>;
+            schema?: SchemaInput;
             model?: string;
         };
     };
@@ -131,6 +133,47 @@ declare function collection<const TFields extends Record<string, CollectionField
 };
 declare function stage(name: string, def: Omit<StageDef, "name">): StageDef;
 declare function pipeline(...stages: StageDef[]): PipelineDef;
+declare const fashionAttributes: {
+    readonly categories: readonly ["dresses", "tops", "bottoms", "outerwear", "ethnic", "activewear", "footwear", "bags", "jewelry", "accessories", "kids", "other"];
+    readonly colors: readonly ["black", "white", "ivory", "beige", "brown", "tan", "grey", "red", "pink", "purple", "blue", "navy", "green", "yellow", "orange", "multicolor"];
+    readonly materials: readonly ["cotton", "linen", "denim", "silk", "satin", "chiffon", "knit", "polyester", "leather", "wool", "blend", "unknown"];
+    readonly patterns: readonly ["solid", "floral", "striped", "checked", "embroidered", "graphic", "other"];
+    readonly fit: readonly ["slim", "regular", "relaxed", "oversized", "tailored", "unknown"];
+    readonly occasions: readonly ["everyday", "office", "party", "wedding guest", "festive", "beach", "gym", "evening"];
+    readonly seasons: readonly ["spring", "summer", "fall", "winter", "all-season"];
+    readonly formality: readonly ["casual", "smart-casual", "formal", "occasion"];
+    readonly modesty: readonly ["modest", "moderate", "revealing"];
+    readonly genders: readonly ["women", "men", "unisex", "kids"];
+    readonly styles: readonly ["casual", "formal", "bohemian", "minimalist", "streetwear", "romantic", "classic", "sporty"];
+};
+declare function fashionAttributeSchema(): Record<string, unknown>;
+declare function fashionEnrichmentPreset(opts?: {
+    model?: string;
+    imageField?: string;
+    titleField?: string;
+    descriptionField?: string;
+}): PipelineDef;
+declare function fashionSearchPreset(opts: {
+    name?: string;
+    textModel: string;
+    textDim: number;
+    imageModel?: string;
+    imageDim?: number;
+    enableVisual?: boolean;
+    enrichmentModel?: string;
+    fields?: {
+        title?: string;
+        brand?: string;
+        price?: string;
+        variants?: string;
+        availability?: string;
+        imageUrl?: string;
+        category?: string;
+        rawTags?: string;
+    };
+}): CollectionDef & {
+    name: string;
+};
 declare const sources: {
     readonly shopifyFeed: (opts: {
         domain: string;
@@ -150,4 +193,4 @@ declare const sources: {
     }) => ConnectorDef;
 };
 
-export { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, Channels, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, IdentError, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, RecencyChannel, RecencySpaceDef, Scorers, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel, assertIdent, assertNoIdentCollisions, collection, entity, f, fields, pipeline, s, sources, stage };
+export { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, Channels, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, IdentError, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, RecencyChannel, RecencySpaceDef, SchemaInput, Scorers, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel, assertIdent, assertNoIdentCollisions, collection, entity, f, fashionAttributeSchema, fashionAttributes, fashionEnrichmentPreset, fashionSearchPreset, fields, isCollectionDef, isEntityDef, pipeline, s, sources, stage };

package/dist/index.js

@@ -36,6 +36,22 @@ function assertNoIdentCollisions(names, kind) {
 }
 
 // src/index.ts
+var DEF_KIND = /* @__PURE__ */ Symbol.for("@samesake/core.defKind");
+function brandDef(def, kind) {
+  Object.defineProperty(def, DEF_KIND, {
+    value: kind,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return def;
+}
+function isEntityDef(value) {
+  return !!value && typeof value === "object" && value[DEF_KIND] === "entity";
+}
+function isCollectionDef(value) {
+  return !!value && typeof value === "object" && value[DEF_KIND] === "collection";
+}
 var fields = {
   text(opts = {}) {
     return { type: "text", ...opts };
@@ -74,7 +90,7 @@ function entity(name, def) {
   assertIdent(name, "entity");
   for (const s2 of def.scopes ?? []) assertIdent(s2, "scope");
   assertNoIdentCollisions(Object.keys(def.fields ?? {}), "field");
-  return { ...def, name };
+  return brandDef({ ...def, name }, "entity");
 }
 var f = {
   text(opts = {}) {
@@ -150,7 +166,7 @@ function collection(name, def) {
   if (def.spaces && Object.keys(def.spaces).length > 0) {
     validateSpaceDims(def.spaces);
   }
-  return { ...def, name };
+  return brandDef({ ...def, name }, "collection");
 }
 function stage(name, def) {
   return { name, ...def };
@@ -158,6 +174,176 @@ function stage(name, def) {
 function pipeline(...stages) {
   return { stages };
 }
+var fashionAttributes = {
+  categories: [
+    "dresses",
+    "tops",
+    "bottoms",
+    "outerwear",
+    "ethnic",
+    "activewear",
+    "footwear",
+    "bags",
+    "jewelry",
+    "accessories",
+    "kids",
+    "other"
+  ],
+  colors: [
+    "black",
+    "white",
+    "ivory",
+    "beige",
+    "brown",
+    "tan",
+    "grey",
+    "red",
+    "pink",
+    "purple",
+    "blue",
+    "navy",
+    "green",
+    "yellow",
+    "orange",
+    "multicolor"
+  ],
+  materials: [
+    "cotton",
+    "linen",
+    "denim",
+    "silk",
+    "satin",
+    "chiffon",
+    "knit",
+    "polyester",
+    "leather",
+    "wool",
+    "blend",
+    "unknown"
+  ],
+  patterns: ["solid", "floral", "striped", "checked", "embroidered", "graphic", "other"],
+  fit: ["slim", "regular", "relaxed", "oversized", "tailored", "unknown"],
+  occasions: ["everyday", "office", "party", "wedding guest", "festive", "beach", "gym", "evening"],
+  seasons: ["spring", "summer", "fall", "winter", "all-season"],
+  formality: ["casual", "smart-casual", "formal", "occasion"],
+  modesty: ["modest", "moderate", "revealing"],
+  genders: ["women", "men", "unisex", "kids"],
+  styles: ["casual", "formal", "bohemian", "minimalist", "streetwear", "romantic", "classic", "sporty"]
+};
+function fashionAttributeSchema() {
+  return {
+    type: "OBJECT",
+    properties: {
+      category: { type: "STRING", enum: fashionAttributes.categories },
+      silhouette: { type: "STRING" },
+      colors: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.colors } },
+      material: { type: "STRING", enum: fashionAttributes.materials },
+      pattern: { type: "STRING", enum: fashionAttributes.patterns },
+      fit: { type: "STRING", enum: fashionAttributes.fit },
+      sleeve_length: { type: "STRING" },
+      neckline: { type: "STRING" },
+      length: { type: "STRING" },
+      occasions: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.occasions } },
+      season: { type: "STRING", enum: fashionAttributes.seasons },
+      formality: { type: "STRING", enum: fashionAttributes.formality },
+      modesty: { type: "STRING", enum: fashionAttributes.modesty },
+      gender: { type: "STRING", enum: fashionAttributes.genders },
+      style_archetypes: { type: "ARRAY", items: { type: "STRING", enum: fashionAttributes.styles } },
+      search_document: { type: "STRING" },
+      confidence: { type: "NUMBER" },
+      uncertain_fields: { type: "ARRAY", items: { type: "STRING" } }
+    },
+    required: ["category", "colors", "search_document", "confidence"]
+  };
+}
+function fashionEnrichmentPreset(opts = {}) {
+  const imageField = opts.imageField ?? "image_url";
+  const titleField = opts.titleField ?? "title";
+  const descriptionField = opts.descriptionField ?? "description";
+  return pipeline(
+    stage("fashion_attributes", {
+      model: opts.model,
+      images: (ctx) => {
+        const url = ctx.data[imageField];
+        return typeof url === "string" && url ? [url] : [];
+      },
+      prompt: (ctx) => [
+        "Extract structured fashion catalog attributes for visual search.",
+        `Title: ${String(ctx.data[titleField] ?? "")}`,
+        `Description: ${String(ctx.data[descriptionField] ?? "").slice(0, 1200)}`,
+        "Prefer observable image evidence, use allowed enum values, and write a concise shopper-facing search_document."
+      ].join("\n"),
+      schema: () => fashionAttributeSchema()
+    })
+  );
+}
+function fashionSearchPreset(opts) {
+  const fieldsMap = {
+    title: opts.fields?.title ?? "title",
+    brand: opts.fields?.brand ?? "brand",
+    price: opts.fields?.price ?? "price",
+    availability: opts.fields?.availability ?? "available",
+    imageUrl: opts.fields?.imageUrl ?? "image_url",
+    category: opts.fields?.category ?? "category"
+  };
+  const spaces = {
+    intent: s.text({
+      source: "$enriched.search_document $title",
+      model: opts.textModel,
+      dim: opts.textDim,
+      taskType: "RETRIEVAL_DOCUMENT"
+    }),
+    price: s.number({ field: "price", mode: "closer", dims: 8, min: 0, max: 1e5, scale: "log" })
+  };
+  if (opts.enableVisual !== false && opts.imageModel && opts.imageDim) {
+    spaces.visual = s.image({
+      source: `$${fieldsMap.imageUrl}`,
+      model: opts.imageModel,
+      dim: opts.imageDim,
+      taskType: "RETRIEVAL_DOCUMENT"
+    });
+  }
+  return collection(opts.name ?? "products", {
+    fields: {
+      title: f.text({ searchable: true, path: fieldsMap.title }),
+      brand: f.text({ filterable: true, facet: true, path: fieldsMap.brand }),
+      price: f.number({ filterable: true, facet: "range", budget: true, path: fieldsMap.price }),
+      available: f.boolean({ filterable: true, facet: true, path: fieldsMap.availability }),
+      category: f.text({ filterable: true, facet: true, path: fieldsMap.category }),
+      colors: f.array(f.enum(fashionAttributes.colors), { filterable: true, soft: true, path: "enriched.colors" }),
+      material: f.enum(fashionAttributes.materials, { filterable: true, soft: true, path: "enriched.material" }),
+      fit: f.enum(fashionAttributes.fit, { filterable: true, soft: true, path: "enriched.fit" }),
+      styles: f.array(f.enum(fashionAttributes.styles), { filterable: true, soft: true, path: "enriched.style_archetypes" })
+    },
+    enrich: fashionEnrichmentPreset({ model: opts.enrichmentModel, imageField: fieldsMap.imageUrl, titleField: fieldsMap.title }),
+    embeddings: {
+      intent: {
+        source: "$enriched.search_document $title",
+        model: opts.textModel,
+        dim: opts.textDim,
+        taskType: "RETRIEVAL_DOCUMENT"
+      }
+    },
+    spaces,
+    search: {
+      channels: [
+        Channels.fts({ fields: ["title"], weight: 1 }),
+        Channels.cosine({ embedding: "intent", weight: 1 }),
+        Channels.spaces({ weight: 1 })
+      ],
+      combiner: "rrf",
+      defaultSpaceWeights: {
+        intent: 1,
+        price: 0.4,
+        ...spaces.visual ? { visual: 1.2 } : {}
+      },
+      nlq: {
+        semanticRewrite: true,
+        schema: fashionAttributeSchema()
+      }
+    }
+  });
+}
 var sources = {
   shopifyFeed(opts) {
     return {
@@ -198,7 +384,13 @@ export {
   collection,
   entity,
   f,
+  fashionAttributeSchema,
+  fashionAttributes,
+  fashionEnrichmentPreset,
+  fashionSearchPreset,
   fields,
+  isCollectionDef,
+  isEntityDef,
   pipeline,
   s,
   sources,

package/dist/types.d.cts

@@ -1,5 +1,5 @@
+import { ZodType } from 'zod';
 export { MatchCandidate, MatchComponents, MatchResult, ResolvedMatch } from './schemas.cjs';
-import 'zod';
 
 interface FieldDef {
     type: "text" | "number";
@@ -269,7 +269,7 @@ interface CollectionSearchDef {
         instructions?: string;
         semanticRewrite?: boolean;
         enable?: boolean;
-        schema?: Record<string, unknown>;
+        schema?: SchemaInput;
         model?: string;
     };
 }
@@ -277,13 +277,14 @@ interface StageContext {
     data: Record<string, unknown>;
     enriched: Record<string, unknown>;
 }
+type SchemaInput = ZodType | Record<string, unknown>;
 interface StageDef {
     name: string;
     model?: string;
     condition?: (ctx: StageContext) => boolean;
     prompt: (ctx: StageContext) => string;
     images?: (ctx: StageContext) => string[];
-    schema: (ctx: StageContext) => Record<string, unknown>;
+    schema: (ctx: StageContext) => SchemaInput;
 }
 interface PipelineDef {
     stages: StageDef[];
@@ -308,9 +309,194 @@ type SearchWeightsInput<S extends string = string> = {
     recency?: number;
     spaces?: number | Partial<Record<S, number>>;
 };
+type ConstraintTraceSource = "nlq" | "explicit" | "budget_hint" | "agent";
+type ConstraintFieldType = "text" | "number" | "boolean" | "enum" | "array";
+type ConstraintOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "exclude" | "not";
+type ConstraintTraceKind = "eq" | "not_eq" | "min" | "max" | "range" | "in" | "not_in" | "contains" | "exclude" | "boolean";
+interface ConstraintTraceItem {
+    field: string;
+    source: ConstraintTraceSource;
+    kind: ConstraintTraceKind;
+    operator?: string;
+    value?: unknown;
+    soft?: boolean;
+}
+interface ConstraintPredicate {
+    field: string;
+    fieldType: ConstraintFieldType;
+    operator: ConstraintOperator;
+    value: unknown;
+    source?: ConstraintTraceSource;
+    soft?: boolean;
+}
+interface ConstraintPlan {
+    predicates: ConstraintPredicate[];
+    excludedTerms: string[];
+    relaxedFields: string[];
+}
+interface ConstraintTrace {
+    semanticQuery?: string;
+    items: ConstraintTraceItem[];
+    plan: ConstraintPlan;
+    derivedFilters: Record<string, unknown>;
+    explicitFilters: Record<string, unknown>;
+    appliedFilters: Record<string, unknown>;
+    relaxedFields: string[];
+    excludedTerms: string[];
+    budgetHints: Record<string, "cheap" | "premium">;
+}
+interface FashionSearchImageInput {
+    /** Remote image URL. The server fetches it through the same hardened image guard used for indexing. */
+    url?: string;
+    /** Base64 image bytes for callers that do not want Samesake to fetch a URL. */
+    bytesBase64?: string;
+    /** In-process callers may pass bytes directly. Not valid over JSON HTTP. */
+    bytes?: Uint8Array;
+    mimeType?: string;
+    /** Product id whose catalog image should be used as the query image. */
+    productId?: string;
+}
+interface FashionRankingPolicy {
+    weights?: {
+        relevance?: number;
+        visual?: number;
+        availability?: number;
+        newness?: number;
+        business?: number;
+        personalization?: number;
+    };
+    /** Numeric field used as a merchant/business signal, for example margin or sell-through. */
+    businessField?: string;
+    boostAvailable?: boolean;
+    buryUnavailable?: boolean;
+}
+interface FashionPersonalizationContext {
+    size?: string;
+    priceBand?: {
+        min?: number;
+        max?: number;
+    };
+    preferredBrands?: string[];
+    blockedBrands?: string[];
+    viewedProductIds?: string[];
+    avoidedStyles?: string[];
+    colorAffinity?: Record<string, number>;
+}
+interface FashionSearchRequest<S extends string = string> {
+    q?: string;
+    image?: FashionSearchImageInput;
+    filters?: Record<string, unknown>;
+    weights?: SearchWeightsInput<S>;
+    rankingPolicy?: FashionRankingPolicy;
+    personalization?: FashionPersonalizationContext;
+    limit?: number;
+    offset?: number;
+    debug?: boolean;
+    explain?: boolean;
+    recoverNoResults?: boolean;
+}
+interface FashionSearchExplanation {
+    hitId: string;
+    factors: Record<string, number | boolean | string | null>;
+    appliedFilters: string[];
+}
+interface FashionSearchResponse {
+    hits: Array<Record<string, unknown> & {
+        id: string;
+        score: number;
+    }>;
+    parsed?: Record<string, unknown>;
+    appliedFilters: Record<string, unknown>;
+    constraintTrace?: ConstraintTrace;
+    explanations?: FashionSearchExplanation[];
+    fallback?: {
+        reason: "no_results" | "low_confidence";
+        relaxedFilters: string[];
+    };
+    debug?: Record<string, unknown>;
+    took_ms: number;
+}
+type AgentImageInput = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "bytes";
+    bytesBase64: string;
+    mimeType?: string;
+} | {
+    kind: "product_image";
+    productId: string;
+    imageField?: string;
+};
+interface FindProductsRequest {
+    intent?: string;
+    image?: AgentImageInput;
+    constraints?: Record<string, unknown>;
+    shopperContext?: Record<string, unknown>;
+    constraintMode?: "best_effort" | "strict";
+    explain?: boolean;
+    limit?: number;
+}
+interface ProductVariantAvailability {
+    id?: string;
+    title?: string;
+    size?: string;
+    price?: number;
+    available?: boolean;
+    inventoryQuantity?: number;
+    updatedAt?: string;
+}
+interface ConstraintVerification {
+    status: "satisfied" | "violated" | "unknown";
+    satisfied: string[];
+    violated: string[];
+    unknown: string[];
+    strictExcluded?: boolean;
+}
+interface GroundedProductCandidate {
+    id: string;
+    title?: string;
+    url?: string;
+    imageUrl?: string;
+    price?: {
+        amount: number;
+        currency?: string;
+        lastUpdatedAt?: string;
+    };
+    availability?: {
+        inStock?: boolean;
+        variants?: ProductVariantAvailability[];
+        lastCheckedAt?: string;
+        freshness: "fresh" | "stale" | "unknown";
+    };
+    score: number;
+    data: Record<string, unknown>;
+    grounding: {
+        project: string;
+        collection: string;
+        productId: string;
+        indexedAt?: string;
+        sourceUpdatedAt?: string;
+    };
+    verification: ConstraintVerification;
+    why?: Record<string, unknown>;
+}
+interface FindProductsResponse {
+    products: GroundedProductCandidate[];
+    parsed?: Record<string, unknown>;
+    constraintTrace?: ConstraintTrace;
+    relaxed?: boolean;
+    took_ms: number;
+}
+interface AgentToolDescriptor {
+    name: "find_products" | "find_similar_products" | "compare_products" | "explain_result" | "get_product_availability" | "recover_no_results";
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+}
 interface ProjectConfig {
     entities?: EntityDef[];
     collections?: CollectionDef[];
 }
 
-export type { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionSearchDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, ProjectConfig, RecencyChannel, RecencySpaceDef, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageContext, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel };
+export type { AgentImageInput, AgentToolDescriptor, AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionSearchDef, CollectionTextFieldDef, ConnectorDef, ConstraintFieldType, ConstraintOperator, ConstraintPlan, ConstraintPredicate, ConstraintTrace, ConstraintTraceItem, ConstraintTraceKind, ConstraintTraceSource, ConstraintVerification, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FashionPersonalizationContext, FashionRankingPolicy, FashionSearchExplanation, FashionSearchImageInput, FashionSearchRequest, FashionSearchResponse, FieldDef, FindProductsRequest, FindProductsResponse, FtsChannel, GroundedProductCandidate, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, ProductVariantAvailability, ProjectConfig, RecencyChannel, RecencySpaceDef, SchemaInput, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageContext, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel };

package/dist/types.d.ts

@@ -1,5 +1,5 @@
+import { ZodType } from 'zod';
 export { MatchCandidate, MatchComponents, MatchResult, ResolvedMatch } from './schemas.js';
-import 'zod';
 
 interface FieldDef {
     type: "text" | "number";
@@ -269,7 +269,7 @@ interface CollectionSearchDef {
         instructions?: string;
         semanticRewrite?: boolean;
         enable?: boolean;
-        schema?: Record<string, unknown>;
+        schema?: SchemaInput;
         model?: string;
     };
 }
@@ -277,13 +277,14 @@ interface StageContext {
     data: Record<string, unknown>;
     enriched: Record<string, unknown>;
 }
+type SchemaInput = ZodType | Record<string, unknown>;
 interface StageDef {
     name: string;
     model?: string;
     condition?: (ctx: StageContext) => boolean;
     prompt: (ctx: StageContext) => string;
     images?: (ctx: StageContext) => string[];
-    schema: (ctx: StageContext) => Record<string, unknown>;
+    schema: (ctx: StageContext) => SchemaInput;
 }
 interface PipelineDef {
     stages: StageDef[];
@@ -308,9 +309,194 @@ type SearchWeightsInput<S extends string = string> = {
     recency?: number;
     spaces?: number | Partial<Record<S, number>>;
 };
+type ConstraintTraceSource = "nlq" | "explicit" | "budget_hint" | "agent";
+type ConstraintFieldType = "text" | "number" | "boolean" | "enum" | "array";
+type ConstraintOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "exclude" | "not";
+type ConstraintTraceKind = "eq" | "not_eq" | "min" | "max" | "range" | "in" | "not_in" | "contains" | "exclude" | "boolean";
+interface ConstraintTraceItem {
+    field: string;
+    source: ConstraintTraceSource;
+    kind: ConstraintTraceKind;
+    operator?: string;
+    value?: unknown;
+    soft?: boolean;
+}
+interface ConstraintPredicate {
+    field: string;
+    fieldType: ConstraintFieldType;
+    operator: ConstraintOperator;
+    value: unknown;
+    source?: ConstraintTraceSource;
+    soft?: boolean;
+}
+interface ConstraintPlan {
+    predicates: ConstraintPredicate[];
+    excludedTerms: string[];
+    relaxedFields: string[];
+}
+interface ConstraintTrace {
+    semanticQuery?: string;
+    items: ConstraintTraceItem[];
+    plan: ConstraintPlan;
+    derivedFilters: Record<string, unknown>;
+    explicitFilters: Record<string, unknown>;
+    appliedFilters: Record<string, unknown>;
+    relaxedFields: string[];
+    excludedTerms: string[];
+    budgetHints: Record<string, "cheap" | "premium">;
+}
+interface FashionSearchImageInput {
+    /** Remote image URL. The server fetches it through the same hardened image guard used for indexing. */
+    url?: string;
+    /** Base64 image bytes for callers that do not want Samesake to fetch a URL. */
+    bytesBase64?: string;
+    /** In-process callers may pass bytes directly. Not valid over JSON HTTP. */
+    bytes?: Uint8Array;
+    mimeType?: string;
+    /** Product id whose catalog image should be used as the query image. */
+    productId?: string;
+}
+interface FashionRankingPolicy {
+    weights?: {
+        relevance?: number;
+        visual?: number;
+        availability?: number;
+        newness?: number;
+        business?: number;
+        personalization?: number;
+    };
+    /** Numeric field used as a merchant/business signal, for example margin or sell-through. */
+    businessField?: string;
+    boostAvailable?: boolean;
+    buryUnavailable?: boolean;
+}
+interface FashionPersonalizationContext {
+    size?: string;
+    priceBand?: {
+        min?: number;
+        max?: number;
+    };
+    preferredBrands?: string[];
+    blockedBrands?: string[];
+    viewedProductIds?: string[];
+    avoidedStyles?: string[];
+    colorAffinity?: Record<string, number>;
+}
+interface FashionSearchRequest<S extends string = string> {
+    q?: string;
+    image?: FashionSearchImageInput;
+    filters?: Record<string, unknown>;
+    weights?: SearchWeightsInput<S>;
+    rankingPolicy?: FashionRankingPolicy;
+    personalization?: FashionPersonalizationContext;
+    limit?: number;
+    offset?: number;
+    debug?: boolean;
+    explain?: boolean;
+    recoverNoResults?: boolean;
+}
+interface FashionSearchExplanation {
+    hitId: string;
+    factors: Record<string, number | boolean | string | null>;
+    appliedFilters: string[];
+}
+interface FashionSearchResponse {
+    hits: Array<Record<string, unknown> & {
+        id: string;
+        score: number;
+    }>;
+    parsed?: Record<string, unknown>;
+    appliedFilters: Record<string, unknown>;
+    constraintTrace?: ConstraintTrace;
+    explanations?: FashionSearchExplanation[];
+    fallback?: {
+        reason: "no_results" | "low_confidence";
+        relaxedFilters: string[];
+    };
+    debug?: Record<string, unknown>;
+    took_ms: number;
+}
+type AgentImageInput = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "bytes";
+    bytesBase64: string;
+    mimeType?: string;
+} | {
+    kind: "product_image";
+    productId: string;
+    imageField?: string;
+};
+interface FindProductsRequest {
+    intent?: string;
+    image?: AgentImageInput;
+    constraints?: Record<string, unknown>;
+    shopperContext?: Record<string, unknown>;
+    constraintMode?: "best_effort" | "strict";
+    explain?: boolean;
+    limit?: number;
+}
+interface ProductVariantAvailability {
+    id?: string;
+    title?: string;
+    size?: string;
+    price?: number;
+    available?: boolean;
+    inventoryQuantity?: number;
+    updatedAt?: string;
+}
+interface ConstraintVerification {
+    status: "satisfied" | "violated" | "unknown";
+    satisfied: string[];
+    violated: string[];
+    unknown: string[];
+    strictExcluded?: boolean;
+}
+interface GroundedProductCandidate {
+    id: string;
+    title?: string;
+    url?: string;
+    imageUrl?: string;
+    price?: {
+        amount: number;
+        currency?: string;
+        lastUpdatedAt?: string;
+    };
+    availability?: {
+        inStock?: boolean;
+        variants?: ProductVariantAvailability[];
+        lastCheckedAt?: string;
+        freshness: "fresh" | "stale" | "unknown";
+    };
+    score: number;
+    data: Record<string, unknown>;
+    grounding: {
+        project: string;
+        collection: string;
+        productId: string;
+        indexedAt?: string;
+        sourceUpdatedAt?: string;
+    };
+    verification: ConstraintVerification;
+    why?: Record<string, unknown>;
+}
+interface FindProductsResponse {
+    products: GroundedProductCandidate[];
+    parsed?: Record<string, unknown>;
+    constraintTrace?: ConstraintTrace;
+    relaxed?: boolean;
+    took_ms: number;
+}
+interface AgentToolDescriptor {
+    name: "find_products" | "find_similar_products" | "compare_products" | "explain_result" | "get_product_availability" | "recover_no_results";
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+}
 interface ProjectConfig {
     entities?: EntityDef[];
     collections?: CollectionDef[];
 }
 
-export type { AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionSearchDef, CollectionTextFieldDef, ConnectorDef, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FieldDef, FtsChannel, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, ProjectConfig, RecencyChannel, RecencySpaceDef, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageContext, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel };
+export type { AgentImageInput, AgentToolDescriptor, AliasHitScorer, BrandGateScorer, CategoricalSpaceDef, CollectionArrayFieldDef, CollectionBooleanFieldDef, CollectionDef, CollectionEmbeddingDef, CollectionEnumFieldDef, CollectionFieldDef, CollectionNumberFieldDef, CollectionSearchDef, CollectionTextFieldDef, ConnectorDef, ConstraintFieldType, ConstraintOperator, ConstraintPlan, ConstraintPredicate, ConstraintTrace, ConstraintTraceItem, ConstraintTraceKind, ConstraintTraceSource, ConstraintVerification, CosineChannel, CosineScorer, EmbeddingDef, EntityDef, FashionPersonalizationContext, FashionRankingPolicy, FashionSearchExplanation, FashionSearchImageInput, FashionSearchRequest, FashionSearchResponse, FieldDef, FindProductsRequest, FindProductsResponse, FtsChannel, GroundedProductCandidate, ImageSpaceDef, InternalCodeExactScorer, NumberSpaceDef, ParseDef, PhoneExactScorer, PhoneticDef, PhoneticEqScorer, PipelineDef, ProductVariantAvailability, ProjectConfig, RecencyChannel, RecencySpaceDef, SchemaInput, ScorerDef, ScoringDef, SearchChannelDef, SearchWeightsInput, SizeUnitGateScorer, SpaceDef, SpacesChannel, StageContext, StageDef, TextSpaceDef, TrigramScorer, TypedScorer, TypedSearchChannel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samesake/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/asyncdotengineering/samesake"
@@ -43,7 +43,11 @@
       }
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "publishConfig": {
     "access": "public"
   },