@almadar/std 16.144.0 → 16.146.0

package/dist/behaviors/registry/ml/atoms/std-ml-similarity.orb

@@ -0,0 +1,917 @@
+{
+  "description": "Retrieval rung (R3) — embed a candidate against references and gate on cosine floor + margin; abstains when not confident.",
+  "ledger": {
+    "entries": {
+      "ent_01KYBN0QT9997QBWPF6WFF1CMM": {
+        "bakedName": "SimilarityComparison",
+        "curName": "SimilarityComparison",
+        "id": "ent_01KYBN0QT9997QBWPF6WFF1CMM",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "evt_01KYBN0QT9A6WZFFTCVGBHF2BT": {
+        "bakedName": "RESET",
+        "curName": "RESET",
+        "id": "evt_01KYBN0QT9A6WZFFTCVGBHF2BT",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9ACZNZH01MYKGTXYX": {
+        "bakedName": "EMBED_FAILED",
+        "curName": "EMBED_FAILED",
+        "id": "evt_01KYBN0QT9ACZNZH01MYKGTXYX",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9FX93HBXP52KRNVX6": {
+        "bakedName": "COMPARE",
+        "curName": "COMPARE",
+        "id": "evt_01KYBN0QT9FX93HBXP52KRNVX6",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9K8NXCX7AMQ2VTNWX": {
+        "bakedName": "SIMILARITY_ABSTAINED",
+        "curName": "SIMILARITY_ABSTAINED",
+        "id": "evt_01KYBN0QT9K8NXCX7AMQ2VTNWX",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9KC3AMM14E9M55ACF": {
+        "bakedName": "SIMILARITY_MATCHED",
+        "curName": "SIMILARITY_MATCHED",
+        "id": "evt_01KYBN0QT9KC3AMM14E9M55ACF",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9WZDN3FMC3T36ACHS": {
+        "bakedName": "EMBEDDED",
+        "curName": "EMBEDDED",
+        "id": "evt_01KYBN0QT9WZDN3FMC3T36ACHS",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "evt_01KYBN0QT9ZTTW50RCT84MH8H1": {
+        "bakedName": "INIT",
+        "curName": "INIT",
+        "id": "evt_01KYBN0QT9ZTTW50RCT84MH8H1",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "renames": []
+      },
+      "orb_01KYBN0QT97QXM5727TNZZSS1B": {
+        "bakedName": "MlSimilarityOrbital",
+        "curName": "MlSimilarityOrbital",
+        "id": "orb_01KYBN0QT97QXM5727TNZZSS1B",
+        "kind": "orbital",
+        "owner": "workspace",
+        "renames": []
+      },
+      "pag_01KYBN0QT9YB0Q6ZEZWC560YEN": {
+        "bakedName": "MlSimilarityPage",
+        "curName": "MlSimilarityPage",
+        "id": "pag_01KYBN0QT9YB0Q6ZEZWC560YEN",
+        "kind": "page",
+        "owner": "workspace",
+        "renames": []
+      },
+      "trt_01KYBN0QT9C1SZTVGAG9X3YA5X": {
+        "bakedName": "SimilarityRun",
+        "curName": "SimilarityRun",
+        "id": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+        "kind": "trait",
+        "owner": "workspace",
+        "renames": []
+      }
+    },
+    "schemaVersion": 1
+  },
+  "name": "std-ml-similarity",
+  "orbitals": [
+    {
+      "entity": {
+        "fields": [
+          {
+            "default": "",
+            "name": "query",
+            "type": "string"
+          },
+          {
+            "default": [],
+            "items": {
+              "type": "string"
+            },
+            "name": "candidates",
+            "type": "array"
+          },
+          {
+            "default": [],
+            "items": {
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "name": "embeddings",
+            "type": "array"
+          },
+          {
+            "default": [],
+            "items": {
+              "type": "number"
+            },
+            "name": "queryVector",
+            "type": "array"
+          },
+          {
+            "default": [],
+            "items": {
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            "name": "candidateVectors",
+            "type": "array"
+          },
+          {
+            "default": 0.0,
+            "name": "matchIndex",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "name": "matchScore",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "name": "matchMargin",
+            "type": "number"
+          },
+          {
+            "default": "",
+            "name": "reason",
+            "type": "string"
+          },
+          {
+            "default": {},
+            "name": "request",
+            "type": "object"
+          },
+          {
+            "default": "idle",
+            "name": "status",
+            "type": "string",
+            "values": [
+              "idle",
+              "embedding",
+              "resolved"
+            ]
+          }
+        ],
+        "id": "ent_01KYBN0QT9997QBWPF6WFF1CMM",
+        "name": "SimilarityComparison",
+        "persistence": "runtime"
+      },
+      "id": "orb_01KYBN0QT97QXM5727TNZZSS1B",
+      "name": "MlSimilarityOrbital",
+      "pages": [
+        {
+          "id": "pag_01KYBN0QT9YB0Q6ZEZWC560YEN",
+          "name": "MlSimilarityPage",
+          "path": "/ml-similarity",
+          "traits": [
+            {
+              "ref": "SimilarityRun",
+              "refId": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X"
+            }
+          ]
+        }
+      ],
+      "traits": [
+        {
+          "category": "lifecycle",
+          "config": {
+            "embedModel": {
+              "default": "",
+              "description": "Reserved for embedding-model selection; llm/embed takes only a texts array today, so this knob is not yet wired into the call",
+              "label": "Embedding model",
+              "tier": "infra",
+              "type": "string"
+            },
+            "floor": {
+              "default": 0.82,
+              "description": "Minimum cosine score for a confident match",
+              "label": "Match floor",
+              "tier": "policy",
+              "type": "float"
+            },
+            "margin": {
+              "default": 0.05,
+              "description": "Minimum gap between the best and second-best score required to trust the match",
+              "label": "Match margin",
+              "tier": "policy",
+              "type": "float"
+            }
+          },
+          "emits": [
+            {
+              "description": "Raw embeddings from llm/embed — query vector at index 0, candidate vectors following in input order",
+              "event": "EMBEDDED",
+              "eventId": "evt_01KYBN0QT9WZDN3FMC3T36ACHS",
+              "payloadSchema": [
+                {
+                  "name": "result",
+                  "required": true,
+                  "type": "[[float]]"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "Candidate matched with high confidence — score at or above floor, with a clear margin over the runner-up",
+              "event": "SIMILARITY_MATCHED",
+              "eventId": "evt_01KYBN0QT9KC3AMM14E9M55ACF",
+              "payloadSchema": [
+                {
+                  "name": "index",
+                  "required": true,
+                  "type": "int"
+                },
+                {
+                  "name": "score",
+                  "required": true,
+                  "type": "float"
+                }
+              ],
+              "scope": "external",
+              "tier": "primary"
+            },
+            {
+              "description": "No confident match — reason is one of: empty candidate list, below floor, thin margin, embedding unavailable. request echoes the originating request untouched so the next rung can project its own inputs out of it",
+              "event": "SIMILARITY_ABSTAINED",
+              "eventId": "evt_01KYBN0QT9K8NXCX7AMQ2VTNWX",
+              "payloadSchema": [
+                {
+                  "name": "reason",
+                  "required": true,
+                  "type": "string"
+                },
+                {
+                  "name": "request",
+                  "type": "object"
+                }
+              ],
+              "scope": "external",
+              "tier": "primary"
+            }
+          ],
+          "entityRefIds": {
+            "SimilarityComparison": "ent_01KYBN0QT9997QBWPF6WFF1CMM"
+          },
+          "id": "trt_01KYBN0QT9C1SZTVGAG9X3YA5X",
+          "linkedEntity": "SimilarityComparison",
+          "linkedEntityId": "ent_01KYBN0QT9997QBWPF6WFF1CMM",
+          "name": "SimilarityRun",
+          "scope": "instance",
+          "stateMachine": {
+            "events": [
+              {
+                "id": "evt_01KYBN0QT9ZTTW50RCT84MH8H1",
+                "key": "INIT",
+                "name": "Initialize"
+              },
+              {
+                "id": "evt_01KYBN0QT9FX93HBXP52KRNVX6",
+                "key": "COMPARE",
+                "name": "Compare",
+                "payloadSchema": [
+                  {
+                    "name": "query",
+                    "required": true,
+                    "type": "string"
+                  },
+                  {
+                    "name": "candidates",
+                    "required": true,
+                    "type": "[string]"
+                  },
+                  {
+                    "name": "request",
+                    "type": "object"
+                  }
+                ]
+              },
+              {
+                "description": "Raw embeddings from llm/embed — query vector at index 0, candidate vectors following in input order",
+                "id": "evt_01KYBN0QT9WZDN3FMC3T36ACHS",
+                "key": "EMBEDDED",
+                "name": "Embedded",
+                "payloadSchema": [
+                  {
+                    "name": "result",
+                    "required": true,
+                    "type": "[[float]]"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "id": "evt_01KYBN0QT9ACZNZH01MYKGTXYX",
+                "key": "EMBED_FAILED",
+                "name": "Embed Failed"
+              },
+              {
+                "id": "evt_01KYBN0QT9A6WZFFTCVGBHF2BT",
+                "key": "RESET",
+                "name": "Reset"
+              },
+              {
+                "description": "Candidate matched with high confidence — score at or above floor, with a clear margin over the runner-up",
+                "id": "evt_01KYBN0QT9KC3AMM14E9M55ACF",
+                "key": "SIMILARITY_MATCHED",
+                "name": "Similarity Matched",
+                "payloadSchema": [
+                  {
+                    "name": "index",
+                    "required": true,
+                    "type": "int"
+                  },
+                  {
+                    "name": "score",
+                    "required": true,
+                    "type": "float"
+                  }
+                ],
+                "tier": "primary"
+              },
+              {
+                "description": "No confident match — reason is one of: empty candidate list, below floor, thin margin, embedding unavailable. request echoes the originating request untouched so the next rung can project its own inputs out of it",
+                "id": "evt_01KYBN0QT9K8NXCX7AMQ2VTNWX",
+                "key": "SIMILARITY_ABSTAINED",
+                "name": "Similarity Abstained",
+                "payloadSchema": [
+                  {
+                    "name": "reason",
+                    "required": true,
+                    "type": "string"
+                  },
+                  {
+                    "name": "request",
+                    "type": "object"
+                  }
+                ],
+                "tier": "primary"
+              }
+            ],
+            "states": [
+              {
+                "isInitial": true,
+                "name": "idle"
+              },
+              {
+                "name": "embedding"
+              },
+              {
+                "name": "resolved"
+              }
+            ],
+            "transitions": [
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.query",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.candidates",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.embeddings",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.queryVector",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.candidateVectors",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.matchIndex",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchScore",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchMargin",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.reason",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.request",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ]
+                ],
+                "event": "INIT",
+                "eventId": "evt_01KYBN0QT9ZTTW50RCT84MH8H1",
+                "from": "idle",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.query",
+                    "@payload.query"
+                  ],
+                  [
+                    "set",
+                    "@entity.candidates",
+                    "@payload.candidates"
+                  ],
+                  [
+                    "set",
+                    "@entity.request",
+                    "@payload.request"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "embedding"
+                  ],
+                  [
+                    "llm/embed",
+                    [
+                      "array/prepend",
+                      "@payload.candidates",
+                      "@payload.query"
+                    ],
+                    {
+                      "emit": {
+                        "failure": "EMBED_FAILED",
+                        "success": "EMBEDDED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "COMPARE",
+                "eventId": "evt_01KYBN0QT9FX93HBXP52KRNVX6",
+                "from": "idle",
+                "guard": [
+                  ">",
+                  [
+                    "array/len",
+                    "@payload.candidates"
+                  ],
+                  0.0
+                ],
+                "to": "embedding"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.query",
+                    "@payload.query"
+                  ],
+                  [
+                    "set",
+                    "@entity.candidates",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.embeddings",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.queryVector",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.candidateVectors",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.matchIndex",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchScore",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchMargin",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.reason",
+                    "empty candidate list"
+                  ],
+                  [
+                    "set",
+                    "@entity.request",
+                    "@payload.request"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "resolved"
+                  ],
+                  [
+                    "emit",
+                    "SIMILARITY_ABSTAINED",
+                    {
+                      "reason": "empty candidate list",
+                      "request": "@entity.request"
+                    }
+                  ]
+                ],
+                "event": "COMPARE",
+                "eventId": "evt_01KYBN0QT9FX93HBXP52KRNVX6",
+                "from": "idle",
+                "guard": [
+                  "==",
+                  [
+                    "array/len",
+                    "@payload.candidates"
+                  ],
+                  0.0
+                ],
+                "to": "resolved"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.embeddings",
+                    "@payload.result"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "resolved"
+                  ],
+                  [
+                    "if",
+                    [
+                      "<",
+                      [
+                        "array/len",
+                        "@payload.result"
+                      ],
+                      2.0
+                    ],
+                    [
+                      "do",
+                      [
+                        "set",
+                        "@entity.queryVector",
+                        []
+                      ],
+                      [
+                        "set",
+                        "@entity.candidateVectors",
+                        []
+                      ],
+                      [
+                        "set",
+                        "@entity.matchIndex",
+                        0.0
+                      ],
+                      [
+                        "set",
+                        "@entity.matchScore",
+                        0.0
+                      ],
+                      [
+                        "set",
+                        "@entity.matchMargin",
+                        0.0
+                      ],
+                      [
+                        "set",
+                        "@entity.reason",
+                        "embedding result incomplete"
+                      ],
+                      [
+                        "emit",
+                        "SIMILARITY_ABSTAINED",
+                        {
+                          "reason": "embedding result incomplete",
+                          "request": "@entity.request"
+                        }
+                      ]
+                    ],
+                    [
+                      "do",
+                      [
+                        "set",
+                        "@entity.queryVector",
+                        [
+                          "array/first",
+                          "@entity.embeddings"
+                        ]
+                      ],
+                      [
+                        "set",
+                        "@entity.candidateVectors",
+                        [
+                          "array/drop",
+                          "@entity.embeddings",
+                          1.0
+                        ]
+                      ],
+                      [
+                        "let",
+                        [
+                          [
+                            "nearest",
+                            [
+                              "array/nearest",
+                              "@entity.queryVector",
+                              "@entity.candidateVectors"
+                            ]
+                          ]
+                        ],
+                        [
+                          "do",
+                          [
+                            "set",
+                            "@entity.matchIndex",
+                            [
+                              "object/get",
+                              "@nearest",
+                              "index"
+                            ]
+                          ],
+                          [
+                            "set",
+                            "@entity.matchScore",
+                            [
+                              "object/get",
+                              "@nearest",
+                              "score"
+                            ]
+                          ],
+                          [
+                            "set",
+                            "@entity.matchMargin",
+                            [
+                              "object/get",
+                              "@nearest",
+                              "margin"
+                            ]
+                          ],
+                          [
+                            "if",
+                            [
+                              "and",
+                              [
+                                ">=",
+                                "@entity.matchScore",
+                                "@config.floor"
+                              ],
+                              [
+                                ">=",
+                                "@entity.matchMargin",
+                                "@config.margin"
+                              ]
+                            ],
+                            [
+                              "do",
+                              [
+                                "set",
+                                "@entity.reason",
+                                ""
+                              ],
+                              [
+                                "emit",
+                                "SIMILARITY_MATCHED",
+                                {
+                                  "index": "@entity.matchIndex",
+                                  "score": "@entity.matchScore"
+                                }
+                              ]
+                            ],
+                            [
+                              "do",
+                              [
+                                "set",
+                                "@entity.reason",
+                                [
+                                  "if",
+                                  [
+                                    "<",
+                                    "@entity.matchScore",
+                                    "@config.floor"
+                                  ],
+                                  "below floor",
+                                  "thin margin"
+                                ]
+                              ],
+                              [
+                                "emit",
+                                "SIMILARITY_ABSTAINED",
+                                {
+                                  "reason": "@entity.reason",
+                                  "request": "@entity.request"
+                                }
+                              ]
+                            ]
+                          ]
+                        ]
+                      ]
+                    ]
+                  ]
+                ],
+                "event": "EMBEDDED",
+                "eventId": "evt_01KYBN0QT9WZDN3FMC3T36ACHS",
+                "from": "embedding",
+                "to": "resolved"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.embeddings",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.queryVector",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.candidateVectors",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.matchIndex",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchScore",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchMargin",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.reason",
+                    "embedding unavailable"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "resolved"
+                  ],
+                  [
+                    "emit",
+                    "SIMILARITY_ABSTAINED",
+                    {
+                      "reason": "embedding unavailable",
+                      "request": "@entity.request"
+                    }
+                  ]
+                ],
+                "event": "EMBED_FAILED",
+                "eventId": "evt_01KYBN0QT9ACZNZH01MYKGTXYX",
+                "from": "embedding",
+                "to": "resolved"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "resolved"
+                  ]
+                ],
+                "event": "INIT",
+                "eventId": "evt_01KYBN0QT9ZTTW50RCT84MH8H1",
+                "from": "resolved",
+                "to": "resolved"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.query",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.candidates",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.embeddings",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.queryVector",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.candidateVectors",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.matchIndex",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchScore",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.matchMargin",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.reason",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.request",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ]
+                ],
+                "event": "RESET",
+                "eventId": "evt_01KYBN0QT9A6WZFFTCVGBHF2BT",
+                "from": "resolved",
+                "to": "idle"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "schemaVersion": 1,
+  "version": "1.0.0"
+}