myaidev-method 0.3.3 → 0.3.5

package/skills/myai-visual-generator/evals/evals.json

@@ -0,0 +1,155 @@
+{
+	"skill_name": "myai-visual-generator",
+	"evals": [
+		{
+			"id": 1,
+			"name": "hero-image-generation",
+			"category": "image",
+			"prompt": "Generate a hero image for my article about Kubernetes horizontal pod autoscaling. Something modern, abstract, with a cloud-native feel. Save it to my project.",
+			"expected_output": "A hero image generated via an AI image service, saved with proper naming and path.",
+			"files": [],
+			"assertions": [
+				"Output mentions using an image generation service (FLUX, Imagen, Gemini, or GPT Image)",
+				"Output includes a file path under content-assets/images/ with a date-based directory",
+				"Output includes markdown embed code using ![alt](path) syntax",
+				"Output includes cost estimation or pricing information for the generation"
+			]
+		},
+		{
+			"id": 2,
+			"name": "article-infographic-pipeline",
+			"category": "infographic",
+			"prompt": "I have an article at ./test-article.md about API design patterns. Analyze it and create infographics for the key concepts - a flowchart for the request lifecycle and an architecture diagram for the gateway pattern.",
+			"expected_output": "Mermaid diagrams rendered for the article's key concepts.",
+			"files": [
+				"test-article.md"
+			],
+			"assertions": [
+				"Output indicates the article was read/analyzed before creating diagrams",
+				"At least 2 diagrams were created (flowchart and architecture/gateway)",
+				"Output mentions Mermaid syntax or .mmd files",
+				"Output includes file paths for the rendered diagram images"
+			]
+		},
+		{
+			"id": 3,
+			"name": "data-infographic-text-accuracy",
+			"category": "infographic",
+			"prompt": "I need a data infographic showing these SaaS metrics: MRR $45K, churn 2.1%, NPS 72, ARR growth 34% YoY. The text and numbers need to be perfectly legible.",
+			"expected_output": "Text-accurate method chosen due to legibility requirement.",
+			"files": [],
+			"assertions": [
+				"Output mentions choosing HTML conversion, Playwright screenshot, or GPT Image due to text accuracy needs",
+				"Output references all 4 metrics (MRR, churn, NPS, ARR growth)",
+				"Output includes a file path for the generated infographic",
+				"Output explains why a text-accurate method was chosen over standard AI generation"
+			]
+		},
+		{
+			"id": 4,
+			"name": "research-visuals",
+			"category": "research",
+			"prompt": "Create a research evaluation comparison chart showing transformer vs LSTM vs Mamba performance across 5 benchmarks: GLUE, SQuAD, WMT, MMLU, and HumanEval. Include accuracy scores and inference speed.",
+			"expected_output": "A data visualization comparing the 3 models across benchmarks.",
+			"files": [],
+			"assertions": [
+				"Output references all 3 models (transformer, LSTM, Mamba)",
+				"Output references at least 4 of the 5 benchmarks",
+				"Output includes a file path for the generated visualization",
+				"Output used a structured data method (HTML conversion, chart library, PaperBanana, or Mermaid)"
+			]
+		},
+		{
+			"id": 5,
+			"name": "missing-api-keys-graceful",
+			"category": "error-handling",
+			"prompt": "Generate a hero image for my blog post about serverless computing.",
+			"expected_output": "Graceful error with instructions on configuring API keys.",
+			"env_override": {
+				"GOOGLE_API_KEY": "",
+				"OPENAI_API_KEY": "",
+				"FAL_KEY": "",
+				"GEMINI_API_KEY": ""
+			},
+			"assertions": [
+				"Output does NOT show a successfully generated image",
+				"Output mentions missing or unconfigured API keys",
+				"Output provides guidance on how to configure keys (referencing .env or configure command)"
+			]
+		},
+		{
+			"id": 6,
+			"name": "ambiguous-prompt-clarification",
+			"category": "routing",
+			"prompt": "Make me a visual.",
+			"expected_output": "Skill asks clarifying questions or presents options before generating.",
+			"files": [],
+			"assertions": [
+				"Output asks what kind of visual (image, video, infographic) OR presents options to choose from",
+				"Output does NOT immediately generate a final image/video without any clarification",
+				"Output asks about the subject matter or purpose of the visual"
+			]
+		},
+		{
+			"id": 7,
+			"name": "html-conversion-for-charts",
+			"category": "infographic",
+			"prompt": "Create a comparison table infographic showing pricing tiers: Starter at $9/mo with 1K API calls, Pro at $49/mo with 50K API calls, Enterprise at $199/mo with unlimited calls. Include exact pricing and feature counts.",
+			"expected_output": "HTML-to-screenshot path used for text-heavy pricing data.",
+			"files": [],
+			"assertions": [
+				"Output mentions using HTML conversion, Playwright, or screenshot-based approach for text accuracy",
+				"Output references all 3 pricing tiers (Starter $9, Pro $49, Enterprise $199)",
+				"Output includes a file path for the generated infographic"
+			]
+		},
+		{
+			"id": 8,
+			"name": "service-fallback-chain",
+			"category": "routing",
+			"prompt": "Generate an illustration of a distributed microservices mesh using FLUX. High quality, 1792x1024.",
+			"expected_output": "Acknowledges FLUX preference, falls back if unavailable.",
+			"env_override": {
+				"FAL_KEY": ""
+			},
+			"assertions": [
+				"Output acknowledges the user's preference for FLUX",
+				"Output indicates FLUX/fal.ai is unavailable (missing FAL_KEY or connection error)",
+				"Output selects an alternative service (Gemini, Imagen, or GPT Image) as fallback",
+				"Output includes a file path for the generated image"
+			]
+		},
+		{
+			"id": 9,
+			"name": "standalone-mermaid-diagram",
+			"category": "infographic",
+			"prompt": "Create a sequence diagram showing OAuth 2.0 authorization code flow between Client, Auth Server, and Resource Server. Include all the standard steps.",
+			"expected_output": "Mermaid sequence diagram rendered with OAuth flow.",
+			"files": [],
+			"assertions": [
+				"Output uses Mermaid diagram approach (mentions Mermaid, sequenceDiagram, or .mmd)",
+				"Output references all 3 participants (Client, Auth Server, Resource Server)",
+				"Output includes standard OAuth steps (authorization, token exchange, resource access)",
+				"Output includes a file path for the rendered diagram image"
+			]
+		}
+	],
+	"trigger_evals": {
+		"should_trigger": [
+			"I need a thumbnail for my YouTube video about React hooks",
+			"Create a diagram showing our database schema",
+			"Generate an image for my blog header",
+			"Make me an architecture diagram of our microservices",
+			"I want a visual showing the CI/CD pipeline flow",
+			"Create a video walkthrough of the dashboard"
+		],
+		"should_not_trigger": [
+			"Can you update my spreadsheet with the latest sales figures?",
+			"Help me write CSS to style my image gallery",
+			"Fix the broken image link in my README",
+			"I need to resize an existing photo",
+			"Add alt text to all images in my HTML",
+			"Convert my PNG files to WebP format"
+		]
+	}
+}

