effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/unstable/ai/AiError.ts

@@ -20,9 +20,75 @@ import { redact } from "../../Redactable.ts"
 import * as Redacted from "../../Redacted.ts"
 import * as Schema from "../../Schema.ts"
 import type * as HttpClientError from "../http/HttpClientError.ts"
-import { HttpRequestDetails, HttpResponseDetails } from "./Response.ts"
 
-const ReasonTypeId = "~effect/unstable/ai/AiError/Reason" as const
+/**
+ * Schema for HTTP requests to an AI provider.
+ *
+ * **Example** (Describing an HTTP request)
+ *
+ * ```ts import.meta.vitest
+ * import type { AiError } from "effect/unstable/ai"
+ *
+ * const requestDetails: typeof AiError.HttpRequestDetails.Type = {
+ *   method: "POST",
+ *   url: "https://api.openai.com/v1/responses",
+ *   urlParams: [],
+ *   hash: undefined,
+ *   headers: { "Content-Type": "application/json" }
+ * }
+ * const result = [requestDetails.method, requestDetails.urlParams] // => ["POST", []]
+ * ```
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const HttpRequestDetails = Schema.Struct({
+  method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]),
+  url: Schema.String,
+  urlParams: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
+  hash: Schema.optional(Schema.String),
+  headers: Schema.Record(
+    Schema.String,
+    Schema.Union([
+      Schema.String,
+      Schema.Redacted(Schema.String)
+    ])
+  )
+}).annotate({ identifier: "HttpRequestDetails" })
+
+/**
+ * Schema for HTTP responses from an AI provider.
+ *
+ * **Example** (Describing an HTTP response)
+ *
+ * ```ts import.meta.vitest
+ * import type { AiError } from "effect/unstable/ai"
+ *
+ * const responseDetails: typeof AiError.HttpResponseDetails.Type = {
+ *   status: 200,
+ *   headers: {
+ *     "Content-Type": "application/json",
+ *     "X-Request-Id": "req_abc123"
+ *   }
+ * }
+ * const result = [responseDetails.status, responseDetails.headers["X-Request-Id"]] // => [200, "req_abc123"]
+ * ```
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const HttpResponseDetails = Schema.Struct({
+  status: Schema.Int,
+  headers: Schema.Record(
+    Schema.String,
+    Schema.Union([
+      Schema.String,
+      Schema.Redacted(Schema.String)
+    ])
+  )
+}).annotate({ identifier: "HttpResponseDetails" })
+
+const ReasonTypeId = "~effect/ai/AiError/Reason" as const
 
 const providerMetadataWithDefaults = <Metadata extends ProviderMetadata>() =>
   (ProviderMetadata as unknown as typeof ProviderMetadata & Schema.Schema<Metadata>).pipe(
@@ -1055,7 +1121,6 @@ export class ToolNotFoundError extends Schema.Error<ToolNotFoundError>(
  *
  * const error = new AiError.ToolParameterValidationError({
  *   toolName: "GetWeather",
- *   toolParams: { location: 123 },
  *   description: "Expected string, got number"
  * })
  *
@@ -1070,7 +1135,6 @@ export class ToolParameterValidationError extends Schema.Error<ToolParameterVali
 )({
   _tag: Schema.tag("ToolParameterValidationError"),
   toolName: Schema.String,
-  toolParams: Schema.Json,
   description: Schema.String
 }) {
   /**
@@ -1452,7 +1516,7 @@ export const AiErrorReason: Schema.Union<[
 // Top-Level AiError
 // =============================================================================
 
-const TypeId = "~effect/unstable/ai/AiError/AiError" as const
+const TypeId = "~effect/ai/AiError" as const
 
 /**
  * Schema for the top-level AI error wrapper using the `reason` pattern.

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -58,7 +58,10 @@ export function toCodecAnthropic<T, E, RD, RE>(
   readonly jsonSchema: JsonSchema.JsonSchema
 } {
   const codec = InternalStructuredOutput.toCodec(schema)
-  const unresolvedDocument = Schema.toJsonSchemaDocument(codec, { generateDescriptions: true })
+  const unresolvedDocument = Schema.toJsonSchemaDocument(codec, {
+    generateDescriptions: true,
+    onExcessProperty: "error"
+  })
   if (hasReferenceCycle(unresolvedDocument.schema, unresolvedDocument.definitions)) {
     throw new Error("AnthropicStructuredOutput: Recursive schemas are not supported")
   }

package/src/unstable/ai/Chat.ts

@@ -33,18 +33,7 @@ import type * as Response from "./Response.ts"
 import type * as Tool from "./Tool.ts"
 
 /**
- * Service tag for stateful AI conversation sessions.
- *
- * **When to use**
- *
- * Use to access or provide conversational AI sessions through the Effect
- * context.
- *
- * **Details**
- *
- * This tag provides access to chat functionality throughout your application,
- * enabling persistent conversational AI interactions with full context
- * management.
+ * Service key for stateful AI conversations.
  *
  * **Example** (Accessing the Chat service)
  *
@@ -82,26 +71,35 @@ import type * as Tool from "./Tool.ts"
  * @category services
  * @since 4.0.0
  */
