@effect-uai/core 0.1.0 → 0.3.0

package/src/loop/Loop.ts

@@ -17,7 +17,19 @@
  * (their producing side effects may already have run). Prefer the
  * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.
  */
-import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream } from "effect"
+import {
+  Cause,
+  Channel,
+  Data,
+  Effect,
+  Exit,
+  Function,
+  Option,
+  Ref,
+  Scope,
+  Stream,
+  SubscriptionRef,
+} from "effect"
 import { IncompleteTurn } from "../domain/AiError.js"
 import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 
@@ -83,7 +95,7 @@ export const stopAfter = <A, E, R>(
  * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
  *
  * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,
- * `build: (s) => s`). Used by `Toolkit.nextStateFrom` to collect tool
+ * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool
  * results and build next state without exposing a Ref to recipes.
  */
 export const nextAfterFold = <A, B, S, E, R>(
@@ -107,7 +119,7 @@ export const nextAfterFold = <A, B, S, E, R>(
   )
 
 // ---------------------------------------------------------------------------
-// streamUntilComplete - turn-aware stream operator for loop bodies
+// onTurnComplete - turn-aware stream operator for loop bodies
 // ---------------------------------------------------------------------------
 
 /**
@@ -125,7 +137,7 @@ export const nextAfterFold = <A, B, S, E, R>(
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
  */
-export const streamUntilComplete =
+export const onTurnComplete =
   <S, A, E2 = never, R2 = never>(
     then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
   ) =>
@@ -162,7 +174,7 @@ export const streamUntilComplete =
 const isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>
   array.length > 0
 
-interface CurrentBody<S, A, E, R> {
+type CurrentBody<S, A, E, R> = {
   readonly scope: Scope.Closeable
   readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>
 }
@@ -293,3 +305,55 @@ export const loop: {
       ),
     ),
 )
+
+// ---------------------------------------------------------------------------
+// loopWithState - same body protocol, plus a live state observable.
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `loop`, but exposes the current loop state as a `SubscriptionRef`
+ * alongside the value stream.
+ *
+ * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the
+ * loop with a wrapped body that taps every `Next(s)` event into the ref
+ * before forwarding it. The caller decides how to consume both channels:
+ *
+ *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
+ *     - the ref holds the state from the last `Next` (or `initial` if the
+ *     loop ended without advancing).
+ *   - **Live transitions**: `SubscriptionRef.changes(state)` is a
+ *     `Stream<S>` of every state observed; subscribe alongside the value
+ *     stream.
+ *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.
+ *
+ * The returned stream and ref are independent of each other - the ref
+ * lives outside the stream's scope, so reading it after the stream
+ * completes is safe.
+ */
+export const loopWithState = <S, A, E, R>(
+  initial: S,
+  body: LoopBody<S, A, E, R>,
+): Effect.Effect<{
+  readonly stream: Stream.Stream<A, E, R>
+  readonly state: SubscriptionRef.SubscriptionRef<S>
+}> =>
+  Effect.gen(function* () {
+    const stateRef = yield* SubscriptionRef.make(initial)
+
+    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>
+      stream.pipe(
+        Stream.tap((event) =>
+          event._tag === "Next" ? SubscriptionRef.set(stateRef, event.state) : Effect.void,
+        ),
+      )
+
+    const wrappedBody: LoopBody<S, A, E, R> = (s) => {
+      const result = body(s)
+      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)
+    }
+
+    return {
+      stream: loop(initial, wrappedBody),
+      state: stateRef,
+    }
+  })

package/src/math/Vector.ts

