@effect/ai 0.28.1 → 0.28.3

package/src/Prompt.ts

@@ -51,9 +51,14 @@
  *
  * @since 1.0.0
  */
+import * as Arbitrary from "effect/Arbitrary"
+import * as Arr from "effect/Array"
 import { constFalse, dual } from "effect/Function"
+import * as ParseResult from "effect/ParseResult"
+import { type Pipeable, pipeArguments } from "effect/Pipeable"
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
+import type * as AST from "effect/SchemaAST"
 import type * as Response from "./Response.js"
 
 const constEmptyObject = () => ({})
@@ -221,10 +226,10 @@ export const makePart = <const Type extends Part["type"]>(
   }
 ): Extract<Part, { type: Type }> =>
   (({
-   ...params,
-   [PartTypeId]: PartTypeId,
-   type,
-   options: params.options ?? {}
+    ...params,
+    [PartTypeId]: PartTypeId,
+    type,
+    options: params.options ?? {}
   }) as any)
 
 // =============================================================================
@@ -720,12 +725,28 @@ export const makeMessage = <const Role extends Message["role"]>(
   }
 ): Extract<Message, { role: Role }> =>
   (({
-   ...params,
-   [MessageTypeId]: MessageTypeId,
-   role,
-   options: params.options ?? {}
+    ...params,
+    [MessageTypeId]: MessageTypeId,
+    role,
+    options: params.options ?? {}
   }) as any)
 
+/**
+ * Schema for decoding message content (i.e. an array containing a single
+ * `TextPart`) from a string.
+ *
+ * @since 1.0.0
+ * @category Schemas
+ */
+export const MessageContentFromString: Schema.Schema<
+  Arr.NonEmptyReadonlyArray<TextPart>,
+  string
+> = Schema.transform(Schema.String, Schema.NonEmptyArray(Schema.typeSchema(TextPart)), {
+  strict: true,
+  decode: (text) => Arr.of(makePart("text", { text })),
+  encode: (content) => content[0].text
+})
+
 // =============================================================================
 // System Message
 // =============================================================================
@@ -851,7 +872,7 @@ export interface UserMessageEncoded extends BaseMessageEncoded<"user", UserMessa
   /**
    * Array of content parts that make up the user's message.
    */
