effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/unstable/ai/Response.ts

@@ -155,7 +155,7 @@ export type AllPartsEncoded =
  *
  * **Example** (Building a response parts schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Response, Tool, Toolkit } from "effect/unstable/ai"
  *
@@ -167,6 +167,7 @@ export type AllPartsEncoded =
  * )
  *
  * const allPartsSchema = Response.AllParts(myToolkit)
+ * Schema.isSchema(allPartsSchema) // => true
  * ```
  *
  * @category schemas
@@ -493,7 +494,7 @@ const BasePart = Schema.Struct({
  *
  * **Example** (Creating response content parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const textPart = Response.makePart("text", {
@@ -506,6 +507,8 @@ const BasePart = Schema.Struct({
  *   params: { city: "San Francisco" },
  *   providerExecuted: false
  * })
+ *
+ * const result = [textPart.type, toolCallPart.name] // => ["text", "get_weather"]
  * ```
  *
  * @category constructors
@@ -557,12 +560,13 @@ export type ConstructorParams<Part extends AnyPart> =
  *
  * **Example** (Creating a text part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const textPart: Response.TextPart = Response.makePart("text", {
  *   text: "The answer to your question is 42."
  * })
+ * textPart.text // => "The answer to your question is 42."
  * ```
  *
  * @category models
@@ -813,13 +817,14 @@ export const TextEndPart: Schema.Struct<{
  *
  * **Example** (Creating a reasoning part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const reasoningPart: Response.ReasoningPart = Response.makePart("reasoning", {
  *   text:
  *     "Let me think step by step: First I need to analyze the user's question..."
  * })
+ * reasoningPart.type // => "reasoning"
  * ```
  *
  * @category models
@@ -1295,7 +1300,7 @@ export const ToolParamsEndPart: Schema.Struct<{
  *
  * **Example** (Creating a tool call part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Response } from "effect/unstable/ai"
  *
@@ -1316,6 +1321,7 @@ export const ToolParamsEndPart: Schema.Struct<{
  *   params: { city: "San Francisco", units: "celsius" },
  *   providerExecuted: false
  * })
+ * const result = [toolCallPart.name, toolCallPart.params.city] // => ["get_weather", "San Francisco"]
  * ```
  *
  * @category models
@@ -1503,7 +1509,7 @@ export interface ToolResultFailure<Name extends string, Failure> extends BaseToo
  *
  * **Example** (Creating a tool result part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * interface WeatherData {
@@ -1533,6 +1539,7 @@ export interface ToolResultFailure<Name extends string, Failure> extends BaseToo
  *   providerExecuted: false,
  *   preliminary: false
  * })
+ * const result = [toolResultPart.name, toolResultPart.result.temperature] // => ["get_weather", 22]
  * ```
  *
  * @category models
@@ -1723,7 +1730,7 @@ export const toolResultPart = <const Params extends ConstructorParams<ToolResult
  *
  * **Example** (Creating an approval request part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const approvalRequest: Response.ToolApprovalRequestPart = Response.makePart(
@@ -1733,6 +1740,7 @@ export const toolResultPart = <const Params extends ConstructorParams<ToolResult
  *     toolCallId: "call_456"
  *   }
  * )
+ * const result = [approvalRequest.approvalId, approvalRequest.toolCallId] // => ["approval_123", "call_456"]
  * ```
  *
  * @category models
@@ -1824,13 +1832,14 @@ export const toolApprovalRequestPart = (
  *
  * **Example** (Creating a file part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const imagePart: Response.FilePart = Response.makePart("file", {
  *   mediaType: "image/jpeg",
  *   data: new Uint8Array([1, 2, 3])
  * })
+ * const result = [imagePart.mediaType, imagePart.data] // => ["image/jpeg", new Uint8Array([1, 2, 3])]
  * ```
  *
  * @category models
@@ -2116,7 +2125,7 @@ export const UrlSourcePart: Schema.Struct<{
  *
  * **Example** (Describing an HTTP request)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Response } from "effect/unstable/ai"
  *
  * const requestDetails: typeof Response.HttpRequestDetails.Type = {
@@ -2126,6 +2135,7 @@ export const UrlSourcePart: Schema.Struct<{
  *   hash: undefined,
  *   headers: { "Content-Type": "application/json" }
  * }
+ * const result = [requestDetails.method, requestDetails.urlParams] // => ["POST", []]
  * ```
  *
  * @category schemas
@@ -2135,7 +2145,7 @@ 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.UndefinedOr(Schema.String),
+  hash: Schema.optional(Schema.String),
   headers: Schema.Record(
     Schema.String,
     Schema.Union([
@@ -2156,7 +2166,7 @@ export const HttpRequestDetails = Schema.Struct({
  *
  * **Example** (Describing an HTTP response)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Response } from "effect/unstable/ai"
  *
  * const responseDetails: typeof Response.HttpResponseDetails.Type = {
@@ -2166,13 +2176,14 @@ export const HttpRequestDetails = Schema.Struct({
  *     "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.Number,
+  status: Schema.Int,
   headers: Schema.Record(
     Schema.String,
     Schema.Union([
@@ -2191,7 +2202,7 @@ export const HttpResponseDetails = Schema.Struct({
  *
  * **Example** (Creating a metadata part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  * import { Response } from "effect/unstable/ai"
  *
@@ -2200,10 +2211,11 @@ export const HttpResponseDetails = Schema.Struct({
  *   {
  *     id: "resp_123",
  *     modelId: "gpt-4",
- *     timestamp: DateTime.nowUnsafe(),
+ *     timestamp: DateTime.makeUnsafe("2024-01-01T00:00:00Z"),
  *     request: undefined
  *   }
  * )
+ * const result = [metadataPart.id, metadataPart.modelId] // => ["resp_123", "gpt-4"]
  * ```
  *
  * @category models
@@ -2213,19 +2225,19 @@ export interface ResponseMetadataPart extends BasePart<"response-metadata", Resp
   /**
    * Optional unique identifier for this specific response.
    */
-  readonly id: string | undefined
+  readonly id?: string | undefined
   /**
    * Optional identifier of the AI model that generated the response.
    */
-  readonly modelId: string | undefined
+  readonly modelId?: string | undefined
   /**
    * Optional timestamp when the response was generated.
    */
-  readonly timestamp: DateTime.Utc | undefined
+  readonly timestamp?: DateTime.Utc | undefined
   /**
    * Optional HTTP request details for the request made to the AI provider.
    */
-  readonly request: typeof HttpRequestDetails.Type | undefined
+  readonly request?: typeof HttpRequestDetails.Type | undefined
 }
 
 /**
@@ -2272,10 +2284,10 @@ export interface ResponseMetadataPartMetadata extends ProviderMetadata {}
  */
 export const ResponseMetadataPart: Schema.Struct<{
   readonly type: Schema.tag<"response-metadata">
-  readonly id: Schema.UndefinedOr<Schema.String>
-  readonly modelId: Schema.UndefinedOr<Schema.String>
-  readonly timestamp: Schema.UndefinedOr<Schema.DateTimeUtcFromString>
-  readonly request: Schema.UndefinedOr<typeof HttpRequestDetails>
+  readonly id: Schema.optional<Schema.String>
+  readonly modelId: Schema.optional<Schema.String>
+  readonly timestamp: Schema.optional<Schema.DateTimeUtcFromString>
+  readonly request: Schema.optional<typeof HttpRequestDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
     Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
@@ -2283,10 +2295,10 @@ export const ResponseMetadataPart: Schema.Struct<{
 }> = Schema.Struct({
   ...BasePart.fields,
   type: Schema.tag("response-metadata"),
-  id: Schema.UndefinedOr(Schema.String),
-  modelId: Schema.UndefinedOr(Schema.String),
-  timestamp: Schema.UndefinedOr(Schema.DateTimeUtcFromString),
-  request: Schema.UndefinedOr(HttpRequestDetails)
+  id: Schema.optional(Schema.String),
+  modelId: Schema.optional(Schema.String),
+  timestamp: Schema.optional(Schema.DateTimeUtcFromString),
+  request: Schema.optional(HttpRequestDetails)
 }).annotate({ identifier: "ResponseMetadataPart" }) satisfies Schema.Codec<
   ResponseMetadataPart,
   ResponseMetadataPartEncoded
@@ -2368,19 +2380,19 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
     /**
      * The number of non-cached input (i.e. prompt) tokens used.
      */
-    uncached: Schema.UndefinedOr(Schema.Number),
+    uncached: Schema.optional(Schema.Int),
     /**
      * The total of number of input (i.e. prompt) tokens used.
      */
-    total: Schema.UndefinedOr(Schema.Number),
+    total: Schema.optional(Schema.Int),
     /**
      * The number of cached input (i.e. prompt) tokens read.
      */
-    cacheRead: Schema.UndefinedOr(Schema.Number),
+    cacheRead: Schema.optional(Schema.Int),
     /**
      * The number of cached input (i.e. prompt) tokens written.
      */
-    cacheWrite: Schema.UndefinedOr(Schema.Number)
+    cacheWrite: Schema.optional(Schema.Int)
   }),
   /**
    * Information about the output (i.e. response) tokens used.
@@ -2389,15 +2401,15 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
     /**
      * The total of number of output (i.e. response) tokens used.
      */
