thanh-kit 2.5.0 → 2.5.2

package/templates/skills/ai-artist/references/nano-banana.md

@@ -1,4 +1,4 @@
-# Nano Banana (Gemini Image)
+# Nano Banana Pro (Gemini Image)
 
 ## Models
 
@@ -29,6 +29,33 @@ image_size="2K"      # 1K, 2K, 4K - MUST be uppercase K
 
 **Product**: `[Product] on [surface]. Materials: [finish]. Lighting: [setup]. Camera: [angle]. Background: [type]. Style: [commercial/lifestyle].`
 
+**Infographic**: `Premium liquid glass Bento grid infographic with 8 modules. Product: [item]. Language: [lang]. Hero card: 28-30%. Background: [ethereal/macro/pattern/context].`
+
+## Prompt Collection / Prompt Search
+
+Read `references/awesome-prompts.csv` directly or search for relevant prompts using `python3 ../scripts/search.py "<query>"`.
+
+## JSON Structured Prompts
+
+For complex scenes, use JSON structure:
+
+```json
+{
+  "meta_data": { "prompt_version": "2.0", "use_case": "..." },
+  "subject_layer": {
+    "anatomy": { "demographics": {}, "face_detail": {}, "hair": {} },
+    "attire_layer": { "garment_main": {}, "accessories": {} },
+    "pose_dynamics": { "posture": "", "limb_placement": {} }
+  },
+  "environment_layer": { "setting_type": "", "spatial_layout": {} },
+  "composition_and_tech": {
+    "framing": { "type": "", "angle": "" },
+    "lighting": { "source": "", "direction": "" },
+    "aesthetic_style": { "visual_core": "", "vibe": "" }
+  }
+}
+```
+
 ## Techniques
 
 | Technique | Example |
@@ -39,6 +66,7 @@ image_size="2K"      # 1K, 2K, 4K - MUST be uppercase K
 | Realism trigger | `Natural lighting, DOF. Captured with Canon EOS 90D DSLR.` |
 | Structured edits | `Make ALL edits: - [1] - [2] - [3]` |
 | Complex logic | `Kittens MUST have heterochromatic eyes matching fur colors` |
+| Identity lock | `Use reference as EXACT facial reference. STRICT identity lock.` |
 
 ## Advanced Features
 
@@ -48,6 +76,53 @@ image_size="2K"      # 1K, 2K, 4K - MUST be uppercase K
 
 **Thinking Mode** (Pro only): `part.thought` in response for complex reasoning.
 
+## Popular Use Case Templates
+
+### Quote Card
+```
+A wide quote card with {background} background, {font_style} font.
+Quote: "{quote_text}" — {author}
+Large subtle quotation mark before text. Portrait on left, text right.
+Text: 2/3 width, portrait: 1/3 width. Gradient transition on portrait.
+```
+
+### Infographic (Bento Grid)
+```
+Premium liquid glass Bento grid product infographic with 8 modules.
+Product: [name]. Language: [lang].
+1) Hero card (28-30%): Product photo/3D glass
+2) Core Benefits: 4 benefits + icons
+3) How to Use: 4 methods + icons
+4) Key Metrics: 5 data points
+5) Who It's For: 4 recommended + 3 caution groups
+6) Important Notes: 4 precautions
+7) Quick Reference: Specs/certifications
+8) Did You Know: 3 facts
+Background: Apple liquid glass cards (85-90% transparent).
+```
+
+### Mirror Selfie
+```
+Scene: Mirror selfie in [room type], [color] tone.
+Subject: [demographics], [body type], [hairstyle].
+Pose: [stance], holding smartphone.
+Clothing: [detailed outfit description].
+Environment: [room details, furnishings, lighting].
+Camera: Smartphone rear camera via mirror, [focal length]mm.
+Negative: [artifacts to avoid].
+```
+
+### Style Transformation
+```
+A Japanese Edo-period Ukiyo-e woodblock print reimagining [modern scene].
+Characters: Edo-era kimono but modern actions.
+Tech transformation: Smartphones → glowing scrolls, trains → wooden carriages.
+Composition: Flattened perspective, bold ink outlines.
+Texture: Wood grain, paper fibers, pigment bleeding.
+Colors: Prussian blue, vermilion red, muted ochre.
+Include vertical Japanese calligraphy and red artist seal.
+```
+
 ## Workflow
 
 1. Narrative description → 2. Photography terms → 3. ALL CAPS emphasis → 4. Multi-turn refine → 5. Negative constraints → 6. Set ratio/resolution
