@effect/ai 0.14.0 → 0.15.0

package/dist/esm/AiResponse.js

@@ -1,60 +1,340 @@
-/**
- * @since 1.0.0
- */
-import * as Chunk from "effect/Chunk";
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
-import * as Iterable from "effect/Iterable";
+import { dual } from "effect/Function";
 import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
 import { AiError } from "./AiError.js";
-import * as AiRole from "./AiRole.js";
+import * as InternalCommon from "./internal/common.js";
+const constDisableValidation = {
+  disableValidation: true
+};
 /**
  * @since 1.0.0
- * @category type ids
+ * @category Type Ids
  */
-export const TypeId = /*#__PURE__*/Symbol("@effect/ai/AiResponse");
+export const TypeId = /*#__PURE__*/Symbol.for("@effect/ai/AiResponse");
 /**
+ * Represents a response received from a large language model.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export const PartTypeId = /*#__PURE__*/Symbol("@effect/ai/AiResponse/Part");
-const constDisableValidation = {
-  disableValidation: true
-};
+export class AiResponse extends /*#__PURE__*/Schema.Class("@effect/ai/AiResponse")({
+  /**
+   * The parts of the response.
+   */
+  parts: /*#__PURE__*/Schema.Array( /*#__PURE__*/Schema.suspend(() => Part))
+}) {
+  /**
+   * @since 1.0.0
+   */
+  [TypeId] = TypeId;
+  /**
+   * Returns the generated text content of the response.
+   */
+  get text() {
+    let text = "";
+    let found = false;
+    for (const part of this.parts) {
+      if (part._tag === "TextPart") {
+        text += found ? "\n\n" + part.text : part.text;
+        found = true;
+      }
+    }
+    return text;
+  }
+  /**
+   * Returns the finish reason for the response, or `"unknown"` if the finish
+   * reason is not known.
+   */
+  get finishReason() {
+    const finishPart = this.parts.find(part => part._tag === "FinishPart");
+    return finishPart?.reason ?? "unknown";
+  }
+  /**
+   * Attempts to retrieve provider-specific response metadata.
+   */
+  getProviderMetadata(tag) {
+    const finishPart = this.parts.find(part => part._tag === "FinishPart");
+    return Option.fromNullable(finishPart?.providerMetadata[tag.key]);
+  }
+}
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export const FromJson = /*#__PURE__*/Schema.parseJson(AiResponse);
+/**
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export const StructuredResponseTypeId = /*#__PURE__*/Symbol.for("@effect/ai/AiResponse/StructuredResponse");
+/**
+ * Represents a response generated by a large language model that includes
+ * structured output.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class WithStructuredOutput extends AiResponse {
+  /**
+   * @since 1.0.0
+   */
+  [StructuredResponseTypeId] = StructuredResponseTypeId;
+  /**
+   * The identifier of the tool which generated the structured output.
+   */
+  id;
+  /**
+   * The name of the tool which generated the structured output.
+   */
+  name;
+  /**
+   * The structured output generated by the model.
+   */
+  value;
+  constructor(props, options) {
+    super({
+      parts: props.parts
+    }, options);
+    this.id = props.id;
+    this.name = props.name;
+    this.value = props.value;
+  }
+}
+/**
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export const WithToolCallResultsTypeId = /*#__PURE__*/Symbol.for("@effect/ai/AiResponse/WithToolCallResults");
+/**
+ * Represents a response generated by a large language model that includes
+ * tool call results.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class WithToolCallResults extends AiResponse {
+  /**
+   * @since 1.0.0
+   */
+  [WithToolCallResultsTypeId] = WithToolCallResultsTypeId;
+  /**
+   * The tool call results, represented as a mapping between the tool call
+   * identifier and the result of the tool call handler.
+   */
+  results;
+  /**
+   * The encoded tool call results, suitable for incorporation into subsequent
+   * requests to the large language model.
+   */
+  encodedResults;
+  constructor(props, options) {
+    super({
+      parts: props.parts
+    }, options);
+    this.results = props.results;
+    this.encodedResults = props.encodedResults;
+  }
+}
+// =============================================================================
+// Part
+// =============================================================================
+/**
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export const PartTypeId = /*#__PURE__*/Symbol.for("@effect/ai/AiResponse/Part");
 /**
+ * Represents a content source that was used to generate a model response.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class TextPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/TextPart")("Text", {
-  content: Schema.String
+export class ContentSourceAnnotation extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/Annotation/ContentSourceAnnotation")("ContentSourceAnnotation", {
+  /**
+   * The identifier for the content source.
+   */
+  id: Schema.String,
+  /**
+   * The index of the content source in the list of sources provided in the
+   * model request parameters.
+   */
+  index: Schema.Int,
+  /**
+   * The provider-specific type of the file annotation.
+   *
+   * For example, when using Anthropic the type may be `char_location`,
+   * `page_location`, or `content_block_location`.
+   */
+  type: Schema.String,
+  /**
+   * The content used from the content source in the message generated by the
+   * model.
+   */
+  referencedContent: Schema.String,
+  /**
+   * The index of the first character of the content referenced by the content
+   * source in the message generated by the model.
+   */
+  startIndex: Schema.Int,
+  /**
+   * The index of the last character of the content referenced by the content
+   * source in the message generated by the model.
+   */
+  endIndex: Schema.Int
+}) {}
+/**
+ * Represents a file that was used to generate a model response.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class FileAnnotation extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/Annotation/FileAnnotation")("FileAnnotation", {
+  /**
+   * The identifier for the file.
+   */
+  id: Schema.String,
+  /**
+   * The provider-specific type of the file annotation.
+   *
+   * For example, when using OpenAi the type may be `file_citation` or
+   * `file_path`.
+   */
+  type: Schema.String,
+  /**
+   * The index of the file in the list of files provided in the model request
+   * parameters.
+   */
+  index: Schema.Int
+}) {}
+/**
+ * Represents a web resource that was used to generate a model response.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class UrlAnnotation extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/Annotation/UrlAnnotation")("UrlAnnotation", {
+  /**
+   * The URL of the web resource.
+   */
+  url: Schema.String,
+  /**
+   * The title of the web resource.
+   */
+  title: Schema.String,
+  /**
+   * The index of the first character of the content referenced by the web
+   * resource in the message generated by the model.
+   */
+  startIndex: Schema.Int,
+  /**
+   * The index of the last character of the content referenced by the web
+   * resource in the message generated by the model.
+   */
+  endIndex: Schema.Int
+}) {}
+/**
+ * Represents annotations that were used to support the message generated by
+ * a model.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export const Annotation = /*#__PURE__*/Schema.Union(ContentSourceAnnotation, FileAnnotation, UrlAnnotation);
+/**
+ * Represents part of the text generated by the model.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class TextPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/TextPart")("TextPart", {
+  /**
+   * The text content generated by the model.
+   */
+  text: Schema.String,
+  /**
+   * The annotations used to support the text generated by the model.
+   */
+  annotations: /*#__PURE__*/Schema.optionalWith( /*#__PURE__*/Schema.Array(Annotation), {
+    default: () => []
+  })
 }) {
   /**
    * @since 1.0.0
    */
   [PartTypeId] = PartTypeId;
+}
+/**
+ * Represents part of the reasoning carried out by the model to generate a
+ * response.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class ReasoningPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/ReasoningPart")("ReasoningPart", {
+  /**
+   * The reasoning content that the model used to return the output.
+   */
+  reasoningText: Schema.String,
+  /**
+   * An optional signature which verifies that the reasoning text was generated
+   * by the model.
+   */
+  signature: /*#__PURE__*/Schema.optional(Schema.String)
+}) {
   /**
    * @since 1.0.0
    */
-  static fromContent(content) {
-    return new TextPart({
-      content
-    }, constDisableValidation);
-  }
+  [PartTypeId] = PartTypeId;
+}
+/**
+ * Represents part of the reasoning carried out by the model to generate a
+ * response which needed to be encrypted by the model provider for safety
+ * reasons.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class RedactedReasoningPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/RedactedReasoningPart")("RedactedReasoningPart", {
+  /**
+   * The content in the reasoning that was encrypted by the model provider for
+   * safety reasons.
+   */
+  redactedText: Schema.String
+}) {
+  /**
+   * @since 1.0.0
+   */
+  [PartTypeId] = PartTypeId;
 }
 /**
+ * Represents the identifier generated by a model when a tool call is requested.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export const ToolCallId = /*#__PURE__*/Schema.String.pipe( /*#__PURE__*/Schema.brand("ToolCallId"));
+export const ToolCallId = InternalCommon.ToolCallId;
 /**
+ * Represents a request by a model to call a specific tool that it has been
+ * provided with.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/ToolCallPart")("ToolCall", {
+export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/ToolCallPart")("ToolCallPart", {
+  /**
+   * The identifier generated by a model when requesting a tool call.
+   */
   id: ToolCallId,
