write-language 0.1.93 → 0.1.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "write-language",
-  "version": "0.1.93",
+  "version": "0.1.94",
   "description": "Multi-provider language generation toolkit using Vercel AI SDK - generate responses with 10+ LLM providers including OpenAI, Anthropic, Google, and more.",
   "author": "vtempest <grokthiscontact@gmail.com>",
   "license": "rights.institute/PROSPER",

package/src/generate-response.attachments.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Verifies that file/image attachments are forwarded to the
+ * Vercel AI SDK as multimodal `messages` content parts, and that plain
+ * (attachment-free) calls keep using the simpler `prompt` form.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Capture the exact arguments passed to generateText so we can assert on the
+// shape of the request the SDK receives.
+const generateTextMock = vi.fn((_args: unknown) => Promise.resolve({ text: "ok" }));
+
+vi.mock("ai", () => ({
+  generateText: (args: unknown) => generateTextMock(args),
+  stepCountIs: (n: number) => n,
+  tool: (t: unknown) => t,
+}));
+
+// Return a truthy fake model so writeLanguageResponse proceeds to generateText.
+vi.mock("./provider-factory", () => ({
+  createLLMProvider: () => ({ id: "fake-model" }),
+}));
+
+// Avoid pulling the markdown/prism stack into the test.
+vi.mock("./utils/markdown-to-html", () => ({
+  convertMarkdownToHTMLEscaped: async (s: string) => s,
+}));
+
+import { writeLanguageResponse } from "./generate-response";
+
+afterEach(() => {
+  generateTextMock.mockClear();
+});
+
+describe("writeLanguageResponse attachments", () => {
+  const base = {
+    provider: "groq",
+    apiKey: "test-key",
+    agent: "question",
+    query: "Describe the attached file",
+    html: false,
+    applyContextLimit: false,
+  } as const;
+
+  it("sends a plain text prompt when there are no attachments", async () => {
+    await writeLanguageResponse({ ...base });
+
+    expect(generateTextMock).toHaveBeenCalledTimes(1);
+    const arg = generateTextMock.mock.calls[0][0] as Record<string, unknown>;
+    expect(typeof arg.prompt).toBe("string");
+    expect(arg.messages).toBeUndefined();
+  });
+
+  it("sends an image attachment as an image content part", async () => {
+    await writeLanguageResponse({
+      ...base,
+      attachments: [
+        { mediaType: "image/png", data: "data:image/png;base64,AAAA" },
+      ],
+    });
+
+    const arg = generateTextMock.mock.calls[0][0] as any;
+    expect(arg.prompt).toBeUndefined();
+    expect(Array.isArray(arg.messages)).toBe(true);
+    const parts = arg.messages[0].content;
+    expect(parts[0]).toMatchObject({ type: "text" });
+    expect(parts[1]).toMatchObject({
+      type: "image",
+      image: "data:image/png;base64,AAAA",
+    });
+  });
+
+  it("sends a document attachment as a file content part with its mediaType", async () => {
+    await writeLanguageResponse({
+      ...base,
+      attachments: [
+        {
+          mediaType: "application/pdf",
+          data: "JVBERi0=",
+          filename: "report.pdf",
+        },
+      ],
+    });
+
+    const arg = generateTextMock.mock.calls[0][0] as any;
+    const parts = arg.messages[0].content;
+    expect(parts[1]).toMatchObject({
+      type: "file",
+      mediaType: "application/pdf",
+      data: "JVBERi0=",
+      filename: "report.pdf",
+    });
+  });
+
+  it("skips malformed attachments (missing data or mediaType)", async () => {
+    await writeLanguageResponse({
+      ...base,
+      attachments: [
+        { mediaType: "", data: "x" } as any,
+        { mediaType: "image/png" } as any,
+        { mediaType: "image/jpeg", data: "data:image/jpeg;base64,BBBB" },
+      ],
+    });
+
+    const arg = generateTextMock.mock.calls[0][0] as any;
+    const parts = arg.messages[0].content;
+    // 1 text part + 1 valid image part only.
+    expect(parts).toHaveLength(2);
+    expect(parts[1]).toMatchObject({ type: "image" });
+  });
+});

package/src/generate-response.ts

@@ -13,12 +13,14 @@ import type {
   AgentTool,
   GenerateLanguageOptions,
   GenerateLanguageResult,
+  LanguageAttachment,
 } from "./generation-types";
 
 export type {
   LLMProviderName,
   GenerateLanguageOptions,
   GenerateLanguageResult,
+  LanguageAttachment,
 } from "./generation-types";
 export { convertMarkdownToHTMLEscaped } from "./utils/markdown-to-html";
 