-    total: Schema.UndefinedOr(Schema.Number),
+    total: Schema.optional(Schema.Int),
     /**
      * The number of text tokens used.
      */
-    text: Schema.UndefinedOr(Schema.Number),
+    text: Schema.optional(Schema.Int),
     /**
      * The number of reasoning tokens used.
      */
-    reasoning: Schema.UndefinedOr(Schema.Number)
+    reasoning: Schema.optional(Schema.Int)
   })
 }) {}
 
@@ -2406,7 +2418,7 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
  *
  * **Example** (Creating a finish part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const finishPart: Response.FinishPart = Response.makePart("finish", {
@@ -2426,6 +2438,7 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
  *   }),
  *   response: undefined
  * })
+ * const result = [finishPart.reason, finishPart.usage.inputTokens.total] // => ["stop", 50]
  * ```
  *
  * @category models
@@ -2443,7 +2456,7 @@ export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
   /**
    * Optional HTTP response details from the AI provider.
    */
-  readonly response: typeof HttpResponseDetails.Type | undefined
+  readonly response?: typeof HttpResponseDetails.Type | undefined
 }
 
 /**
@@ -2500,7 +2513,7 @@ export const FinishPart: Schema.Struct<{
     "unknown"
   ]>
   readonly usage: typeof Usage
-  readonly response: Schema.UndefinedOr<typeof HttpResponseDetails>
+  readonly response: Schema.optional<typeof HttpResponseDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
     Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
@@ -2510,7 +2523,7 @@ export const FinishPart: Schema.Struct<{
   type: Schema.tag("finish"),
   reason: FinishReason,
   usage: Usage,
-  response: Schema.UndefinedOr(HttpResponseDetails)
+  response: Schema.optional(HttpResponseDetails)
 }).annotate({ identifier: "FinishPart" }) satisfies Schema.Codec<FinishPart, FinishPartEncoded>
 
 // =============================================================================
@@ -2522,12 +2535,13 @@ export const FinishPart: Schema.Struct<{
  *
  * **Example** (Creating an error part)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Response } from "effect/unstable/ai"
  *
  * const errorPart: Response.ErrorPart = Response.makePart("error", {
  *   error: new Error("boom")
  * })
+ * const result = [errorPart.type, errorPart.error instanceof Error] // => ["error", true]
  * ```
  *
  * @category models

