@llm4ts/core 0.1.0

package/src/ProcessExecutor.ts

@@ -0,0 +1,157 @@
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import type * as Queue from "effect/Queue"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { InvalidRequestError, ProviderError, type LlmError } from "./Errors.ts"
+
+const emptyLines: ReadonlyArray<string> = Object.freeze([])
+const emptyEnvironment: Readonly<Record<string, string>> = Object.freeze({})
+
+export class ProcessResult extends Schema.Class<ProcessResult>("ProcessResult")({
+  stdout: Schema.Array(Schema.String),
+  exitCode: Schema.Int,
+  stderr: Schema.Array(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyLines))
+  )
+}) {}
+
+export class ProcessInvocation extends Schema.Class<ProcessInvocation>("ProcessInvocation")({
+  argv: Schema.Array(Schema.String),
+  cwd: Schema.String,
+  envVars: Schema.Record(Schema.String, Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.succeed(emptyEnvironment))
+  ),
+  stdin: Schema.optionalKey(Schema.String),
+  streaming: Schema.Boolean
+}) {}
+
+export type BidirectionalProcess = readonly [
+  stdin: Queue.Queue<string>,
+  stdout: Stream.Stream<string, LlmError>
+]
+
+export interface ProcessExecutorShape {
+  readonly run: (
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>>
+  ) => Effect.Effect<ProcessResult, LlmError>
+  readonly runStreaming: (
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>>
+  ) => Stream.Stream<string, LlmError>
+  readonly runWithStdin: (
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>>,
+    stdin: string
+  ) => Effect.Effect<ProcessResult, LlmError>
+  readonly runStreamingWithStdin: (
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>>,
+    stdin: string
+  ) => Stream.Stream<string, LlmError>
+  readonly runBidirectional: (
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>>
+  ) => Effect.Effect<BidirectionalProcess, LlmError, Scope.Scope>
+}
+
+export class ProcessExecutor extends Context.Service<ProcessExecutor, ProcessExecutorShape>()(
+  "@llm4ts/core/ProcessExecutor"
+) {}
+
+export interface ProcessExecutorPrimitives {
+  readonly run: ProcessExecutorShape["run"]
+  readonly runStreaming: ProcessExecutorShape["runStreaming"]
+  readonly runWithStdin?: ProcessExecutorShape["runWithStdin"]
+  readonly runStreamingWithStdin?: ProcessExecutorShape["runStreamingWithStdin"]
+  readonly runBidirectional?: ProcessExecutorShape["runBidirectional"]
+}
+
+export const makeProcessExecutor = (
+  primitives: ProcessExecutorPrimitives
+): ProcessExecutorShape => ({
+  run: primitives.run,
+  runStreaming: primitives.runStreaming,
+  runWithStdin:
+    primitives.runWithStdin ?? ((argv, cwd, envVars, _stdin) => primitives.run(argv, cwd, envVars)),
+  runStreamingWithStdin:
+    primitives.runStreamingWithStdin ??
+    ((argv, cwd, envVars, _stdin) => primitives.runStreaming(argv, cwd, envVars)),
+  runBidirectional:
+    primitives.runBidirectional ??
+    ((argv, _cwd, _envVars) =>
+      Effect.fail(
+        InvalidRequestError.make({
+          message: `${argv[0] ?? "process"} does not support bidirectional sessions`
+        })
+      ))
+})
+
+export const processCommandKey = (argv: ReadonlyArray<string>): string => JSON.stringify(argv)
+
+export interface FakeProcessExecutor {
+  readonly executor: ProcessExecutorShape
+  readonly recorded: Effect.Effect<ReadonlyArray<ProcessInvocation>>
+}
+
+export interface FakeProcessPlan {
+  readonly responses?: ReadonlyMap<string, ProcessResult>
+  readonly streamResponses?: ReadonlyMap<string, ReadonlyArray<string>>
+}
+
+export const makeFakeProcessExecutor = Effect.fn("@llm4ts/core/ProcessExecutor.makeFake")(
+  function* (plan: FakeProcessPlan = {}): Effect.fn.Return<FakeProcessExecutor> {
+    const invocations = yield* Ref.make<ReadonlyArray<ProcessInvocation>>([])
+    const record = (invocation: ProcessInvocation): Effect.Effect<void> =>
+      Ref.update(invocations, (current) => [...current, invocation])
+
+    const executor = makeProcessExecutor({
+      run: (argv, cwd, envVars) => {
+        const invocation = ProcessInvocation.make({
+          argv,
+          cwd,
+          envVars,
+          streaming: false
+        })
+        const response = plan.responses?.get(processCommandKey(argv))
+        return record(invocation).pipe(
+          Effect.andThen(
+            response === undefined
+              ? Effect.fail(
+                  ProviderError.make({
+                    message: `No fake response for argv: ${argv.join(" ")}`
+                  })
+                )
+              : Effect.succeed(response)
+          )
+        )
+      },
+      runStreaming: (argv, cwd, envVars) => {
+        const invocation = ProcessInvocation.make({
+          argv,
+          cwd,
+          envVars,
+          streaming: true
+        })
+        const lines = plan.streamResponses?.get(processCommandKey(argv)) ?? emptyLines
+        return Stream.concat(
+          Stream.drain(Stream.fromEffect(record(invocation))),
+          Stream.fromIterable(lines)
+        )
+      }
+    })
+
+    return {
+      executor,
+      recorded: Ref.get(invocations)
+    }
+  }
+)