@@ -61,6 +63,7 @@ export async function writeLanguageResponse(
     temperature = 1,
     html = true,
     applyContextLimit = true,
+    attachments,
     ...context
   } = options;
 
@@ -144,10 +147,23 @@ export async function writeLanguageResponse(
         : undefined;
 
     // \u2500\u2500 8. Invoke LLM via Vercel AI SDK generateText \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // When files/images are attached, issue a multimodal `messages` request so
+    // the model receives the uploaded content directly. Otherwise fall back to
+    // the simpler `prompt` form.
+    const fileParts = buildAttachmentParts(attachments);
     const { text: rawReply } = await generateText({
       model: llm,
-      prompt,
       temperature,
+      ...(fileParts.length > 0
+        ? {
+            messages: [
+              {
+                role: "user" as const,
+                content: [{ type: "text" as const, text: prompt }, ...fileParts],
+              },
+            ],
+          }
+        : { prompt }),
       ...(tools && { tools, stopWhen: stepCountIs(10) }),
     });
 
@@ -172,6 +188,42 @@ export async function writeLanguageResponse(
   }
 }
 
+/**
+ * Converts {@link LanguageAttachment}s into Vercel AI SDK message content
+ * parts. `image/*` attachments (or those with `kind: "image"`) become
+ * `image` parts; everything else becomes a `file` part carrying its
+ * `mediaType`. Attachments without usable data are skipped.
+ *
+ * @param attachments - File/image attachments from the caller
+ * @returns An array of AI SDK content parts (empty when none are supplied)
+ */
+function buildAttachmentParts(
+  attachments: LanguageAttachment[] | undefined,
+): Array<
+  | { type: "image"; image: LanguageAttachment["data"] }
+  | { type: "file"; data: LanguageAttachment["data"]; mediaType: string; filename?: string }
+> {
+  if (!Array.isArray(attachments) || attachments.length === 0) return [];
+
+  return attachments
+    .filter((a) => a && a.data != null && a.mediaType)
+    .map((a) => {
+      const isImage =
+        a.kind === "image" ||
+        (a.kind !== "file" && a.mediaType.toLowerCase().startsWith("image/"));
+
+      if (isImage) {
+        return { type: "image" as const, image: a.data };
+      }
+      return {
+        type: "file" as const,
+        data: a.data,
+        mediaType: a.mediaType,
+        ...(a.filename ? { filename: a.filename } : {}),
+      };
+    });
+}
+
 /**
  * Substitutes `{variableName}` placeholders in a template string with values
  * from `vars`. Object/array values are pretty-printed without braces or

package/src/generation-types.ts

@@ -20,6 +20,31 @@ export type LLMProviderName =
   | "togetherai"
   | (string & {}); // preserve autocomplete while allowing arbitrary strings
 
+/**
+ * A file or image attachment passed to the model alongside the text prompt.
+ *
+ * The Vercel AI SDK accepts these as multimodal message content parts:
+ * images become `{ type: "image", image }` parts and every other media type
+ * becomes a `{ type: "file", data, mediaType }` part. `data` may be a base64
+ * string, a `data:` URL, an `http(s)` URL, a `URL` instance, or raw bytes.
+ */
+export interface LanguageAttachment {
+  /** MIME type, e.g. `"image/png"`, `"application/pdf"`. */
+  mediaType: string;
+  /**
+   * The attachment payload: a base64 string, a `data:`/`http(s)` URL, a `URL`
+   * instance, or raw bytes (`Uint8Array`/`ArrayBuffer`).
+   */
+  data: string | Uint8Array | ArrayBuffer | URL;
+  /** Optional original filename (used by providers that surface it). */
+  filename?: string;
+  /**
+   * Force how the part is sent. Defaults to auto-detection from `mediaType`
+   * (`image/*` → image part, otherwise a file part).
+   */
+  kind?: "image" | "file";
+}
+
 /**
  * Configuration options for {@link writeLanguageResponse}.
  */
@@ -47,6 +72,12 @@ export interface GenerateLanguageOptions {
   article?: string;
   /** Prior conversation history for context-aware agents */
   chat_history?: string;
+  /**
+   * File and image attachments to send to the model alongside the prompt.
+   * When present, the request is issued as a multimodal `messages` call so the
+   * model receives the uploaded files (images and documents) directly.
+   */
+  attachments?: LanguageAttachment[];
   /** Return `HTML` (`true`) or raw Markdown (`false`). Default: `true` */
   html?: boolean;
   /** Truncate the prompt to the model's context window length. Default: `true` */

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
   LLMProviderName,
   GenerateLanguageOptions,
   GenerateLanguageResult,
+  LanguageAttachment,
 } from "./generate-response";
 
 export type {