effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/testing/TestSchema.ts

@@ -78,7 +78,7 @@ import * as Parser from "../SchemaParser.ts"
 import * as FastCheck from "../testing/FastCheck.ts"
 
 /**
- * Entry point for schema test assertions. Wraps a schema and exposes operation-specific helpers for decoding, encoding, make, arbitrary generation, and round-trip verification.
+ * Provides schema test assertions for decoding, encoding, make, arbitrary generation, and round-trip verification.
  *
  * **When to use**
  *
@@ -344,7 +344,7 @@ export class Asserts<S extends Schema.Top> {
 }
 
 /**
- * Decoding test helper that wraps a schema and exposes `succeed` and `fail` methods that run the schema's decoder and compare the result.
+ * Provides decoding test assertions through `succeed` and `fail` methods that run the schema's decoder and compare the result.
  *
  * **When to use**
  *
@@ -470,10 +470,6 @@ export class Decoding<S extends Schema.Top> {
    *
    * Use when the schema's decoder requires a service dependency.
    *
-   * **Details**
-   *
-   * This method does not mutate the current instance.
-   *
    * @see {@link Encoding.provide}
    */
   provide<Id, Service>(
@@ -488,7 +484,7 @@ export class Decoding<S extends Schema.Top> {
 }
 
 /**
- * Encoding test helper that wraps a schema and exposes `succeed` and `fail` methods that run the schema's encoder and compare the result.
+ * Provides encoding test assertions through `succeed` and `fail` methods that run the schema's encoder and compare the result.
  *
  * **When to use**
  *
@@ -614,10 +610,6 @@ export class Encoding<S extends Schema.Top> {
    *
    * Use when the schema's encoder requires a service dependency.
    *
-   * **Details**
-   *
-   * This method does not mutate the current instance.
-   *
    * @see {@link Decoding.provide}
    */
   provide<Id, Service>(

package/src/unstable/ai/AiError.ts

@@ -364,11 +364,11 @@ export interface UnsupportedSchemaErrorMetadata extends ProviderMetadata {}
 export interface UnknownErrorMetadata extends ProviderMetadata {}
 
 /**
- * Token usage information from AI operations.
+ * Schema for token usage information from AI operations.
  *
  * **Details**
  *
- * Contains optional provider-reported token counts for prompt tokens,
+ * Schema for optional provider-reported token counts for prompt tokens,
  * completion tokens, and total tokens.
  *
  * @category schemas
@@ -381,7 +381,12 @@ export const UsageInfo = Schema.Struct({
 }).annotate({ identifier: "UsageInfo" })
 
 /**
- * Combined HTTP context for error reporting.
+ * Schema for the combined HTTP context used in error reporting.
+ *
+ * **When to use**
+ *
+ * Use to attach request details, optional response details, and optional body
+ * text to AI provider errors.
  *
  * **Details**
  *
@@ -950,7 +955,7 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
 }
 
 /**
- * Catch-all error for unknown or unexpected errors.
+ * Error data for unknown or unexpected AI failures.
  *
  * **Details**
  *
@@ -1488,7 +1493,7 @@ export const AiErrorReason: Schema.Union<[
 const TypeId = "~effect/unstable/ai/AiError/AiError" as const
 
 /**
- * Top-level AI error wrapper using the `reason` pattern.
+ * Schema for the top-level AI error wrapper using the `reason` pattern.
  *
  * **When to use**
  *

package/src/unstable/ai/Chat.ts

@@ -79,7 +79,12 @@ import type * as Response from "./Response.ts"
 import type * as Tool from "./Tool.ts"
 
 /**
- * The `Chat` service tag for dependency injection.
+ * Service tag for stateful AI conversation sessions.
+ *
+ * **When to use**
+ *
+ * Use to access or provide conversational AI sessions through the Effect
+ * context.
  *
  * **Details**
  *
@@ -102,7 +107,7 @@ import type * as Tool from "./Tool.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class Chat extends Context.Service<Chat, Service>()(
@@ -694,9 +699,14 @@ export const fromJson = (data: string): Effect.Effect<
 // =============================================================================
 
 /**
- * An error that occurs when attempting to retrieve a persisted `Chat` that
+ * Represents an error that occurs when attempting to retrieve a persisted `Chat` that
  * does not exist in the backing persistence store.
  *
+ * **When to use**
+ *
+ * Use to represent a missing persisted conversation when lookup by id cannot
+ * find stored history.
+ *
  * @category errors
  * @since 4.0.0
  */
@@ -708,9 +718,14 @@ export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
 }) {}
 
 /**
- * The context tag for chat persistence.
+ * Service tag for persistence-backed AI conversation storage.
+ *
+ * **When to use**
+ *
+ * Use to provide the storage operations needed by persisted conversation
+ * sessions.
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 // @effect-diagnostics effect/leakingRequirements:off

package/src/unstable/ai/EmbeddingModel.ts

@@ -92,7 +92,7 @@ export class Dimensions extends Context.Service<Dimensions, number>()(
 ) {}
 
 /**
- * Token usage metadata for embedding operations.
+ * Represents token usage metadata for embedding operations.
  *
  * **Details**
  *
@@ -122,7 +122,8 @@ export class EmbedResponse extends Schema.Class<EmbedResponse>(
 }) {}
 
 /**
- * Batch embedding response containing per-input embeddings and usage metadata.
+ * Response for batch embedding requests containing per-input embeddings and usage
+ * metadata.
  *
  * **Details**
  *
@@ -166,7 +167,7 @@ export interface ProviderResponse {
 }
 
 /**
- * Tagged request used by request resolvers for embedding operations.
+ * Represents a tagged request used by request resolvers for embedding operations.
  *
  * **When to use**
  *
@@ -187,7 +188,7 @@ export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
 > {}
 
 /**
- * Service interface for embedding operations.
+ * Defines the service interface for embedding operations.
  *
  * @category models
  * @since 4.0.0

package/src/unstable/ai/IdGenerator.ts

@@ -55,7 +55,12 @@ import * as Predicate from "../../Predicate.ts"
 import * as Random from "../../Random.ts"
 
 /**
- * The `IdGenerator` service tag for dependency injection.
+ * Service tag for AI identifier generation services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide the service that creates identifiers for AI tool
+ * calls and related generated values.
  *
  * **Details**
  *
@@ -76,7 +81,7 @@ import * as Random from "../../Random.ts"
  * })
  * ```
  *
- * @category models
+ * @category tags
  * @since 4.0.0
  */
 export class IdGenerator extends Context.Service<IdGenerator, Service>()(

package/src/unstable/ai/LanguageModel.ts

@@ -82,7 +82,12 @@ import * as Toolkit from "./Toolkit.ts"
 // =============================================================================
 
 /**
- * The `LanguageModel` service key for dependency injection, providing access to text generation, streaming, and structured output capabilities throughout an application.
+ * Service tag for AI model services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide text generation, streaming generation, structured
+ * output, and tool-calling capabilities through the Effect context.
  *
  * **Example** (Accessing the language model service)
  *
@@ -99,7 +104,7 @@ import * as Toolkit from "./Toolkit.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class LanguageModel extends Context.Service<LanguageModel, Service>()(
@@ -1621,7 +1626,7 @@ export const make: (params: {
 // =============================================================================
 
 /**
- * Generate text using a language model.
+ * Generates text using a language model.
  *
  * **Example** (Generating text with options)
  *
@@ -1690,7 +1695,7 @@ export const generateText: {
   )
 
 /**
- * Generate a structured object from a schema using a language model.
+ * Generates a structured object from a schema using a language model.
  *
  * **Example** (Generating an object)
  *
@@ -1742,7 +1747,7 @@ export const generateObject = <
   ) as any
 
 /**
- * Generate text using a language model with streaming output.
+ * Generates text using a language model with streaming output.
  *
  * **Details**
  *