@samesake/core 1.0.0

package/dist/index.js

@@ -0,0 +1,206 @@
+import "./chunk-6F4PWJZI.js";
+
+// src/ident.ts
+var IDENT_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+var IDENT_MAX = 63;
+var IdentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IdentError";
+  }
+};
+function assertIdent(name, kind) {
+  if (name.length > IDENT_MAX) {
+    throw new IdentError(
+      `${kind} name "${name}" exceeds max length ${IDENT_MAX}`
+    );
+  }
+  if (!IDENT_RE.test(name)) {
+    throw new IdentError(
+      `${kind} name "${name}" is invalid: use letters, digits, underscores; must start with a letter (no hyphens)`
+    );
+  }
+}
+function assertNoIdentCollisions(names, kind) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const key = name.toLowerCase();
+    const prev = seen.get(key);
+    if (prev && prev !== name) {
+      throw new IdentError(
+        `${kind} names "${prev}" and "${name}" collide (case-insensitive)`
+      );
+    }
+    seen.set(key, name);
+  }
+}
+
+// src/index.ts
+var fields = {
+  text(opts = {}) {
+    return { type: "text", ...opts };
+  },
+  number(opts = {}) {
+    return { type: "number", ...opts };
+  }
+};
+var Scorers = {
+  cosine(opts) {
+    return { kind: "cosine", ...opts };
+  },
+  trigram(opts) {
+    return { kind: "trigram", ...opts };
+  },
+  phoneticEq(opts) {
+    return { kind: "phoneticEq", ...opts };
+  },
+  phoneExact(opts) {
+    return { kind: "phoneExact", ...opts };
+  },
+  aliasHit(opts) {
+    return { kind: "aliasHit", ...opts };
+  },
+  internalCodeExact(opts) {
+    return { kind: "internalCodeExact", ...opts };
+  },
+  sizeUnitGate(opts) {
+    return { kind: "sizeUnitGate", ...opts };
+  },
+  brandGate(opts) {
+    return { kind: "brandGate", ...opts };
+  }
+};
+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 };
+}
+var f = {
+  text(opts = {}) {
+    return { type: "text", ...opts };
+  },
+  number(opts = {}) {
+    return { type: "number", ...opts };
+  },
+  boolean(opts = {}) {
+    return { type: "boolean", ...opts };
+  },
+  enum(values, opts = {}) {
+    return { type: "enum", values, ...opts };
+  },
+  array(item, opts = {}) {
+    if (item.type === "enum") {
+      return { type: "array", itemType: "enum", values: item.values, ...opts };
+    }
+    return { type: "array", itemType: "text", ...opts };
+  }
+};
+var Channels = {
+  fts(opts) {
+    return { kind: "fts", ...opts };
+  },
+  cosine(opts) {
+    return { kind: "cosine", ...opts };
+  },
+  recency(opts) {
+    return { kind: "recency", ...opts };
+  },
+  spaces(opts) {
+    return { kind: "spaces", ...opts };
+  }
+};
+var PGVECTOR_HNSW_MAX_DIMS = 2e3;
+function spaceDim(def) {
+  return def.kind === "text" || def.kind === "image" ? def.dim : def.dims;
+}
+function validateSpaceDims(spaces) {
+  let total = 0;
+  for (const def of Object.values(spaces)) {
+    total += spaceDim(def);
+  }
+  if (total > PGVECTOR_HNSW_MAX_DIMS) {
+    throw new Error(
+      `spaces total dimension ${total} exceeds pgvector HNSW limit of ${PGVECTOR_HNSW_MAX_DIMS} for vector columns. Reduce space dims or split spaces across collections. Future escape hatch: halfvec (up to 4000 dims).`
+    );
+  }
+}
+var s = {
+  text(opts) {
+    return { kind: "text", ...opts };
+  },
+  image(opts) {
+    return { kind: "image", ...opts };
+  },
+  number(opts) {
+    return { kind: "number", ...opts };
+  },
+  recency(opts) {
+    return { kind: "recency", ...opts };
+  },
+  categorical(opts) {
+    return { kind: "categorical", ...opts };
+  }
+};
+function collection(name, def) {
+  assertIdent(name, "collection");
+  assertNoIdentCollisions(Object.keys(def.fields ?? {}), "field");
+  if (def.spaces) assertNoIdentCollisions(Object.keys(def.spaces), "space");
+  if (def.embeddings) assertNoIdentCollisions(Object.keys(def.embeddings), "embedding");
+  if (def.spaces && Object.keys(def.spaces).length > 0) {
+    validateSpaceDims(def.spaces);
+  }
+  return { ...def, name };
+}
+function stage(name, def) {
+  return { name, ...def };
+}
+function pipeline(...stages) {
+  return { stages };
+}
+var sources = {
+  shopifyFeed(opts) {
+    return {
+      name: opts.name ?? `shopify:${opts.domain}`,
+      kind: "shopify",
+      options: {
+        domain: opts.domain,
+        currency: opts.currency ?? "LKR",
+        maxPages: opts.maxPages ?? 8
+      }
+    };
+  },
+  wooStoreFeed(opts) {
+    return {
+      name: opts.name ?? `woo:${opts.domain}`,
+      kind: "woocommerce",
+      options: {
+        domain: opts.domain,
+        currency: opts.currency ?? "LKR",
+        maxPages: opts.maxPages ?? 8
+      }
+    };
+  },
+  jsonl(opts) {
+    return {
+      name: opts.name ?? `jsonl:${opts.path}`,
+      kind: "jsonl",
+      options: { path: opts.path }
+    };
+  }
+};
+export {
+  Channels,
+  IdentError,
+  Scorers,
+  assertIdent,
+  assertNoIdentCollisions,
+  collection,
+  entity,
+  f,
+  fields,
+  pipeline,
+  s,
+  sources,
+  stage
+};