@@ -57,3 +132,5 @@ image_size="2K"      # 1K, 2K, 4K - MUST be uppercase K
 - Keyword spam ("4k, trending, masterpiece")
 - Vague text ("add some text" → specify exact text, font, position)
 - Lowercase resolution ("4k" rejected, use "4K")
+- Over-smoothed skin requests (leads to plastic look)
+- Generic prompts without specific details

package/templates/skills/ai-artist/references/validation-workflow.md

@@ -0,0 +1,117 @@
+# AI Artist Validation Workflow
+
+Agent instructions for mandatory validation interview before image generation.
+
+## Step 1: Parse Arguments
+
+Extract from user input:
+- **concept**: The subject/description (required)
+- **--mode**: search (default), creative, or wild
+- **--skip**: If present, use defaults and skip to Step 4
+
+**Defaults for --skip mode:** Style=Photorealistic, Mood=Professional, Colors=Auto, Aspect=16:9
+
+## Step 2: Interview User
+
+Use `AskUserQuestion` with these 4 questions in a single call:
+
+```json
+{"questions": [
+  {"question": "Visual style?", "header": "Style", "multiSelect": false, "options": [
+    {"label": "Photorealistic (Recommended)", "description": "Professional photography, 8K"},
+    {"label": "Cinematic", "description": "Film-like, dramatic lighting"},
+    {"label": "Illustration", "description": "Digital art, stylized"},
+    {"label": "Minimalist", "description": "Clean, white space"}
+  ]},
+  {"question": "Mood?", "header": "Mood", "multiSelect": false, "options": [
+    {"label": "Professional", "description": "Corporate, trustworthy"},
+    {"label": "Energetic", "description": "Dynamic, bold"},
+    {"label": "Calm", "description": "Peaceful, serene"},
+    {"label": "Dramatic", "description": "High contrast, intense"}
+  ]},
+  {"question": "Colors?", "header": "Colors", "multiSelect": false, "options": [
+    {"label": "Auto-select (Recommended)", "description": "AI chooses"},
+    {"label": "Warm tones", "description": "Oranges, reds"},
+    {"label": "Cool tones", "description": "Blues, greens"},
+    {"label": "High contrast", "description": "Blacks, neons"}
+  ]},
+  {"question": "Aspect ratio?", "header": "Ratio", "multiSelect": false, "options": [
+    {"label": "16:9 (Recommended)", "description": "Widescreen"},
+    {"label": "1:1", "description": "Square"},
+    {"label": "9:16", "description": "Vertical"},
+    {"label": "4:3", "description": "Standard"}
+  ]}
+]}
+```
+
+**Dynamic questions** (ask separately if concept matches):
+- "banner/poster/thumbnail" → Ask about text space
+- "product/showcase" → Ask about background preference
+
+## Step 3: Build Prompt
+
+Map answers to keywords:
+
+| Style | Keywords |
+|-------|----------|
+| Photorealistic | photorealistic, professional photography, 8K, RAW |
+| Cinematic | cinematic, film still, anamorphic, dramatic lighting |
+| Illustration | digital illustration, artistic, stylized |
+| Minimalist | minimalist, clean design, white space |
+
+| Mood | Keywords |
+|------|----------|
+| Professional | professional, clean, corporate, polished |
+| Energetic | dynamic, bold, vibrant, high energy |
+| Calm | serene, peaceful, soft, tranquil |
+| Dramatic | dramatic, high contrast, intense, moody |
+
+| Colors | Keywords |
+|--------|----------|
+| Auto-select | (none) |
+| Warm tones | warm palette, golden tones, amber |
+| Cool tones | cool palette, blue tones, teal |
+| High contrast | high contrast, bold blacks, neon |
+
+**Template:** `[concept], [style], [mood], [colors]. Professional quality. NEVER add watermarks.`
+
+## Step 4: Confirm & Generate
+
+Show preview, then ask confirmation:
+
+```json
+{"questions": [{"question": "Generate?", "header": "Confirm", "multiSelect": false, "options": [
+  {"label": "Yes, generate (Recommended)", "description": "Proceed"},
+  {"label": "Edit prompt", "description": "Modify first"},
+  {"label": "Start over", "description": "Re-answer"}
+]}]}
+```
+
+**If "Edit prompt":** Ask user for edited text, use that instead.
+**If "Start over":** Return to Step 2.
+
+Run generation:
+```bash
+cd .claude/skills/ai-artist && .venv/bin/python3 scripts/generate.py "[concept]" \
+  -o ./generated-$(date +%Y%m%d-%H%M%S).png \
+  --mode [mode] \
+  -ar [ratio] \
+  -v
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| API key missing | Tell user to set GEMINI_API_KEY |
+| Model error | Suggest `--model flash` |
+| No concept | Ask user for concept |
+
+## Output
+
+```
+[OK] Image generated: [path]
+    Style: [style] | Mood: [mood] | Aspect: [ratio]
+
+Tip: Use --skip to bypass interview next time.
+```

package/templates/skills/ai-artist/scripts/core.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+AI Artist Core - BM25 search engine for prompt engineering resources
+"""
+
+import csv
+import re
+from pathlib import Path
+from math import log
+from collections import defaultdict
+
+# ============ CONFIGURATION ============
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAX_RESULTS = 3
+
+CSV_CONFIG = {
+    "use-case": {
+        "file": "use-cases.csv",
+        "search_cols": ["Use Case", "Category", "Keywords", "Best Platforms"],
+        "output_cols": ["Use Case", "Category", "Keywords", "Prompt Template", "Key Elements", "Best Platforms", "Aspect Ratios", "Tips", "Example"]
+    },
+    "style": {
+        "file": "styles.csv",
+        "search_cols": ["Style Name", "Category", "Keywords", "Description", "Best For"],
+        "output_cols": ["Style Name", "Category", "Description", "Key Characteristics", "Color Palette", "Best For", "Platforms", "Prompt Keywords"]
+    },
+    "platform": {
+        "file": "platforms.csv",
+        "search_cols": ["Platform", "Type", "Keywords", "Strengths"],
+        "output_cols": ["Platform", "Type", "Prompt Style", "Key Parameters", "Strengths", "Limitations", "Aspect Ratios", "Best Practices"]
+    },
+    "technique": {
+        "file": "techniques.csv",
+        "search_cols": ["Technique", "Category", "Keywords", "Description", "When to Use"],
+        "output_cols": ["Technique", "Category", "Description", "When to Use", "Syntax Example", "Platforms", "Tips"]
+    },
+    "lighting": {
+        "file": "lighting.csv",
+        "search_cols": ["Lighting Type", "Category", "Keywords", "Description", "Mood", "Best For"],
+        "output_cols": ["Lighting Type", "Category", "Description", "Mood", "Best For", "Prompt Keywords", "Technical Notes"]
+    },
+    "template": {
+        "file": "nano-banana-templates.csv",
+        "search_cols": ["Category", "Template Name", "Keywords"],
+        "output_cols": ["Category", "Template Name", "Keywords", "Prompt Template", "Aspect Ratio", "Tips"]
+    },
+    "awesome": {
+        "file": "awesome-prompts.csv",
+        "search_cols": ["title", "description", "prompt"],
+        "output_cols": ["id", "title", "category", "description", "prompt", "author", "source"]
+    }
+}
+
+
+# ============ BM25 IMPLEMENTATION ============
+class BM25:
+    """BM25 ranking algorithm for text search"""
+
+    def __init__(self, k1=1.5, b=0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus = []
+        self.doc_lengths = []
+        self.avgdl = 0
+        self.idf = {}
+        self.doc_freqs = defaultdict(int)
+        self.N = 0
+
+    def tokenize(self, text):
+        """Lowercase, split, remove punctuation, filter short words"""
+        text = re.sub(r'[^\w\s]', ' ', str(text).lower())
+        return [w for w in text.split() if len(w) > 2]
+
+    def fit(self, documents):
+        """Build BM25 index from documents"""
+        self.corpus = [self.tokenize(doc) for doc in documents]
+        self.N = len(self.corpus)
+        if self.N == 0:
+            return
+        self.doc_lengths = [len(doc) for doc in self.corpus]
+        self.avgdl = sum(self.doc_lengths) / self.N
+
+        for doc in self.corpus:
+            seen = set()
+            for word in doc:
+                if word not in seen:
+                    self.doc_freqs[word] += 1
+                    seen.add(word)
+
+        for word, freq in self.doc_freqs.items():
+            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+    def score(self, query):
+        """Score all documents against query"""
+        query_tokens = self.tokenize(query)
+        scores = []
+
+        for idx, doc in enumerate(self.corpus):
+            score = 0
+            doc_len = self.doc_lengths[idx]
+            term_freqs = defaultdict(int)
+            for word in doc:
+                term_freqs[word] += 1
+
+            for token in query_tokens:
+                if token in self.idf:
+                    tf = term_freqs[token]
+                    idf = self.idf[token]
+                    numerator = tf * (self.k1 + 1)
+                    denominator = tf + self.k1 * (1 - self.b + self.b * doc_len / self.avgdl)
+                    score += idf * numerator / denominator
+
+            scores.append((idx, score))
+
+        return sorted(scores, key=lambda x: x[1], reverse=True)
+
+
+# ============ SEARCH FUNCTIONS ============
+def _load_csv(filepath):
+    """Load CSV and return list of dicts"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return list(csv.DictReader(f))
+
+
+def _search_csv(filepath, search_cols, output_cols, query, max_results):
+    """Core search function using BM25"""
+    if not filepath.exists():
+        return []
+
+    data = _load_csv(filepath)
+
+    # Build documents from search columns
+    documents = [" ".join(str(row.get(col, "")) for col in search_cols) for row in data]
+
+    # BM25 search
+    bm25 = BM25()
+    bm25.fit(documents)
+    ranked = bm25.score(query)
+
+    # Get top results with score > 0
+    results = []
+    for idx, score in ranked[:max_results]:
+        if score > 0:
+            row = data[idx]
+            results.append({col: row.get(col, "") for col in output_cols if col in row})
+
+    return results
+
+
+def detect_domain(query):
+    """Auto-detect the most relevant domain from query"""
+    query_lower = query.lower()
+
+    domain_keywords = {
+        "use-case": ["avatar", "profile", "thumbnail", "poster", "social", "youtube", "instagram", "marketing", "product", "e-commerce", "infographic", "comic", "game", "app", "web", "header", "banner"],
+        "style": ["style", "aesthetic", "photorealistic", "anime", "manga", "3d", "render", "illustration", "pixel", "watercolor", "oil", "cyberpunk", "vaporwave", "minimalist", "vintage", "retro"],
+        "platform": ["midjourney", "dalle", "dall-e", "stable diffusion", "flux", "nano banana", "gemini", "imagen", "ideogram", "leonardo", "firefly", "platform", "tool"],
+        "technique": ["prompt", "technique", "weight", "emphasis", "negative", "json", "structured", "iteration", "reference", "identity", "multi-panel", "search grounding"],
+        "lighting": ["lighting", "light", "shadow", "golden hour", "blue hour", "rembrandt", "butterfly", "neon", "volumetric", "softbox", "rim light", "studio"]
+    }
+
+    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=scores.get)
+    return best if scores[best] > 0 else "style"
+
+
+def search(query, domain=None, max_results=MAX_RESULTS):
+    """Main search function with auto-domain detection"""
+    if domain is None:
+        domain = detect_domain(query)
+
+    config = CSV_CONFIG.get(domain, CSV_CONFIG["style"])
+    filepath = DATA_DIR / config["file"]
+
+    if not filepath.exists():
+        return {"error": f"File not found: {filepath}", "domain": domain}
+
+    results = _search_csv(filepath, config["search_cols"], config["output_cols"], query, max_results)
+
+    return {
+        "domain": domain,
+        "query": query,
+        "file": config["file"],
+        "count": len(results),
+        "results": results
+    }
+
+
+def search_all_domains(query, max_per_domain=2):
+    """Search across all domains for comprehensive results"""
+    all_results = {}
+    for domain in CSV_CONFIG.keys():
+        result = search(query, domain, max_per_domain)
+        if result.get("count", 0) > 0:
+            all_results[domain] = result
+    return all_results

package/templates/skills/ai-artist/scripts/extract_prompts.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Extract all prompts from awesome-nano-banana-pro-prompts.md into CSV."""
+
+import re
+import csv
+from pathlib import Path
+
+def extract_prompts(md_content: str) -> list[dict]:
+    """Extract all prompts with their metadata."""
+    prompts = []
+
+    # Split by prompt entries (### No. X:)
+    entries = re.split(r'### No\. \d+:', md_content)
+
+    for i, entry in enumerate(entries[1:], 1):  # Skip content before first entry
+        prompt_data = {
+            "id": i,
+            "title": "",
+            "category": "",
+            "description": "",
+            "prompt": "",
+            "author": "",
+            "source": "",
+        }
+
+        # Extract title (first line after split)
+        title_match = re.search(r'^([^\n]+)', entry.strip())
+        if title_match:
+            prompt_data["title"] = title_match.group(1).strip()
+
+        # Extract category from badges
+        categories = re.findall(r'!\[([^\]]+)\]\([^)]+badge[^)]*\)', entry)
+        if categories:
+            # Filter out non-category badges
+            cats = [c for c in categories if c not in ["Featured", "Raycast", "Language-ZH", "Language-EN", "Language-JA"]]
+            prompt_data["category"] = ", ".join(cats[:3]) if cats else ""
+
+        # Extract description
+        desc_match = re.search(r'#### 📖 Description\s*\n\n([^\n#]+)', entry)
+        if desc_match:
+            prompt_data["description"] = desc_match.group(1).strip()
+
+        # Extract prompt (between ``` markers after "#### 📝 Prompt")
+        prompt_section = re.search(r'#### 📝 Prompt\s*\n\n```[^\n]*\n(.*?)```', entry, re.DOTALL)
+        if prompt_section:
+            prompt_data["prompt"] = prompt_section.group(1).strip()
+
+        # Extract author
+        author_match = re.search(r'\*\*Author:\*\*\s*\[([^\]]+)\]', entry)
+        if author_match:
+            prompt_data["author"] = author_match.group(1).strip()
+
+        # Extract source URL
+        source_match = re.search(r'\*\*Source:\*\*\s*\[([^\]]+)\]\(([^)]+)\)', entry)
+        if source_match:
+            prompt_data["source"] = source_match.group(2).strip()
+
+        if prompt_data["prompt"]:  # Only add if we found a prompt
+            prompts.append(prompt_data)
+
+    return prompts
+
+
+def save_to_csv(prompts: list[dict], output_path: Path):
+    """Save prompts to CSV file."""
+    fieldnames = ["id", "title", "category", "description", "prompt", "author", "source"]
+
+    with open(output_path, 'w', newline='', encoding='utf-8') as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames, quoting=csv.QUOTE_ALL)
+        writer.writeheader()
+        for p in prompts:
+            writer.writerow(p)
+
+    print(f"Saved {len(prompts)} prompts to {output_path}")
+
+
+def main():
+    script_dir = Path(__file__).parent
+    md_path = script_dir.parent / "references" / "awesome-nano-banana-pro-prompts.md"
+    csv_path = script_dir.parent / "data" / "awesome-prompts.csv"
+
+    print(f"Reading from: {md_path}")
+
+    with open(md_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    prompts = extract_prompts(content)
+    print(f"Extracted {len(prompts)} prompts")
+
+    # Print sample
+    if prompts:
+        print("\nSample prompts:")
+        for p in prompts[:3]:
+            print(f"\n[{p['id']}] {p['title'][:50]}...")
+            print(f"  Category: {p['category']}")
+            print(f"  Prompt: {p['prompt'][:100]}...")
+
+    save_to_csv(prompts, csv_path)
+
+
+if __name__ == "__main__":
+    main()