package/src/unstable/ai/Telemetry.ts

@@ -229,7 +229,7 @@ export type WellKnownSystem =
  *
  * **Example** (Prefixing telemetry attributes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Telemetry } from "effect/unstable/ai"
  *
  * type RequestAttrs = {
@@ -245,6 +245,11 @@ export type WellKnownSystem =
  * //   "gen_ai.request.model_name": string
  * //   "gen_ai.request.max_tokens": number
  * // }
+ * const attributes: PrefixedAttrs = {
+ *   "gen_ai.request.model_name": "gpt-4",
+ *   "gen_ai.request.max_tokens": 1000
+ * }
+ * Object.keys(attributes) // => ["gen_ai.request.model_name", "gen_ai.request.max_tokens"]
  * ```
  *
  * @category utility types
@@ -264,12 +269,19 @@ export type AttributesWithPrefix<Attributes extends Record<string, any>, Prefix
  *
  * **Example** (Formatting attribute names)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Telemetry } from "effect/unstable/ai"
  *
  * type Formatted1 = Telemetry.FormatAttributeName<"modelName"> // "model_name"
  * type Formatted2 = Telemetry.FormatAttributeName<"maxTokens"> // "max_tokens"
  * type Formatted3 = Telemetry.FormatAttributeName<"temperature"> // "temperature"
+ *
+ * const formatted: [Formatted1, Formatted2, Formatted3] = [
+ *   "model_name",
+ *   "max_tokens",
+ *   "temperature"
+ * ]
+ * formatted // => ["model_name", "max_tokens", "temperature"]
  * ```
  *
  * @category utility types
@@ -292,9 +304,8 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  *
  * **Example** (Adding prefixed span attributes)
  *
- * ```ts
- * import { String } from "effect"
- * import type { Tracer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Option, String, Tracer } from "effect"
  * import { Telemetry } from "effect/unstable/ai"
  *
  * const addCustomAttributes = Telemetry.addSpanAttributes(
@@ -302,13 +313,22 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  *   String.camelToSnake
  * )
  *
- * // Usage with a span
- * declare const span: Tracer.Span
+ * const span = new Tracer.NativeSpan({
+ *   name: "request",
+ *   parent: Option.none(),
+ *   annotations: Context.empty(),
+ *   links: [],
+ *   startTime: 0n,
+ *   kind: "internal",
+ *   sampled: true
+ * })
+ *
  * addCustomAttributes(span, {
  *   modelName: "gpt-4",
  *   maxTokens: 1000
  * })
- * // Results in attributes: "custom.ai.model_name" and "custom.ai.max_tokens"
+ *
+ * Array.from(span.attributes.keys()) // => ["custom.ai.model_name", "custom.ai.max_tokens"]
  * ```
  *
  * @category annotations
@@ -358,7 +378,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *
  * **Example** (Configuring GenAI telemetry attributes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Telemetry } from "effect/unstable/ai"
  *
  * const telemetryOptions: Telemetry.GenAITelemetryAttributeOptions = {
@@ -381,6 +401,8 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  *     outputTokens: 25
  *   }
  * }
