@ljoukov/llm 0.1.2 → 0.1.3

package/README.md

@@ -25,8 +25,10 @@ npm i @ljoukov/llm
 
 ## Environment variables
 
-This package reads a `.env.local` file in `process.cwd()` (Node.js) using the same rules as Spark, and falls back to
-plain environment variables.
+This package optionally loads a `.env.local` file from `process.cwd()` (Node.js) on first use (dotenv-style `KEY=value`
+syntax) and does not override already-set `process.env` values. It always falls back to plain environment variables.
+
+See Node.js docs on environment variables and dotenv files: https://nodejs.org/api/environment_variables.html#dotenv
 
 ### OpenAI
 
@@ -36,17 +38,43 @@ plain environment variables.
 
 - `GOOGLE_SERVICE_ACCOUNT_JSON` (the contents of a service account JSON key file, not a file path)
 
-For local dev it is usually easiest to store the JSON on one line:
+#### Get a service account key JSON
+
+You need a **Google service account key JSON** for your Firebase / GCP project (this is what you put into
+`GOOGLE_SERVICE_ACCOUNT_JSON`).
+
+- **Firebase Console:** your project -> Project settings -> **Service accounts** -> **Generate new private key**
+- **Google Cloud Console:** IAM & Admin -> **Service Accounts** -> select/create an account -> **Keys** -> **Add key** ->
+  **Create new key** -> JSON
+
+Either path is enough. Both produce the same kind of service account key `.json` file.
+
+Official docs: https://docs.cloud.google.com/iam/docs/keys-create-delete
+
+Store the JSON on one line (recommended):
 
 ```bash
 jq -c . < path/to/service-account.json
 ```
 
+Set it for local dev:
+
+```bash
+export GOOGLE_SERVICE_ACCOUNT_JSON="$(jq -c . < path/to/service-account.json)"
+```
+
+If deploying to Cloudflare Workers/Pages:
+
+```bash
+jq -c . < path/to/service-account.json | wrangler secret put GOOGLE_SERVICE_ACCOUNT_JSON
+```
+
 ### ChatGPT subscription models
 
 - `CHATGPT_AUTH_JSON_B64`
 
-This is a base64url-encoded JSON blob containing the ChatGPT OAuth tokens + account id (Spark-compatible).
+This is a base64url-encoded JSON blob containing the ChatGPT OAuth tokens + account id (RFC 4648):
+https://www.rfc-editor.org/rfc/rfc4648
 
 ## Usage
 