+  /**
+   * The name of the tool to call.
+   */
   name: Schema.String,
+  /**
+   * The arguments to call the tool with as a JSON-serializable object that
+   * matches the tool call input schema.
+   */
   params: Schema.Unknown
 }) {
   /**
@@ -62,6 +342,10 @@ export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/Ai
    */
   [PartTypeId] = PartTypeId;
   /**
+   * Converts a raw tool call into a `ToolCallPart` by parsing tool call
+   * parameters as a JSON string. If your tool call parameters are already
+   * parsed, use `ToolCallPart.fromUnknown`.
+   *
    * @since 1.0.0
    */
   static fromJson({
@@ -72,7 +356,7 @@ export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/Ai
     return Effect.try({
       try() {
         return new ToolCallPart({
-          id: ToolCallId.make(id),
+          id: ToolCallId.make(id, constDisableValidation),
           name,
           params: JSON.parse(params)
         }, constDisableValidation);
@@ -80,12 +364,16 @@ export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/Ai
       catch: cause => new AiError({
         module: "AiResponse",
         method: "ToolCall.fromJson",
-        description: "Failed to parse parameters",
+        description: `Failed to parse parameters from JSON:\n${params}`,
         cause
       })
     });
   }
   /**
+   * Converts a raw tool call into a `ToolCallPart` assuming that the tool call
+   * parameters have already been parsed. If your tool call parameters have not
+   * already been parsed, use `ToolCallPart.fromJson`.
+   *
    * @since 1.0.0
    */
   static fromUnknown({
@@ -94,18 +382,33 @@ export class ToolCallPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/Ai
     params
   }) {
     return new ToolCallPart({
-      id: ToolCallId.make(id),
+      id: ToolCallId.make(id, constDisableValidation),
       name,
       params
     }, constDisableValidation);
   }
 }
 /**
+ * Represents the initial response metadata generated by a model when responding
+ * to a request.
+ *
  * @since 1.0.0
- * @category parts
+ * @categor Models
  */
-export class ImageUrlPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/ImageUrlPart")("ImageUrl", {
-  url: Schema.String
+export class MetadataPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/MetadataPart")("MetadataPart", {
+  /**
+   * The unique identifier for the response. Each chunk of the response should
+   * have the same identifier.
+   */
+  id: /*#__PURE__*/Schema.optional(Schema.String),
+  /**
+   * The model that was used to generate the response.
+   */
+  model: Schema.String,
+  /**
+   * The Unix timestamp of when the model began generated the response.
+   */
+  timestamp: /*#__PURE__*/Schema.optional(Schema.DateFromNumber)
 }) {
   /**
    * @since 1.0.0
@@ -113,169 +416,171 @@ export class ImageUrlPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/Ai
   [PartTypeId] = PartTypeId;
 }
 /**
+ * Represents the reason why a model finished generation of a response.
+ *
+ * Possible finish reasons:
+ * - `"stop"`: The model generated a stop sequence.
+ * - `"length"`: The model exceeded its token budget.
+ * - `"content-filter"`: The model generated content which violated a content filter.
+ * - `"tool-calls"`: The model triggered a tool call.
+ * - `"error"`: The model encountered an error.
+ * - `"other"`: The model stopped for a reason not supported by this protocol.
+ * - `"unknown"`: The model did not specify a finish reason.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export const Part = /*#__PURE__*/Schema.Union(TextPart, ToolCallPart, ImageUrlPart);
+export const FinishReason = /*#__PURE__*/Schema.Literal("stop", "length", "content-filter", "tool-calls", "error", "other", "unknown");
 /**
+ * Represents information about the number of tokens used by the model to
+ * generate a response.
+ *
  * @since 1.0.0
- * @category models
+ * @category Models
  */
-export class AiResponse extends /*#__PURE__*/Schema.Class("@effect/ai/AiResponse")({
-  role: AiRole.AiRole,
-  parts: /*#__PURE__*/Schema.Chunk(Part)
-}) {
+export class Usage extends /*#__PURE__*/Schema.Class("@effect/ai/AiResponse/Usage")({
   /**
-   * @since 1.0.0
+   * The number of tokens sent in the request to the model.
    */
-  [TypeId] = TypeId;
+  inputTokens: Schema.Number,
   /**
-   * @since 1.0.0
+   * The number of tokens that the model generated for the request.
    */
-  static is(u) {
-    return Predicate.hasProperty(u, TypeId);
-  }
+  outputTokens: Schema.Number,
   /**
-   * @since 1.0.0
+   * The total of number of input tokens and output tokens generated by the
+   * model.
    */
-  static empty = /*#__PURE__*/new AiResponse({
-    role: AiRole.model,
-    parts: /*#__PURE__*/Chunk.empty()
-  });
+  totalTokens: Schema.Number,
   /**
-   * @since 1.0.0
+   * The number of reasoning tokens that the model used to generate the output
+   * for the request.
    */
-  static fromText(options) {
-    return new AiResponse({
-      role: options.role,
-      parts: Chunk.of(TextPart.fromContent(options.content))
-    }, constDisableValidation);
-  }
+  reasoningTokens: Schema.Number,
   /**
-   * @since 1.0.0
+   * The number of input tokens read from the prompt cache for the request.
    */
-  get text() {
-    let text = "";
-    let found = false;
-    for (const part of this.parts) {
-      if (part._tag === "Text") {
-        text += found ? "\n\n" + part.content : part.content;
-        found = true;
-      }
-    }
-    return text;
-  }
+  cacheReadInputTokens: Schema.Number,
   /**
-   * @since 1.0.0
+   * The number of input tokens written to the prompt cache for the request.
    */
-  get imageUrl() {
-    for (const part of this.parts) {
-      if (part._tag === "ImageUrl") {
-        return Option.some(part.url);
-      }
-    }
-    return Option.none();
-  }
+  cacheWriteInputTokens: Schema.Number
+}) {}
+/**
+ * Represents the final part of a response generated by a large language model.
+ *
+ * Contains useful information such as tokens used as part of the interaction
+ * with the model.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class FinishPart extends /*#__PURE__*/Schema.TaggedClass("@effect/ai/AiResponse/FinishPart")("FinishPart", {
   /**
-   * @since 1.0.0
+   * The usage information for the response.
    */
-  withToolCallsJson(calls) {
-    return Effect.forEach(calls, call => ToolCallPart.fromJson(call)).pipe(Effect.map(parts => new AiResponse({
-      role: this.role,
-      parts: Chunk.appendAll(this.parts, Chunk.unsafeFromArray(parts))
-    }, constDisableValidation)));
-  }
+  usage: Usage,
   /**
-   * @since 1.0.0
+   * The reason the model finished generating a response.
    */
-  withToolCallsUnknown(calls) {
-    return new AiResponse({
-      role: this.role,
-      parts: Chunk.fromIterable(calls).pipe(Chunk.map(part => ToolCallPart.fromUnknown(part)))
-    }, constDisableValidation);
-  }
+  reason: FinishReason,
+  /**
+   * Provider-specific metadata associated with the response.
+   */
+  providerMetadata: /*#__PURE__*/Schema.optionalWith( /*#__PURE__*/Schema.Record({
+    key: Schema.String,
+    value: /*#__PURE__*/Schema.Record({
+      key: Schema.String,
+      value: Schema.Unknown
+    })
+  }), {
+    default: () => ({})
+  })
+}) {
   /**
    * @since 1.0.0
    */
-  concat(that) {
-    if (Chunk.isEmpty(that.parts)) {
-      return this;
-    }
-    const lastPart = Chunk.last(this.parts);
-    if (Option.isNone(lastPart)) {
-      return that;
-    }
-    const newParts = [];
-    let content = lastPart.value._tag === "Text" ? lastPart.value.content : "";
-    for (const part of that.parts) {
-      if (part._tag === "Text") {
-        content += part.content;
-      }
-    }
-    if (content.length > 0) {
-      newParts.push(TextPart.fromContent(content));
-    }
-    return newParts.length === 0 ? this : new AiResponse({
-      role: that.role,
-      parts: Chunk.appendAll(Chunk.dropRight(this.parts, 1), Chunk.unsafeFromArray(newParts))
-    }, constDisableValidation);
-  }
+  [PartTypeId] = PartTypeId;
 }
 /**
+ * Represents an single part of a response received from a large language model.
+ *
  * @since 1.0.0
- * @category tools
+ * @category Models
  */
-export const WithResolvedTypeId = /*#__PURE__*/Symbol("@effect/ai/AiResponse/WithResolved");
+export const Part = /*#__PURE__*/Schema.Union(TextPart, ReasoningPart, RedactedReasoningPart, ToolCallPart, MetadataPart, FinishPart);
 /**
  * @since 1.0.0
- * @category tools
+ * @category Guards
  */
-export class WithResolved extends Data.Class {
-  /**
-   * @since 1.0.0
-   */
-  [WithResolvedTypeId] = WithResolvedTypeId;
-  /**
-   * @since 1.0.0
-   */
-  static is(u) {
-    return Predicate.hasProperty(u, WithResolvedTypeId);
-  }
-  /**
-   * @since 1.0.0
-   */
-  static empty = /*#__PURE__*/new WithResolved({
-    response: AiResponse.empty,
-    resolved: /*#__PURE__*/new Map(),
-    encoded: /*#__PURE__*/new Map()
-  });
-  /**
-   * @since 1.0.0
-   */
-  get values() {
-    return Array.from(this.resolved.values());
+export const is = u => Predicate.hasProperty(u, TypeId);
+/**
+ * @since 1.0.0
+ * @category Guards
+ */
+export const isPart = u => Predicate.hasProperty(u, PartTypeId);
+/**
+ * @since 1.0.0
+ * @category Guards
+ */
+export const isStructured = u => Predicate.hasProperty(u, StructuredResponseTypeId);
+/**
+ * @since 1.0.0
+ * @category Guards
+ */
+export const hasToolCallResults = u => Predicate.hasProperty(u, WithToolCallResultsTypeId);
+/**
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const empty = /*#__PURE__*/new AiResponse({
+  parts: []
+}, constDisableValidation);
+/**
+ * Combines two responses into a single response.
+ *
+ * @since 1.0.0
+ * @category Combination
+ */
+export const merge = /*#__PURE__*/dual(2, (self, other) => {
+  if (other.parts.length === 0) {
+    return new AiResponse({
+      parts: self.parts
+    }, constDisableValidation);
   }
-  /**
-   * @since 1.0.0
-   */
-  get value() {
-    return Iterable.head(this.resolved.values());
+  if (self.parts.length === 0) {
+    return new AiResponse({
+      parts: other.parts
+    }, constDisableValidation);
   }
-  /**
-   * @since 1.0.0
-   */
-  get unsafeValue() {
-    return Iterable.unsafeHead(this.resolved.values());
+  const lastPart = self.parts[self.parts.length - 1];
+  const newParts = [];
+  let text = lastPart._tag === "TextPart" ? lastPart.text : "";
+  for (const part of other.parts) {
+    if (part._tag === "TextPart") {
+      text += part.text;
+    }
   }
-  /**
-   * @since 1.0.0
-   */
-  concat(that) {
-    return new WithResolved({
-      response: this.response.concat(that.response),
-      resolved: that.resolved.size === 0 ? this.resolved : new Map([...this.resolved, ...that.resolved]),
-      encoded: that.encoded.size === 0 ? this.encoded : new Map([...this.encoded, ...that.encoded])
-    });
+  if (text.length > 0) {
+    newParts.push(new TextPart({
+      text
+    }, constDisableValidation));
   }
-}
+  return newParts.length === 0 ? self : new AiResponse({
+    parts: [...self.parts.slice(0, self.parts.length - 1), ...newParts]
+  }, constDisableValidation);
+});
+/**
+ * Adds the specified tool calls to the provided `AiResponse`.
+ *
+ * **NOTE**: With this method, the tool call parameters will be parsed as a
+ * JSON string. If your tool call parameters are already parsed, use
+ * `AiResponse.withToolCallsUnknown`.
+ *
+ * @since 1.0.0
+ * @category Combination
+ */
+export const withToolCallsJson = /*#__PURE__*/dual(2, (self, toolCalls) => Effect.forEach(toolCalls, toolCall => ToolCallPart.fromJson(toolCall)).pipe(Effect.map(parts => new AiResponse({
+  parts: [...self.parts, ...parts]
+}, constDisableValidation))));
 //# sourceMappingURL=AiResponse.js.map