zer0-image-generator 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa19b12882a78f0dc868ca031b657d0500635ef08617f30a309640d0977e1db2
-  data.tar.gz: 64534f19ed7e404810f15e1326bd5db3e82e3eacc8160b9ddc86ca59c5cc6d29
+  metadata.gz: 8abc47b88bb6730b91b0358f17328e477db2a16d56a315ac8a7189bc54e6471d
+  data.tar.gz: 68d3d6064d3fe7d709a1957baf245dbc12a7c02e6d9e81569f639ea140a5647a
 SHA512:
-  metadata.gz: d2ea741174826fdb479b5a53fee673e5b8cc0b43bd0209cf5329bc1391db9f70420d58c3cc81f4bb40cce075e435ee5877b2e6ccef31ba820f1e41e943c5a085
-  data.tar.gz: 0060573caeca1124dd219b1ea070bde2f7401135a6423d686dbe2504f5fc93e220bbfe8fa47143e7b7419c3f5ac13e6b28bb093b3714f90cabef6d195b855792
+  metadata.gz: 25b6769e4645e195e6a776790f3735cc608d5d76bc4057510de0a9e5cdeec8c31701840fbe8d893017fc159a932f29c3dca59031cf63a5e6729efcff63b58c54
+  data.tar.gz: 00aab1bfadf7cf22f32ca7c4abe3b4f02de118d025c8441e107928e1edd9b91ddfd848bd09218c8bfa445aaa5742f8d43577e6115f5b88346ba45dbb567e0148

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+
+- Per-collection style/theme overrides: a `collection_styles:` map under
+  `preview_images:` lets each collection (`posts`, `docs`, `hacks`, …) carry
+  its own `style`, `style_modifiers`, `size`, `quality`, and `model` — so
+  field notes, docs, and hacks render with distinct visual identities. A
+  file's collection is derived from its `_<name>` directory; precedence is
+  author overrides → collection styles → CLI flags → env → config → defaults.
+
 ## [0.2.2] - 2026-07-14
 
 ### Fixed

data/README.md

@@ -87,18 +87,22 @@ 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
   collections_dir: ''         # falls back to Jekyll's top-level collections_dir
   front_matter_key: preview   # key to read/write (jekyll-seo-tag sites: image)
   authors_file: _data/authors.yml  # per-author style overrides ('' disables)