package/dist/schemas.cjs

@@ -0,0 +1,80 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/schemas.ts
+var schemas_exports = {};
+__export(schemas_exports, {
+  CalibrateResultSchema: () => CalibrateResultSchema,
+  CalibrationCurvePointSchema: () => CalibrationCurvePointSchema,
+  MatchCandidateSchema: () => MatchCandidateSchema,
+  MatchComponentsSchema: () => MatchComponentsSchema,
+  MatchResultSchema: () => MatchResultSchema,
+  ResolvedMatchSchema: () => ResolvedMatchSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+var MatchComponentsSchema = import_zod.z.object({
+  cosSim: import_zod.z.number().nullable(),
+  trgmSim: import_zod.z.number(),
+  phonEq: import_zod.z.boolean(),
+  phoneEq: import_zod.z.boolean(),
+  aliasHit: import_zod.z.boolean()
+});
+var MatchCandidateSchema = import_zod.z.object({
+  entityId: import_zod.z.string(),
+  name: import_zod.z.string(),
+  combined: import_zod.z.number(),
+  rrfScore: import_zod.z.number(),
+  components: MatchComponentsSchema
+});
+var ResolvedMatchSchema = import_zod.z.object({
+  entityId: import_zod.z.string(),
+  confidence: import_zod.z.number(),
+  source: import_zod.z.literal("autolink")
+});
+var MatchResultSchema = import_zod.z.object({
+  candidates: import_zod.z.array(MatchCandidateSchema),
+  queryTextNormalised: import_zod.z.string(),
+  resolved: ResolvedMatchSchema.optional()
+});
+var CalibrationCurvePointSchema = import_zod.z.object({
+  threshold: import_zod.z.number(),
+  f1: import_zod.z.number(),
+  precision: import_zod.z.number(),
+  recall: import_zod.z.number()
+});
+var CalibrateResultSchema = import_zod.z.object({
+  threshold: import_zod.z.number(),
+  f1: import_zod.z.number(),
+  precision: import_zod.z.number(),
+  recall: import_zod.z.number(),
+  sampleSize: import_zod.z.number().int(),
+  positives: import_zod.z.number().int(),
+  negatives: import_zod.z.number().int(),
+  curve: import_zod.z.array(CalibrationCurvePointSchema)
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CalibrateResultSchema,
+  CalibrationCurvePointSchema,
+  MatchCandidateSchema,
+  MatchComponentsSchema,
+  MatchResultSchema,
+  ResolvedMatchSchema
+});

package/dist/schemas.d.cts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+declare const MatchComponentsSchema: z.ZodObject<{
+    cosSim: z.ZodNullable<z.ZodNumber>;
+    trgmSim: z.ZodNumber;
+    phonEq: z.ZodBoolean;
+    phoneEq: z.ZodBoolean;
+    aliasHit: z.ZodBoolean;
+}, z.core.$strip>;
+type MatchComponents = z.infer<typeof MatchComponentsSchema>;
+declare const MatchCandidateSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    name: z.ZodString;
+    combined: z.ZodNumber;
+    rrfScore: z.ZodNumber;
+    components: z.ZodObject<{
+        cosSim: z.ZodNullable<z.ZodNumber>;
+        trgmSim: z.ZodNumber;
+        phonEq: z.ZodBoolean;
+        phoneEq: z.ZodBoolean;
+        aliasHit: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type MatchCandidate = z.infer<typeof MatchCandidateSchema>;
+declare const ResolvedMatchSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    confidence: z.ZodNumber;
+    source: z.ZodLiteral<"autolink">;
+}, z.core.$strip>;
+type ResolvedMatch = z.infer<typeof ResolvedMatchSchema>;
+declare const MatchResultSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        entityId: z.ZodString;
+        name: z.ZodString;
+        combined: z.ZodNumber;
+        rrfScore: z.ZodNumber;
+        components: z.ZodObject<{
+            cosSim: z.ZodNullable<z.ZodNumber>;
+            trgmSim: z.ZodNumber;
+            phonEq: z.ZodBoolean;
+            phoneEq: z.ZodBoolean;
+            aliasHit: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    queryTextNormalised: z.ZodString;
+    resolved: z.ZodOptional<z.ZodObject<{
+        entityId: z.ZodString;
+        confidence: z.ZodNumber;
+        source: z.ZodLiteral<"autolink">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type MatchResult = z.infer<typeof MatchResultSchema>;
+declare const CalibrationCurvePointSchema: z.ZodObject<{
+    threshold: z.ZodNumber;
+    f1: z.ZodNumber;
+    precision: z.ZodNumber;
+    recall: z.ZodNumber;
+}, z.core.$strip>;
+type CalibrationCurvePoint = z.infer<typeof CalibrationCurvePointSchema>;
+declare const CalibrateResultSchema: z.ZodObject<{
+    threshold: z.ZodNumber;
+    f1: z.ZodNumber;
+    precision: z.ZodNumber;
+    recall: z.ZodNumber;
+    sampleSize: z.ZodNumber;
+    positives: z.ZodNumber;
+    negatives: z.ZodNumber;
+    curve: z.ZodArray<z.ZodObject<{
+        threshold: z.ZodNumber;
+        f1: z.ZodNumber;
+        precision: z.ZodNumber;
+        recall: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CalibrateResult = z.infer<typeof CalibrateResultSchema>;
+
+export { type CalibrateResult, CalibrateResultSchema, type CalibrationCurvePoint, CalibrationCurvePointSchema, type MatchCandidate, MatchCandidateSchema, type MatchComponents, MatchComponentsSchema, type MatchResult, MatchResultSchema, type ResolvedMatch, ResolvedMatchSchema };

package/dist/schemas.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+declare const MatchComponentsSchema: z.ZodObject<{
+    cosSim: z.ZodNullable<z.ZodNumber>;
+    trgmSim: z.ZodNumber;
+    phonEq: z.ZodBoolean;
+    phoneEq: z.ZodBoolean;
+    aliasHit: z.ZodBoolean;
+}, z.core.$strip>;
+type MatchComponents = z.infer<typeof MatchComponentsSchema>;
+declare const MatchCandidateSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    name: z.ZodString;
+    combined: z.ZodNumber;
+    rrfScore: z.ZodNumber;
+    components: z.ZodObject<{
+        cosSim: z.ZodNullable<z.ZodNumber>;
+        trgmSim: z.ZodNumber;
+        phonEq: z.ZodBoolean;
+        phoneEq: z.ZodBoolean;
+        aliasHit: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type MatchCandidate = z.infer<typeof MatchCandidateSchema>;
+declare const ResolvedMatchSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    confidence: z.ZodNumber;
+    source: z.ZodLiteral<"autolink">;
+}, z.core.$strip>;
+type ResolvedMatch = z.infer<typeof ResolvedMatchSchema>;
+declare const MatchResultSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        entityId: z.ZodString;
+        name: z.ZodString;
+        combined: z.ZodNumber;
+        rrfScore: z.ZodNumber;
+        components: z.ZodObject<{
+            cosSim: z.ZodNullable<z.ZodNumber>;
+            trgmSim: z.ZodNumber;
+            phonEq: z.ZodBoolean;
+            phoneEq: z.ZodBoolean;
+            aliasHit: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    queryTextNormalised: z.ZodString;
+    resolved: z.ZodOptional<z.ZodObject<{
+        entityId: z.ZodString;
+        confidence: z.ZodNumber;
+        source: z.ZodLiteral<"autolink">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type MatchResult = z.infer<typeof MatchResultSchema>;
+declare const CalibrationCurvePointSchema: z.ZodObject<{
+    threshold: z.ZodNumber;
+    f1: z.ZodNumber;
+    precision: z.ZodNumber;
+    recall: z.ZodNumber;
+}, z.core.$strip>;
+type CalibrationCurvePoint = z.infer<typeof CalibrationCurvePointSchema>;
+declare const CalibrateResultSchema: z.ZodObject<{
+    threshold: z.ZodNumber;
+    f1: z.ZodNumber;
+    precision: z.ZodNumber;
+    recall: z.ZodNumber;
+    sampleSize: z.ZodNumber;
+    positives: z.ZodNumber;
+    negatives: z.ZodNumber;
+    curve: z.ZodArray<z.ZodObject<{
+        threshold: z.ZodNumber;
+        f1: z.ZodNumber;
+        precision: z.ZodNumber;
+        recall: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CalibrateResult = z.infer<typeof CalibrateResultSchema>;
+
+export { type CalibrateResult, CalibrateResultSchema, type CalibrationCurvePoint, CalibrationCurvePointSchema, type MatchCandidate, MatchCandidateSchema, type MatchComponents, MatchComponentsSchema, type MatchResult, MatchResultSchema, type ResolvedMatch, ResolvedMatchSchema };

package/dist/schemas.js

@@ -0,0 +1,50 @@
+// src/schemas.ts
+import { z } from "zod";
+var MatchComponentsSchema = z.object({
+  cosSim: z.number().nullable(),
+  trgmSim: z.number(),
+  phonEq: z.boolean(),
+  phoneEq: z.boolean(),
+  aliasHit: z.boolean()
+});
+var MatchCandidateSchema = z.object({
+  entityId: z.string(),
+  name: z.string(),
+  combined: z.number(),
+  rrfScore: z.number(),
+  components: MatchComponentsSchema
+});
+var ResolvedMatchSchema = z.object({
+  entityId: z.string(),
+  confidence: z.number(),
+  source: z.literal("autolink")
+});
+var MatchResultSchema = z.object({
+  candidates: z.array(MatchCandidateSchema),
+  queryTextNormalised: z.string(),
+  resolved: ResolvedMatchSchema.optional()
+});
+var CalibrationCurvePointSchema = z.object({
+  threshold: z.number(),
+  f1: z.number(),
+  precision: z.number(),
+  recall: z.number()
+});
+var CalibrateResultSchema = z.object({
+  threshold: z.number(),
+  f1: z.number(),
+  precision: z.number(),
+  recall: z.number(),
+  sampleSize: z.number().int(),
+  positives: z.number().int(),
+  negatives: z.number().int(),
+  curve: z.array(CalibrationCurvePointSchema)
+});
+export {
+  CalibrateResultSchema,
+  CalibrationCurvePointSchema,
+  MatchCandidateSchema,
+  MatchComponentsSchema,
+  MatchResultSchema,
+  ResolvedMatchSchema
+};

package/dist/types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);