@effect-uai/core 0.16.0 → 0.17.0

package/src/index.ts

@@ -6,6 +6,8 @@ export * as BrowserTool from "./browser/BrowserTool.js"
 export * as Capabilities from "./capabilities/Capabilities.js"
 export * as Chunker from "./chunker/Chunker.js"
 export * as Citation from "./domain/Citation.js"
+export * as Decision from "./decision-model/Decision.js"
+export * as DecisionModel from "./decision-model/DecisionModel.js"
 export * as DeepResearch from "./research/DeepResearch.js"
 export * as Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
@@ -37,6 +39,7 @@ export * as WebRead from "./web-read/WebRead.js"
 export * as WebReadTool from "./web-read/WebReadTool.js"
 export * as WebSearch from "./web-search/WebSearch.js"
 export * as WebSearchTool from "./web-search/WebSearchTool.js"
+export * as Probability from "./math/Probability.js"
 export * as Vector from "./math/Vector.js"
 export * as Tokenizer from "./tokenizer/Tokenizer.js"
 export * as Settle from "./streaming/Settle.js"

package/src/math/Probability.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest"
+import { confidence, margin } from "./Probability.js"
+
+describe("confidence", () => {
+  it("is 1 when all mass sits on one outcome", () => {
+    expect(confidence([1, 0, 0])).toBeCloseTo(1, 10)
+  })
+
+  it("is 0 when mass is spread evenly, at any length", () => {
+    expect(confidence([0.5, 0.5])).toBeCloseTo(0, 10)
+    expect(confidence([0.25, 0.25, 0.25, 0.25])).toBeCloseTo(0, 10)
+  })
+
+  it("is 1 for fewer than two outcomes, which have nothing to be uncertain between", () => {
+    expect(confidence([])).toBe(1)
+    expect(confidence([1])).toBe(1)
+  })
+
+  it("rises as mass concentrates", () => {
+    const spread = confidence([0.4, 0.35, 0.25])
+    const leaning = confidence([0.6, 0.25, 0.15])
+    const decided = confidence([0.9, 0.07, 0.03])
+    expect(spread).toBeLessThan(leaning)
+    expect(leaning).toBeLessThan(decided)
+  })
+
+  it("is conservative on two outcomes, so a threshold does not transfer across lengths", () => {
+    expect(confidence([0.94, 0.06])).toBeCloseTo(0.67, 2)
+  })
+})
+
+describe("margin", () => {
+  it("is the gap between the top two, whatever order they arrive in", () => {
+    expect(margin([0.6, 0.3, 0.1])).toBeCloseTo(0.3, 10)
+    expect(margin([0.1, 0.6, 0.3])).toBeCloseTo(0.3, 10)
+  })
+
+  it("is 0 on a tie and 0 when empty", () => {
+    expect(margin([0.5, 0.5])).toBeCloseTo(0, 10)
+    expect(margin([])).toBe(0)
+  })
+
+  it("yields the lone probability for a single outcome", () => {
+    expect(margin([0.7])).toBeCloseTo(0.7, 10)
+  })
+})
+
+describe("confidence and margin disagree, which is why both exist", () => {
+  // Two plausible answers versus no idea. Same winner, same top mass.
+  const closeSecond = [0.45, 0.42, 0.13]
+  const flatSpread = [0.45, 0.11, 0.11, 0.11, 0.11, 0.11]
+
+  it("confidence cannot separate them", () => {
+    expect(Math.abs(confidence(closeSecond) - confidence(flatSpread))).toBeLessThan(0.05)
+  })
+
+  it("margin separates them sharply", () => {
+    expect(margin(closeSecond)).toBeCloseTo(0.03, 10)
+    expect(margin(flatSpread)).toBeCloseTo(0.34, 10)
+  })
+})

package/src/math/Probability.ts

@@ -0,0 +1,44 @@
+/** Certainty measures over a probability vector. */
+import { Array as A, Number as N, Option, Order, pipe } from "effect"
+
+const descending = Order.flip(Order.Number)
+
+/**
+ * 1 minus normalized Shannon entropy: 1 when all mass sits on one outcome, 0
+ * when spread evenly. Fewer than two outcomes yields 1.
+ *
+ * Conservative on two outcomes, where `[0.94, 0.06]` scores ~0.67, so a
+ * threshold tuned on a long vector does not transfer. {@link margin} is the
+ * more stable gate across vectors of different length.
+ */
+export const confidence = (probabilities: ReadonlyArray<number>): number =>
+  probabilities.length < 2
+    ? 1
+    : 1 -
+      pipe(
+        probabilities,
+        A.filter((p) => p > 0),
+        A.map((p) => -p * Math.log(p)),
+        N.sumAll,
+      ) /
+        Math.log(probabilities.length)
+
+/**
+ * Top mass minus runner-up mass, which unlike {@link confidence} separates a
+ * close second from a flat spread. A single outcome yields its own
+ * probability; empty yields 0.
+ */
+export const margin = (probabilities: ReadonlyArray<number>): number => {
+  const top = pipe(probabilities, A.sort(descending), A.take(2))
+  return pipe(
+    A.get(top, 0),
+    Option.map((first) =>
+      pipe(
+        A.get(top, 1),
+        Option.getOrElse(() => 0),
+        (second) => first - second,
+      ),
+    ),
+    Option.getOrElse(() => 0),
+  )
+}