package/src/RateLimiter.ts

@@ -0,0 +1,238 @@
+import * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import type { LlmConfig } from "./Models.ts"
+
+export class RateLimiterAcquireTimeout extends Schema.TaggedErrorClass<RateLimiterAcquireTimeout>()(
+  "AcquireTimeout",
+  {
+    timeout: Schema.Duration
+  }
+) {}
+
+export class RateLimiterInvalidConfig extends Schema.TaggedErrorClass<RateLimiterInvalidConfig>()(
+  "InvalidConfig",
+  {
+    details: Schema.String
+  }
+) {}
+
+export const RateLimiterError = Schema.Union([RateLimiterAcquireTimeout, RateLimiterInvalidConfig])
+export type RateLimiterError = typeof RateLimiterError.Type
+
+export class RateLimiterConfig extends Schema.Class<RateLimiterConfig>("RateLimiterConfig")({
+  requestsPerMinute: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(60))),
+  burstSize: Schema.Int.pipe(Schema.withConstructorDefault(Effect.succeed(10))),
+  acquireTimeout: Schema.Duration.pipe(
+    Schema.withConstructorDefault(Effect.succeed(Duration.seconds(30)))
+  )
+}) {}
+
+export const rateLimiterConfigFromLlmConfig = (config: LlmConfig): RateLimiterConfig =>
+  RateLimiterConfig.make({
+    requestsPerMinute: config.requestsPerMinute,
+    burstSize: config.burstSize,
+    acquireTimeout: config.acquireTimeout
+  })
+
+export class RateLimiterMetrics extends Schema.Class<RateLimiterMetrics>("RateLimiterMetrics")({
+  totalRequests: Schema.Int,
+  throttledRequests: Schema.Int,
+  currentTokens: Schema.Int
+}) {}
+
+export interface RateLimiterShape {
+  readonly acquire: Effect.Effect<void, RateLimiterError>
+  readonly tryAcquire: Effect.Effect<boolean>
+  readonly metrics: Effect.Effect<RateLimiterMetrics>
+}
+
+export class RateLimiter extends Context.Service<RateLimiter, RateLimiterShape>()(
+  "@llm4ts/core/RateLimiter"
+) {}
+
+interface BucketState {
+  readonly tokens: number
+  readonly lastRefillNanos: bigint
+}
+
+interface TakeResult {
+  readonly acquired: boolean
+  readonly tokensAfter: number
+  readonly deficit: number
+}
+
+const nanosPerSecond = 1_000_000_000
+
+const configDetails = (config: RateLimiterConfig): string =>
+  `requestsPerMinute=${config.requestsPerMinute}, burstSize=${config.burstSize}, ` +
+  `acquireTimeout=${Duration.format(config.acquireTimeout)}`
+
+const isConfigValid = (config: RateLimiterConfig): boolean =>
+  config.requestsPerMinute > 0 &&
+  config.burstSize > 0 &&
+  Duration.toMillis(config.acquireTimeout) > 0
+
+export const makeRateLimiter = Effect.fn("@llm4ts/core/RateLimiter.make")(function* (
+  config: RateLimiterConfig
+) {
+  const initialNanos = yield* Clock.currentTimeNanos
+  const state = yield* Ref.make<BucketState>({
+    tokens: config.burstSize,
+    lastRefillNanos: initialNanos
+  })
+  const metrics = yield* Ref.make(
+    RateLimiterMetrics.make({
+      totalRequests: 0,
+      throttledRequests: 0,
+      currentTokens: config.burstSize
+    })
+  )
+  const capacity = config.burstSize
+  const ratePerSecond = config.requestsPerMinute / 60
+
+  const takeToken: Effect.Effect<TakeResult> = Effect.gen(function* () {
+    const now = yield* Clock.currentTimeNanos
+
+    return yield* Ref.modify(state, (current) => {
+      const elapsedNanos = now - current.lastRefillNanos
+      const tokensToAdd =
+        elapsedNanos <= 0n ? 0 : (Number(elapsedNanos) / nanosPerSecond) * ratePerSecond
+      const refilled =
+        tokensToAdd <= 0 ? current.tokens : Math.min(capacity, current.tokens + tokensToAdd)
+      const lastRefillNanos = tokensToAdd <= 0 ? current.lastRefillNanos : now
+
+      if (refilled >= 1) {
+        const remaining = refilled - 1
+        return [
+          {
+            acquired: true,
+            tokensAfter: remaining,
+            deficit: 0
+          },
+          {
+            tokens: remaining,
+            lastRefillNanos
+          }
+        ]
+      }
+
+      return [
+        {
+          acquired: false,
+          tokensAfter: refilled,
+          deficit: 1 - refilled
+        },
+        {
+          tokens: refilled,
+          lastRefillNanos
+        }
+      ]
+    })
+  })
+
+  const updateCurrentTokens = (tokens: number): Effect.Effect<void> =>
+    Ref.update(metrics, (current) =>
+      RateLimiterMetrics.make({
+        ...current,
+        currentTokens: Math.trunc(tokens)
+      })
+    )
+
+  const waitForToken = (deficit: number): Effect.Effect<void, RateLimiterInvalidConfig> => {
+    if (ratePerSecond <= 0) {
+      return Effect.fail(
+        RateLimiterInvalidConfig.make({
+          details: configDetails(config)
+        })
+      )
+    }
+
+    const nanoseconds = BigInt(Math.max(0, Math.ceil((deficit / ratePerSecond) * nanosPerSecond)))
+    return Effect.sleep(Duration.nanos(nanoseconds))
+  }
+
+  const acquireLoop = (alreadyThrottled: boolean): Effect.Effect<void, RateLimiterError> =>
+    Effect.gen(function* () {
+      const result = yield* takeToken
+      yield* updateCurrentTokens(result.tokensAfter)
+
+      if (result.acquired) {
+        return
+      }
+
+      if (!alreadyThrottled) {
+        yield* Ref.update(metrics, (current) =>
+          RateLimiterMetrics.make({
+            ...current,
+            throttledRequests: current.throttledRequests + 1
+          })
+        )
+      }
+
+      yield* waitForToken(result.deficit)
+      return yield* Effect.suspend(() => acquireLoop(true))
+    })
+
+  const acquire: Effect.Effect<void, RateLimiterError> = Effect.suspend(() => {
+    if (!isConfigValid(config)) {
+      return Effect.fail(
+        RateLimiterInvalidConfig.make({
+          details: configDetails(config)
+        })
+      )
+    }
+
+    return Ref.update(metrics, (current) =>
+      RateLimiterMetrics.make({
+        ...current,
+        totalRequests: current.totalRequests + 1
+      })
+    ).pipe(
+      Effect.andThen(acquireLoop(false)),
+      Effect.timeoutOrElse({
+        duration: config.acquireTimeout,
+        orElse: () =>
+          Effect.fail(
+            RateLimiterAcquireTimeout.make({
+              timeout: config.acquireTimeout
+            })
+          )
+      })
+    )
+  })
+
+  const tryAcquire: Effect.Effect<boolean> = Effect.suspend(() => {
+    if (!isConfigValid(config)) {
+      return Effect.logWarning(`Rate limiter config invalid: ${configDetails(config)}`).pipe(
+        Effect.as(false)
+      )
+    }
+
+    return Effect.gen(function* () {
+      const result = yield* takeToken
+      yield* updateCurrentTokens(result.tokensAfter)
+      yield* Ref.update(metrics, (current) =>
+        RateLimiterMetrics.make({
+          ...current,
+          totalRequests: current.totalRequests + 1,
+          throttledRequests: current.throttledRequests + (result.acquired ? 0 : 1)
+        })
+      )
+      return result.acquired
+    })
+  })
+
+  return RateLimiter.of({
+    acquire,
+    tryAcquire,
+    metrics: Ref.get(metrics)
+  })
+})
+
+export const rateLimiterLayer = (config: RateLimiterConfig): Layer.Layer<RateLimiter> =>
+  Layer.effect(RateLimiter, makeRateLimiter(config))