package/skills/myai-visual-generator/references/infographic-pipeline.md

@@ -0,0 +1,73 @@
+# Infographic Pipeline Reference
+
+## Article-Aware Infographic Generation
+
+When input is a markdown article file, run this pipeline:
+
+1. **Analyze**: Read the article and identify sections suitable for diagrams
+2. **Design**: Create Mermaid diagram source for each opportunity
+3. **Render**: Use Mermaid CLI (`mmdc`) to render PNGs
+4. **Insert**: Add `![alt](path)` references back into the article
+5. **Save**: Put assets in `assets/` directory near the article
+
+## Infographic Types
+
+### Quick Mode (default choices)
+- `flowchart` — Decision trees, processes
+- `sequence-diagram` — API/service interactions
+
+### Full Mode (when user requests richer output)
+- `infographic-data` — Statistics, metrics, charts
+- `infographic-process` — Step flows, workflows
+- `infographic-comparison` — Side-by-side comparisons
+- `infographic-timeline` — Chronological events
+- `architecture-diagram` — System design, tech stacks
+
+Ask quick-mode choices first. Only present the full set if the user asks for something beyond flowchart/sequence-diagram.
+
+## Mermaid Rendering Configuration
+
+Always use this config with `mmdc`:
+
+```json
+{
+  "flowchart": {
+    "htmlLabels": false,
+    "useMaxWidth": false
+  },
+  "sequence": {
+    "useMaxWidth": false
+  },
+  "gantt": {
+    "useMaxWidth": false
+  },
+  "theme": "default"
+}
+```
+
+Key rules:
+- `htmlLabels: false` — prevents rendering issues in non-browser contexts
+- `useMaxWidth: false` — ensures diagrams render at natural size
+- Default to `png` format for compatibility; use `svg` only when explicitly requested
+- Validate rendered output exists and is >1KB before inserting references
+
+## Pipeline Output Format
+
+When running as part of the content-writer pipeline, return:
+
+```
+INFOGRAPHICS COMPLETE
+article: .content-session/draft.md
+diagrams_created: {count}
+diagrams_attempted: {count}
+assets_dir: {path}
+```
+
+## Defaults
+
+| Setting | Default |
+|---------|---------|
+| Style | modern |
+| Theme | default |
+| Format | png |
+| Max diagrams | 8 |

