@almadar/std 16.143.0 → 16.145.0

package/dist/modules/array.js

@@ -565,6 +565,34 @@ var ARRAY_OPERATORS = {
       { name: "n", type: "number", description: "Number of elements to skip" }
     ],
     example: '["array/dropLast", "@items", 2]'
+  },
+  "array/cosine": {
+    module: "array",
+    category: "std-array",
+    minArity: 2,
+    maxArity: 2,
+    description: 'Cosine similarity between two numeric vectors, in [-1, 1] (1 = identical direction). The building block for "is this answer semantically the reference answer" checks over embeddings. Pure math \u2014 usable in guards and value position, unlike the async llm/* substrate operators.',
+    hasSideEffects: false,
+    returnType: "number",
+    params: [
+      { name: "a", type: { kind: "array", of: "number" }, description: "First vector" },
+      { name: "b", type: { kind: "array", of: "number" }, description: "Second vector" }
+    ],
+    example: '["array/cosine", "@entity.answerEmbedding", "@entity.referenceEmbedding"]'
+  },
+  "array/nearest": {
+    module: "array",
+    category: "std-array",
+    minArity: 2,
+    maxArity: 2,
+    description: "Find the candidate vector nearest a query vector by cosine similarity. Returns { index, score, margin } \u2014 index/score of the best match, and margin (best score minus second-best), which is what makes an abstaining gate possible: a small margin means the top match is not confidently distinguished from the runner-up.",
+    hasSideEffects: false,
+    returnType: "object",
+    params: [
+      { name: "query", type: { kind: "array", of: "number" }, description: "Query vector" },
+      { name: "candidates", type: { kind: "array", of: { kind: "array", of: "number" } }, description: "Candidate vectors to search" }
+    ],
+    example: '["array/nearest", "@entity.queryEmbedding", "@entity.candidateEmbeddings"]'
   }
 };
 function getArrayOperators() {

package/dist/modules/contract.js

@@ -8,9 +8,9 @@ var CONTRACT_OPERATORS = {
     category: "ml-contract",
     minArity: 2,
     maxArity: 2,
-    description: "Validate tensor against input contract",
+    description: "Validate tensor against input contract. Returns { valid, violations } \u2014 guard on `valid`, or read `violations` for the detail.",
     hasSideEffects: false,
-    returnType: "boolean",
+    returnType: "object",
     params: [
       { name: "tensor", type: "tensor", description: "Input tensor" },
       { name: "contract", type: "object", description: "Input contract spec" }
@@ -22,9 +22,9 @@ var CONTRACT_OPERATORS = {
     category: "ml-contract",
     minArity: 2,
     maxArity: 2,
-    description: "Validate tensor against output contract",
+    description: "Validate tensor against output contract. Returns { valid, violations } \u2014 guard on `valid`, or read `violations` for the detail.",
     hasSideEffects: false,
-    returnType: "boolean",
+    returnType: "object",
     params: [
       { name: "tensor", type: "tensor", description: "Output tensor" },
       { name: "contract", type: "object", description: "Output contract spec" }

package/dist/modules/data.js

@@ -36,14 +36,14 @@ var DATA_OPERATORS = {
     category: "ml-data",
     minArity: 2,
     maxArity: 2,
-    description: "Train/val/test split",
+    description: "Train/validation split. Config carries `trainRatio` (default 0.8); the remainder is the validation split.",
     hasSideEffects: false,
     returnType: "array",
     params: [
       { name: "dataset", type: "object", description: "Dataset" },
-      { name: "ratios", type: "array", description: "Split ratios e.g. [0.8, 0.1, 0.1]" }
+      { name: "config", type: "object", description: "Split config, e.g. { trainRatio: 0.8 }" }
     ],
-    example: '["data/split", "@entity.dataset", [0.8, 0.1, 0.1]]'
+    example: '["data/split", "@entity.dataset", { "trainRatio": 0.8 }]'
   },
   // ============================================================================
   // Preprocessing

package/dist/modules/index.js

@@ -1988,6 +1988,34 @@ var ARRAY_OPERATORS = {
       { name: "n", type: "number", description: "Number of elements to skip" }
     ],
     example: '["array/dropLast", "@items", 2]'
+  },
+  "array/cosine": {
+    module: "array",
+    category: "std-array",
+    minArity: 2,
+    maxArity: 2,
+    description: 'Cosine similarity between two numeric vectors, in [-1, 1] (1 = identical direction). The building block for "is this answer semantically the reference answer" checks over embeddings. Pure math \u2014 usable in guards and value position, unlike the async llm/* substrate operators.',
+    hasSideEffects: false,
+    returnType: "number",
+    params: [
+      { name: "a", type: { kind: "array", of: "number" }, description: "First vector" },
+      { name: "b", type: { kind: "array", of: "number" }, description: "Second vector" }
+    ],
+    example: '["array/cosine", "@entity.answerEmbedding", "@entity.referenceEmbedding"]'
+  },
+  "array/nearest": {
+    module: "array",
+    category: "std-array",
+    minArity: 2,
+    maxArity: 2,
+    description: "Find the candidate vector nearest a query vector by cosine similarity. Returns { index, score, margin } \u2014 index/score of the best match, and margin (best score minus second-best), which is what makes an abstaining gate possible: a small margin means the top match is not confidently distinguished from the runner-up.",
+    hasSideEffects: false,
+    returnType: "object",
+    params: [
+      { name: "query", type: { kind: "array", of: "number" }, description: "Query vector" },
+      { name: "candidates", type: { kind: "array", of: { kind: "array", of: "number" } }, description: "Candidate vectors to search" }
+    ],
+    example: '["array/nearest", "@entity.queryEmbedding", "@entity.candidateEmbeddings"]'
   }
 };
 function getArrayOperators() {
@@ -4403,9 +4431,9 @@ var CONTRACT_OPERATORS = {
     category: "ml-contract",
     minArity: 2,
     maxArity: 2,
-    description: "Validate tensor against input contract",
+    description: "Validate tensor against input contract. Returns { valid, violations } \u2014 guard on `valid`, or read `violations` for the detail.",
     hasSideEffects: false,
-    returnType: "boolean",
+    returnType: "object",
     params: [
       { name: "tensor", type: "tensor", description: "Input tensor" },
       { name: "contract", type: "object", description: "Input contract spec" }
@@ -4417,9 +4445,9 @@ var CONTRACT_OPERATORS = {
     category: "ml-contract",
     minArity: 2,
     maxArity: 2,
-    description: "Validate tensor against output contract",
+    description: "Validate tensor against output contract. Returns { valid, violations } \u2014 guard on `valid`, or read `violations` for the detail.",
     hasSideEffects: false,
-    returnType: "boolean",
+    returnType: "object",
     params: [
       { name: "tensor", type: "tensor", description: "Output tensor" },
       { name: "contract", type: "object", description: "Output contract spec" }
@@ -4528,14 +4556,14 @@ var DATA_OPERATORS = {
     category: "ml-data",
     minArity: 2,
     maxArity: 2,
-    description: "Train/val/test split",
+    description: "Train/validation split. Config carries `trainRatio` (default 0.8); the remainder is the validation split.",
     hasSideEffects: false,
     returnType: "array",
     params: [
       { name: "dataset", type: "object", description: "Dataset" },
-      { name: "ratios", type: "array", description: "Split ratios e.g. [0.8, 0.1, 0.1]" }
+      { name: "config", type: "object", description: "Split config, e.g. { trainRatio: 0.8 }" }
     ],
-    example: '["data/split", "@entity.dataset", [0.8, 0.1, 0.1]]'
+    example: '["data/split", "@entity.dataset", { "trainRatio": 0.8 }]'
   },
   // ============================================================================
   // Preprocessing