@almadar/std 16.144.0 → 16.146.0

package/dist/registry.js

@@ -2026,6 +2026,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"]'
   }
 };
 
@@ -4408,9 +4436,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" }
@@ -4422,9 +4450,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" }
@@ -4530,14 +4558,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/std",
-  "version": "16.144.0",
+  "version": "16.146.0",
   "description": "Standard library operators for Almadar (math, string, array, etc.)",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,11 +49,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.34.0"
+    "@almadar/core": "^10.36.0"
   },
   "devDependencies": {
     "@almadar/eslint-plugin": "^2.15.0",
-    "@almadar/llm": "^2.36.0",
+    "@almadar/llm": "^2.37.0",
     "@types/node": "^20.0.0",
     "@typescript-eslint/parser": "8.56.0",
     "eslint": "10.0.0",