@@ -0,0 +1,138 @@
+/**
+ * Linear-algebra primitives for embedding vectors:
+ *
+ * - **Dense float32**: `dot`, `l2Norm`, `normalize`, `cosine`,
+ *   `euclidean`. Used for retrieval over single-vector embeddings.
+ * - **Sparse**: `sparseDot`, `sparseL2Norm`, `sparseCosine`. Used with
+ *   `SparseEmbedding`, e.g. Jina ELSER outputs.
+ * - **Multivector** (late-interaction): `maxSim`. Used with
+ *   `MultivectorEmbedding`, e.g. Jina v4 multivector / ColBERT.
+ *
+ * Hot loops are allocation-free; consumers can call these inside
+ * `.map()` over thousands of vectors without GC pressure. For
+ * GPU / SIMD / WASM-accelerated math at vector-DB scale, reach for a
+ * dedicated library - this module deliberately stays at the
+ * recipe-volume tier.
+ */
+import type { MultivectorEmbedding, SparseEmbedding } from "../embedding-model/Embedding.js"
+
+/** Inner / dot product. */
+export const dot = (a: Float32Array, b: Float32Array): number => {
+  let s = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) s += a[i]! * b[i]!
+  return s
+}
+
+/** L2 norm (Euclidean magnitude). */
+export const l2Norm = (v: Float32Array): number => {
+  let s = 0
+  for (let i = 0; i < v.length; i++) s += v[i]! * v[i]!
+  return Math.sqrt(s)
+}
+
+/**
+ * L2-normalize to a unit vector. Allocates a new `Float32Array`. A zero
+ * vector returns zeros (no division-by-zero).
+ */
+export const normalize = (v: Float32Array): Float32Array => {
+  const n = l2Norm(v)
+  if (n === 0) return new Float32Array(v.length)
+  const out = new Float32Array(v.length)
+  for (let i = 0; i < v.length; i++) out[i] = v[i]! / n
+  return out
+}
+
+/**
+ * Cosine similarity. Range `[-1, 1]`; higher = more similar. Returns
+ * `NaN` if either vector has zero magnitude.
+ */
+export const cosine = (a: Float32Array, b: Float32Array): number => {
+  let d = 0
+  let na = 0
+  let nb = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    const ai = a[i]!
+    const bi = b[i]!
+    d += ai * bi
+    na += ai * ai
+    nb += bi * bi
+  }
+  return d / (Math.sqrt(na) * Math.sqrt(nb))
+}
+
+/** Euclidean (L2) distance. */
+export const euclidean = (a: Float32Array, b: Float32Array): number => {
+  let s = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    const d = a[i]! - b[i]!
+    s += d * d
+  }
+  return Math.sqrt(s)
+}
+
+// ---------------------------------------------------------------------------
+// Sparse vectors (Record<string, number>)
+// ---------------------------------------------------------------------------
+
+/** Inner product over the intersection of token keys. */
+export const sparseDot = (a: SparseEmbedding, b: SparseEmbedding): number => {
+  // Iterate the smaller map; lookup against the larger one. O(min(|a|, |b|)).
+  const aSize = Object.keys(a.weights).length
+  const bSize = Object.keys(b.weights).length
+  const [smaller, larger] = aSize <= bSize ? [a.weights, b.weights] : [b.weights, a.weights]
+  let s = 0
+  for (const token in smaller) {
+    const other = larger[token]
+    if (other !== undefined) s += smaller[token]! * other
+  }
+  return s
+}
+
+/** L2 norm of a sparse vector. */
+export const sparseL2Norm = (v: SparseEmbedding): number => {
+  let s = 0
+  for (const token in v.weights) {
+    const w = v.weights[token]!
+    s += w * w
+  }
+  return Math.sqrt(s)
+}
+
+/**
+ * Sparse cosine similarity. Range `[-1, 1]` (typically `[0, 1]` for
+ * learned-sparse encoders since weights are non-negative). Returns
+ * `NaN` if either vector has zero magnitude.
+ */
+export const sparseCosine = (a: SparseEmbedding, b: SparseEmbedding): number =>
+  sparseDot(a, b) / (sparseL2Norm(a) * sparseL2Norm(b))
+
+// ---------------------------------------------------------------------------
+// Multivector / late-interaction (ColBERT-style)
+// ---------------------------------------------------------------------------
+
+/**
+ * MaxSim score for late-interaction retrieval. For each *query* vector,
+ * find the maximum dot product with any *document* vector, then sum.
+ *
+ * Captures fine-grained relevance that single-vector cosine smears out:
+ * each query token finds its own best-matching document token.
+ *
+ * Cost: O(|q| × |d| × dim). Fine at recipe volume; for production-scale
+ * retrieval use a vector store with native multivector indexing
+ * (Vespa, Qdrant, PLAID).
+ */
+export const maxSim = (q: MultivectorEmbedding, d: MultivectorEmbedding): number => {
+  let total = 0
+  for (const qv of q.vectors) {
+    let best = -Infinity
+    for (const dv of d.vectors) {
+      const s = dot(qv, dv)
+      if (s > best) best = s
+    }
+    total += best
+  }
+  return total
+}