package/skills/myai-visual-generator/references/research-visuals.md

@@ -0,0 +1,57 @@
+# Research Visuals Reference (PaperBanana Integration)
+
+Use this subcategory for publication-style academic visuals.
+
+## Research Visual Types
+
+| Type | Description | Tool |
+|------|-------------|------|
+| `research-diagram` | Methodology/framework diagram from research text | `paperbanana generate` |
+| `research-plot` | Statistical plot from CSV/JSON data | `paperbanana plot` |
+| `research-evaluation` | Compare generated diagram vs reference | `paperbanana evaluate` |
+
+## Prerequisites
+
+- Python 3.10+
+- `pip install paperbanana`
+- `GOOGLE_API_KEY` configured (required for default Gemini pipeline)
+- Optional: `paperbanana setup` for local config
+
+## Required User Inputs (minimum questions)
+
+### research-diagram (minimum required)
+1. Source context text (methodology description)
+2. Figure caption / communicative intent
+
+Defaults (do not ask unless needed):
+- Style: `clean academic`
+- Iterations: `3`
+- Output path: auto-generated
+
+### research-plot (minimum required)
+1. Data file path (`.csv` or `.json`)
+2. Plot intent (what comparison/story the chart should convey)
+
+Defaults (do not ask unless needed):
+- Style constraints: none
+- Iterations: `3`
+- Output path: auto-generated
+
+### research-evaluation (required)
+1. Generated diagram path
+2. Human reference diagram path
+3. Source context text path
+4. Figure caption / intent
+
+## CLI Commands
+
+```bash
+# Generate methodology diagram
+paperbanana generate --context "methodology text" --caption "Figure 1: System overview"
+
+# Generate statistical plot
+paperbanana plot --data data.csv --intent "Compare latency across regions"
+
+# Evaluate diagram quality
+paperbanana evaluate --generated gen.png --reference ref.png --context ctx.txt --caption "Fig 1"
+```

package/skills/myai-visual-generator/references/services.md