package/src/Streaming.ts

@@ -0,0 +1,164 @@
+import * as Clock from "effect/Clock"
+import * as Deferred from "effect/Deferred"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import { ParseError, TimeoutError, type LlmError } from "./Errors.ts"
+import { LlmChunk, LlmResponse, StreamProgress } from "./Models.ts"
+
+const appendChunk = (response: LlmResponse, chunk: LlmChunk): LlmResponse => {
+  const usage = chunk.usage ?? response.usage
+
+  return LlmResponse.make({
+    content: response.content + chunk.delta,
+    metadata: {
+      ...response.metadata,
+      ...chunk.metadata
+    },
+    ...(usage === undefined ? {} : { usage })
+  })
+}
+
+export const collect = Effect.fn("@llm4ts/core/Streaming.collect")(
+  <R>(stream: Stream.Stream<LlmChunk, LlmError, R>) =>
+    Stream.runFold(stream, () => LlmResponse.make({ content: "" }), appendChunk)
+)
+
+const estimateTokens = (text: string): number => Math.max(1, Math.floor(text.length / 4))
+
+export const trackProgress = <R, R2>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  onProgress: (progress: StreamProgress) => Effect.Effect<void, never, R2>
+): Stream.Stream<LlmChunk, LlmError, R | R2> =>
+  Stream.unwrap(
+    Effect.map(Clock.currentTimeMillis, (startTime) =>
+      stream.pipe(
+        Stream.mapAccumEffect(
+          () => 0,
+          (tokensProcessed, chunk) =>
+            Effect.gen(function* () {
+              const now = yield* Clock.currentTimeMillis
+              const elapsedMs = now - startTime
+              const nextTokensProcessed = tokensProcessed + estimateTokens(chunk.delta)
+              const elapsedSeconds = elapsedMs / 1_000
+              const tokensPerSecond = elapsedSeconds > 0 ? nextTokensProcessed / elapsedSeconds : 0
+
+              yield* onProgress(
+                StreamProgress.make({
+                  tokensProcessed: nextTokensProcessed,
+                  tokensPerSecond,
+                  elapsedMs
+                })
+              )
+
+              return [nextTokensProcessed, [chunk]] as const
+            })
+        )
+      )
+    )
+  )
+
+export const parsePartialJson = <A, E, RD, RE, R>(
+  stream: Stream.Stream<string, LlmError, R>,
+  schema: Schema.ConstraintCodec<A, E, RD, RE>
+): Stream.Stream<A, LlmError, R | RD> =>
+  stream.pipe(
+    Stream.mapAccumEffect(
+      () => "",
+      (accumulated, chunk) => {
+        const next = accumulated + chunk
+        return Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(next).pipe(
+          Effect.match({
+            onFailure: () => [next, []] as const,
+            onSuccess: (value) => [next, [value]] as const
+          })
+        )
+      }
+    )
+  )
+
+const timeoutError = (duration: Duration.Input): TimeoutError =>
+  TimeoutError.make({ duration: Duration.fromInputUnsafe(duration) })
+
+export const withTimeout = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  duration: Duration.Input
+): Stream.Stream<LlmChunk, LlmError, R> =>
+  Stream.timeoutOrElse(stream, {
+    duration,
+    orElse: () => Stream.fail(timeoutError(duration))
+  })
+
+export const cancellable = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>
+): Effect.Effect<
+  readonly [stream: Stream.Stream<LlmChunk, LlmError, R>, cancel: Effect.Effect<void>]
+> =>
+  Effect.map(Deferred.make<void>(), (deferred) => [
+    Stream.interruptWhen(stream, Deferred.await(deferred)),
+    Deferred.succeed(deferred, undefined).pipe(Effect.asVoid)
+  ])
+
+export const withSnapshots = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  snapshotInterval: Duration.Input = "500 millis"
+): Stream.Stream<string, LlmError, R> =>
+  stream.pipe(
+    Stream.scan("", (content, chunk) => content + chunk.delta),
+    Stream.debounce(snapshotInterval)
+  )
+
+const chunkJson = Schema.fromJsonString(Schema.toCodecJson(LlmChunk))
+
+export const toSSE = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>
+): Stream.Stream<string, LlmError, R> =>
+  Stream.mapEffect(stream, (chunk) =>
+    Schema.encodeEffect(chunkJson)(chunk).pipe(
+      Effect.map((encoded) => `data: ${encoded}\n\n`),
+      Effect.mapError((error) =>
+        ParseError.make({
+          message: `Failed to encode SSE chunk: ${String(error)}`,
+          raw: chunk.delta
+        })
+      )
+    )
+  )
+
+export const fromSSE = <R>(
+  stream: Stream.Stream<string, LlmError, R>
+): Stream.Stream<LlmChunk, LlmError, R> =>
+  stream.pipe(
+    Stream.filter((line) => line.startsWith("data: ")),
+    Stream.map((line) => line.slice("data: ".length).trim()),
+    Stream.filter((payload) => payload.length > 0 && payload !== "[DONE]"),
+    Stream.mapEffect((payload) =>
+      Schema.decodeUnknownEffect(chunkJson)(payload).pipe(
+        Effect.mapError((error) =>
+          ParseError.make({
+            message: `Failed to parse SSE chunk: ${String(error)}`,
+            raw: payload
+          })
+        )
+      )
+    )
+  )
+
+export const withHeartbeat = <R>(
+  stream: Stream.Stream<LlmChunk, LlmError, R>,
+  heartbeatTimeout: Duration.Input
+): Stream.Stream<LlmChunk, LlmError, R> =>
+  withTimeout(stream, heartbeatTimeout).pipe(Stream.rechunk(1))
+
+export const parallelStream = <A, B, R>(
+  inputs: Iterable<A>,
+  parallelism: number,
+  f: (input: A) => Stream.Stream<B, LlmError, R>
+): Stream.Stream<B, LlmError, R> =>
+  Stream.fromIterable(inputs).pipe(
+    Stream.mapEffect((input) => Stream.runCollect(f(input)), {
+      concurrency: parallelism
+    }),
+    Stream.flatMap(Stream.fromIterable)
+  )