package/src/observability/Metrics.ts

@@ -38,7 +38,7 @@ export const timeToFirst =
       Effect.map(Option.map(({ elapsed }) => elapsed)),
     )
 
-export interface RatePoint<A> {
+export type RatePoint<A> = {
   readonly value: A
   readonly total: number
   readonly ratePerSecond: number

package/src/streaming/SSE.ts

@@ -6,7 +6,7 @@ import { Stream } from "effect"
  * - `data`: payload, with multiple `data:` lines joined by `\n`
  * - `id`: optional last-event id
  */
-export interface Event {
+export type Event = {
   readonly event?: string
   readonly data: string
   readonly id?: string

package/src/structured-format/StructuredFormat.ts

@@ -19,7 +19,7 @@ export type StructuredSchema<Output = unknown> = StandardSchemaV1<unknown, Outpu
  * cross-validator schema with metadata providers need (name, description,
  * strict-mode flag).
  */
-export interface StructuredFormat<A> {
+export type StructuredFormat<A> = {
   readonly name: string
   readonly description?: string
   readonly schema: StructuredSchema<A>
@@ -31,7 +31,7 @@ export interface StructuredFormat<A> {
 }
 
 /** A single path-scoped validation problem. Library-agnostic shape. */
-export interface DecodeIssue {
+export type DecodeIssue = {
   readonly path: ReadonlyArray<string | number>
   readonly message: string
 }

package/src/testing/MockProvider.ts

@@ -4,7 +4,7 @@ import type { Item } from "../domain/Items.js"
 import { LanguageModel, type LanguageModelService } from "../language-model/LanguageModel.js"
 import type { Turn, TurnEvent } from "../domain/Turn.js"
 
-export interface MockOptions {
+export type MockOptions = {
   /**
    * If set, deltas of each scripted turn are spaced by this duration via
    * `Schedule.spaced`. Combine with `TestClock.adjust` for deterministic
@@ -19,7 +19,7 @@ export interface MockOptions {
  * deltas (text → tool_call_start → tool_call_args_delta → ... → turn_complete)
  * so streaming consumers can see realistic delta shapes.
  */
-export interface MockRecorder {
+export type MockRecorder = {
   readonly calls: ReadonlyArray<{
     readonly history: ReadonlyArray<Item>
     readonly turn: Turn

package/src/tool/HistoryCheck.ts

@@ -23,9 +23,7 @@ import { type ToolResult, cancelled } from "./Outcome.js"
  * `function_call_output` later in `history` (correlated by `call_id`).
  * Empty result = history is provider-submittable from this invariant.
  */
-export const findUnansweredCalls = (
-  history: ReadonlyArray<Item>,
-): ReadonlyArray<FunctionCall> => {
+export const findUnansweredCalls = (history: ReadonlyArray<Item>): ReadonlyArray<FunctionCall> => {
   const answered = new Set(history.filter(isFunctionCallOutput).map((o) => o.call_id))
   return history.filter(isFunctionCall).filter((c) => !answered.has(c.call_id))
 }
@@ -45,5 +43,4 @@ export const isReconciled = (history: ReadonlyArray<Item>): boolean =>
 export const cancelAllPending = (
   history: ReadonlyArray<Item>,
   reason?: string,
-): ReadonlyArray<ToolResult> =>
-  findUnansweredCalls(history).map((call) => cancelled(call, reason))
+): ReadonlyArray<ToolResult> => findUnansweredCalls(history).map((call) => cancelled(call, reason))

package/src/tool/Outcome.ts

@@ -1,9 +1,8 @@
 /**
- * Pre-execution decision (`ToolDecision`) and post-execution result
- * (`ToolResult`) for the resolver-based executor.
+ * Post-execution and synthetic tool results.
  *
- *   - Resolver returns ToolDecision (Execute | Reject(result)) per call.
- *   - Executor emits ToolResult (Value | Failure) per call.
+ *   - Executed tools emit ToolResult.Value.
+ *   - Approval/cancellation policy emits synthetic ToolResult.Failure.
  *
  * Wire conversion stays at the recipe boundary via `toFunctionCallOutput`
  * so recipes can inspect, redact, or audit values before serialization.
@@ -12,7 +11,7 @@
  * and `unknown` would invite non-serializable values (Date, Map, BigInt,
  * fn). Recipes that want structured detail JSON.stringify themselves.
  */
-import { Match } from "effect"
+import { Data } from "effect"
 import type { FunctionCall, FunctionCallOutput } from "../domain/Items.js"
 import { functionCallOutput } from "../domain/Items.js"
 
@@ -20,55 +19,44 @@ import { functionCallOutput } from "../domain/Items.js"
 // ToolResult
 // ---------------------------------------------------------------------------
 
-export type ToolResult =
-  | {
-      readonly _tag: "Value"
-      readonly call_id: string
-      readonly tool: string
-      readonly value: unknown
-    }
-  | {
-      readonly _tag: "Failure"
-      readonly call_id: string
-      readonly tool: string
-      readonly kind: string
-      readonly reason?: string
-    }
+export type ToolResult = Data.TaggedEnum<{
+  Value: {
+    readonly call_id: string
+    readonly tool: string
+    readonly value: unknown
+  }
+  Failure: {
+    readonly call_id: string
+    readonly tool: string
+    readonly kind: string
+    readonly reason?: string
+  }
+}>
 
-export const isValue = (r: ToolResult): r is Extract<ToolResult, { _tag: "Value" }> =>
-  r._tag === "Value"
-
-export const isFailure = (r: ToolResult): r is Extract<ToolResult, { _tag: "Failure" }> =>
-  r._tag === "Failure"
-
-// ---------------------------------------------------------------------------
-// ToolDecision
-// ---------------------------------------------------------------------------
-
-export type ToolDecision =
-  | { readonly _tag: "Execute" }
-  | { readonly _tag: "Reject"; readonly result: ToolResult }
-
-export const execute: ToolDecision = { _tag: "Execute" }
+/**
+ * Namespace of constructors, type guards, and matchers for `ToolResult`,
+ * provided by `Data.taggedEnum`. Use `ToolResult.$is("Value")` for type
+ * narrowing and `ToolResult.$match({ Value, Failure })` for exhaustive
+ * pattern matching. Synthetic-result helpers (`denied`, `cancelled`,
+ * `executionError`, `rejected`) below are kinder constructors than the
+ * raw `ToolResult.Failure(...)`.
+ */
+export const ToolResult = Data.taggedEnum<ToolResult>()
 
-export const reject = (result: ToolResult): ToolDecision => ({ _tag: "Reject", result })
+export const isValue = ToolResult.$is("Value")
+export const isFailure = ToolResult.$is("Failure")
 
-// ---------------------------------------------------------------------------
 // Synthesizers. `denied` and `cancelled` are operationally distinct;
 // anything else is just a recipe-chosen `kind` via `rejected`.
 // ---------------------------------------------------------------------------
 
-export const rejected = (
-  call: FunctionCall,
-  kind: string,
-  reason?: string,
-): ToolResult => ({
-  _tag: "Failure",
-  call_id: call.call_id,
-  tool: call.name,
-  kind,
-  ...(reason !== undefined ? { reason } : {}),
-})
+export const rejected = (call: FunctionCall, kind: string, reason?: string): ToolResult =>
+  ToolResult.Failure({
+    call_id: call.call_id,
+    tool: call.name,
+    kind,
+    ...(reason !== undefined ? { reason } : {}),
+  })
 
 /** Explicit user/policy rejection. */
 export const denied = (call: FunctionCall, reason?: string): ToolResult =>
@@ -87,15 +75,13 @@ export const executionError = (call: FunctionCall, reason: string): ToolResult =
 // ---------------------------------------------------------------------------
 
 export const toFunctionCallOutput = (r: ToolResult): FunctionCallOutput =>
-  Match.value(r).pipe(
-    Match.tag("Value", (v) => functionCallOutput(v.call_id, JSON.stringify(v.value))),
-    Match.tag("Failure", (f) =>
+  ToolResult.$match(r, {
+    Value: (v) => functionCallOutput(v.call_id, JSON.stringify(v.value)),
+    Failure: (f) =>
       functionCallOutput(
         f.call_id,
         JSON.stringify(
           f.reason !== undefined ? { kind: f.kind, reason: f.reason } : { kind: f.kind },
         ),
       ),
-    ),
-    Match.exhaustive,
-  )
+  })