-export class Chat extends Context.Service<Chat, Service>()(
-  "effect/ai/Chat"
-) {}
+export const Chat: Context.Service<Chat, Chat> = Context.Service("effect/ai/Chat")
 
 /**
- * Represents the interface that the `Chat` service provides.
+ * Brand type for `Chat`.
  *
- * **When to use**
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type TypeId = "~effect/ai/Chat"
+
+/**
+ * Brand for `Chat` implementations.
  *
- * Use as the service contract for code that receives or constructs a stateful
- * chat session and needs history, export, text generation, streaming, and
- * structured-output operations.
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const TypeId: TypeId = "~effect/ai/Chat"
+
+/**
+ * Chat session with history, export, and generation operations.
  *
- * @see {@link Chat} for the context tag that provides this service
  * @see {@link Persisted} for the persistence-backed extension
  *
  * @category models
  * @since 4.0.0
  */
-export interface Service {
+export interface Chat {
+  readonly [TypeId]: TypeId
+
   /**
    * Reference to the chat history.
    *
@@ -240,7 +238,7 @@ export interface Service {
         readonly toolkit: LanguageModel.ToolkitInput<Tools>
       }
     ): Effect.Effect<
-      LanguageModel.GenerateTextResponse<Tools, LanguageModel.ExtractEncodedToolParameters<Options>>,
+      LanguageModel.GenerateTextResponse<Tools, LanguageModel.ExtractToolParametersMode<Options>>,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
     >
@@ -255,7 +253,7 @@ export interface Service {
     ): Effect.Effect<
       LanguageModel.GenerateTextResponse<
         LanguageModel.ExtractTools<Options>,
-        LanguageModel.ExtractEncodedToolParameters<Options>
+        LanguageModel.ExtractToolParametersMode<Options>
       >,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
@@ -322,7 +320,7 @@ export interface Service {
         readonly toolkit: LanguageModel.ToolkitInput<Tools>
       }
     ): Stream.Stream<
-      Response.StreamPart<Tools, LanguageModel.ExtractEncodedToolParameters<Options>>,
+      Response.StreamPart<Tools, LanguageModel.ExtractToolParametersMode<Options>>,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
     >
@@ -337,7 +335,7 @@ export interface Service {
     ): Stream.Stream<
       Response.StreamPart<
         LanguageModel.ExtractTools<Options>,
-        LanguageModel.ExtractEncodedToolParameters<Options>
+        LanguageModel.ExtractToolParametersMode<Options>
       >,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
@@ -399,7 +397,7 @@ export interface Service {
     LanguageModel.GenerateObjectResponse<
       LanguageModel.ExtractTools<Options>,
       ObjectSchema["Type"],
-      LanguageModel.ExtractEncodedToolParameters<Options>
+      LanguageModel.ExtractToolParametersMode<Options>
     >,
     LanguageModel.ExtractError<Options>,
     LanguageModel.ExtractServices<Options> | ObjectSchema["DecodingServices"] | LanguageModel.LanguageModel
@@ -419,6 +417,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
   const semaphore = Semaphore.makeUnsafe(1)
 
   return Chat.of({
+    [TypeId]: TypeId,
     history,
     export: Ref.get(history).pipe(
       Effect.flatMap(encodeHistory),
@@ -455,7 +454,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
       },
       semaphore.withPermits(1),
       (effect) => Effect.withSpan(effect, "Chat.generateText", { captureStackTrace: false })
-    ) as Service["generateText"],
+    ) as Chat["generateText"],
     streamText: Effect.fnUntraced(
       function*(options) {
         let parts = Chunk.empty<Response.AnyPart>()
@@ -487,7 +486,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
         )
       },
       Stream.unwrap
-    ) as Service["streamText"],
+    ) as Chat["streamText"],
     generateObject: Effect.fnUntraced(
       function*(options) {
         const newPrompt = Prompt.make(options.prompt)
@@ -539,7 +538,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  * @category constructors
  * @since 4.0.0
  */
-export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.empty)))
+export const empty: Effect.Effect<Chat> = Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.empty)))
 
 /**
  * Creates a new Chat service from an initial prompt.
@@ -655,7 +654,7 @@ export const fromPrompt = (prompt: Prompt.RawInput) =>
  * @since 4.0.0
  */
 export const fromExport = (data: unknown): Effect.Effect<
-  Service,
+  Chat,
   Schema.SchemaError
 > => Effect.flatMap(decodeHistory(data), fromPrompt)
 
@@ -689,7 +688,7 @@ export const fromExport = (data: unknown): Effect.Effect<
  * @since 4.0.0
  */
 export const fromJson = (data: string): Effect.Effect<
-  Service,
+  Chat,
   Schema.SchemaError
 > => Effect.flatMap(decodeHistoryJson(data), fromPrompt)
 