@@ -90,6 +118,116 @@ const result = await call.result;
 console.log("\nmodelVersion:", result.modelVersion);
 ```
 
+### Full conversation (multi-turn)
+
+If you want to pass the full conversation (multiple user/assistant turns), use `contents` instead of `prompt`.
+
+Note: assistant messages use `role: "model"`.
+
+```ts
+import { generateText, type LlmContent } from "@ljoukov/llm";
+
+const contents: LlmContent[] = [
+  {
+    role: "system",
+    parts: [{ type: "text", text: "You are a concise assistant." }],
+  },
+  {
+    role: "user",
+    parts: [{ type: "text", text: "Summarize: Rust is a systems programming language." }],
+  },
+  {
+    role: "model",
+    parts: [{ type: "text", text: "Rust is a fast, memory-safe systems language." }],
+  },
+  {
+    role: "user",
+    parts: [{ type: "text", text: "Now rewrite it in 1 sentence." }],
+  },
+];
+
+const result = await generateText({ model: "gpt-5.2", contents });
+console.log(result.text);
+```
+
+### Attachments (files / images)
+
+Use `inlineData` parts to attach base64-encoded bytes (intermixed with text). `inlineData.data` is base64 (not a data
+URL).
+
+Note: `inlineData` is mapped based on `mimeType`.
+
+- `image/*` -> image input (`input_image`)
+- otherwise -> file input (`input_file`, e.g. `application/pdf`)
+
+```ts
+import fs from "node:fs";
+import { generateText, type LlmContent } from "@ljoukov/llm";
+
+const imageB64 = fs.readFileSync("image.png").toString("base64");
+
+const contents: LlmContent[] = [
+  {
+    role: "user",
+    parts: [
+      { type: "text", text: "Describe this image in 1 paragraph." },
+      { type: "inlineData", mimeType: "image/png", data: imageB64 },
+    ],
+  },
+];
+
+const result = await generateText({ model: "gpt-5.2", contents });
+console.log(result.text);
+```
+
+PDF attachment example:
+
+```ts
+import fs from "node:fs";
+import { generateText, type LlmContent } from "@ljoukov/llm";
+
+const pdfB64 = fs.readFileSync("doc.pdf").toString("base64");
+
+const contents: LlmContent[] = [
+  {
+    role: "user",
+    parts: [
+      { type: "text", text: "Summarize this PDF in 5 bullet points." },
+      { type: "inlineData", mimeType: "application/pdf", data: pdfB64 },
+    ],
+  },
+];
+
+const result = await generateText({ model: "gpt-5.2", contents });
+console.log(result.text);
+```
+
+Intermixed text + multiple images (e.g. compare two images):
+
+```ts
+import fs from "node:fs";
+import { generateText, type LlmContent } from "@ljoukov/llm";
+
+const a = fs.readFileSync("a.png").toString("base64");
+const b = fs.readFileSync("b.png").toString("base64");
+
+const contents: LlmContent[] = [
+  {
+    role: "user",
+    parts: [
+      { type: "text", text: "Compare the two images. List the important differences." },
+      { type: "text", text: "Image A:" },
+      { type: "inlineData", mimeType: "image/png", data: a },
+      { type: "text", text: "Image B:" },
+      { type: "inlineData", mimeType: "image/png", data: b },
+    ],
+  },
+];
+
+const result = await generateText({ model: "gpt-5.2", contents });
+console.log(result.text);
+```
+
 ### Gemini
 
 ```ts

package/dist/index.cjs

@@ -1655,6 +1655,20 @@ function isInlineImageMime(mimeType) {
   }
   return mimeType.startsWith("image/");
 }
+function guessInlineDataFilename(mimeType) {
+  switch (mimeType) {
+    case "application/pdf":
+      return "document.pdf";
+    case "application/json":
+      return "data.json";
+    case "text/markdown":
+      return "document.md";
+    case "text/plain":
+      return "document.txt";
+    default:
+      return "attachment.bin";
+  }
+}
 function mergeConsecutiveTextParts(parts) {
   if (parts.length === 0) {
     return [];
@@ -1797,9 +1811,18 @@ function toOpenAiInput(contents) {
         parts.push({ type: "input_text", text: part.text });
         continue;
       }
-      const mimeType = part.mimeType ?? "application/octet-stream";
-      const dataUrl = `data:${mimeType};base64,${part.data}`;
-      parts.push({ type: "input_image", image_url: dataUrl, detail: "auto" });
+      const mimeType = part.mimeType;
+      if (isInlineImageMime(mimeType)) {
+        const dataUrl = `data:${mimeType};base64,${part.data}`;
+        parts.push({ type: "input_image", image_url: dataUrl, detail: "auto" });
+        continue;
+      }
+      const fileData = decodeInlineDataBuffer(part.data).toString("base64");
+      parts.push({
+        type: "input_file",
+        filename: guessInlineDataFilename(mimeType),
+        file_data: fileData
+      });
     }
     if (parts.length === 1 && parts[0]?.type === "input_text" && typeof parts[0].text === "string") {
       return {
@@ -1835,19 +1858,29 @@ function toChatGptInput(contents) {
         });
         continue;
       }
-      const mimeType = part.mimeType ?? "application/octet-stream";
-      const dataUrl = `data:${mimeType};base64,${part.data}`;
       if (isAssistant) {
+        const mimeType = part.mimeType ?? "application/octet-stream";
         parts.push({
           type: "output_text",
-          text: `[image:${mimeType}]`
+          text: isInlineImageMime(part.mimeType) ? `[image:${mimeType}]` : `[file:${mimeType}]`
         });
       } else {
-        parts.push({
-          type: "input_image",
-          image_url: dataUrl,
-          detail: "auto"
-        });
+        if (isInlineImageMime(part.mimeType)) {
+          const mimeType = part.mimeType ?? "application/octet-stream";
+          const dataUrl = `data:${mimeType};base64,${part.data}`;
+          parts.push({
+            type: "input_image",
+            image_url: dataUrl,
+            detail: "auto"
+          });
+        } else {
+          const fileData = decodeInlineDataBuffer(part.data).toString("base64");
+          parts.push({
+            type: "input_file",
+            filename: guessInlineDataFilename(part.mimeType),
+            file_data: fileData
+          });
+        }
       }
     }
     if (parts.length === 0) {