@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 256 lines 8.78 KB
Raw
1 /**
2 * The `OpenAiEmbeddingModel` module adapts OpenAI-compatible embeddings
3 * endpoints to Effect's embedding model service. It sends embedding requests
4 * through {@link OpenAiClient}, exposes constructors for layers and `AiModel`
5 * values, supports scoped request configuration overrides, and checks that the
6 * provider returns one numeric vector for each requested input.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11 import * as AiError from "effect/ai/AiError"
12 import * as EmbeddingModel from "effect/ai/EmbeddingModel"
13 import * as AiModel from "effect/ai/Model"
14 import * as Context from "effect/Context"
15 import * as Effect from "effect/Effect"
16 import { dual } from "effect/Function"
17 import * as Layer from "effect/Layer"
18 import type { Simplify } from "effect/Types"
19 import type { CreateEmbedding200, CreateEmbeddingRequestJson } from "./OpenAiClient.ts"
20 import { OpenAiClient } from "./OpenAiClient.ts"
21 import { OpenAiConfig } from "./OpenAiConfig.ts"
22
23 /**
24 * A model identifier accepted by an OpenAI-compatible embeddings endpoint.
25 *
26 * @stability unstable
27 * @category models
28 * @since 4.0.0
29 */
30 export type Model = string
31
32 type ConfigOptions = Simplify<Partial<Omit<CreateEmbeddingRequestJson, "input">>>
33 type ModelConfig = Omit<ConfigOptions, "model"> & { readonly [x: string]: unknown }
34
35 /**
36 * Context service for OpenAI embedding model configuration.
37 *
38 * **When to use**
39 *
40 * Use when you need to provide shared default request options for
41 * OpenAI-compatible embedding operations through the Effect context, such as
42 * `dimensions`, `encoding_format`, or `user`.
43 *
44 * **Details**
45 *
46 * The service stores the embedding request payload without `input`. Requests
47 * combine the selected model, layer or constructor config, and scoped context
48 * config, with scoped context config taking precedence.
49 *
50 * @see {@link withConfigOverride} for scoping embedding request overrides
51 *
52 * @stability unstable
53 * @category services
54 * @since 4.0.0
55 */
56 export class Config extends Context.Service<
57 Config,
58 ConfigOptions & { readonly [x: string]: unknown }
59 >()("@effect/ai-openai-compat/OpenAiEmbeddingModel/Config") {}
60
61 /**
62 * Creates an `AiModel` for an OpenAI-compatible embedding model with its configured vector dimensions.
63 *
64 * **When to use**
65 *
66 * Use to provide an OpenAI-compatible `EmbeddingModel` and its `Dimensions`
67 * service to an Effect program.
68 *
69 * @see {@link layer} for providing only the embedding model service
70 * @see {@link withConfigOverride} for scoped request configuration overrides
71 *
72 * @stability unstable
73 * @category constructors
74 * @since 4.0.0
75 */
76 export const model = (
77 model: string,
78 options: Omit<ConfigOptions, "model" | "dimensions"> & {
79 readonly dimensions: number
80 readonly [x: string]: unknown
81 }
82 ): AiModel.Model<"openai", EmbeddingModel.EmbeddingModel | EmbeddingModel.Dimensions, OpenAiClient> =>
83 AiModel.make(
84 "openai",
85 model,
86 Layer.merge(
87 layer({
88 model,
89 config: options
90 }),
91 Layer.succeed(EmbeddingModel.Dimensions, options.dimensions)
92 )
93 )
94
95 /**
96 * Creates an OpenAI-compatible embedding model service backed by `OpenAiClient`.
97 *
98 * **When to use**
99 *
100 * Use when you need to build or provide an `EmbeddingModel` service directly
101 * from an existing `OpenAiClient`.
102 *
103 * **Details**
104 *
105 * The service sends embedding requests through `OpenAiClient.createEmbedding`.
106 * Request config is merged as the selected model, constructor config, then
107 * scoped `Config`, so scoped overrides take precedence. Provider usage
108 * `prompt_tokens` is exposed as `usage.inputTokens`.
109 *
110 * **Gotchas**
111 *
112 * Concurrent `embed` calls share a request when their `Config` and
113 * `OpenAiConfig` values are equal. Other per-call context, such as
114 * `FetchHttpClient.RequestInit`, takes the first caller's value for the batch.
115 *
116 * Provider responses must contain one numeric vector for every requested input
117 * with unique, in-range `index` values; otherwise embedding operations fail with
118 * `AiError.InvalidOutputError`.
119 *
120 * @see {@link model} for the higher-level `AiModel` descriptor that also provides `EmbeddingModel.Dimensions`
121 * @see {@link layer} for providing the service as a `Layer`
122 * @see {@link withConfigOverride} for scoping embedding request overrides
123 *
124 * @stability unstable
125 * @category constructors
126 * @since 4.0.0
127 */
128 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
129 readonly model: string
130 readonly config?: ModelConfig | undefined
131 }): Effect.fn.Return<EmbeddingModel.EmbeddingModel, never, OpenAiClient> {
132 const client = yield* OpenAiClient
133
134 const makeConfig = Effect.contextWith((services: Context.Context<never>) =>
135 Effect.succeed({ model, ...providerConfig, ...Context.getOrUndefined(services, Config) })
136 )
137
138 return yield* EmbeddingModel.make({
139 batchKey: (context) => [Context.getOrUndefined(context, Config), Context.getOrUndefined(context, OpenAiConfig)],
140 embedMany: Effect.fnUntraced(function*({ inputs }) {
141 const config = yield* makeConfig
142 const response = yield* client.createEmbedding({ ...config, input: inputs })
143 return yield* mapProviderResponse(inputs.length, response)
144 })
145 })
146 })
147
148 /**
149 * Creates a layer for an OpenAI-compatible embedding model service.
150 *
151 * **When to use**
152 *
153 * Use when composing application layers and you want an OpenAI-compatible
154 * embeddings endpoint to satisfy `EmbeddingModel.EmbeddingModel` while
155 * supplying `OpenAiClient` from another layer.
156 *
157 * @see {@link make} for constructing the embedding model service effectfully
158 * @see {@link model} for creating an `AiModel` with configured dimensions
159 *
160 * @stability unstable
161 * @category layers
162 * @since 4.0.0
163 */
164 export const layer = (options: {
165 readonly model: string
166 readonly config?: ModelConfig | undefined
167 }): Layer.Layer<EmbeddingModel.EmbeddingModel, never, OpenAiClient> =>
168 Layer.effect(EmbeddingModel.EmbeddingModel, make(options))
169
170 /**
171 * Provides scoped request config overrides for OpenAI-compatible embedding model operations.
172 *
173 * **When to use**
174 *
175 * Use to apply embedding request options to one effect without changing the
176 * model's default configuration.
177 *
178 * **Details**
179 *
180 * The overrides are merged with any existing `Config` service for the duration
181 * of the supplied effect. Fields in `overrides` take precedence over existing
182 * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
183 * and `withConfigOverride(effect, overrides)`.
184 *
185 * @see {@link Config} for available OpenAI-compatible embedding request configuration fields
186 *
187 * @stability unstable
188 * @category configuration
189 * @since 4.0.0
190 */
191 export const withConfigOverride: {
192 (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
193 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
194 } = dual<
195 (
196 overrides: typeof Config.Service
197 ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
198 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
199 >(2, (self, overrides) =>
200 Effect.flatMap(
201 Effect.serviceOption(Config),
202 (config) =>
203 Effect.provideService(self, Config, {
204 ...(config._tag === "Some" ? config.value : {}),
205 ...overrides
206 })
207 ))
208
209 const mapProviderResponse = (
210 inputLength: number,
211 response: CreateEmbedding200
212 ): Effect.Effect<EmbeddingModel.ProviderResponse, AiError.AiError> => {
213 if (response.data.length !== inputLength) {
214 return Effect.fail(
215 invalidOutput(`Provider returned ${response.data.length} embeddings but expected ${inputLength}`)
216 )
217 }
218
219 const results = new Array<Array<number>>(inputLength)
220 const seen = new Set<number>()
221
222 for (const entry of response.data) {
223 if (!Number.isInteger(entry.index) || entry.index < 0 || entry.index >= inputLength) {
224 return Effect.fail(invalidOutput(`Provider returned invalid embedding index: ${entry.index}`))
225 }
226 if (seen.has(entry.index)) {
227 return Effect.fail(invalidOutput(`Provider returned duplicate embedding index: ${entry.index}`))
228 }
229 if (!Array.isArray(entry.embedding)) {
230 return Effect.fail(invalidOutput(`Provider returned non-vector embedding at index ${entry.index}`))
231 }
232
233 seen.add(entry.index)
234 results[entry.index] = [...entry.embedding]
235 }
236
237 if (seen.size !== inputLength) {
238 return Effect.fail(
239 invalidOutput(`Provider returned embeddings for ${seen.size} inputs but expected ${inputLength}`)
240 )
241 }
242
243 return Effect.succeed({
244 results,
245 usage: {
246 inputTokens: response.usage?.prompt_tokens
247 }
248 })
249 }
250
251 const invalidOutput = (description: string): AiError.AiError =>
252 AiError.make({
253 module: "OpenAiEmbeddingModel",
254 method: "embedMany",
255 reason: new AiError.InvalidOutputError({ description })
256 })