+ *
+ * const result = [telemetryOptions.system, telemetryOptions.usage?.inputTokens] // => ["openai", 50]
  * ```
  *
  * @category options
@@ -428,7 +450,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *
  * **Example** (Adding GenAI telemetry annotations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { Telemetry } from "effect/unstable/ai"
  *
@@ -440,7 +462,10 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  *     request: { model: "gpt-4", temperature: 0.7 },
  *     usage: { inputTokens: 100, outputTokens: 50 }
  *   })
+ *   return (span as { attributes: ReadonlyMap<string, unknown> }).attributes.size
  * })
+ *
+ * await Effect.runPromise(Effect.withSpan(directUsage, "example")) // => 5
  * ```
  *
  * @category annotations
@@ -466,7 +491,7 @@ export const addGenAIAnnotations: {
    *
    * **Example** (Adding GenAI telemetry annotations)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect } from "effect"
    * import { Telemetry } from "effect/unstable/ai"
    *
@@ -478,7 +503,10 @@ export const addGenAIAnnotations: {
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
+   *   return (span as { attributes: ReadonlyMap<string, unknown> }).attributes.size
    * })
+   *
+   * await Effect.runPromise(Effect.withSpan(directUsage, "example")) // => 5
    * ```
    *
    * @category annotations
@@ -504,7 +532,7 @@ export const addGenAIAnnotations: {
    *
    * **Example** (Adding GenAI telemetry annotations)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect } from "effect"
    * import { Telemetry } from "effect/unstable/ai"
    *
@@ -516,7 +544,10 @@ export const addGenAIAnnotations: {
    *     request: { model: "gpt-4", temperature: 0.7 },
    *     usage: { inputTokens: 100, outputTokens: 50 }
    *   })
+   *   return (span as { attributes: ReadonlyMap<string, unknown> }).attributes.size
    * })
+   *
+   * await Effect.runPromise(Effect.withSpan(directUsage, "example")) // => 5
    * ```
    *
    * @category annotations