package/src/StructuredOutput.ts

@@ -0,0 +1,138 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { SchemaError } from "effect/SchemaError"
+import { ParseError, ProviderError, type LlmError } from "./Errors.ts"
+import type { JsonSchema } from "./Models.ts"
+
+const snippet = (text: string): string => {
+  const trimmed = text.trim()
+  return trimmed.length <= 120 ? trimmed : `${trimmed.slice(0, 117)}...`
+}
+
+const extractJsonFromMarkdownFences = (raw: string): ReadonlyArray<string> => {
+  const pattern = /```(?:[\w.+-]+)?\s*(.*?)\s*```/gis
+  const results: Array<string> = []
+
+  for (const match of raw.matchAll(pattern)) {
+    const content = match[1]?.trim()
+    if (content !== undefined && content.length > 0) {
+      results.push(content)
+    }
+  }
+
+  return results
+}
+
+const extractBalancedJsonObjects = (raw: string): ReadonlyArray<string> => {
+  const results: Array<string> = []
+  let startIndex: number | undefined
+  let depth = 0
+  let inString = false
+  let escaping = false
+
+  for (let index = 0; index < raw.length; index += 1) {
+    const character = raw.charAt(index)
+
+    if (inString) {
+      if (escaping) {
+        escaping = false
+      } else if (character === "\\") {
+        escaping = true
+      } else if (character === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (character === '"') {
+      inString = true
+    } else if (character === "{") {
+      startIndex ??= index
+      depth += 1
+    } else if (character === "}" && depth > 0) {
+      depth -= 1
+      if (depth === 0 && startIndex !== undefined) {
+        results.push(raw.slice(startIndex, index + 1))
+        startIndex = undefined
+      }
+    }
+  }
+
+  return results
+}
+
+export const jsonCandidates = (raw: string): ReadonlyArray<string> => {
+  const fenced = extractJsonFromMarkdownFences(raw)
+  const balanced = [
+    ...extractBalancedJsonObjects(raw),
+    ...fenced.flatMap(extractBalancedJsonObjects)
+  ]
+  const seen = new Set<string>()
+  const candidates: Array<string> = []
+
+  for (const candidate of [raw, ...fenced, ...balanced]) {
+    const trimmed = candidate.trim()
+    if (trimmed.length > 0 && !seen.has(trimmed)) {
+      seen.add(trimmed)
+      candidates.push(trimmed)
+    }
+  }
+
+  return candidates
+}
+
+export const withSchemaHint = (prompt: string, schema: JsonSchema): string => {
+  if (Object.keys(schema).length === 0) {
+    return prompt
+  }
+
+  const encoded = JSON.stringify(schema) ?? "{}"
+  return `${prompt}\n\nReturn JSON matching this schema:\n${encoded}`
+}
+
+interface CandidateFailure {
+  readonly candidate: string
+  readonly error: SchemaError
+}
+
+export const parseFromText = Effect.fn("@llm4ts/core/StructuredOutput.parseFromText")(<
+  A,
+  E,
+  RD,
+  RE
+>(
+  raw: string,
+  schema: Schema.ConstraintCodec<A, E, RD, RE>,
+  _jsonSchema: JsonSchema
+): Effect.Effect<A, LlmError, RD> => {
+  if (raw.trim().length === 0) {
+    return Effect.fail(
+      ProviderError.make({
+        message: "empty response from provider — no text to parse as structured output"
+      })
+    )
+  }
+
+  const candidates = jsonCandidates(raw)
+  const attempts = candidates.map((candidate) =>
+    Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(candidate).pipe(
+      Effect.mapError(
+        (error): CandidateFailure => ({
+          candidate,
+          error
+        })
+      )
+    )
+  )
+
+  return Effect.firstSuccessOf(attempts).pipe(
+    Effect.mapError(({ candidate, error }) =>
+      ParseError.make({
+        message:
+          `Failed to parse response as structured output: ${String(error)} ` +
+          `(tried ${attempts.length} candidate(s); last: ${snippet(candidate)})`,
+        raw
+      })
+    )
+  )
+})