+  collection_styles: {}       # per-collection style/theme overrides (below)
   assets_prefix: /assets      # written paths omit this prefix ...
   auto_prefix: true           # ... and it is re-added for existence checks
 ```
 
-Priority per file: author overrides → CLI flags → environment variables →
-`_config.yml` → built-in defaults.
+Priority per file: author overrides → collection styles → CLI flags →
+environment variables → `_config.yml` → built-in defaults.
 
 Jekyll's own top-level `source:` key is honored automatically: on a site with
 `source: pages` (content, assets, and `_data` under `pages/`), every disk path
@@ -129,6 +133,42 @@ 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
+from field notes, docs differently from reviews. Any of `style`,
+`style_modifiers`, `size`, `quality`, and `model` can be set per collection;
+everything else inherits the global config. A file's collection comes from its
+`_<name>` directory; author overrides still win over collection styles.
+
+```yaml
+preview_images:
+  style: "retro pixel art"          # global fallback
+  collection_styles:
+    posts:
+      style: "hand-inked editorial illustration, warm print tones"
+    docs:
+      style: "clean isometric technical diagram"
+      style_modifiers: "matte surfaces, labeled parts, blueprint accents"
+    hacks:
+      style: "circuit-board schematic, glowing traces"
+```
+
 ### Per-author style overrides
 
 If `authors_file` points at a YAML map, an author's `preview:` block overrides

data/lib/zer0_image_generator/preview_generator.py

@@ -17,6 +17,9 @@ knob with zer0-compatible defaults:
     author overrides    authors_file ("" disables)           _data/authors.yml
     collections         collections (list, or "auto" to      [posts]
                         discover from Jekyll's collections:)
+    collection styles   collection_styles (map of            {} (global style)
+                        collection → style/style_modifiers/
+                        size/quality/model overrides)
 
 Architecture — Claude ORCHESTRATES, an image model RENDERS:
 
@@ -125,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)
@@ -573,6 +578,22 @@ def read_authors(project_root: Path, authors_file: str) -> Dict[str, Any]:
     return load_yaml_file(project_root / authors_file.strip().lstrip("/"))
 
 
+# Settings fields an override block (author preview: / collection_styles:)
+# may replace per file.
+OVERRIDE_KEYS = ("style", "style_modifiers", "size", "quality", "model")
+
+
+def _filter_override_block(block: Any) -> Dict[str, str]:
+    """Keep only the recognized override keys with non-empty values."""
+    if not isinstance(block, dict):
+        return {}
+    return {
+        key: str(value).strip()
+        for key, value in block.items()
+        if key in OVERRIDE_KEYS and value is not None and str(value).strip()
+    }
+
+
 def author_preview_overrides(authors: Dict[str, Any], author_key: Any) -> Dict[str, str]:
     """`preview:` override block for an author key (style/style_modifiers/size/
     quality/model). `author:` may be a list or mapping in some posts — only a
@@ -582,15 +603,27 @@ def author_preview_overrides(authors: Dict[str, Any], author_key: Any) -> Dict[s
     author = authors.get(author_key)
     if not isinstance(author, dict):
         return {}
-    preview = author.get("preview")
-    if not isinstance(preview, dict):
+    return _filter_override_block(author.get("preview"))
+
+
+def collection_of(path: Path) -> str:
+    """The file's collection, from the nearest `_<name>` ancestor directory
+    (Jekyll's collection layout) — '' for files outside any collection."""
+    for parent in Path(path).resolve().parents:
+        name = parent.name
+        if name.startswith("_") and len(name) > 1:
+            return name[1:]
+    return ""
+
+
+def collection_preview_overrides(
+    collection_styles: Dict[str, Any], collection: str
+) -> Dict[str, str]:
+    """`collection_styles:` override block for a collection — same keys as
+    author overrides, so each collection can carry its own visual theme."""
+    if not collection or not isinstance(collection_styles, dict):
         return {}
-    return {
-        key: str(value).strip()
-        for key, value in preview.items()
-        if key in ("style", "style_modifiers", "size", "quality", "model")
-        and value is not None and str(value).strip()
-    }
+    return _filter_override_block(collection_styles.get(collection))
 
 
 def _env_flag(name: str) -> bool:
@@ -613,11 +646,13 @@ class Settings:
     enabled: bool = True
     collections: List[str] = field(default_factory=lambda: list(DEFAULTS["collections"]))
     collections_dir: str = DEFAULTS["collections_dir"]
+    collection_styles: Dict[str, Any] = field(default_factory=dict)
     front_matter_key: str = DEFAULTS["front_matter_key"]
     authors_file: str = DEFAULTS["authors_file"]
     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
@@ -703,6 +738,10 @@ def resolve_settings(args: argparse.Namespace, config: Dict[str, Any]) -> Settin
         ),
         enabled=bool(cfg("enabled", True)),
         collections=[str(c) for c in collections],
+        collection_styles=(
+            cfg("collection_styles", {})
+            if isinstance(cfg("collection_styles", {}), dict) else {}
+        ),
         collections_dir=str(collections_dir or "").strip().strip("/"),
         front_matter_key=(
             args.front_matter_key
@@ -716,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"),
@@ -748,20 +788,38 @@ def resolve_settings(args: argparse.Namespace, config: Dict[str, Any]) -> Settin
     return settings
 
 
-def apply_author_overrides(settings: Settings, overrides: Dict[str, str]) -> Settings:
-    """Per-file settings copy with the author's preview block applied on top."""
-    if not overrides:
+def apply_preview_overrides(
+    settings: Settings, *override_blocks: Dict[str, str]
+) -> Settings:
+    """Per-file settings copy with override blocks applied in order — later
+    blocks win (pass collection styles first, author overrides on top)."""
+    merged: Dict[str, str] = {}
+    for block in override_blocks:
+        merged.update(block or {})
+    if not merged:
         return settings
     return replace(
         settings,
-        style=overrides.get("style", settings.style),
-        style_modifiers=overrides.get("style_modifiers", settings.style_modifiers),
-        size=overrides.get("size", settings.size),
-        quality=overrides.get("quality", settings.quality),
-        model=overrides.get("model", settings.model),
+        **{key: merged.get(key, getattr(settings, key)) for key in OVERRIDE_KEYS},
     )
 
 
+def file_preview_settings(settings: Settings, cf: "ContentFile",
+                          authors: Dict[str, Any]) -> Settings:
+    """The per-file settings: global → collection_styles[collection] →
+    author preview: block (most specific wins)."""
+    coll_overrides = collection_preview_overrides(
+        settings.collection_styles, collection_of(cf.path))
+    author_overrides = author_preview_overrides(authors, cf.author)
+    result = apply_preview_overrides(settings, coll_overrides, author_overrides)
+    if coll_overrides:
+        info(f"  ↳ Collection '{collection_of(cf.path)}' preview style applied")
+    if author_overrides:
+        info(f"  ↳ Author '{cf.author}' preview overrides applied "
+             f"({settings.authors_file})")
+    return result
+
+
 def model_family(model: str) -> Optional[str]:
     m = (model or "").strip().lower()
     for prefix, family in MODEL_FAMILIES.items():
@@ -1066,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]}...")
@@ -1105,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:
@@ -1442,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.
 
@@ -1466,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(
@@ -1476,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)
@@ -1510,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."""
@@ -1541,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)
@@ -2025,13 +2109,8 @@ class Runner:
             return
         out_base = self.root / settings.output_dir / slug
 
-        # Author overrides apply only once an image/prompt is actually built.
-        file_settings = apply_author_overrides(
-            settings, author_preview_overrides(self.authors, cf.author)
-        )
-        if file_settings is not settings:
-            info(f"  ↳ Author '{cf.author}' preview overrides applied "
-                 f"({settings.authors_file})")
+        # Style overrides apply only once an image/prompt is actually built.
+        file_settings = file_preview_settings(settings, cf, self.authors)
 
         # ---- Analyze: Claude reads the article and writes the art brief ----
         base_prompt = build_prompt(cf, file_settings)
@@ -2114,9 +2193,7 @@ class Runner:
             return
 
         info(f"Enhancing preview for: {cf.title}")
-        file_settings = apply_author_overrides(
-            settings, author_preview_overrides(self.authors, cf.author)
-        )
+        file_settings = file_preview_settings(settings, cf, self.authors)
         prompt = build_enhance_prompt(cf, file_settings)
         debug(f"Enhancement prompt: {prompt[:400]}...")
 

data/lib/zer0_image_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zer0ImageGenerator
-  VERSION = "0.2.2"
+  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.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Amr Abdel