@@ -542,7 +573,7 @@ export const addGenAIAnnotations: {
  *
  * **Example** (Transforming AI spans)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Telemetry } from "effect/unstable/ai"
  *
  * const customTransformer: Telemetry.SpanTransformer = ({ response, span }) => {
@@ -554,6 +585,8 @@ export const addGenAIAnnotations: {
  *   )
  *   span.attribute("total_text_length", totalTextLength)
  * }
+ *
+ * typeof customTransformer // => "function"
  * ```
  *
  * @category models

package/src/unstable/ai/Tokenizer.ts

@@ -31,7 +31,7 @@ import * as Prompt from "./Prompt.ts"
  *
  * **Example** (Accessing the Tokenizer service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { Tokenizer } from "effect/unstable/ai"
  *
@@ -40,6 +40,12 @@ import * as Prompt from "./Prompt.ts"
  *   const tokens = yield* tokenizer.tokenize("Hello, world!")
  *   return tokens.length
  * })
+ *
+ * const tokenizer = Tokenizer.make({
+ *   tokenize: (prompt) => Effect.succeed(prompt.content.map((_, index) => index))
+ * })
+ * const result = useTokenizer.pipe(Effect.provideService(Tokenizer.Tokenizer, tokenizer))
+ * await Effect.runPromise(result) // => 1
  * ```
  *
  * @category services
@@ -60,7 +66,7 @@ export class Tokenizer extends Context.Service<Tokenizer, Service>()(
  *
  * **Example** (Implementing a custom tokenizer)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { Prompt } from "effect/unstable/ai"
  * import type { Tokenizer } from "effect/unstable/ai"
@@ -71,6 +77,9 @@ export class Tokenizer extends Context.Service<Tokenizer, Service>()(
  *   truncate: (input, maxTokens) =>
  *     Effect.succeed(Prompt.make(input.toString().slice(0, maxTokens * 5)))
  * }
+ *
+ * const tokenCount = (await Effect.runPromise(customTokenizer.tokenize("one two three"))).length // => 3
+ * const messageCount = (await Effect.runPromise(customTokenizer.truncate("hello world", 1))).content.length // => 1
  * ```
  *
  * @category models
@@ -112,7 +121,7 @@ export interface Service {
  *
  * **Example** (Creating a word tokenizer)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { Tokenizer } from "effect/unstable/ai"
  *
@@ -131,6 +140,8 @@ export interface Service {
  *         .map((_, index) => index)
  *     )
  * })
+ *
+ * await Effect.runPromise(wordTokenizer.tokenize("hello effect world")) // => [0, 1, 2]
  * ```
  *
  * @category constructors