-  readonly content: ReadonlyArray<UserMessagePartEncoded>
+  readonly content: string | ReadonlyArray<UserMessagePartEncoded>
 }
 
 /**
@@ -879,7 +900,10 @@ export interface UserMessageOptions extends ProviderOptions {}
  */
 export const UserMessage: Schema.Schema<UserMessage, UserMessageEncoded> = Schema.Struct({
   role: Schema.Literal("user"),
-  content: Schema.Array(Schema.Union(TextPart, FilePart)),
+  content: Schema.Union(
+    MessageContentFromString,
+    Schema.Array(Schema.Union(TextPart, FilePart))
+  ),
   options: Schema.optionalWith(ProviderOptions, { default: constEmptyObject })
 }).pipe(
   Schema.attachPropertySignature(MessageTypeId, MessageTypeId),
@@ -950,7 +974,7 @@ export type AssistantMessagePart =
  * @category Models
  */
 export interface AssistantMessageEncoded extends BaseMessageEncoded<"assistant", AssistantMessageOptions> {
-  readonly content: ReadonlyArray<AssistantMessagePartEncoded>
+  readonly content: string | ReadonlyArray<AssistantMessagePartEncoded>
 }
 
 /**
@@ -983,7 +1007,10 @@ export interface AssistantMessageOptions extends ProviderOptions {}
  */
 export const AssistantMessage: Schema.Schema<AssistantMessage, AssistantMessageEncoded> = Schema.Struct({
   role: Schema.Literal("assistant"),
-  content: Schema.Array(Schema.Union(TextPart, FilePart, ReasoningPart, ToolCallPart, ToolResultPart)),
+  content: Schema.Union(
+    MessageContentFromString,
+    Schema.Array(Schema.Union(TextPart, FilePart, ReasoningPart, ToolCallPart, ToolResultPart))
+  ),
   options: Schema.optionalWith(ProviderOptions, { default: constEmptyObject })
 }).pipe(
   Schema.attachPropertySignature(MessageTypeId, MessageTypeId),
@@ -1157,7 +1184,7 @@ export const isPrompt = (u: unknown): u is Prompt => Predicate.hasProperty(u, Ty
  * @since 1.0.0
  * @category Models
  */
-export interface Prompt {
+export interface Prompt extends Pipeable {
   readonly [TypeId]: TypeId
   /**
    * Array of messages that make up the conversation.
@@ -1178,18 +1205,61 @@ export interface PromptEncoded {
   readonly content: ReadonlyArray<MessageEncoded>
 }
 
+/**
+ * Describes a schema that represents a `Prompt` instance.
+ *
+ * @since 1.0.0
+ * @category Schemas
+ */
+export class PromptFromSelf extends Schema.declare(
+  (u) => isPrompt(u),
+  {
+    identifier: "PromptFromSelf",
+    description: "a Prompt instance",
+    arbitrary: (): Arbitrary.LazyArbitrary<Prompt> => (fc) =>
+      fc.array(
+        Arbitrary.makeLazy(Message)(fc)
+      ).map(makePrompt)
+  }
+) {}
+
 /**
  * Schema for validation and encoding of prompts.
  *
  * @since 1.0.0
  * @category Schemas
  */
-export const Prompt: Schema.Schema<Prompt, PromptEncoded> = Schema.Struct({
-  content: Schema.Array(Message)
-}).pipe(
-  Schema.attachPropertySignature(TypeId, TypeId),
-  Schema.annotations({ identifier: "Prompt" })
-)
+export const Prompt: Schema.Schema<Prompt, PromptEncoded> = Schema.transformOrFail(
+  Schema.Struct({ content: Schema.Array(Schema.encodedSchema(Message)) }),
+  PromptFromSelf,
+  {
+    strict: true,
+    decode: (i, _, ast) => decodePrompt(i, ast),
+    encode: (a, _, ast) => encodePrompt(a, ast)
+  }
+).annotations({ identifier: "Prompt" })
+
+const decodeMessages = ParseResult.decodeEither(Schema.Array(Message))
+const encodeMessages = ParseResult.encodeEither(Schema.Array(Message))
+
+const decodePrompt = (input: PromptEncoded, ast: AST.AST) =>
+  ParseResult.mapBoth(decodeMessages(input.content), {
+    onFailure: () => new ParseResult.Type(ast, input, `Unable to decode ${JSON.stringify(input)} into a Prompt`),
+    onSuccess: makePrompt
+  })
+
+const encodePrompt = (input: Prompt, ast: AST.AST) =>
+  ParseResult.mapBoth(encodeMessages(input.content), {
+    onFailure: () => new ParseResult.Type(ast, input, `Failed to encode Prompt`),
+    onSuccess: (messages) => ({ content: messages })
+  })
+
+// export const Prompt: Schema.Schema<Prompt, PromptEncoded> = Schema.Struct({
+//   content: Schema.Array(Message)
+// }).pipe(
+//   Schema.attachPropertySignature(TypeId, TypeId),
+//   Schema.annotations({ identifier: "Prompt" })
+// )
 
 /**
  * Schema for parsing a Prompt from JSON strings.
@@ -1231,10 +1301,17 @@ export type RawInput =
   | Iterable<MessageEncoded>
   | Prompt
 
-const makePrompt = (content: ReadonlyArray<Message>): Prompt => ({
+const Proto = {
   [TypeId]: TypeId,
-  content
-})
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+const makePrompt = (content: ReadonlyArray<Message>): Prompt =>
+  Object.assign(Object.create(Proto), {
+    content
+  })
 
 const decodeMessagesSync = Schema.decodeSync(Schema.Array(Message))
 
@@ -1289,7 +1366,7 @@ export const make = (input: RawInput): Prompt => {
   }
 
   if (Predicate.isIterable(input)) {
-    return makePrompt(decodeMessagesSync(Array.from(input), {
+    return makePrompt(decodeMessagesSync(Arr.fromIterable(input), {
       errors: "all"
     }))
   }
@@ -1395,14 +1472,15 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     return empty
   }
 
-  const content: Array<AssistantMessagePart> = []
+  const assistantParts: Array<AssistantMessagePart> = []
+  const toolParts: Array<ToolMessagePart> = []
 
   const textDeltas: Array<string> = []
   function flushTextDeltas() {
     if (textDeltas.length > 0) {
       const text = textDeltas.join("")
       if (text.length > 0) {
-        content.push(makePart("text", { text }))
+        assistantParts.push(makePart("text", { text }))
       }
       textDeltas.length = 0
     }
@@ -1413,7 +1491,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     if (reasoningDeltas.length > 0) {
       const text = reasoningDeltas.join("")
       if (text.length > 0) {
-        content.push(makePart("reasoning", { text }))
+        assistantParts.push(makePart("reasoning", { text }))
       }
       reasoningDeltas.length = 0
     }
@@ -1429,7 +1507,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
       switch (part.type) {
         case "text": {
           flushDeltas()
-          content.push(makePart("text", { text: part.text }))
+          assistantParts.push(makePart("text", { text: part.text }))
           break
         }
         case "text-delta": {
@@ -1439,7 +1517,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         }
         case "reasoning": {
           flushDeltas()
-          content.push(makePart("reasoning", { text: part.text }))
+          assistantParts.push(makePart("reasoning", { text: part.text }))
           break
         }
         case "reasoning-delta": {
@@ -1449,7 +1527,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         }
         case "tool-call": {
           flushDeltas()
-          content.push(makePart("tool-call", {
+          assistantParts.push(makePart("tool-call", {
             id: part.id,
             name: part.providerName ?? part.name,
             params: part.params,
@@ -1459,7 +1537,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         }
         case "tool-result": {
           flushDeltas()
-          content.push(makePart("tool-result", {
+          toolParts.push(makePart("tool-result", {
             id: part.id,
             name: part.providerName ?? part.name,
             result: part.encodedResult
@@ -1472,9 +1550,18 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 
   flushDeltas()
 
-  const message = makeMessage("assistant", { content })
+  if (assistantParts.length === 0 && toolParts.length === 0) {
+    return empty
+  }
 
-  return makePrompt([message])
+  const messages: Array<Message> = []
+  if (assistantParts.length > 0) {
+    messages.push(makeMessage("assistant", { content: assistantParts }))
+  }
+  if (toolParts.length > 0) {
+    messages.push(makeMessage("tool", { content: toolParts }))
+  }
+  return makePrompt(messages)
 }
 
 // =============================================================================
@@ -1482,10 +1569,10 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 // =============================================================================
 
 /**
- * Merges two prompts by concatenating their messages.
+ * Merges a prompt with additional raw input by concatenating messages.
  *
- * Creates a new prompt containing all messages from both prompts, maintaining
- * the order of messages within each prompt.
+ * Creates a new prompt containing all messages from both the original prompt,
+ * and the provided raw input, maintaining the order of messages.
  *
  * @example
  * ```ts
@@ -1496,9 +1583,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
  *   content: "You are a helpful assistant."
  * }])
  *
- * const userPrompt = Prompt.make("Hello, world!")
- *
- * const merged = Prompt.merge(systemPrompt, userPrompt)
+ * const merged = Prompt.merge(systemPrompt, "Hello, world!")
  * ```
  *
  * @since 1.0.0
@@ -1510,10 +1595,10 @@ export const merge: {
   // =============================================================================
 
   /**
-   * Merges two prompts by concatenating their messages.
+   * Merges a prompt with additional raw input by concatenating messages.
    *
-   * Creates a new prompt containing all messages from both prompts, maintaining
-   * the order of messages within each prompt.
+   * Creates a new prompt containing all messages from both the original prompt,
+   * and the provided raw input, maintaining the order of messages.
    *
    * @example
    * ```ts
@@ -1524,24 +1609,22 @@ export const merge: {
    *   content: "You are a helpful assistant."
    * }])
    *
-   * const userPrompt = Prompt.make("Hello, world!")
-   *
-   * const merged = Prompt.merge(systemPrompt, userPrompt)
+   * const merged = Prompt.merge(systemPrompt, "Hello, world!")
    * ```
    *
    * @since 1.0.0
    * @category Combinators
    */
-  (other: Prompt): (self: Prompt) => Prompt
+  (input: RawInput): (self: Prompt) => Prompt
   // =============================================================================
   // Merging Prompts
   // =============================================================================
 
   /**
-   * Merges two prompts by concatenating their messages.
+   * Merges a prompt with additional raw input by concatenating messages.
    *
-   * Creates a new prompt containing all messages from both prompts, maintaining
-   * the order of messages within each prompt.
+   * Creates a new prompt containing all messages from both the original prompt,
+   * and the provided raw input, maintaining the order of messages.
    *
    * @example
    * ```ts
@@ -1552,25 +1635,68 @@ export const merge: {
    *   content: "You are a helpful assistant."
    * }])
    *
-   * const userPrompt = Prompt.make("Hello, world!")
-   *
-   * const merged = Prompt.merge(systemPrompt, userPrompt)
+   * const merged = Prompt.merge(systemPrompt, "Hello, world!")
    * ```
    *
    * @since 1.0.0
    * @category Combinators
    */
-  (self: Prompt, other: Prompt): Prompt
-} = dual<
+  (self: Prompt, input: RawInput): Prompt
+} = dual(2, (self: Prompt, input: RawInput): Prompt => {
+  const other = make(input)
+  if (self.content.length === 0) {
+    return other
+  }
+  if (other.content.length === 0) {
+    return self
+  }
+  return fromMessages([...self.content, ...other.content])
+})
+
+// =============================================================================
+// Manipulating Prompts
+// =============================================================================
+
+/**
+ * Creates a new prompt from the specified prompt with the system message set
+ * to the specified text content.
+ *
+ * **NOTE**: This method will remove and replace any previous system message
+ * from the prompt.
+ *
+ * @example
+ * ```ts
+ * import { Prompt } from "@effect/ai"
+ *
+ * const systemPrompt = Prompt.make([{
+ *   role: "system",
+ *   content: "You are a helpful assistant."
+ * }])
+ *
+ * const userPrompt = Prompt.make("Hello, world!")
+ *
+ * const prompt = Prompt.merge(systemPrompt, userPrompt)
+ *
+ * const replaced = Prompt.setSystem(
+ *   prompt,
+ *   "You are an expert in programming"
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combinators
+ */
+export const setSystem: {
   // =============================================================================
-  // Merging Prompts
+  // Manipulating Prompts
   // =============================================================================
 
   /**
-   * Merges two prompts by concatenating their messages.
+   * Creates a new prompt from the specified prompt with the system message set
+   * to the specified text content.
    *
-   * Creates a new prompt containing all messages from both prompts, maintaining
-   * the order of messages within each prompt.
+   * **NOTE**: This method will remove and replace any previous system message
+   * from the prompt.
    *
    * @example
    * ```ts
@@ -1583,22 +1709,203 @@ export const merge: {
    *
    * const userPrompt = Prompt.make("Hello, world!")
    *
-   * const merged = Prompt.merge(systemPrompt, userPrompt)
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.setSystem(
+   *   prompt,
+   *   "You are an expert in programming"
+   * )
    * ```
    *
    * @since 1.0.0
    * @category Combinators
    */
-  (other: Prompt) => (self: Prompt) => Prompt,
+  (content: string): (self: Prompt) => Prompt
   // =============================================================================
-  // Merging Prompts
+  // Manipulating Prompts
   // =============================================================================
 
   /**
-   * Merges two prompts by concatenating their messages.
+   * Creates a new prompt from the specified prompt with the system message set
+   * to the specified text content.
+   *
+   * **NOTE**: This method will remove and replace any previous system message
+   * from the prompt.
+   *
+   * @example
+   * ```ts
+   * import { Prompt } from "@effect/ai"
+   *
+   * const systemPrompt = Prompt.make([{
+   *   role: "system",
+   *   content: "You are a helpful assistant."
+   * }])
+   *
+   * const userPrompt = Prompt.make("Hello, world!")
+   *
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.setSystem(
+   *   prompt,
+   *   "You are an expert in programming"
+   * )
+   * ```
+   *
+   * @since 1.0.0
+   * @category Combinators
+   */
+  (self: Prompt, content: string): Prompt
+} = dual(2, (self: Prompt, content: string): Prompt => {
+  const messages: Array<Message> = [makeMessage("system", { content })]
+  for (const message of self.content) {
+    if (message.role !== "system") {
+      messages.push(message)
+    }
+  }
+  return makePrompt(messages)
+})
+
+/**
+ * Creates a new prompt from the specified prompt with the provided text content
+ * prepended to the start of existing system message content.
+ *
+ * If no system message exists in the specified prompt, the provided content
+ * will be used to create a system message.
+ *
+ * @example
+ * ```ts
+ * import { Prompt } from "@effect/ai"
+ *
+ * const systemPrompt = Prompt.make([{
+ *   role: "system",
+ *   content: "You are an expert in programming."
+ * }])
+ *
+ * const userPrompt = Prompt.make("Hello, world!")
+ *
+ * const prompt = Prompt.merge(systemPrompt, userPrompt)
+ *
+ * const replaced = Prompt.prependSystem(
+ *   prompt,
+ *   "You are a helpful assistant. "
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combinators
+ */
+export const prependSystem: {
+  /**
+   * Creates a new prompt from the specified prompt with the provided text content
+   * prepended to the start of existing system message content.
+   *
+   * If no system message exists in the specified prompt, the provided content
+   * will be used to create a system message.
+   *
+   * @example
+   * ```ts
+   * import { Prompt } from "@effect/ai"
+   *
+   * const systemPrompt = Prompt.make([{
+   *   role: "system",
+   *   content: "You are an expert in programming."
+   * }])
+   *
+   * const userPrompt = Prompt.make("Hello, world!")
+   *
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.prependSystem(
+   *   prompt,
+   *   "You are a helpful assistant. "
+   * )
+   * ```
+   *
+   * @since 1.0.0
+   * @category Combinators
+   */
+  (content: string): (self: Prompt) => Prompt
+  /**
+   * Creates a new prompt from the specified prompt with the provided text content
+   * prepended to the start of existing system message content.
+   *
+   * If no system message exists in the specified prompt, the provided content
+   * will be used to create a system message.
+   *
+   * @example
+   * ```ts
+   * import { Prompt } from "@effect/ai"
+   *
+   * const systemPrompt = Prompt.make([{
+   *   role: "system",
+   *   content: "You are an expert in programming."
+   * }])
+   *
+   * const userPrompt = Prompt.make("Hello, world!")
+   *
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.prependSystem(
+   *   prompt,
+   *   "You are a helpful assistant. "
+   * )
+   * ```
+   *
+   * @since 1.0.0
+   * @category Combinators
+   */
+  (self: Prompt, content: string): Prompt
+} = dual(2, (self: Prompt, content: string): Prompt => {
+  const messages: Array<Message> = []
+  for (const message of self.content) {
+    if (message.role === "system") {
+      const system = makeMessage("system", {
+        content: content + message.content
+      })
+      messages.push(system)
+    } else {
+      messages.push(message)
+    }
+  }
+  return makePrompt(messages)
+})
+
+/**
+ * Creates a new prompt from the specified prompt with the provided text content
+ * appended to the end of existing system message content.
+ *
+ * If no system message exists in the specified prompt, the provided content
+ * will be used to create a system message.
+ *
+ * @example
+ * ```ts
+ * import { Prompt } from "@effect/ai"
+ *
+ * const systemPrompt = Prompt.make([{
+ *   role: "system",
+ *   content: "You are a helpful assistant."
+ * }])
+ *
+ * const userPrompt = Prompt.make("Hello, world!")
+ *
+ * const prompt = Prompt.merge(systemPrompt, userPrompt)
+ *
+ * const replaced = Prompt.appendSystem(
+ *   prompt,
+ *   " You are an expert in programming."
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combinators
+ */
+export const appendSystem: {
+  /**
+   * Creates a new prompt from the specified prompt with the provided text content
+   * appended to the end of existing system message content.
    *
-   * Creates a new prompt containing all messages from both prompts, maintaining
-   * the order of messages within each prompt.
+   * If no system message exists in the specified prompt, the provided content
+   * will be used to create a system message.
    *
    * @example
    * ```ts
@@ -1611,11 +1918,59 @@ export const merge: {
    *
    * const userPrompt = Prompt.make("Hello, world!")
    *
-   * const merged = Prompt.merge(systemPrompt, userPrompt)
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.appendSystem(
+   *   prompt,
+   *   " You are an expert in programming."
+   * )
+   * ```
+   *
+   * @since 1.0.0
+   * @category Combinators
+   */
+  (content: string): (self: Prompt) => Prompt
+  /**
+   * Creates a new prompt from the specified prompt with the provided text content
+   * appended to the end of existing system message content.
+   *
+   * If no system message exists in the specified prompt, the provided content
+   * will be used to create a system message.
+   *
+   * @example
+   * ```ts
+   * import { Prompt } from "@effect/ai"
+   *
+   * const systemPrompt = Prompt.make([{
+   *   role: "system",
+   *   content: "You are a helpful assistant."
+   * }])
+   *
+   * const userPrompt = Prompt.make("Hello, world!")
+   *
+   * const prompt = Prompt.merge(systemPrompt, userPrompt)
+   *
+   * const replaced = Prompt.appendSystem(
+   *   prompt,
+   *   " You are an expert in programming."
+   * )
    * ```
    *
    * @since 1.0.0
    * @category Combinators
    */
-  (self: Prompt, other: Prompt) => Prompt
->(2, (self, other) => fromMessages([...self.content, ...other.content]))
+  (self: Prompt, content: string): Prompt
+} = dual(2, (self: Prompt, content: string): Prompt => {
+  const messages: Array<Message> = []
+  for (const message of self.content) {
+    if (message.role === "system") {
+      const system = makeMessage("system", {
+        content: message.content + content
+      })
+      messages.push(system)
+    } else {
+      messages.push(message)
+    }
+  }
+  return makePrompt(messages)
+})