pi-banana 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Frapporti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# pi-banana
+
+Generate and edit images directly inside [pi](https://github.com/badlogic/pi-mono) using Google's **Nano Banana 2** (`gemini-3.1-flash-image-preview`) and **Nano Banana Pro** (`gemini-3-pro-image-preview`).
+
+- **Inline preview** in Kitty / iTerm2 / WezTerm — image shows up right under the tool call, no copy-pasting paths.
+- **Reference-image editing** — pass `referenceImage: "./logo.png"` and the model edits that picture instead of starting from scratch.
+- **Auto-save** to `./generated/` so the agent and you both have a real file to refer back to.
+- **One env var** — `GOOGLE_API_KEY`. Works with both AI Studio (`AIza…`) and Vertex AI Express (`AQ.…`) keys.
+- **Backend-aware** — Vertex publishes the `-preview` model id, AI Studio sometimes publishes the GA name; the extension transparently retries the other variant on 404 so it just works.
+
+## Install
+
+```sh
+pi install npm:pi-banana
+```
+
+Or for a single-session try:
+
+```sh
+pi -e npm:pi-banana
+```
+
+Then export your key:
+
+```sh
+export GOOGLE_API_KEY="AIza…"   # AI Studio key, or
+export GOOGLE_API_KEY="AQ.…"    # Vertex AI Express key
+```
+
+Get one at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).
+
+## Usage
+
+Just ask pi for what you want:
+
+> *"Generate a 16:9 wallpaper of a foggy redwood forest at dawn"*
+>
+> *"Edit `./generated/logo-20260508.png` — make the background transparent"*
+>
+> *"Draw a pixel-art banana with sunglasses, 1:1, save it as `./assets/mascot.png`"*
+
+The model calls `generate_image` automatically. The PNG is shown inline and written to disk.
+
+## Tool: `generate_image`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `prompt` | string | — | Required. What to draw, or what to change about the reference image. |
+| `aspectRatio` | enum | `1:1` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
+| `imageSize` | enum | `1K` | `1K`, `2K`, `4K`. `4K` requires `quality=high`. |
+| `quality` | enum | `fast` | `fast` = Nano Banana 2 (~3–10 s, cheapest). `high` = Nano Banana Pro (slower, top quality). |
+| `referenceImage` | string | — | Optional path to a PNG/JPEG/WebP/GIF to edit instead of generating from scratch. |
+| `outputPath` | string | `./generated/<slug>-<ts>.png` | Optional output path. Parent dirs are created. |
+
+## Configuration
+
+Two env vars adjust defaults without touching tool parameters:
+
+| Env var | Default | Effect |
+|---|---|---|
+| `PI_IMAGE_DIR` | `generated` | Default save directory (relative paths resolve against cwd). |
+| `PI_IMAGE_QUALITY` | `fast` | Default quality if the model doesn't pass one. |
+
+## How is this different from `@benvargas/pi-antigravity-image-gen`?
+
+| | pi-banana | @benvargas |
+|---|---|---|
+| Auth | `GOOGLE_API_KEY` env var | OAuth via Antigravity (`pi /login`) |
+| Models | Flash + Pro | Pro only |
+| Image edit (input picture) | ✅ | ❌ |
+| Auto-save default | ✅ to `./generated/` | ❌ disabled by default |
+| Aspect ratios | 10 | 10 |
+| Inline terminal preview | ✅ | ✅ |
+
+If you have an Antigravity OAuth setup and want quota tracking, benvargas is great. If you just want to drop in an API key and start making pictures, this one is simpler.
+
+## Development
+
+```sh
+npm install
+npm run typecheck             # tsc --noEmit
+GOOGLE_API_KEY=… npm run smoke  # full live-API smoke test in _tmp/
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,385 @@
+/**
+ * pi-image
+ *
+ * Image generation + editing tool for pi, powered by Google's
+ *   - Nano Banana 2  (gemini-3.1-flash-image-preview)  — fast, cheap, default
+ *   - Nano Banana Pro (gemini-3-pro-image-preview)     — top quality, slower
+ *
+ * Returns images as flat { type: "image", data, mimeType } content blocks so
+ * pi-coding-agent renders them inline (Kitty / iTerm2). Also writes the file
+ * to disk so the agent and the user always have a path to refer back to.
+ *
+ * Auth: GOOGLE_API_KEY in the environment.
+ *   - AI Studio keys (AIza...) hit the Gemini API.
+ *   - Vertex AI Express keys (AQ....) automatically switch to Vertex.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { GoogleGenAI } from "@google/genai";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { Type } from "typebox";
+
+// ─── Config ────────────────────────────────────────────────────────────────
+
+// Per Vertex AI / AI Studio docs, gemini-3.1-flash-image supports a wider set
+// than older Imagen models. Keep to the broadly-supported subset.
+const ASPECT_RATIOS = [
+	"1:1",
+	"2:3",
+	"3:2",
+	"3:4",
+	"4:3",
+	"4:5",
+	"5:4",
+	"9:16",
+	"16:9",
+	"21:9",
+] as const;
+const IMAGE_SIZES = ["1K", "2K", "4K"] as const;
+const QUALITY = ["fast", "high"] as const;
+
+// Resolved against a live Vertex Express (AQ.*) key on 2026-05-08:
+//   gemini-3.1-flash-image          → 404
+//   gemini-3.1-flash-image-preview  → ok  (Nano Banana 2)
+//   gemini-3-pro-image              → 404
+//   gemini-3-pro-image-preview      → ok  (Nano Banana Pro)
+// AI Studio keys (AIza*) sometimes publish the un-suffixed GA names.
+// `callWithModelFallback` below transparently retries with `-preview`
+// if the un-suffixed id 404s, so both backends just work.
+const MODEL_FOR_QUALITY: Record<(typeof QUALITY)[number], string> = {
+	fast: "gemini-3.1-flash-image-preview", // Nano Banana 2
+	high: "gemini-3-pro-image-preview", // Nano Banana Pro
+};
+
+const DEFAULT_OUTPUT_DIR =
+	process.env.PI_IMAGE_DIR?.trim() || "generated";
+const DEFAULT_QUALITY = (process.env.PI_IMAGE_QUALITY as
+	| "fast"
+	| "high"
+	| undefined) ?? "fast";
+const SUPPORTED_INPUT_MIME = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif",
+]);
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function buildClient(): GoogleGenAI {
+	const apiKey = process.env.GOOGLE_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"GOOGLE_API_KEY not set. Get one at https://aistudio.google.com/apikey (AIza…) " +
+				"or use a Vertex AI Express key (AQ.…) — both work.",
+		);
+	}
+	// AQ.* express keys authenticate against Vertex; AIza* against Gemini API.
+	return new GoogleGenAI({
+		apiKey,
+		...(apiKey.startsWith("AQ.") ? { vertexai: true } : {}),
+	});
+}
+
+function slugify(text: string): string {
+	return (
+		text
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "")
+			.slice(0, 48) || "image"
+	);
+}
+
+function timestamp(): string {
+	const d = new Date();
+	const p = (n: number) => String(n).padStart(2, "0");
+	return (
+		`${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}` +
+		`-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+	);
+}
+
+function extForMime(mime: string): string {
+	switch (mime.toLowerCase()) {
+		case "image/png":
+			return ".png";
+		case "image/jpeg":
+		case "image/jpg":
+			return ".jpg";
+		case "image/webp":
+			return ".webp";
+		case "image/gif":
+			return ".gif";
+		default:
+			return ".png";
+	}
+}
+
+function mimeFromExt(path: string): string {
+	switch (extname(path).toLowerCase()) {
+		case ".png":
+			return "image/png";
+		case ".jpg":
+		case ".jpeg":
+			return "image/jpeg";
+		case ".webp":
+			return "image/webp";
+		case ".gif":
+			return "image/gif";
+		default:
+			return "image/png";
+	}
+}
+
+async function loadReferenceImage(
+	cwd: string,
+	pathArg: string,
+): Promise<{ data: string; mimeType: string }> {
+	// Strip leading @ — some models include it in path arguments.
+	const cleaned = pathArg.replace(/^@/, "");
+	const abs = isAbsolute(cleaned) ? cleaned : resolve(cwd, cleaned);
+	if (!existsSync(abs)) {
+		throw new Error(`Reference image not found: ${abs}`);
+	}
+	const mimeType = mimeFromExt(abs);
+	if (!SUPPORTED_INPUT_MIME.has(mimeType)) {
+		throw new Error(
+			`Unsupported reference image type: ${mimeType}. Use PNG, JPEG, WebP, or GIF.`,
+		);
+	}
+	const buf = await readFile(abs);
+	return { data: buf.toString("base64"), mimeType };
+}
+
+async function resolveOutputPath(
+	cwd: string,
+	prompt: string,
+	mimeType: string,
+	override: string | undefined,
+): Promise<string> {
+	if (override) {
+		const cleaned = override.replace(/^@/, "");
+		const abs = isAbsolute(cleaned) ? cleaned : resolve(cwd, cleaned);
+		await mkdir(resolve(abs, ".."), { recursive: true });
+		return abs;
+	}
+	const dir = isAbsolute(DEFAULT_OUTPUT_DIR)
+		? DEFAULT_OUTPUT_DIR
+		: resolve(cwd, DEFAULT_OUTPUT_DIR);
+	await mkdir(dir, { recursive: true });
+	return resolve(dir, `${slugify(prompt)}-${timestamp()}${extForMime(mimeType)}`);
+}
+
+// ─── Extension ─────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "generate_image",
+		label: "Image Gen",
+		description:
+			"Generate or edit a PNG/JPEG image with Google's Nano Banana 2 " +
+			"(Gemini 3.1 Flash Image) or Nano Banana Pro. The image is shown " +
+			"inline in the terminal AND saved to disk so it can be re-used. " +
+			"Pass `referenceImage` to iterate on an existing picture.",
+		promptSnippet:
+			"Generate or edit images with Google Nano Banana via the GOOGLE_API_KEY env var.",
+		promptGuidelines: [
+			"Call generate_image when the user asks to create, draw, illustrate, or edit a picture.",
+			"For tweaks like 'make the sky purple', pass the previous file path as referenceImage to generate_image.",
+			"Default quality 'fast' is right for most asks; switch to 'high' only when the user explicitly wants top quality.",
+		],
+		parameters: Type.Object({
+			prompt: Type.String({
+				description:
+					"What to draw. Be specific about subject, style, lighting, " +
+					"composition. For edits with a reference image, describe only the change.",
+			}),
+			aspectRatio: Type.Optional(
+				StringEnum(ASPECT_RATIOS, {
+					description: "Aspect ratio of the output image.",
+					default: "1:1",
+				}),
+			),
+			imageSize: Type.Optional(
+				StringEnum(IMAGE_SIZES, {
+					description:
+						"Largest dimension of the image. 4K is only available on quality=high.",
+					default: "1K",
+				}),
+			),
+			quality: Type.Optional(
+				StringEnum(QUALITY, {
+					description:
+						"'fast' = Nano Banana 2 (default, ~3s, cheap). 'high' = Nano Banana Pro (slower, top quality).",
+					default: DEFAULT_QUALITY,
+				}),
+			),
+			referenceImage: Type.Optional(
+				Type.String({
+					description:
+						"Optional path to an existing image (PNG/JPEG/WebP/GIF) to edit or iterate on. " +
+						"Relative paths resolve to the current working directory.",
+				}),
+			),
+			outputPath: Type.Optional(
+				Type.String({
+					description:
+						"Optional output path. Defaults to ./generated/<slug>-<timestamp>.png " +
+						"(override the dir with PI_IMAGE_DIR).",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const aspectRatio = params.aspectRatio ?? "1:1";
+			const imageSize = params.imageSize ?? "1K";
+			const quality = params.quality ?? DEFAULT_QUALITY;
+			const model = MODEL_FOR_QUALITY[quality];
+			const cwd = ctx.cwd;
+
+			if (signal?.aborted) {
+				return { content: [{ type: "text", text: "Cancelled." }], details: {} };
+			}
+			if (imageSize === "4K" && quality !== "high") {
+				throw new Error(
+					"imageSize=4K requires quality='high' (Nano Banana Pro).",
+				);
+			}
+
+			const client = buildClient();
+
+			// Build content parts — text + (optional) reference image.
+			const parts: Array<{
+				text?: string;
+				inlineData?: { mimeType: string; data: string };
+			}> = [];
+			let editing = false;
+			if (params.referenceImage) {
+				const ref = await loadReferenceImage(cwd, params.referenceImage);
+				parts.push({ inlineData: ref });
+				editing = true;
+			}
+			parts.push({ text: params.prompt });
+
+			const verbLabel = editing ? "Editing" : "Generating";
+			onUpdate?.({
+				content: [
+					{
+						type: "text",
+						text: `🎨 ${verbLabel} ${aspectRatio} ${imageSize} image with ${quality === "fast" ? "Nano Banana 2" : "Nano Banana Pro"}…`,
+					},
+				],
+				details: { model, aspectRatio, imageSize, quality, editing },
+			});
+
+			const callWithFallback = async (modelId: string) => {
+				try {
+					return await client.models.generateContent({
+						model: modelId,
+						contents: [{ role: "user", parts }],
+						config: {
+							responseModalities: ["IMAGE"],
+							imageConfig: { aspectRatio, imageSize },
+							abortSignal: signal,
+						},
+					});
+				} catch (err: any) {
+					const msg = String(err?.message ?? err);
+					// Vertex publishes the `-preview` id while AI Studio sometimes
+					// publishes the GA id. Retry the other variant on 404.
+					const is404 = /\b404\b|NOT_FOUND|not found/i.test(msg);
+					if (is404 && !modelId.endsWith("-preview")) {
+						return await client.models.generateContent({
+							model: `${modelId}-preview`,
+							contents: [{ role: "user", parts }],
+							config: {
+								responseModalities: ["IMAGE"],
+								imageConfig: { aspectRatio, imageSize },
+								abortSignal: signal,
+							},
+						});
+					}
+					if (is404 && modelId.endsWith("-preview")) {
+						return await client.models.generateContent({
+							model: modelId.replace(/-preview$/, ""),
+							contents: [{ role: "user", parts }],
+							config: {
+								responseModalities: ["IMAGE"],
+								imageConfig: { aspectRatio, imageSize },
+								abortSignal: signal,
+							},
+						});
+					}
+					throw err;
+				}
+			};
+
+			let response;
+			try {
+				response = await callWithFallback(model);
+			} catch (err: any) {
+				// Surface API errors verbatim — they tell the user (and the agent)
+				// exactly what to fix (bad key, model not enabled, etc).
+				throw new Error(
+					`Google image API error: ${err?.message ?? String(err)}`,
+				);
+			}
+
+			const candidate = response.candidates?.[0];
+			const imagePart = candidate?.content?.parts?.find((p) => p.inlineData);
+			if (!imagePart?.inlineData?.data) {
+				const reason = candidate?.finishReason ?? "unknown";
+				const safety = candidate?.safetyRatings
+					?.filter((r: any) => r.blocked || r.probability === "HIGH")
+					.map((r: any) => r.category)
+					.join(", ");
+				const textOut = response.candidates?.[0]?.content?.parts
+					?.map((p) => p.text)
+					.filter(Boolean)
+					.join(" ");
+				throw new Error(
+					`No image returned (finishReason=${reason}` +
+						(safety ? `, blocked=${safety}` : "") +
+						`). ${textOut ?? ""}`.trim(),
+				);
+			}
+
+			const base64 = imagePart.inlineData.data;
+			const mimeType = imagePart.inlineData.mimeType ?? "image/png";
+			const outPath = await resolveOutputPath(
+				cwd,
+				params.prompt,
+				mimeType,
+				params.outputPath,
+			);
+			await writeFile(outPath, Buffer.from(base64, "base64"));
+
+			const summary = editing
+				? `Edited "${params.referenceImage}" → ${outPath}`
+				: `Generated → ${outPath}`;
+
+			return {
+				// Flat ImageContent block — pi-coding-agent auto-renders inline
+				// in Kitty/iTerm2 terminals. Older terminals get the text fallback.
+				content: [
+					{ type: "text", text: summary },
+					{ type: "image", data: base64, mimeType },
+				],
+				details: {
+					model,
+					quality,
+					aspectRatio,
+					imageSize,
+					mimeType,
+					outputPath: outPath,
+					editing,
+					referenceImage: params.referenceImage,
+				},
+			};
+		},
+	});
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pi-banana",
+  "version": "2.0.0",
+  "description": "Generate and edit images in pi using Google Nano Banana 2 (gemini-3.1-flash-image) and Nano Banana Pro. Inline terminal preview, reference-image editing, auto-save.",
+  "author": "Francesco Frapporti <effedue@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/Fornace/pi-banana#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fornace/pi-banana.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Fornace/pi-banana/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "google",
+    "gemini",
+    "nano-banana",
+    "nano-banana-2",
+    "nano-banana-pro",
+    "image-generation",
+    "image-edit",
+    "imagen"
+  ],
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "smoke": "node _tmp/smoke.mjs"
+  },
+  "dependencies": {
+    "@google/genai": "^1.52.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^22.0.0",
+    "jiti": "^2.7.0",
+    "typebox": "^1.1.24",
+    "typescript": "^6.0.3"
+  }
+}