conectese 0.1.14

package/skills/conectese-skill-creator/scripts/run_eval.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Run trigger evaluation for a skill description.
+
+Tests whether a skill's description causes Claude to trigger (read the skill)
+for a set of queries. Outputs results as JSON.
+"""
+
+import argparse
+import json
+import os
+import select
+import subprocess
+import sys
+import time
+import uuid
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+from scripts.utils import parse_skill_md
+
+
+def find_project_root() -> Path:
+    """Find the project root by walking up from cwd looking for .claude/.
+
+    Mimics how Claude Code discovers its project root, so the command file
+    we create ends up where claude -p will look for it.
+    """
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        if (parent / ".claude").is_dir():
+            return parent
+    return current
+
+
+def run_single_query(
+    query: str,
+    skill_name: str,
+    skill_description: str,
+    timeout: int,
+    project_root: str,
+    model: str | None = None,
+) -> bool:
+    """Run a single query and return whether the skill was triggered.
+
+    Creates a command file in .claude/commands/ so it appears in Claude's
+    available_skills list, then runs `claude -p` with the raw query.
+    Uses --include-partial-messages to detect triggering early from
+    stream events (content_block_start) rather than waiting for the
+    full assistant message, which only arrives after tool execution.
+    """
+    unique_id = uuid.uuid4().hex[:8]
+    clean_name = f"{skill_name}-skill-{unique_id}"
+    project_commands_dir = Path(project_root) / ".claude" / "commands"
+    command_file = project_commands_dir / f"{clean_name}.md"
+
+    try:
+        project_commands_dir.mkdir(parents=True, exist_ok=True)
+        # Use YAML block scalar to avoid breaking on quotes in description
+        indented_desc = "\n  ".join(skill_description.split("\n"))
+        command_content = (
+            f"---\n"
+            f"description: |\n"
+            f"  {indented_desc}\n"
+            f"---\n\n"
+            f"# {skill_name}\n\n"
+            f"This skill handles: {skill_description}\n"
+        )
+        command_file.write_text(command_content)
+
+        cmd = [
+            "claude",
+            "-p", query,
+            "--output-format", "stream-json",
+            "--verbose",
+            "--include-partial-messages",
+        ]
+        if model:
+            cmd.extend(["--model", model])
+
+        # Remove CLAUDECODE env var to allow nesting claude -p inside a
+        # Claude Code session. The guard is for interactive terminal conflicts;
+        # programmatic subprocess usage is safe.
+        env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+
+        process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            cwd=project_root,
+            env=env,
+        )
+
+        triggered = False
+        start_time = time.time()
+        buffer = ""
+        # Track state for stream event detection
+        pending_tool_name = None
+        accumulated_json = ""
+
+        try:
+            while time.time() - start_time < timeout:
+                if process.poll() is not None:
+                    remaining = process.stdout.read()
+                    if remaining:
+                        buffer += remaining.decode("utf-8", errors="replace")
+                    break
+
+                ready, _, _ = select.select([process.stdout], [], [], 1.0)
+                if not ready:
+                    continue
+
+                chunk = os.read(process.stdout.fileno(), 8192)
+                if not chunk:
+                    break
+                buffer += chunk.decode("utf-8", errors="replace")
+
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    try:
+                        event = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    # Early detection via stream events
+                    if event.get("type") == "stream_event":
+                        se = event.get("event", {})
+                        se_type = se.get("type", "")
+
+                        if se_type == "content_block_start":
+                            cb = se.get("content_block", {})
+                            if cb.get("type") == "tool_use":
+                                tool_name = cb.get("name", "")
+                                if tool_name in ("Skill", "Read"):
+                                    pending_tool_name = tool_name
+                                    accumulated_json = ""
+                                else:
+                                    return False
+
+                        elif se_type == "content_block_delta" and pending_tool_name:
+                            delta = se.get("delta", {})
+                            if delta.get("type") == "input_json_delta":
+                                accumulated_json += delta.get("partial_json", "")
+                                if clean_name in accumulated_json:
+                                    return True
+
+                        elif se_type in ("content_block_stop", "message_stop"):
+                            if pending_tool_name:
+                                return clean_name in accumulated_json
+                            if se_type == "message_stop":
+                                return False
+
+                    # Fallback: full assistant message
+                    elif event.get("type") == "assistant":
+                        message = event.get("message", {})
+                        for content_item in message.get("content", []):
+                            if content_item.get("type") != "tool_use":
+                                continue
+                            tool_name = content_item.get("name", "")
+                            tool_input = content_item.get("input", {})
+                            if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
+                                triggered = True
+                            elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
+                                triggered = True
+                            return triggered
+
+                    elif event.get("type") == "result":
+                        return triggered
+        finally:
+            # Clean up process on any exit path (return, exception, timeout)
+            if process.poll() is None:
+                process.kill()
+                process.wait()
+
+        return triggered
+    finally:
+        if command_file.exists():
+            command_file.unlink()
+
+
+def run_eval(
+    eval_set: list[dict],
+    skill_name: str,
+    description: str,
+    num_workers: int,
+    timeout: int,
+    project_root: Path,
+    runs_per_query: int = 1,
+    trigger_threshold: float = 0.5,
+    model: str | None = None,
+) -> dict:
+    """Run the full eval set and return results."""
+    results = []
+
+    with ProcessPoolExecutor(max_workers=num_workers) as executor:
+        future_to_info = {}
+        for item in eval_set:
+            for run_idx in range(runs_per_query):
+                future = executor.submit(
+                    run_single_query,
+                    item["query"],
+                    skill_name,
+                    description,
+                    timeout,
+                    str(project_root),
+                    model,
+                )
+                future_to_info[future] = (item, run_idx)
+
+        query_triggers: dict[str, list[bool]] = {}
+        query_items: dict[str, dict] = {}
+        for future in as_completed(future_to_info):
+            item, _ = future_to_info[future]
+            query = item["query"]
+            query_items[query] = item
+            if query not in query_triggers:
+                query_triggers[query] = []
+            try:
+                query_triggers[query].append(future.result())
+            except Exception as e:
+                print(f"Warning: query failed: {e}", file=sys.stderr)
+                query_triggers[query].append(False)
+
+    for query, triggers in query_triggers.items():
+        item = query_items[query]
+        trigger_rate = sum(triggers) / len(triggers)
+        should_trigger = item["should_trigger"]
+        if should_trigger:
+            did_pass = trigger_rate >= trigger_threshold
+        else:
+            did_pass = trigger_rate < trigger_threshold
+        results.append({
+            "query": query,
+            "should_trigger": should_trigger,
+            "trigger_rate": trigger_rate,
+            "triggers": sum(triggers),
+            "runs": len(triggers),
+            "pass": did_pass,
+        })
+
+    passed = sum(1 for r in results if r["pass"])
+    total = len(results)
+
+    return {
+        "skill_name": skill_name,
+        "description": description,
+        "results": results,
+        "summary": {
+            "total": total,
+            "passed": passed,
+            "failed": total - passed,
+        },
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--description", default=None, help="Override description to test")
+    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
+    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
+    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
+    parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
+    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text())
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, original_description, content = parse_skill_md(skill_path)
+    description = args.description or original_description
+    project_root = find_project_root()
+
+    if args.verbose:
+        print(f"Evaluating: {description}", file=sys.stderr)
+
+    output = run_eval(
+        eval_set=eval_set,
+        skill_name=name,
+        description=description,
+        num_workers=args.num_workers,
+        timeout=args.timeout,
+        project_root=project_root,
+        runs_per_query=args.runs_per_query,
+        trigger_threshold=args.trigger_threshold,
+        model=args.model,
+    )
+
+    if args.verbose:
+        summary = output["summary"]
+        print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
+        for r in output["results"]:
+            status = "PASS" if r["pass"] else "FAIL"
+            rate_str = f"{r['triggers']}/{r['runs']}"
+            print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)
+
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/conectese-skill-creator/scripts/utils.py

@@ -0,0 +1,47 @@
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/skills/image-ai-generator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: image-ai-generator
+description: >
+  Generates images via Openrouter API using AI image models.
+  Supports two modes: test (cheap model for iteration) and production (high-quality model for final output).
+  Handles prompt construction, API calls, base64 decoding, and file saving.
+  Supports reference images (logos, mascots) for brand-consistent generation.
+description_pt-BR: >
+  Gera imagens via API do Openrouter usando modelos de IA.
+  Suporta dois modos: test (modelo barato para iteração) e production (modelo de alta qualidade para output final).
+  Cuida da construção de prompts, chamadas de API, decodificação base64 e salvamento de arquivos.
+  Suporta imagens de referência (logos, mascotes) para geração consistente com a marca.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/generate.py
+  runtime: python3
+  invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
+env:
+  - OPENROUTER_API_KEY
+categories: [assets, images, ai, generation]
+---
+
+# Image Generator
+
+## When to use
+
+Use the Image Generator when you need to create visual assets from text prompts. This skill calls the Openrouter API with AI image generation models and saves the resulting images locally.
+
+**IMPORTANT: Think twice before generating images.** Image generation costs money and takes time. Before generating:
+1. Check if a suitable image already exists in the squad's assets folder
+2. Check if a web search could find a free/open image that works
+3. Consider if the image is truly necessary for the content quality
+4. Only generate when no existing alternative is good enough
+5. **Generate only what you need** — never batch-generate "test variations". One image is enough to validate a concept.
+
+## Modes
+
+### Test mode (`--mode test`)
+- **Model:** `sourceful/riverflow-v2-fast`
+- **When to use:** During iteration, testing layouts, checking composition, reviewing concepts
+- **Cost:** ~R$0.01-0.02 per image (very low)
+- **Quality:** Good enough for layout validation, not for final output
+
+### Production mode (`--mode production`)
+- **Model:** `google/gemini-3.1-flash-image-preview`
+- **When to use:** Only when generating the final images that will be published or delivered
+- **Cost:** ~R$0.07-0.10 per image
+- **Quality:** High quality, suitable for social media and publishing
+
+**Default mode is `test`.** Only switch to `production` when the user has approved the layout/composition and you are generating the final deliverable images.
+
+## Instructions
+
+### Single image generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A detailed description of the image to generate" \
+  --output "squads/{squad}/output/{run_id}/assets/image-name.jpg" \
+  --mode test
+```
+
+### With a reference image (logo, mascot, brand asset)
+
+Use `--reference` to send a local image to the model as visual context. The model will incorporate the referenced image (e.g., a logo or mascot) into the generated output.
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A social media banner featuring the company logo prominently in the center" \
+  --output "squads/{squad}/output/{run_id}/assets/banner.jpg" \
+  --reference "squads/{squad}/assets/logo.png" \
+  --mode production
+```
+
+Supported reference formats: PNG, JPEG, WEBP, GIF.
+
+### Batch generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --batch "squads/{squad}/output/{run_id}/assets/batch.json" \
+  --mode production
+```
+
+The batch JSON file should contain:
+```json
+[
+  {"prompt": "Description of image 1", "output": "path/to/image1.jpg"},
+  {"prompt": "Description of image 2", "output": "path/to/image2.jpg"}
+]
+```
+
+Each item can optionally include a `"reference": "path/to/ref.png"` field.
+
+### Prompt guidelines
+
+- Be specific about composition, lighting, style, and mood
+- Specify aspect ratio or orientation when relevant (e.g., "portrait 3:4", "landscape 16:9")
+- Include "hyper realistic, 4K quality" for photographic styles
+- Include "clean composition" to avoid cluttered outputs
+- Avoid requesting text in images — AI models struggle with text rendering
+
+### Cost awareness
+
+- Each production image costs approximately R$0.07-0.10
+- Each test image costs approximately R$0.01-0.02
+- A typical carousel with 8 images costs ~R$0.60-0.80 in production mode
+- **Always use test mode first**, then regenerate only the approved concepts in production mode
+- When testing, generate **1 image only** — not 3, not 5, just 1
+
+## Available operations
+
+- **Single generation** — Generate one image from a text prompt
+- **Batch generation** — Generate multiple images from a JSON batch file
+- **Mode selection** — Choose between test (cheap) and production (high-quality) models
+- **Reference image** — Send a logo/mascot/brand asset as visual context for the generation
+
+## Error handling
+
+- If `OPENROUTER_API_KEY` is not set, the script exits with an error message. Set it in your `.env` file or environment.
+- If the API returns an error, the script prints the error code and body, then exits with code 1.
+- If no image is found in the API response, the script reports which model was used and exits with code 1.
+- For batch mode, partial failures are reported with a success count summary.

package/skills/image-ai-generator/scripts/generate.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Image Generator — Conectese Skill
+Generates images via Openrouter API using AI image models.
+
+Usage:
+  # Single image
+  python3 generate.py --prompt "description" --output "path/to/image.jpg" --mode test
+
+  # Single image with reference (logo/mascot)
+  python3 generate.py --prompt "description" --output "path/to/image.jpg" --reference "path/to/logo.png" --mode production
+
+  # Batch (JSON file with list of {prompt, output} objects)
+  python3 generate.py --batch "path/to/batch.json" --mode production
+"""
+
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+
+# Model configuration per mode
+MODELS = {
+    "test": "sourceful/riverflow-v2-fast",
+    "production": "google/gemini-3.1-flash-image-preview",
+}
+
+API_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+
+def load_api_key():
+    """Load OPENROUTER_API_KEY from environment."""
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        # Try loading from .env in project root
+        env_candidates = [
+            os.path.join(os.getcwd(), ".env"),
+            os.path.join(os.path.dirname(__file__), "..", "..", "..", ".env"),
+        ]
+        for env_path in env_candidates:
+            env_path = os.path.abspath(env_path)
+            if os.path.exists(env_path):
+                with open(env_path, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line.startswith("OPENROUTER_API_KEY=") and not line.startswith("#"):
+                            key = line.split("=", 1)[1].strip().strip('"').strip("'")
+                            break
+                if key:
+                    break
+    if not key:
+        print("ERROR: OPENROUTER_API_KEY not found in environment or .env file", file=sys.stderr)
+        sys.exit(1)
+    return key
+
+
+def generate_image(prompt, output_path, mode, api_key, reference_image=None):
+    """Generate a single image and save to output_path."""
+    model = MODELS.get(mode, MODELS["test"])
+
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+
+    if reference_image and os.path.exists(reference_image):
+        # Multimodal: send reference image + text prompt
+        ext = os.path.splitext(reference_image)[1].lower()
+        mime_map = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif"}
+        mime = mime_map.get(ext, "image/png")
+        with open(reference_image, "rb") as img_f:
+            img_b64 = base64.b64encode(img_f.read()).decode("utf-8")
+        content = [
+            {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{img_b64}"}},
+            {"type": "text", "text": f"Generate an image using the logo/mascot shown in the reference image above. {prompt}. Only output the image, no text."}
+        ]
+    else:
+        content = f"Generate an image: {prompt}. Only output the image, no text."
+
+    payload = json.dumps({
+        "model": model,
+        "messages": [{
+            "role": "user",
+            "content": content
+        }]
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        API_URL,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8", errors="replace")
+        print(f"  API error [{e.code}]: {error_body[:200]}", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"  Request error: {e}", file=sys.stderr)
+        return False
+
+    images = data.get("choices", [{}])[0].get("message", {}).get("images", [])
+    if not images:
+        # Some models return image in content as base64
+        content_resp = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+        if content_resp and isinstance(content_resp, str) and content_resp.startswith("data:image"):
+            img_data = content_resp.split(",", 1)[1] if "," in content_resp else content_resp
+        else:
+            print(f"  No image returned by model {model}", file=sys.stderr)
+            return False
+    else:
+        img_data = images[0].get("image_url", {}).get("url", "")
+        if img_data.startswith("data:"):
+            img_data = img_data.split(",", 1)[1]
+
+    with open(output_path, "wb") as f:
+        f.write(base64.b64decode(img_data))
+
+    size_kb = os.path.getsize(output_path) / 1024
+    print(f"  OK: {output_path} ({size_kb:.0f} KB)")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate images via Openrouter API")
+    parser.add_argument("--prompt", help="Text prompt for single image generation")
+    parser.add_argument("--output", help="Output file path for single image")
+    parser.add_argument("--batch", help="Path to JSON batch file")
+    parser.add_argument("--mode", choices=["test", "production"], default="test",
+                        help="Generation mode: test (cheap) or production (high-quality)")
+    parser.add_argument("--reference", help="Path to reference image to include in the prompt")
+    args = parser.parse_args()
+
+    if not args.prompt and not args.batch:
+        parser.error("Either --prompt or --batch is required")
+
+    api_key = load_api_key()
+    model = MODELS[args.mode]
+    print(f"Image Generator — Mode: {args.mode} | Model: {model}")
+
+    if args.batch:
+        # Batch mode
+        with open(args.batch, "r") as f:
+            items = json.load(f)
+        print(f"Generating {len(items)} images...\n")
+        success = 0
+        for i, item in enumerate(items, 1):
+            prompt = item["prompt"]
+            output = item["output"]
+            ref = item.get("reference")
+            print(f"[{i}/{len(items)}] {os.path.basename(output)}...")
+            if generate_image(prompt, output, args.mode, api_key, reference_image=ref):
+                success += 1
+            if i < len(items):
+                time.sleep(1)  # Rate limiting
+        print(f"\nDone: {success}/{len(items)} images generated.")
+        sys.exit(0 if success == len(items) else 1)
+    else:
+        # Single mode
+        if not args.output:
+            parser.error("--output is required for single image generation")
+        print(f"Generating: {os.path.basename(args.output)}...")
+        ok = generate_image(args.prompt, args.output, args.mode, api_key, reference_image=args.reference)
+        sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()