zer0-image-generator 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24975e688896196e8e883c15ed17d09e5856a9b68f18b47b347bc61d701cc265
-  data.tar.gz: da2d123ed3067f36c2e5962bd3a351a9d1ae48e1fd97bfe6dbcccb23aac53e52
+  metadata.gz: 8abc47b88bb6730b91b0358f17328e477db2a16d56a315ac8a7189bc54e6471d
+  data.tar.gz: 68d3d6064d3fe7d709a1957baf245dbc12a7c02e6d9e81569f639ea140a5647a
 SHA512:
-  metadata.gz: 2add913663a1f13bfebc00746b3ace4ebf5c4e096fd34ee1db89754245762d011e1a2ca8173ed2f0aefbf46abdacb041625f9ac916f9b8e48aa13c6c38c87467
-  data.tar.gz: e275f913cfeb197728138bc154a6963e31b1cdf0a1b11081a8526ef002667dfa504b1c7a0e55bac799a5977a599995012f2fe0f66aa28a3e5b28d599244c16a1
+  metadata.gz: 25b6769e4645e195e6a776790f3735cc608d5d76bc4057510de0a9e5cdeec8c31701840fbe8d893017fc159a932f29c3dca59031cf63a5e6729efcff63b58c54
+  data.tar.gz: 00aab1bfadf7cf22f32ca7c4abe3b4f02de118d025c8441e107928e1edd9b91ddfd848bd09218c8bfa445aaa5742f8d43577e6115f5b88346ba45dbb567e0148

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-07-15
+
+### Added
+
+- `claude_effort` knob (default `low`): the Claude art-brief and vision-review
+  calls now send `output_config: {effort: ...}` — short creative tasks don't
+  need deep reasoning, and `low` substantially cuts per-image orchestration
+  latency. Configurable per site (`preview_images.claude_effort`); `''`
+  disables. Gracefully retries without the parameter on models that reject it.
+
+### Changed
+
+- README documents the batch-performance contract: one `--collection` run
+  parallelizes across files (`--parallel N`, default 4); per-file loops don't.
+
 ## [0.3.0] - 2026-07-14
 
 ### Added

data/README.md

@@ -87,6 +87,9 @@ preview_images:
   output_dir: assets/images/previews
   prompt_engine: claude       # claude analyzes each article | template
   review_engine: claude       # claude vision-reviews each render | none
+  claude_effort: low          # output_config.effort for the brief/review calls
+                              # (low = fastest, right-sized for short briefs;
+                              #  high = deepest; '' sends no effort parameter)
   # --- portability knobs (the zer0-isms, now configurable) ---
   collections: [posts]        # list of collections, or 'auto' to discover
                               # them from Jekyll's own `collections:` map