@@ -779,7 +778,7 @@ export declare namespace Persistence {
  * @category models
  * @since 4.0.0
  */
-export interface Persisted extends Service {
+export interface Persisted extends Chat {
   /**
    * The identifier for the chat in the backing persistence store.
    */
@@ -816,7 +815,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
   const store = yield* persistence.make(options.storeId)
 
   const toPersisted = Effect.fnUntraced(
-    function*(chatId: string, chat: Service, ttl: Duration.Input | undefined) {
+    function*(chatId: string, chat: Chat, ttl: Duration.Input | undefined) {
       const idGenerator = yield* Effect.serviceOption(IdGenerator.IdGenerator).pipe(
         Effect.map(Option.getOrElse(() => IdGenerator.defaultIdGenerator))
       )
@@ -865,7 +864,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
           return yield* chat.generateText(options).pipe(
             Effect.ensuring(Effect.orDie(saveChat(history)))
           )
-        }) as Service["generateText"],
+        }) as Chat["generateText"],
         generateObject: Effect.fnUntraced(function*(options) {
           const history = yield* Ref.get(chat.history)
           return yield* chat.generateObject(options).pipe(
@@ -878,7 +877,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
             Stream.ensuring(Effect.orDie(saveChat(history)))
           )
           return stream
-        }, Stream.unwrap) as Service["streamText"]
+        }, Stream.unwrap) as Chat["streamText"]
       }
 
       return persisted

package/src/unstable/ai/EmbeddingModel.ts

@@ -19,23 +19,33 @@ import * as Schema from "../../Schema.ts"
 import * as AiError from "./AiError.ts"
 
 /**
- * Service tag for embedding model operations.
+ * Service key for embedding text into vectors.
  *
- * **When to use**
- *
- * Use to retrieve or provide the embedding model service for an `Effect`
- * program that embeds text into vectors.
- *
- * @see {@link Service} for the service contract provided by this tag
  * @see {@link make} for constructing an embedding model service from a provider
  * @see {@link Dimensions} for the current embedding vector size service
  *
  * @category services
  * @since 4.0.0
  */
-export class EmbeddingModel extends Context.Service<EmbeddingModel, Service>()(
+export const EmbeddingModel: Context.Service<EmbeddingModel, EmbeddingModel> = Context.Service(
   "effect/unstable/ai/EmbeddingModel"
-) {}
+)
+
+/**
+ * Brand type for `EmbeddingModel`.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type TypeId = "~effect/ai/EmbeddingModel"
+
+/**
+ * Brand for `EmbeddingModel` implementations.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const TypeId: TypeId = "~effect/ai/EmbeddingModel"
 
 /**
  * Service tag that provides the current embedding dimensions.
@@ -137,7 +147,7 @@ export interface ProviderResponse {
  * Use when you need a typed request for one embedding input while building or
  * calling a low-level embedding request resolver.
  *
- * @see {@link Service} for the resolver-bearing service contract
+ * @see {@link EmbeddingModel} for the resolver-bearing service contract
  * @see {@link make} for constructing the request resolver from a provider implementation
  * @see {@link EmbedResponse} for the response produced by this request
  *
@@ -151,12 +161,13 @@ export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
 > {}
 
 /**
- * Defines the service interface for embedding operations.
+ * Single-input and batch embedding operations.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Service {
+export interface EmbeddingModel {
+  readonly [TypeId]: TypeId
   readonly resolver: RequestResolver.RequestResolver<EmbeddingRequest>
   readonly embed: (input: string) => Effect.Effect<EmbedResponse, AiError.AiError>
   readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<EmbedManyResponse, AiError.AiError>
@@ -175,7 +186,7 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
  * **When to use**
  *
  * Use to adapt a provider's batch embedding implementation into an
- * `EmbeddingModel.Service` that offers single-input and batch embedding
+ * `EmbeddingModel` that offers single-input and batch embedding
  * operations.
  *
  * **Details**
@@ -192,7 +203,7 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
  * result for each requested input. If the provider returns a different number
  * of results, `embed` and `embedMany` fail with `AiError.InvalidOutputError`.
  *
- * @see {@link Service} for the service shape returned by this constructor
+ * @see {@link EmbeddingModel} for the service shape returned by this constructor
  * @see {@link ProviderOptions} for the input passed to the provider implementation
  * @see {@link ProviderResponse} for the provider response contract consumed by this constructor
  *
@@ -201,7 +212,7 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
  */
 export const make: (params: {
   readonly embedMany: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>
-}) => Effect.Effect<Service> = Effect.fnUntraced(function*(params) {
+}) => Effect.Effect<EmbeddingModel> = Effect.fnUntraced(function*(params) {
   const resolver = RequestResolver.make<EmbeddingRequest>((entries) =>
     Effect.flatMap(
       params.embedMany({
@@ -219,6 +230,7 @@ export const make: (params: {
   )
 
   return EmbeddingModel.of({
+    [TypeId]: TypeId,
     resolver,
     embed: (input) =>
       Effect.request(new EmbeddingRequest({ input }), resolver).pipe(