@miketromba/ploof 0.1.2 → 0.1.4

package/README.md

@@ -9,7 +9,7 @@
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version" />
 </p>
 
-Ploof is a CLI for generating and editing creative assets with AI providers. It supports OpenAI image generation and editing today, with a provider registry designed for audio, video, and broader model marketplaces over time.
+Ploof is a CLI for generating and editing creative assets with AI providers. It supports OpenAI image generation, editing, and variations today, with a provider registry designed for audio, video, and broader model marketplaces over time.
 
 It is built for both developers and AI agents: predictable commands, parseable output, local auth profiles, YAML manifests, parallel execution, and a companion skill.
 
@@ -20,6 +20,7 @@ It is built for both developers and AI agents: predictable commands, parseable o
 | OpenAI auth profiles | Supported |
 | OpenAI image generation | Supported |
 | OpenAI image editing | Supported |
+| OpenAI image variations | Supported |
 | Context images and masks | Supported |
 | YAML/JSON batch manifests | Supported |
 | Dependency-aware parallel runs | Supported |
@@ -58,7 +59,6 @@ ploof login openai --api-key <your-api-key>
 ploof image generate \
   --prompt "Studio product photo of a matte black water bottle" \
   --out assets/hero.png \
-  --model gpt-image-1 \
   --size 1024x1024
 
 # Edit an image with context
@@ -108,13 +108,15 @@ ploof login openai \
 
 ## Image Generation
 
+OpenAI image generation and editing default to `gpt-image-2` when `--model` is omitted.
+
 ```bash
 ploof image generate \
   --provider openai \
   --profile default \
   --prompt "Editorial portrait, dramatic side light" \
   --out assets/portrait.png \
-  --model gpt-image-1 \
+  --model gpt-image-2 \
   --size 1024x1024 \
   --quality high \
   --format png
@@ -150,6 +152,24 @@ ploof image edit \
 
 Use repeated `--image` flags for context/reference images. Use `--mask` when the selected provider/model supports masked edits.
 
+## Image Variations
+
+OpenAI image variations use the legacy variations endpoint and default to `dall-e-2`, which is currently the only supported model for that endpoint.
+
+```bash
+ploof image variation \
+  --provider openai \
+  --image input.png \
+  --out variation.png \
+  --size 1024x1024
+```
+
+The plural alias also works:
+
+```bash
+ploof image variations --image input.png --out variation.png
+```
+
 ## Batch Manifests
 
 ```yaml
@@ -161,7 +181,7 @@ tasks:
     provider: openai
     prompt: "Studio product photo"
     params:
-      model: gpt-image-1
+      model: gpt-image-2
       size: 1024x1024
       quality: high
     output: assets/base.png
@@ -176,6 +196,15 @@ tasks:
       mask: ./mask.png
     prompt: "Add a premium background"
     output: assets/final.png
+
+  - id: variation
+    kind: image.variation
+    provider: openai
+    needs: [base]
+    inputs:
+      images:
+        - task: base
+    output: assets/variation.png
 ```
 
 Run it:
@@ -265,7 +294,7 @@ PLOOF_OPENAI_API_KEY=sk-... bun test tests/e2e
 Optional live-test overrides:
 
 ```bash
-PLOOF_OPENAI_LIVE_MODEL=gpt-image-1
+PLOOF_OPENAI_LIVE_MODEL=gpt-image-2
 PLOOF_OPENAI_LIVE_SIZE=1024x1024
 ```
 

package/SPEC.md

@@ -86,6 +86,7 @@ Initial capabilities:
 
 - `image.generate`
 - `image.edit`
+- `image.variation`
 
 Future providers should be added through the provider registry without changing the manifest model.
 
@@ -176,13 +177,15 @@ ploof config reset
 
 ### Image Generation
 
+OpenAI image generation and editing default to `gpt-image-2` when no model is specified.
+
 ```bash
 ploof image generate \
   --provider openai \
   --profile default \
   --prompt "Studio product photo" \
   --out assets/hero.png \
-  --model gpt-image-1 \
+  --model gpt-image-2 \
   --size 1024x1024 \
   --quality high \
   --format png
@@ -209,6 +212,20 @@ ploof image edit \
 
 The CLI must support multiple context images where the provider supports them.
 
+### Image Variations
+
+```bash
+ploof image variation \
+  --provider openai \
+  --image input.png \
+  --out assets/variation.png \
+  --model dall-e-2 \
+  --size 1024x1024
+```
+
+OpenAI variations default to `dall-e-2`, because the current OpenAI variations
+endpoint only supports that model. `ploof image variations` is an alias.
+
 ### Batch Run
 
 ```bash
@@ -226,7 +243,7 @@ tasks:
     provider: openai
     prompt: "Studio product photo"
     params:
-      model: gpt-image-1
+      model: gpt-image-2
       size: 1024x1024
       quality: high
     output: assets/base.png
@@ -241,6 +258,15 @@ tasks:
       mask: ./mask.png
     prompt: "Add a premium background"
     output: assets/final.png
+
+  - id: variation
+    kind: image.variation
+    provider: openai
+    needs: [base]
+    inputs:
+      images:
+        - task: base
+    output: assets/variation.png
 ```
 
 ## Asset Input Model
@@ -280,6 +306,7 @@ type Provider = {
   capabilities: ProviderCapability[]
   runImageGenerate(job, context): Promise<ProviderResult>
   runImageEdit(job, context): Promise<ProviderResult>
+  runImageVariation(job, context): Promise<ProviderResult>
 }
 ```
 
@@ -325,7 +352,7 @@ Asset-producing commands should write the asset to disk and print structured met
   "provider": "openai",
   "outputs": ["assets/hero.png"],
   "metadata": {
-    "model": "gpt-image-1"
+    "model": "gpt-image-2"
   }
 }
 ```
@@ -429,7 +456,7 @@ The initial complete implementation should include:
 - npm package scaffolding for `@miketromba/ploof`.
 - Build, test, typecheck, lint setup.
 - OpenAI auth profiles.
-- OpenAI image generate/edit.
+- OpenAI image generate/edit/variation.
 - Asset input normalization.
 - Manifest run with dependency-aware parallelism.
 - Output formats and sidecar metadata.