@@ -130,6 +133,21 @@ preview_images:
   # front_matter_key/preview + /assets prefixing are already the defaults
 ```
 
+### Batch performance
+
+The engine parallelizes **within one invocation** (4 workers by default, `-j N`
+to change). For many files, one collection run beats a loop of single-file
+runs — the loop pays process startup per file and never engages the pool:
+
+```bash
+bundle exec jekyll preview-images --collection posts --parallel 6   # ✓ parallel
+for f in ...; do jekyll preview-images -f "$f"; done                # ✗ serial
+```
+
+Claude orchestration runs at `claude_effort: low` by default — right-sized for
+a short art brief and a render verdict. Raise it (or set `claude_model`) if you
+want deeper art direction at the cost of latency.
+
 ### Per-collection styles
 
 Give each collection its own visual identity — tutorials render differently

data/lib/zer0_image_generator/preview_generator.py

@@ -128,6 +128,8 @@ DEFAULTS: Dict[str, Any] = {
     "prompt_engine": "claude",   # claude analyzes the article; falls back to template
     "review_engine": "claude",   # claude vision-reviews the render; `none` disables
     "claude_model": "",          # empty → DEFAULT_CLAUDE_MODEL
+    "claude_effort": "low",      # output_config.effort for brief/review calls
+                                 # (short creative tasks; "" sends no effort)
 }
 
 # Enhance mode (OpenAI /v1/images/edits — see OpenAIProvider.edit)
@@ -650,6 +652,7 @@ class Settings:
     prompt_engine: str = DEFAULTS["prompt_engine"]
     review_engine: str = DEFAULTS["review_engine"]
     claude_model: str = DEFAULTS["claude_model"]
+    claude_effort: str = DEFAULTS["claude_effort"]
 
     dry_run: bool = False
     verbose: bool = False
@@ -752,6 +755,7 @@ def resolve_settings(args: argparse.Namespace, config: Dict[str, Any]) -> Settin
         prompt_engine=pick(args.prompt_engine, "PROMPT_ENGINE", "prompt_engine"),
         review_engine=pick(args.review, "REVIEW_ENGINE", "review_engine"),
         claude_model=str(cfg("claude_model", "") or ""),
+        claude_effort=str(cfg("claude_effort", DEFAULTS["claude_effort"]) or ""),
         dry_run=args.dry_run or _env_flag("DRY_RUN"),
         verbose=args.verbose or _env_flag("VERBOSE"),
         force=args.force or _env_flag("FORCE"),
@@ -1120,6 +1124,7 @@ def claude_article_brief(client: "AnthropicClient", cf: ContentFile,
         text = client.complete(
             ART_DIRECTOR_SYSTEM, article,
             model=claude_model_for(settings), max_tokens=2048,
+            effort=settings.claude_effort,
         ).strip()
         if text:
             debug(f"Claude art-direction brief: {text[:300]}...")
@@ -1159,6 +1164,7 @@ def claude_review_image(client: "AnthropicClient", image_path: Path,
         text = client.complete_vision(
             REVIEWER_SYSTEM, context, image_path,
             model=claude_model_for(settings),
+            effort=settings.claude_effort,
         )
         data = _extract_json_object(text)
         if not data:
@@ -1496,6 +1502,7 @@ class AnthropicClient:
         user_text: str,
         model: str = DEFAULT_CLAUDE_MODEL,
         max_tokens: int = CLAUDE_MAX_TOKENS,
+        effort: str = "",
     ) -> str:
         """One Messages-API turn (or CLI run); returns concatenated text blocks.
 
@@ -1520,6 +1527,8 @@ class AnthropicClient:
             "system": system_blocks,
             "messages": [{"role": "user", "content": user_text}],
         }
+        if effort:
+            payload["output_config"] = {"effort": effort}
 
         def call(body: Dict[str, Any]) -> dict:
             return with_retries(
@@ -1530,7 +1539,12 @@ class AnthropicClient:
         try:
             data = call(payload)
         except HttpStatusError as exc:
-            if exc.status == 400 and "thinking" in exc.message().lower():
+            message = exc.message().lower() if exc.status == 400 else ""
+            if exc.status == 400 and ("output_config" in message or "effort" in message):
+                debug("Retrying without output_config parameter")
+                payload.pop("output_config", None)
+                data = call(payload)
+            elif exc.status == 400 and "thinking" in message:
                 debug("Retrying without thinking parameter")
                 payload.pop("thinking", None)
                 data = call(payload)
@@ -1564,6 +1578,7 @@ class AnthropicClient:
         image_path: Path,
         model: str = DEFAULT_CLAUDE_MODEL,
         max_tokens: int = 2048,
+        effort: str = "",
     ) -> str:
         """One vision turn over a local PNG (review stage). CLI mode passes the
         file path and lets `claude -p` read it; API modes embed base64."""
@@ -1595,10 +1610,25 @@ class AnthropicClient:
                 ],
             }],
         }
-        data = with_retries(
-            lambda: http_json(ANTHROPIC_API_URL, payload, self.headers(), timeout=900),
-            "Anthropic API (review)",
-        )
+        if effort:
+            payload["output_config"] = {"effort": effort}
+
+        def call(body: Dict[str, Any]) -> dict:
+            return with_retries(
+                lambda: http_json(ANTHROPIC_API_URL, body, self.headers(), timeout=900),
+                "Anthropic API (review)",
+            )
+
+        try:
+            data = call(payload)
+        except HttpStatusError as exc:
+            message = exc.message().lower() if exc.status == 400 else ""
+            if exc.status == 400 and ("output_config" in message or "effort" in message):
+                debug("Retrying review without output_config parameter")
+                payload.pop("output_config", None)
+                data = call(payload)
+            else:
+                raise
         if data.get("stop_reason") == "refusal":
             details = data.get("stop_details") or {}
             raise ClaudeRefusal(details.get("category") if isinstance(details, dict) else None)

data/lib/zer0_image_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zer0ImageGenerator
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zer0-image-generator
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Amr Abdel