@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 270 lines 8.75 KB
Raw
1 /**
2 * The `OpenAiEmbeddingModel` module provides the OpenAI implementation of
3 * Effect AI's `EmbeddingModel` service. It sends embedding requests through
4 * `OpenAiClient`, exposes constructors for layers and `AiModel` values,
5 * supports scoped request configuration overrides, and checks that OpenAI
6 * 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 { OpenAiClient } from "./OpenAiClient.ts"
20 import { OpenAiConfig } from "./OpenAiConfig.ts"
21 import type * as OpenAiSchema from "./OpenAiSchema.ts"
22
23 /**
24 * Model identifiers supported by OpenAI's embeddings API.
25 *
26 * @stability unstable
27 * @category models
28 * @since 4.0.0
29 */
30 export type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large"
31
32 /**
33 * Context service for OpenAI embedding model configuration.
34 *
35 * **When to use**
36 *
37 * Use when you need scoped OpenAI request defaults or overrides for embedding
38 * requests from Effect context.
39 *
40 * **Details**
41 *
42 * The service stores the OpenAI create-embedding request payload without
43 * `input`, carrying options such as `model`, `dimensions`, `encoding_format`,
44 * and `user`.
45 *
46 * @see {@link withConfigOverride} for scoping embedding request overrides
47 *
48 * @stability unstable
49 * @category services
50 * @since 4.0.0
51 */
52 export class Config extends Context.Service<
53 Config,
54 Simplify<
55 & Partial<
56 Omit<
57 typeof OpenAiSchema.CreateEmbeddingRequest.Encoded,
58 "input"
59 >
60 >
61 & {
62 readonly [x: string]: unknown
63 }
64 >
65 >()("@effect/ai-openai/OpenAiEmbeddingModel/Config") {}
66
67 /**
68 * Creates an `AiModel` for an OpenAI embedding model with its configured vector dimensions.
69 *
70 * **When to use**
71 *
72 * Use to provide an OpenAI `EmbeddingModel` and its `Dimensions` service to an
73 * Effect program.
74 *
75 * @see {@link layer} for providing only the embedding model service
76 * @see {@link withConfigOverride} for scoped request configuration overrides
77 *
78 * @stability unstable
79 * @category constructors
80 * @since 4.0.0
81 */
82 export const model = (
83 model: (string & {}) | Model,
84 options: {
85 readonly dimensions: number
86 readonly config?: Omit<typeof Config.Service, "model" | "dimensions">
87 }
88 ): AiModel.Model<"openai", EmbeddingModel.EmbeddingModel | EmbeddingModel.Dimensions, OpenAiClient> =>
89 AiModel.make(
90 "openai",
91 model,
92 Layer.merge(
93 layer({
94 model,
95 config: {
96 ...options.config,
97 dimensions: options.dimensions
98 }
99 }),
100 Layer.succeed(EmbeddingModel.Dimensions, options.dimensions)
101 )
102 )
103
104 /**
105 * Creates an OpenAI embedding model service.
106 *
107 * **When to use**
108 *
109 * Use to construct the `EmbeddingModel` effectfully when
110 * `OpenAiClient` is already available in the environment.
111 *
112 * **Details**
113 *
114 * The `model` option is sent with each embedding request. Constructor `config`
115 * supplies create-embedding request fields other than `model` and `input`, and
116 * scoped overrides from `withConfigOverride` are merged last for each request.
117 *
118 * **Gotchas**
119 *
120 * Concurrent `embed` calls share a request when their `Config` and
121 * `OpenAiConfig` values are equal. Other per-call context, such as
122 * `FetchHttpClient.RequestInit`, takes the first caller's value for the batch.
123 *
124 * The service expects numeric embedding vectors. It fails with
125 * `InvalidOutputError` when the provider returns base64 embeddings,
126 * out-of-range indexes, duplicate indexes, or an unexpected number of
127 * embeddings.
128 *
129 * @see {@link layer} for providing the embedding model service as a layer
130 * @see {@link model} for creating an `AiModel` that also provides dimensions
131 * @see {@link withConfigOverride} for scoped request configuration overrides
132 *
133 * @stability unstable
134 * @category constructors
135 * @since 4.0.0
136 */
137 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
138 readonly model: (string & {}) | Model
139 readonly config?: Omit<typeof Config.Service, "model"> | undefined
140 }): Effect.fn.Return<EmbeddingModel.EmbeddingModel, never, OpenAiClient> {
141 const client = yield* OpenAiClient
142
143 const makeConfig = Effect.contextWith((services: Context.Context<never>) =>
144 Effect.succeed({ model, ...providerConfig, ...Context.getOrUndefined(services, Config) })
145 )
146
147 return yield* EmbeddingModel.make({
148 batchKey: (context) => [Context.getOrUndefined(context, Config), Context.getOrUndefined(context, OpenAiConfig)],
149 embedMany: Effect.fnUntraced(function*({ inputs }) {
150 const config = yield* makeConfig
151 const response = yield* client.createEmbedding({ ...config, input: inputs })
152 return yield* mapProviderResponse(inputs.length, response)
153 })
154 })
155 })
156
157 /**
158 * Creates a layer for the OpenAI embedding model.
159 *
160 * **When to use**
161 *
162 * Use when composing application layers and you want OpenAI to satisfy
163 * `EmbeddingModel.EmbeddingModel` while supplying `OpenAiClient` from another
164 * layer.
165 *
166 * **Gotchas**
167 *
168 * Use the default floating-point embedding format. The service expects numeric
169 * vectors and fails with `InvalidOutputError` if OpenAI returns base64
170 * embeddings.
171 *
172 * @see {@link make} for constructing the embedding model service effectfully
173 * @see {@link model} for creating an `AiModel` that also provides embedding dimensions
174 *
175 * @stability unstable
176 * @category layers
177 * @since 4.0.0
178 */
179 export const layer = (options: {
180 readonly model: (string & {}) | Model
181 readonly config?: Omit<typeof Config.Service, "model"> | undefined
182 }): Layer.Layer<EmbeddingModel.EmbeddingModel, never, OpenAiClient> =>
183 Layer.effect(EmbeddingModel.EmbeddingModel, make(options))
184
185 /**
186 * Provides config overrides for OpenAI embedding model operations.
187 *
188 * **When to use**
189 *
190 * Use when you need scoped OpenAI embedding request defaults for a single
191 * effect or workflow without rebuilding the embedding model service.
192 *
193 * **Details**
194 *
195 * Supports both data-first and data-last forms. Existing scoped config is read
196 * first, then the provided overrides are applied so override fields take
197 * precedence.
198 *
199 * @see {@link Config} for the scoped embedding request configuration service
200 *
201 * @stability unstable
202 * @category configuration
203 * @since 4.0.0
204 */
205 export const withConfigOverride: {
206 (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
207 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
208 } = dual<
209 (
210 overrides: typeof Config.Service
211 ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
212 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
213 >(2, (self, overrides) =>
214 Effect.flatMap(
215 Effect.serviceOption(Config),
216 (config) =>
217 Effect.provideService(self, Config, {
218 ...(config._tag === "Some" ? config.value : {}),
219 ...overrides
220 })
221 ))
222
223 const mapProviderResponse = (
224 inputLength: number,
225 response: typeof OpenAiSchema.CreateEmbeddingResponse.Type
226 ): Effect.Effect<EmbeddingModel.ProviderResponse, AiError.AiError> => {
227 if (response.data.length !== inputLength) {
228 return Effect.fail(
229 invalidOutput("Provider returned " + response.data.length + " embeddings but expected " + inputLength)
230 )
231 }
232
233 const results = new Array<Array<number>>(inputLength)
234 const seen = new Set<number>()
235
236 for (const entry of response.data) {
237 if (!Number.isInteger(entry.index) || entry.index < 0 || entry.index >= inputLength) {
238 return Effect.fail(invalidOutput("Provider returned invalid embedding index: " + entry.index))
239 }
240 if (seen.has(entry.index)) {
241 return Effect.fail(invalidOutput("Provider returned duplicate embedding index: " + entry.index))
242 }
243 if (!Array.isArray(entry.embedding)) {
244 return Effect.fail(invalidOutput("Provider returned non-vector embedding at index " + entry.index))
245 }
246
247 seen.add(entry.index)
248 results[entry.index] = [...entry.embedding]
249 }
250
251 if (seen.size !== inputLength) {
252 return Effect.fail(
253 invalidOutput("Provider returned embeddings for " + seen.size + " inputs but expected " + inputLength)
254 )
255 }
256
257 return Effect.succeed({
258 results,
259 usage: {
260 inputTokens: response.usage?.prompt_tokens
261 }
262 })
263 }
264
265 const invalidOutput = (description: string): AiError.AiError =>
266 AiError.make({
267 module: "OpenAiEmbeddingModel",
268 method: "embedMany",
269 reason: new AiError.InvalidOutputError({ description })
270 })