[recipes] Infographic Generator: turn research docs into visual infographics

[jaredirish]

Summary

Turn any research doc, analysis, or Open Brain thought cluster into professional infographic images using Gemini's free-tier image generation API.

• Auto-chunks content into logical segments (one infographic per topic)
• Writes verbose prompts (300+ words each with specific hex colors, layout, typography)
• Generates PNG images via Gemini API
• Supports --redo N for individual image regeneration and --premium for better text
• Open Brain integration: search thoughts as source, capture prompts as searchable templates

Part of the Open Brain Flywheel (#84)

This is the visualize side of a three-recipe capture-process-visualize loop:

Recipe	PR	Role
Panning for Gold	#21 (merged)	Process raw brain dumps into evaluated ideas
Auto-Capture Protocol	#42 (open)	Automatically save session insights on close
Infographic Generator	This PR	Turn findings into shareable visuals

Second recipe contribution from @jaredirish.

Files

• README.md - Full recipe with Prerequisites, Steps, Expected Outcome, Troubleshooting
• metadata.json - Recipe metadata
• infographic-generator.skill.md - AI coding tool skill (Claude Code compatible)
• generate.py - Image generation script (uses GEMINI_API_KEY env var, no hardcoded keys)

Test Plan

• CI passes all 14 OB1 checks
• generate.py errors cleanly when GEMINI_API_KEY is not set
• README sections match OB1 requirements (Prerequisites, Steps, Expected Outcome, Troubleshooting)
• No credentials or API keys in any file

[justfinethanku]

Code Review: Infographic Generator Recipe

Summary

This is a well-structured and thoughtfully designed contribution. The recipe adds a valuable capability to the Open Brain ecosystem by enabling users to generate professional infographic images from their research and thoughts using Gemini's free-tier API. The contribution demonstrates excellent documentation, clean code, and strong integration with the Open Brain flywheel concept.

What's Good

Documentation Excellence:

• README is comprehensive with all required sections (Prerequisites, Steps, Expected Outcome, Troubleshooting)
• Credential tracker is a nice touch for helping users track their setup
• Troubleshooting section covers realistic failure scenarios with actionable solutions
• Clear connection to the Open Brain Flywheel (#84) provides context for the contribution's role

Code Quality:

• Python script properly checks for environment variables before proceeding
• No hardcoded credentials anywhere
• Clean error handling with retry logic for API failures
• Well-structured argument parsing with helpful usage documentation
• Proper use of pathlib for cross-platform compatibility

Skill Design:

• Comprehensive step-by-step process with clear routing logic
• Audience calibration is a thoughtful feature
• Detailed prompt template ensures consistent, high-quality outputs
• Good integration points with Open Brain (both read and write sides)

metadata.json:

• All required fields present and valid
• Appropriate difficulty level (intermediate) and time estimate (15 minutes)
• Tags are relevant and searchable
• Free-tier service requirement aligns with OB1 principles

Required Changes

1. Reference to non-existent recipe (blocking)

Line 132 in README.md references ../brain-dump-processor/:

Together with [Panning for Gold](../brain-dump-processor/) and [Auto-Capture Protocol](../auto-capture-protocol/)...

The correct path should be ../panning-for-gold/ (checking the recipes directory). Also, the Auto-Capture Protocol recipe doesn't exist yet in the repo (PR #42 is still open). You should either:

• Change to: Together with [Panning for Gold](../panning-for-gold/) and Auto-Capture Protocol (PR #42)...
• Or remove the broken link until PR #42 merges

2. Skills directory path assumption (minor but important)

The README assumes the user has a ~/.claude/skills/ directory structure. While this is common for Claude Code, it would be helpful to add a note in the Prerequisites or Step 1 clarifying this is for Claude Code specifically, or provide alternative instructions for other AI coding tools mentioned in the prerequisites.

3. Missing validation for prompt file format (nice-to-have)

The generate.py script assumes the prompts file follows a specific markdown format. If the format is wrong, users get a generic "No prompts found" error. Consider adding:

• More specific error messages about what's expected (e.g., "Expected '## Infographic N: Title' headers followed by '### Prompt' sections")
• Or a --validate flag to check file format before attempting generation

The script does print the expected format on line 142, which is good, but catching specific format errors earlier would improve UX.

Nice-to-Haves (optional improvements)

1. Dependencies documentation: Consider mentioning approximate install sizes or noting that google-genai and Pillow are the only dependencies (keeping the venv lightweight).

2. Example output: A brief description or even a note about what the generated images typically look like would help users set expectations.

3. Model versioning: The Gemini model names (gemini-2.5-flash-image, gemini-3.1-flash-image-preview) may change. Consider adding a comment in the code about when these were last verified or a link to Gemini's model documentation.

Security & Safety ✅

• No credentials, API keys, or secrets in any file
• No SQL (not applicable)
• No binary blobs
• No modifications to core Open Brain infrastructure
• Environment variable properly checked before use
• No destructive operations

Category-Specific Requirements ✅

Recipe requirements met:

• Folder structure correct (recipes/infographic-generator/)
• README.md present and complete
• metadata.json present and valid
• Code files present (generate.py, skill file)
• Step-by-step instructions clear and copy-paste ready
• Troubleshooting section with multiple scenarios

PR Format ✅

• Title follows [recipes] Description format
• Body includes what it does, requirements, and test plan
• Proper attribution to @jaredirish

Verdict: Minor fixes needed

This is a strong contribution that's nearly ready to merge. The primary blocker is the broken internal link to brain-dump-processor which should be panning-for-gold. Once that's fixed (and ideally the Auto-Capture Protocol link is updated to note it's not yet merged), this should be good to go.

Great work @jaredirish! This is a creative and practical addition to the Open Brain ecosystem. The skill design is particularly well thought out, and I appreciate how it fits into the larger capture-process-visualize workflow.

[justfinethanku]

Code Review: Infographic Generator Recipe

Summary

This is a well-structured and thoughtfully designed contribution. The recipe adds a valuable capability to the Open Brain ecosystem by enabling users to generate professional infographic images from their research and thoughts using Gemini's free-tier API. The contribution demonstrates excellent documentation, clean code, and strong integration with the Open Brain flywheel concept.

What's Good

Documentation Excellence:

• README is comprehensive with all required sections (Prerequisites, Steps, Expected Outcome, Troubleshooting)
• Credential tracker is a nice touch for helping users track their setup
• Troubleshooting section covers realistic failure scenarios with actionable solutions
• Clear connection to the Open Brain Flywheel (#84) provides context for the contribution's role

Code Quality:

• Python script properly checks for environment variables before proceeding
• No hardcoded credentials anywhere
• Clean error handling with retry logic for API failures
• Well-structured argument parsing with helpful usage documentation
• Proper use of pathlib for cross-platform compatibility

Skill Design:

• Comprehensive step-by-step process with clear routing logic
• Audience calibration is a thoughtful feature
• Detailed prompt template ensures consistent, high-quality outputs
• Good integration points with Open Brain (both read and write sides)

metadata.json:

• All required fields present and valid
• Appropriate difficulty level (intermediate) and time estimate (15 minutes)
• Tags are relevant and searchable
• Free-tier service requirement aligns with OB1 principles

Required Changes

1. Reference to non-existent recipe (blocking)

Line 132 in README.md references ../brain-dump-processor/:

Together with [Panning for Gold](../brain-dump-processor/) and [Auto-Capture Protocol](../auto-capture-protocol/)...

The correct path should be ../panning-for-gold/ (the actual directory name in the repo). Also, the Auto-Capture Protocol recipe doesn't exist yet (PR #42 is still open). You should either:

• Change to: Together with [Panning for Gold](../panning-for-gold/) and Auto-Capture Protocol (PR #42)...
• Or remove the broken link until PR #42 merges

2. Skills directory path assumption (minor but important)

The README assumes the user has a ~/.claude/skills/ directory structure. While this is common for Claude Code, it would be helpful to add a note in the Prerequisites or Step 1 clarifying this is for Claude Code specifically, or provide alternative instructions for other AI coding tools mentioned in the prerequisites.

3. Missing validation for prompt file format (nice-to-have)

The generate.py script assumes the prompts file follows a specific markdown format. If the format is wrong, users get a generic "No prompts found" error. Consider adding more specific error messages about what's expected (the script does print the expected format on line 142, which helps).

Nice-to-Haves (optional improvements)

1. Dependencies documentation: Consider mentioning approximate install sizes or noting that google-genai and Pillow are the only dependencies (keeping the venv lightweight).

2. Example output: A brief description of what the generated images typically look like would help users set expectations.

3. Model versioning: The Gemini model names (gemini-2.5-flash-image, gemini-3.1-flash-image-preview) may change. Consider adding a comment in the code about when these were last verified.

Security & Safety ✅

• No credentials, API keys, or secrets in any file
• No SQL (not applicable)
• No binary blobs
• No modifications to core Open Brain infrastructure
• Environment variable properly checked before use
• No destructive operations

Category-Specific Requirements ✅

Recipe requirements met:

• Folder structure correct (recipes/infographic-generator/)
• README.md present and complete
• metadata.json present and valid
• Code files present (generate.py, skill file)
• Step-by-step instructions clear and copy-paste ready
• Troubleshooting section with multiple scenarios

PR Format ✅

• Title follows [recipes] Description format
• Body includes what it does, requirements, and test plan
• Proper attribution to @jaredirish

Verdict: Minor fixes needed

This is a strong contribution that's nearly ready to merge. The primary blocker is the broken internal link to brain-dump-processor which should be panning-for-gold. Once that's fixed (and ideally the Auto-Capture Protocol link is updated to note it's not yet merged), this should be good to go.

Great work @jaredirish! This is a creative and practical addition to the Open Brain ecosystem. The skill design is particularly well thought out, and I appreciate how it fits into the larger capture-process-visualize workflow.

[matthallett1]

@claude review this PR

[github-actions]

Claude Code is working…

I'll analyze this and get back to you.

View job run

[matthallett1]

@claude review this PR

[github-actions]

Claude finished @matthallett1's task in 1m 42s —— View job

---

PR Review: Infographic Generator

• Gathering context (reading files, existing reviews)
• Reviewing alignment, clarity, completeness, safety, and design patterns
• Posting findings

---

@matthallett1 — review complete. Building on @justfinethanku's earlier feedback (which covers the documentation issues well), I want to flag some technical correctness concerns that need attention before merge.

---

Alignment & Value ✅

This fits OB1's flywheel framing cleanly. Using Open Brain as both a source (search_thoughts) and sink (capture_thought) for infographic prompts is a genuinely creative integration pattern — making prompts themselves into searchable memory is a nice idea. The contribution is well-scoped and doesn't try to grow into its own project.

One nuance worth flagging: open_brain: true in metadata.json implies OB integration is required, but in practice it's entirely optional — the recipe functions standalone with just a markdown file and a Gemini key. Consider whether this should be open_brain: false with OB mentioned as an enhancement, or update the description to clarify that OB integration is optional.

---

Blocking Technical Issues

1. part.as_image() is not a standard google-genai API method

generate.py lines 99 and 116 call part.as_image(). This method does not exist in the google-genai SDK. The standard pattern for extracting image bytes from a Gemini response is through part.inline_data.data (raw bytes) and then saving them with Pillow. As written, the script will throw AttributeError on every generation attempt — meaning no images will be produced.

The correct approach looks like:

from PIL import Image
import io
# ...
image_bytes = part.inline_data.data
image = Image.open(io.BytesIO(image_bytes))
image.save(str(out_path))

This also explains why Pillow is listed as a dependency — it's needed for this, but the current code never imports or uses it directly. Fix this →

2. Model names look speculative

MODEL_FREE = "gemini-2.5-flash-image" and MODEL_PREMIUM = "gemini-3.1-flash-image-preview" (generate.py lines 39–40). These don't correspond to any documented Gemini image generation model names. The actual model names for Gemini image generation (as of early 2026) follow patterns like gemini-2.0-flash-preview-image-generation. Using incorrect model names means every API call will fail with a 404/model-not-found error.

Please verify these against the current Gemini model documentation and update accordingly. Fix this →

3. Broken internal links (confirming @justfinethanku's finding)

README.md line 132 references ../brain-dump-processor/ (doesn't exist — should be ../panning-for-gold/) and ../auto-capture-protocol/ (PR #42 is still open, no directory exists). Both links will 404.

Suggested fix:

Together with [Panning for Gold](../panning-for-gold/) and Auto-Capture Protocol (coming in PR #42), this forms a complete capture-process-visualize flywheel...

Fix this →

---

Minor Issues

sys.path injection is fragile (generate.py lines 25–28): If the venv doesn't exist (e.g., user skips Step 3 or uses a different path), the glob finds nothing and the script silently falls through to from google import genai — which may or may not work depending on what's installed globally. A missing venv gives no warning. A small guard or a clearer error message would help, but this is low priority.

--redo display logic bug (generate.py line 161): total = len(prompts) if not args.redo else args.redo — after filtering, prompts always has 1 item, but total shows the redo index (e.g., --redo 5 would print [5/5] instead of [1/1]). Cosmetic but confusing.

Skill path is Claude Code-specific: The skill hardcodes ~/.claude/skills/infographic-generator/generate.py in Step 6. The README's prerequisites say "Claude Code (or another AI coding tool)" but the skill file only works with Claude Code's skill system. Worth adding a note. (@justfinethanku flagged this as well.)

---

What's Working Well

The skill file's prompt template is genuinely high quality — the "what to avoid" section, the hex color requirement, and the audience calibration table are all thoughtful touches that will actually improve output. The step-by-step README structure is clear, the credential tracker is a nice UX addition, and the manifest JSON output makes the skill's handoff clean.

---

Verdict: Needs fixes before merge

Issues 1 and 2 above (the broken API call and unverified model names) mean the script won't generate any images as written — the core function of the recipe won't work. These need to be confirmed against the actual Gemini SDK + model list. Issue 3 (broken links) was already flagged and also needs to be addressed.

Once those three are fixed, this is a solid contribution. Great work @jaredirish on the overall design and documentation quality.

[matthallett1]

Great concept and the skill prompt template is genuinely high quality. However, the automated review caught two issues that mean the script won't produce any images as written:

P1: part.as_image() doesn't exist in the google-genai SDK. Lines 99 and 116 of generate.py call this method, but it's not a standard API. The correct pattern is part.inline_data.data (raw bytes) + PIL.Image.open(io.BytesIO(...)). As written, every generation attempt throws AttributeError.

P1: Model names need verification. gemini-2.5-flash-image and gemini-3.1-flash-image-preview don't match documented Gemini model IDs. The actual names follow patterns like gemini-2.0-flash-preview-image-generation. Please verify against https://ai.google.dev/gemini-api/docs/models.

P2: Broken links. ../brain-dump-processor/ should be ../panning-for-gold/, and ../auto-capture-protocol/ doesn't exist yet.

Once the script actually runs and produces images, this is a strong contribution. The design and documentation quality are well above the bar.

[jaredirish]

Thanks for the thorough review! Pushed fixes addressing all the feedback. Here's what changed and what was clarified:

Fixed:

• Broken links: ../brain-dump-processor/ → ../panning-for-gold/, and the auto-capture link now points to PR [recipes] Auto-Capture Protocol: the write side of the flywheel #42 instead of a non-existent directory
• Synced generate.py with the working local version (cleaner error handling, fixed --redo display counter bug)
• Rebased onto main to pick up the markdown lint fix

Clarification on the two "P1" items:

1. part.as_image() is valid. The official google-genai SDK docs show part.as_image() as the standard pattern for extracting generated images. This has been working in production daily. See the SDK codegen instructions for examples.

2. gemini-2.5-flash-image is a real model. It's documented in the SDK and has been the free-tier image generation model. The premium model name (gemini-3.1-flash-image-preview) is also working in production.

The script generates images correctly as written — tested daily across multiple projects.

[justfinethanku]

"gemini-2.5-flash-image is a real model. It's documented in the SDK and has been the free-tier image generation model. The premium model name (gemini-3.1-flash-image-preview) is also working in production."

yay for ai having NO IDEA what the latest models are facepalm

[justfinethanku]

Thanks for the work here. This is close, and we’ll merge it as soon as these last small issues are cleaned up:

• rebase or merge main to clear the current merge conflicts
• fix the --redo progress counter in generate.py so the displayed total matches the regenerated single item

If you want, enable maintainer edits and we can patch the small stuff directly.