@@ -0,0 +1,89 @@
+# Visual Generation Services Reference
+
+## Service Catalog
+
+### SOTA Recommended Models
+
+| Service | Type | Cost | Best For | API Key |
+|---------|------|------|----------|---------|
+| Gemini 3.0 Pro Image ("Nano Banana") | Image | $0.02 | Fast, diagrams, general use | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
+| GPT Image 1.5 | Image | $0.02-$0.19 | Best text rendering, highest quality | `OPENAI_API_KEY` |
+
+### Additional Models
+
+| Service | Type | Cost | Best For | API Key |
+|---------|------|------|----------|---------|
+| Imagen 3 | Image | $0.03 | Premium quality heroes | `GEMINI_API_KEY` |
+| GPT Image 1 | Image | $0.19 | High quality images | `OPENAI_API_KEY` |
+| GPT Image 1 Mini | Image | $0.02 | Budget option, high volume | `OPENAI_API_KEY` |
+| Nano Banana Pro | Image | $0.15 | High-quality branded visuals | `FAL_KEY` |
+| FLUX 2 Pro | Image | $0.05 | Detailed illustrations, multi-ref | `FAL_KEY` |
+| FLUX 2 Flex | Image | $0.04 | Developer-controlled params | `FAL_KEY` |
+| FLUX 2 Dev | Image | $0.025 | 32B open-weight model | `FAL_KEY` |
+| Veo 3 | Video | $0.40/sec | Product demos, tutorials | `FAL_KEY` |
+
+### GPT Image 1.5 Quality Tiers
+
+| Quality | Cost | Tokens |
+|---------|------|--------|
+| low | $0.02 | ~272 |
+| medium | $0.07 | ~1056 |
+| high | $0.19 | ~4160 |
+
+## Service Selection Logic
+
+Route based on visual type and text requirements:
+
+| Scenario | Recommended Service |
+|----------|-------------------|
+| Hero image, artistic | FLUX 2 Pro or Imagen |
+| Text-heavy visuals (exact numbers, labels) | GPT Image 1.5 or HTML Conversion |
+| Fast/cheap general image | Gemini 3.0 Pro Image |
+| Technical diagrams | Gemini or Mermaid render path |
+| Video content | Veo 3 |
+| Specialized models | fal.ai MCP discovery |
+
+### HTML Conversion Alternative
+
+For data-driven visuals requiring pixel-perfect text accuracy, use HTML-to-screenshot instead of AI generation:
+
+| Use Case | Tool |
+|----------|------|
+| Exact numbers/data | HTML Conversion (Playwright) |
+| Precise text labels | HTML/D2 Conversion |
+| Charts and graphs | HTML Conversion |
+| Creative/artistic | AI Generation |
+
+When text fidelity is critical and the user explicitly says "perfectly legible" or similar, prefer HTML conversion even when AI services are available.
+
+## fal.ai MCP Tools (When FAL_KEY is configured)
+
+The fal.ai MCP server provides capabilities beyond the built-in SDK:
+
+| Tool | Purpose |
+|------|---------|
+| Model search/discovery | Find specialized models across 600+ fal.ai models |
+| Schema inspection | Understand model parameters before generation |
+| Real-time pricing | Accurate cost estimation from live pricing data |
+| File upload | Upload reference images to fal.ai CDN for FLUX 2 multi-ref |
+| Request status/cancel | Monitor or cancel long-running generation requests |
+
+### When to Use MCP vs SDK
+
+| Scenario | Approach |
+|----------|----------|
+| Standard generation (FLUX 2, Veo 3) | SDK (`visual-generation-utils.js`) |
+| Discover new/specialized models | MCP (model search tools) |
+| Check real-time pricing | MCP (pricing tools) |
+| Upload reference images for multi-ref | MCP (upload tool) then SDK |
+| Generate with non-standard fal.ai models | MCP (generate/result tools) |
+| Cancel or monitor long-running requests | MCP (status/cancel tools) |
+
+## Budget Defaults
+
+- Daily budget: $5.00 (`VISUAL_DAILY_BUDGET`)
+- Monthly budget: $50.00 (`VISUAL_MONTHLY_BUDGET`)
+
+## API Key Priority
+
+The SDK supports both `GEMINI_API_KEY` (preferred) and `GOOGLE_API_KEY` (legacy). See `validateAPIKeys()` in the bundled script for the full resolution logic.