diff --git a/optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py b/optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py new file mode 100644 index 0000000000000000000000000000000000000000..be2a95d5f993744c5512b8b0dbc8eb884d5c10ef --- /dev/null +++ b/optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py @@ -0,0 +1,1660 @@ +#!/usr/bin/env python3 +""" +Hyperliquid CLI Tool for Hermes Agent +------------------------------------- +Queries the Hyperliquid info endpoint for market and account data. +Uses only Python standard library - no external packages required. + +Usage: + python3 hyperliquid_client.py dexs + python3 hyperliquid_client.py markets [--dex DEX] [--limit N] + python3 hyperliquid_client.py spots [--limit N] + python3 hyperliquid_client.py candles [--interval 1h] [--hours 24] + python3 hyperliquid_client.py funding [--hours 72] + python3 hyperliquid_client.py l2 [--levels 10] + python3 hyperliquid_client.py state [address] [--dex DEX] + python3 hyperliquid_client.py spot-balances [address] + python3 hyperliquid_client.py fills [address] [--hours N] [--limit N] + python3 hyperliquid_client.py orders [address] [--limit N] + python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N] + python3 hyperliquid_client.py export [--interval 1h] [--hours N] + +Environment: + HYPERLIQUID_API_URL Override API base URL + (default: https://api.hyperliquid.xyz) + HYPERLIQUID_USER_ADDRESS Default address for state/fills/orders/review commands +""" + +from __future__ import annotations + +import argparse +import datetime as dt +import json +import os +import sys +import time +import urllib.error +import urllib.request +from collections import Counter +from pathlib import Path +from typing import Any, Dict, Iterable, List, Optional + + +USER_AGENT = "HermesAgent/1.0" +DEFAULT_USER_ENV = "HYPERLIQUID_USER_ADDRESS" +DEFAULT_API_BASE = "https://api.hyperliquid.xyz" + + +def _hermes_home() -> Path: + return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser() + + +def _dotenv_paths() -> List[Path]: + paths: List[Path] = [] + project_env = Path.cwd() / ".env" + if project_env.exists(): + paths.append(project_env) + + user_env = _hermes_home() / ".env" + if user_env.exists(): + paths.append(user_env) + + return paths + + +def _load_dotenv_values() -> Dict[str, str]: + values: Dict[str, str] = {} + for env_path in _dotenv_paths(): + try: + lines = env_path.read_text(encoding="utf-8").splitlines() + except UnicodeDecodeError: + lines = env_path.read_text(encoding="latin-1").splitlines() + + for raw_line in lines: + line = raw_line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + key, _, value = raw_line.partition("=") + key = key.strip() + value = value.strip() + if value.startswith('"') and value.endswith('"') and len(value) >= 2: + value = value[1:-1].replace('\\"', '"').replace('\\\\', '\\') + values[key] = value + return values + + +def _env_lookup(key: str, default: str = "") -> str: + value = os.environ.get(key, "").strip() + if value: + return value + dotenv_value = _load_dotenv_values().get(key, "").strip() + if dotenv_value: + return dotenv_value + return default + + +def _api_base() -> str: + return _env_lookup("HYPERLIQUID_API_URL", DEFAULT_API_BASE).rstrip("/") + + +def _info_url() -> str: + api_base = _api_base() + if api_base.endswith("/info"): + return api_base + return f"{api_base}/info" + + +def _resolve_user(user: Optional[str]) -> str: + candidate = (user or "").strip() + if candidate: + return candidate + + env_value = _env_lookup(DEFAULT_USER_ENV, "") + if env_value: + return env_value + + sys.exit( + "Missing Hyperliquid address. Pass
explicitly or set " + f"{DEFAULT_USER_ENV} in your environment or {_hermes_home() / '.env'}." + ) + + +def _post_info(payload: Dict[str, Any], timeout: int = 20, retries: int = 2) -> Any: + data = json.dumps(payload).encode("utf-8") + headers = { + "Content-Type": "application/json", + "Accept": "application/json", + "User-Agent": USER_AGENT, + } + + for attempt in range(retries + 1): + request = urllib.request.Request(_info_url(), data=data, headers=headers, method="POST") + try: + with urllib.request.urlopen(request, timeout=timeout) as response: + body = json.load(response) + return body + except urllib.error.HTTPError as exc: + if exc.code == 429 and attempt < retries: + time.sleep(1.5 * (attempt + 1)) + continue + sys.exit(f"Hyperliquid HTTP error: {exc}") + except urllib.error.URLError as exc: + sys.exit(f"Hyperliquid connection error: {exc}") + except json.JSONDecodeError as exc: + sys.exit(f"Hyperliquid response was not valid JSON: {exc}") + + return None + + +def _safe_float(value: Any) -> Optional[float]: + try: + if value is None or value == "": + return None + return float(value) + except (TypeError, ValueError): + return None + + +def _limit_items(items: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]: + if limit <= 0: + return items + return items[:limit] + + +def _hours_ago_ms(hours: float, now_ms: Optional[int] = None) -> int: + end_ms = now_ms if now_ms is not None else int(time.time() * 1000) + return end_ms - int(hours * 60 * 60 * 1000) + + +def _format_timestamp_ms(value: Any) -> str: + try: + ts_ms = int(value) + except (TypeError, ValueError): + return "-" + return dt.datetime.utcfromtimestamp(ts_ms / 1000).strftime("%Y-%m-%d %H:%M:%S UTC") + + +def _compact_number(value: Any, decimals: int = 2) -> str: + number = _safe_float(value) + if number is None: + return "-" + sign = "-" if number < 0 else "" + number = abs(number) + if number >= 1_000_000_000: + return f"{sign}{number / 1_000_000_000:.{decimals}f}B" + if number >= 1_000_000: + return f"{sign}{number / 1_000_000:.{decimals}f}M" + if number >= 1_000: + return f"{sign}{number / 1_000:.{decimals}f}K" + if number >= 100: + return f"{sign}{number:.2f}" + if number >= 1: + return f"{sign}{number:.4f}".rstrip("0").rstrip(".") + return f"{sign}{number:.6f}".rstrip("0").rstrip(".") + + +def _format_price(value: Any) -> str: + number = _safe_float(value) + if number is None: + return "-" + if abs(number) >= 1000: + return f"{number:,.2f}" + if abs(number) >= 1: + return f"{number:,.4f}".rstrip("0").rstrip(".") + return f"{number:,.6f}".rstrip("0").rstrip(".") + + +def _format_percent(value: Any, decimals: int = 2) -> str: + number = _safe_float(value) + if number is None: + return "-" + return f"{number:+.{decimals}f}%" + + +def _format_fraction_percent(value: Any, decimals: int = 4) -> str: + number = _safe_float(value) + if number is None: + return "-" + return f"{number * 100:+.{decimals}f}%" + + +def _percent_change(current: Any, previous: Any) -> Optional[float]: + curr = _safe_float(current) + prev = _safe_float(previous) + if curr is None or prev is None or prev == 0: + return None + return ((curr - prev) / prev) * 100 + + +def _short_address(address: Any) -> str: + if not isinstance(address, str) or len(address) < 12: + return str(address) + return f"{address[:6]}...{address[-4:]}" + + +def _render_table(headers: List[tuple[str, str]], rows: List[Dict[str, Any]]) -> str: + if not rows: + return "(no data)" + + prepared_rows: List[List[str]] = [] + widths = [len(label) for label, _ in headers] + + for row in rows: + rendered = [] + for index, (_label, key) in enumerate(headers): + value = row.get(key, "") + text = str(value) + rendered.append(text) + if len(text) > widths[index]: + widths[index] = len(text) + prepared_rows.append(rendered) + + lines = [] + header_line = " ".join(label.ljust(widths[idx]) for idx, (label, _key) in enumerate(headers)) + separator = " ".join("-" * widths[idx] for idx in range(len(headers))) + lines.extend([header_line, separator]) + + for rendered in prepared_rows: + lines.append(" ".join(rendered[idx].ljust(widths[idx]) for idx in range(len(rendered)))) + return "\n".join(lines) + + +def _normalize_dexs(payload: Any) -> List[Dict[str, Any]]: + rows: List[Dict[str, Any]] = [] + if not isinstance(payload, list): + return rows + + for index, item in enumerate(payload): + if item is None: + rows.append( + { + "index": index, + "name": "", + "label": "first-perp-dex", + "full_name": "First perp dex", + "deployer": "-", + "asset_caps": 0, + } + ) + continue + + if not isinstance(item, dict): + continue + + caps = item.get("assetToStreamingOiCap") or [] + rows.append( + { + "index": index, + "name": item.get("name", ""), + "label": item.get("name") or "first-perp-dex", + "full_name": item.get("fullName") or "-", + "deployer": item.get("deployer") or "-", + "asset_caps": len(caps) if isinstance(caps, list) else 0, + } + ) + return rows + + +def _normalize_perp_markets(payload: Any) -> List[Dict[str, Any]]: + if not isinstance(payload, list) or len(payload) < 2: + return [] + + meta = payload[0] if isinstance(payload[0], dict) else {} + ctxs = payload[1] if isinstance(payload[1], list) else [] + universe = meta.get("universe") if isinstance(meta, dict) else [] + if not isinstance(universe, list): + return [] + + rows: List[Dict[str, Any]] = [] + for index, spec in enumerate(universe): + if not isinstance(spec, dict): + continue + ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {} + mark_px = ctx.get("markPx") or ctx.get("midPx") or ctx.get("oraclePx") + row = { + "coin": spec.get("name", f"asset-{index}"), + "mark_px": mark_px, + "mid_px": ctx.get("midPx"), + "oracle_px": ctx.get("oraclePx"), + "prev_day_px": ctx.get("prevDayPx"), + "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")), + "funding": ctx.get("funding"), + "premium": ctx.get("premium"), + "open_interest": ctx.get("openInterest"), + "day_ntl_vlm": ctx.get("dayNtlVlm"), + "day_base_vlm": ctx.get("dayBaseVlm"), + "max_leverage": spec.get("maxLeverage"), + "sz_decimals": spec.get("szDecimals"), + "is_delisted": bool(spec.get("isDelisted")), + "only_isolated": bool(spec.get("onlyIsolated")), + "margin_mode": spec.get("marginMode") or "-", + } + rows.append(row) + return rows + + +def _normalize_spot_markets(payload: Any) -> List[Dict[str, Any]]: + if not isinstance(payload, list) or len(payload) < 2: + return [] + + meta = payload[0] if isinstance(payload[0], dict) else {} + ctxs = payload[1] if isinstance(payload[1], list) else [] + pairs = meta.get("universe") if isinstance(meta, dict) else [] + tokens = meta.get("tokens") if isinstance(meta, dict) else [] + token_lookup = {} + if isinstance(tokens, list): + for token in tokens: + if isinstance(token, dict) and "index" in token: + token_lookup[token["index"]] = token.get("name", str(token["index"])) + + rows: List[Dict[str, Any]] = [] + if not isinstance(pairs, list): + return rows + + for index, pair in enumerate(pairs): + if not isinstance(pair, dict): + continue + ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {} + raw_name = pair.get("name", f"@{index}") + tokens_for_pair = pair.get("tokens") if isinstance(pair.get("tokens"), list) else [] + display_name = raw_name + if "/" not in raw_name and len(tokens_for_pair) == 2: + base = token_lookup.get(tokens_for_pair[0], str(tokens_for_pair[0])) + quote = token_lookup.get(tokens_for_pair[1], str(tokens_for_pair[1])) + display_name = f"{base}/{quote} ({raw_name})" + + mark_px = ctx.get("markPx") or ctx.get("midPx") + rows.append( + { + "pair": raw_name, + "display_name": display_name, + "mark_px": mark_px, + "mid_px": ctx.get("midPx"), + "prev_day_px": ctx.get("prevDayPx"), + "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")), + "day_ntl_vlm": ctx.get("dayNtlVlm"), + } + ) + return rows + + +def _normalize_candles(payload: Any) -> List[Dict[str, Any]]: + rows: List[Dict[str, Any]] = [] + if not isinstance(payload, list): + return rows + + for candle in payload: + if not isinstance(candle, dict): + continue + rows.append( + { + "time": candle.get("t") or candle.get("time"), + "open": candle.get("o"), + "high": candle.get("h"), + "low": candle.get("l"), + "close": candle.get("c"), + "volume": candle.get("v"), + "trades": candle.get("n"), + } + ) + + rows.sort(key=lambda item: int(item.get("time") or 0)) + return rows + + +def _normalize_funding_history(payload: Any) -> List[Dict[str, Any]]: + rows: List[Dict[str, Any]] = [] + if not isinstance(payload, list): + return rows + + for item in payload: + if not isinstance(item, dict): + continue + rows.append( + { + "coin": item.get("coin", "-"), + "funding_rate": item.get("fundingRate"), + "premium": item.get("premium"), + "time": item.get("time"), + } + ) + + rows.sort(key=lambda item: int(item.get("time") or 0)) + return rows + + +def _normalize_book_levels(payload: Any) -> Dict[str, List[Dict[str, Any]]]: + if not isinstance(payload, dict): + return {"bids": [], "asks": []} + + levels = payload.get("levels") + if not isinstance(levels, list) or len(levels) < 2: + return {"bids": [], "asks": []} + + def convert(side: Iterable[Any]) -> List[Dict[str, Any]]: + converted = [] + for entry in side: + if isinstance(entry, dict): + converted.append( + { + "px": entry.get("px"), + "sz": entry.get("sz"), + "orders": entry.get("n"), + } + ) + elif isinstance(entry, (list, tuple)) and len(entry) >= 2: + converted.append( + { + "px": entry[0], + "sz": entry[1], + "orders": entry[2] if len(entry) > 2 else None, + } + ) + return converted + + return {"bids": convert(levels[0]), "asks": convert(levels[1])} + + +def _normalize_positions(payload: Any) -> Dict[str, Any]: + if not isinstance(payload, dict): + return {"summary": {}, "positions": []} + + positions: List[Dict[str, Any]] = [] + for item in payload.get("assetPositions", []): + if not isinstance(item, dict): + continue + position = item.get("position") if isinstance(item.get("position"), dict) else item + if not isinstance(position, dict): + continue + leverage = position.get("leverage") if isinstance(position.get("leverage"), dict) else {} + positions.append( + { + "coin": position.get("coin", "-"), + "size": position.get("szi"), + "entry_px": position.get("entryPx"), + "position_value": position.get("positionValue"), + "unrealized_pnl": position.get("unrealizedPnl"), + "return_on_equity": position.get("returnOnEquity"), + "liquidation_px": position.get("liquidationPx"), + "margin_used": position.get("marginUsed"), + "leverage": leverage.get("value"), + "leverage_type": leverage.get("type"), + } + ) + + positions.sort( + key=lambda item: abs(_safe_float(item.get("position_value")) or 0.0), + reverse=True, + ) + + summary = payload.get("marginSummary") if isinstance(payload.get("marginSummary"), dict) else {} + cross_summary = ( + payload.get("crossMarginSummary") if isinstance(payload.get("crossMarginSummary"), dict) else {} + ) + + return { + "summary": { + "account_value": summary.get("accountValue"), + "total_ntl_pos": summary.get("totalNtlPos"), + "total_raw_usd": summary.get("totalRawUsd"), + "withdrawable": payload.get("withdrawable"), + "cross_account_value": cross_summary.get("accountValue"), + }, + "positions": positions, + } + + +def _normalize_spot_balances(payload: Any) -> List[Dict[str, Any]]: + if not isinstance(payload, dict): + return [] + + rows: List[Dict[str, Any]] = [] + for item in payload.get("balances", []): + if not isinstance(item, dict): + continue + rows.append( + { + "coin": item.get("coin", item.get("token", "-")), + "total": item.get("total"), + "hold": item.get("hold"), + "entry_ntl": item.get("entryNtl"), + } + ) + + rows.sort(key=lambda item: abs(_safe_float(item.get("entry_ntl")) or 0.0), reverse=True) + return rows + + +def _normalize_fills(payload: Any) -> List[Dict[str, Any]]: + rows: List[Dict[str, Any]] = [] + if not isinstance(payload, list): + return rows + + for item in payload: + if not isinstance(item, dict): + continue + fill = item.get("fill") if isinstance(item.get("fill"), dict) else item + rows.append( + { + "coin": fill.get("coin", "-"), + "dir": fill.get("dir") or fill.get("side") or "-", + "px": fill.get("px"), + "sz": fill.get("sz"), + "closed_pnl": fill.get("closedPnl"), + "fee": fill.get("fee"), + "fee_token": fill.get("feeToken"), + "start_position": fill.get("startPosition"), + "time": fill.get("time"), + "hash": fill.get("hash"), + "oid": fill.get("oid"), + "twap_id": item.get("twapId"), + } + ) + + rows.sort(key=lambda item: int(item.get("time") or 0), reverse=True) + return rows + + +def _normalize_orders(payload: Any) -> List[Dict[str, Any]]: + rows: List[Dict[str, Any]] = [] + if not isinstance(payload, list): + return rows + + for item in payload: + if not isinstance(item, dict): + continue + order = item.get("order") if isinstance(item.get("order"), dict) else item + rows.append( + { + "coin": order.get("coin", "-"), + "side": order.get("side", "-"), + "limit_px": order.get("limitPx") or order.get("px"), + "size": order.get("sz") or order.get("origSz"), + "timestamp": item.get("statusTimestamp") + or order.get("timestamp") + or order.get("time"), + "status": item.get("status") or order.get("status") or "-", + "oid": order.get("oid"), + "order_type": order.get("orderType") or "-", + } + ) + + rows.sort(key=lambda item: int(item.get("timestamp") or 0), reverse=True) + return rows + + +def _direction_bucket(direction: Any) -> str: + text = str(direction or "").strip().lower() + if "open" in text and "long" in text: + return "open_long" + if "close" in text and "long" in text: + return "close_long" + if "open" in text and "short" in text: + return "open_short" + if "close" in text and "short" in text: + return "close_short" + if text in {"b", "buy"}: + return "buy" + if text in {"s", "sell"}: + return "sell" + return "other" + + +def _average(values: Iterable[Optional[float]]) -> Optional[float]: + clean_values = [value for value in values if value is not None] + if not clean_values: + return None + return round(sum(clean_values) / len(clean_values), 12) + + +def _is_spot_coin(coin: str) -> bool: + return "/" in coin or coin.startswith("@") + + +def _safe_info_query(payload: Dict[str, Any]) -> Any: + try: + return _post_info(payload) + except SystemExit: + return None + + +def _market_context_for_coin(coin: str, interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]: + candles = _normalize_candles( + _safe_info_query( + { + "type": "candleSnapshot", + "req": { + "coin": coin, + "interval": interval, + "startTime": start_ms, + "endTime": end_ms, + }, + } + ) + ) + funding_history: List[Dict[str, Any]] = [] + if not _is_spot_coin(coin): + funding_history = _normalize_funding_history( + _safe_info_query( + { + "type": "fundingHistory", + "coin": coin, + "startTime": start_ms, + "endTime": end_ms, + } + ) + ) + + candle_change = None + if candles: + candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open")) + + funding_average = _average(_safe_float(item.get("funding_rate")) for item in funding_history) + return { + "coin": coin, + "interval": interval, + "candle_count": len(candles), + "price_change_pct": candle_change, + "window_open": candles[0].get("open") if candles else None, + "window_close": candles[-1].get("close") if candles else None, + "average_funding_rate": funding_average, + "funding_samples": len(funding_history), + } + + +def _build_coin_review(coin: str, fills: List[Dict[str, Any]], interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]: + pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills] + fee_values = [_safe_float(fill.get("fee")) for fill in fills] + scored = [value for value in pnl_values if value is not None] + wins = [value for value in scored if value > 0] + losses = [value for value in scored if value < 0] + breakeven = [value for value in scored if value == 0] + + direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills) + market_context = _market_context_for_coin(coin, interval, start_ms, end_ms) + total_pnl = sum(value for value in pnl_values if value is not None) + total_fees = sum(value for value in fee_values if value is not None) + net_after_fees = total_pnl - total_fees + + if direction_counts["open_long"] > direction_counts["open_short"]: + open_bias = "long" + elif direction_counts["open_short"] > direction_counts["open_long"]: + open_bias = "short" + elif direction_counts["open_long"] or direction_counts["open_short"]: + open_bias = "mixed" + else: + open_bias = "none" + + return { + "coin": coin, + "fill_count": len(fills), + "realized_pnl": total_pnl, + "total_fees": total_fees, + "net_after_fees": net_after_fees, + "wins": len(wins), + "losses": len(losses), + "breakeven": len(breakeven), + "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None, + "open_long_count": direction_counts["open_long"], + "open_short_count": direction_counts["open_short"], + "close_long_count": direction_counts["close_long"], + "close_short_count": direction_counts["close_short"], + "open_bias": open_bias, + "market_context": market_context, + } + + +def _review_findings(summary: Dict[str, Any], coin_reviews: List[Dict[str, Any]]) -> List[str]: + findings: List[str] = [] + + if summary["fill_count"] == 0: + return ["No fills were found in the requested review window."] + + if summary["outcome_fill_count"] == 0: + findings.append("Most fills in this window look like opens or adjustments, so realized-outcome review is limited until positions close.") + + if summary["net_after_fees"] < 0: + findings.append( + f"Net realized PnL after fees was negative ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)." + ) + elif summary["net_after_fees"] > 0: + findings.append( + f"Net realized PnL after fees was positive ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)." + ) + + realized_abs = abs(summary["realized_pnl"]) + if summary["total_fees"] > 0: + if realized_abs == 0: + findings.append("Fees were non-trivial while realized PnL stayed flat, which usually means churn without enough edge.") + elif summary["total_fees"] / realized_abs >= 0.25: + ratio_pct = (summary["total_fees"] / realized_abs) * 100 + findings.append(f"Fees consumed about {ratio_pct:.1f}% of absolute realized PnL, so execution efficiency is materially affecting results.") + + if summary["fill_count"] >= 20 and summary["net_after_fees"] < 0: + win_rate = summary.get("win_rate_pct") + if win_rate is None or win_rate < 45: + findings.append("Activity was high relative to results, which suggests overtrading in this review window.") + + if coin_reviews: + worst_coin = min(coin_reviews, key=lambda item: item["net_after_fees"]) + best_coin = max(coin_reviews, key=lambda item: item["net_after_fees"]) + if worst_coin["net_after_fees"] < 0: + findings.append( + f"The weakest coin was {worst_coin['coin']} with net after fees of {_compact_number(worst_coin['net_after_fees'])}." + ) + if best_coin["net_after_fees"] > 0 and best_coin["coin"] != worst_coin["coin"]: + findings.append( + f"The strongest coin was {best_coin['coin']} with net after fees of {_compact_number(best_coin['net_after_fees'])}." + ) + + for item in coin_reviews: + market_change = item["market_context"].get("price_change_pct") + if item["net_after_fees"] >= 0 or market_change is None: + continue + if market_change > 2 and item["open_short_count"] > item["open_long_count"]: + findings.append(f"{item['coin']}: losses came while leaning short into a rising market window.") + elif market_change < -2 and item["open_long_count"] > item["open_short_count"]: + findings.append(f"{item['coin']}: losses came while leaning long into a falling market window.") + + deduped: List[str] = [] + for finding in findings: + if finding not in deduped: + deduped.append(finding) + return deduped[:6] + + +def _recent_fill_rows(fills: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]: + rows = [] + for fill in _limit_items(fills, limit): + rows.append( + { + "time": fill.get("time"), + "coin": fill.get("coin"), + "dir": fill.get("dir"), + "px": fill.get("px"), + "sz": fill.get("sz"), + "closed_pnl": fill.get("closed_pnl"), + "fee": fill.get("fee"), + "fee_token": fill.get("fee_token"), + } + ) + return rows + + +def _coin_slug(coin: str) -> str: + slug = str(coin or "market").strip().lower() + for old, new in (("/", "-"), (":", "-"), ("@", "spot-"), (" ", "-")): + slug = slug.replace(old, new) + return slug or "market" + + +def _default_export_path(coin: str, interval: str, hours: float) -> Path: + hour_label = str(int(hours)) if float(hours).is_integer() else str(hours).replace(".", "p") + filename = f"hyperliquid-{_coin_slug(coin)}-{interval}-{hour_label}h.json" + return Path.cwd() / filename + + +def _write_json_file(path: Path, payload: Dict[str, Any]) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8") + + +def _export_summary(candles: List[Dict[str, Any]], funding_history: List[Dict[str, Any]]) -> Dict[str, Any]: + candle_change = None + if candles: + candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open")) + return { + "candle_count": len(candles), + "funding_count": len(funding_history), + "window_open": candles[0].get("open") if candles else None, + "window_close": candles[-1].get("close") if candles else None, + "price_change_pct": candle_change, + "average_funding_rate": _average(_safe_float(item.get("funding_rate")) for item in funding_history), + } + + +def run_dexs(_args: argparse.Namespace) -> Dict[str, Any]: + payload = _post_info({"type": "perpDexs"}) + rows = _normalize_dexs(payload) + return {"api_url": _info_url(), "count": len(rows), "dexs": rows} + + +def run_markets(args: argparse.Namespace) -> Dict[str, Any]: + payload: Dict[str, Any] = {"type": "metaAndAssetCtxs"} + if args.dex: + payload["dex"] = args.dex + rows = _normalize_perp_markets(_post_info(payload)) + + if args.sort == "name": + rows.sort(key=lambda item: item["coin"]) + elif args.sort == "oi": + rows.sort(key=lambda item: _safe_float(item.get("open_interest")) or 0.0, reverse=True) + elif args.sort == "funding_abs": + rows.sort(key=lambda item: abs(_safe_float(item.get("funding")) or 0.0), reverse=True) + elif args.sort == "change_abs": + rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True) + else: + rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True) + + return { + "dex": args.dex or "", + "count": len(rows), + "sort": args.sort, + "markets": _limit_items(rows, args.limit), + } + + +def run_spots(args: argparse.Namespace) -> Dict[str, Any]: + rows = _normalize_spot_markets(_post_info({"type": "spotMetaAndAssetCtxs"})) + + if args.sort == "name": + rows.sort(key=lambda item: item["display_name"]) + elif args.sort == "change_abs": + rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True) + else: + rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True) + + return {"count": len(rows), "sort": args.sort, "pairs": _limit_items(rows, args.limit)} + + +def run_candles(args: argparse.Namespace) -> Dict[str, Any]: + end_ms = int(time.time() * 1000) + start_ms = _hours_ago_ms(args.hours, end_ms) + payload = { + "type": "candleSnapshot", + "req": { + "coin": args.coin, + "interval": args.interval, + "startTime": start_ms, + "endTime": end_ms, + }, + } + candles = _normalize_candles(_post_info(payload)) + summary = {} + if candles: + highs = [_safe_float(item.get("high")) for item in candles] + lows = [_safe_float(item.get("low")) for item in candles] + clean_highs = [value for value in highs if value is not None] + clean_lows = [value for value in lows if value is not None] + summary = { + "first_time": candles[0]["time"], + "last_time": candles[-1]["time"], + "open": candles[0]["open"], + "close": candles[-1]["close"], + "high": max(clean_highs) if clean_highs else None, + "low": min(clean_lows) if clean_lows else None, + "change_pct": _percent_change(candles[-1]["close"], candles[0]["open"]), + } + return { + "coin": args.coin, + "interval": args.interval, + "hours": args.hours, + "count": len(candles), + "summary": summary, + "candles": _limit_items(candles, args.limit), + } + + +def run_funding(args: argparse.Namespace) -> Dict[str, Any]: + end_ms = int(time.time() * 1000) + start_ms = _hours_ago_ms(args.hours, end_ms) + payload = {"type": "fundingHistory", "coin": args.coin, "startTime": start_ms, "endTime": end_ms} + rows = _normalize_funding_history(_post_info(payload)) + avg_rate = None + if rows: + values = [_safe_float(item.get("funding_rate")) for item in rows] + clean_values = [value for value in values if value is not None] + if clean_values: + avg_rate = sum(clean_values) / len(clean_values) + return { + "coin": args.coin, + "hours": args.hours, + "count": len(rows), + "average_funding_rate": avg_rate, + "history": _limit_items(list(reversed(rows)), args.limit), + } + + +def run_l2(args: argparse.Namespace) -> Dict[str, Any]: + payload: Dict[str, Any] = {"type": "l2Book", "coin": args.coin} + if args.n_sig_figs is not None: + payload["nSigFigs"] = args.n_sig_figs + if args.mantissa is not None: + payload["mantissa"] = args.mantissa + raw = _post_info(payload) + levels = _normalize_book_levels(raw) + return { + "coin": args.coin, + "time": raw.get("time") if isinstance(raw, dict) else None, + "bids": _limit_items(levels["bids"], args.levels), + "asks": _limit_items(levels["asks"], args.levels), + } + + +def run_state(args: argparse.Namespace) -> Dict[str, Any]: + user = _resolve_user(args.user) + payload: Dict[str, Any] = {"type": "clearinghouseState", "user": user} + if args.dex: + payload["dex"] = args.dex + normalized = _normalize_positions(_post_info(payload)) + return { + "user": user, + "dex": args.dex or "", + "summary": normalized["summary"], + "positions": normalized["positions"], + } + + +def run_spot_balances(args: argparse.Namespace) -> Dict[str, Any]: + user = _resolve_user(args.user) + payload = {"type": "spotClearinghouseState", "user": user} + rows = _normalize_spot_balances(_post_info(payload)) + return {"user": user, "count": len(rows), "balances": _limit_items(rows, args.limit)} + + +def run_fills(args: argparse.Namespace) -> Dict[str, Any]: + user = _resolve_user(args.user) + payload: Dict[str, Any] = {"user": user} + if args.hours is not None: + payload["type"] = "userFillsByTime" + payload["startTime"] = _hours_ago_ms(args.hours) + else: + payload["type"] = "userFills" + if args.aggregate_by_time: + payload["aggregateByTime"] = True + rows = _normalize_fills(_post_info(payload)) + return { + "user": user, + "hours": args.hours, + "aggregate_by_time": args.aggregate_by_time, + "count": len(rows), + "fills": _limit_items(rows, args.limit), + } + + +def run_orders(args: argparse.Namespace) -> Dict[str, Any]: + user = _resolve_user(args.user) + payload = {"type": "historicalOrders", "user": user} + rows = _normalize_orders(_post_info(payload)) + return {"user": user, "count": len(rows), "orders": _limit_items(rows, args.limit)} + + +def run_review(args: argparse.Namespace) -> Dict[str, Any]: + user = _resolve_user(args.user) + end_ms = int(time.time() * 1000) + start_ms = _hours_ago_ms(args.hours, end_ms) + payload: Dict[str, Any] = {"type": "userFillsByTime", "user": user, "startTime": start_ms} + if args.aggregate_by_time: + payload["aggregateByTime"] = True + + fills = _normalize_fills(_post_info(payload)) + if args.coin: + target = args.coin.lower() + fills = [fill for fill in fills if str(fill.get("coin", "")).lower() == target] + fills = _limit_items(fills, args.fills) + + grouped: Dict[str, List[Dict[str, Any]]] = {} + for fill in fills: + grouped.setdefault(fill.get("coin", "-"), []).append(fill) + + coin_reviews = [ + _build_coin_review(coin, coin_fills, args.interval, start_ms, end_ms) + for coin, coin_fills in sorted(grouped.items(), key=lambda item: len(item[1]), reverse=True) + ] + + pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills] + fee_values = [_safe_float(fill.get("fee")) for fill in fills] + scored = [value for value in pnl_values if value is not None] + wins = [value for value in scored if value > 0] + losses = [value for value in scored if value < 0] + direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills) + total_pnl = sum(value for value in pnl_values if value is not None) + total_fees = sum(value for value in fee_values if value is not None) + + summary = { + "fill_count": len(fills), + "scored_fill_count": len(scored), + "outcome_fill_count": len(wins) + len(losses), + "unique_coins": len(grouped), + "realized_pnl": total_pnl, + "total_fees": total_fees, + "net_after_fees": total_pnl - total_fees, + "wins": len(wins), + "losses": len(losses), + "breakeven": len([value for value in scored if value == 0]), + "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None, + "open_long_count": direction_counts["open_long"], + "open_short_count": direction_counts["open_short"], + "close_long_count": direction_counts["close_long"], + "close_short_count": direction_counts["close_short"], + } + + return { + "user": user, + "coin_filter": args.coin, + "hours": args.hours, + "interval": args.interval, + "fills_requested": args.fills, + "summary": summary, + "findings": _review_findings(summary, coin_reviews), + "coin_reviews": coin_reviews, + "recent_fills": _recent_fill_rows(fills, args.recent), + } + + +def run_export(args: argparse.Namespace) -> Dict[str, Any]: + end_ms = args.end_time_ms if args.end_time_ms is not None else int(time.time() * 1000) + start_ms = _hours_ago_ms(args.hours, end_ms) + + candle_payload = { + "type": "candleSnapshot", + "req": { + "coin": args.coin, + "interval": args.interval, + "startTime": start_ms, + "endTime": end_ms, + }, + } + candles = _normalize_candles(_post_info(candle_payload)) + + funding_history: List[Dict[str, Any]] = [] + if not _is_spot_coin(args.coin): + funding_history = _normalize_funding_history( + _safe_info_query( + { + "type": "fundingHistory", + "coin": args.coin, + "startTime": start_ms, + "endTime": end_ms, + } + ) + ) + + output_path = Path(args.output) if args.output else _default_export_path(args.coin, args.interval, args.hours) + payload = { + "schema_version": "hyperliquid-market-export-v1", + "source": { + "api_url": _info_url(), + "interval": args.interval, + "coin": args.coin, + "market_type": "spot" if _is_spot_coin(args.coin) else "perp", + }, + "window": { + "start_time_ms": start_ms, + "end_time_ms": end_ms, + "hours": args.hours, + }, + "summary": _export_summary(candles, funding_history), + "candles": candles, + "funding_history": funding_history, + } + _write_json_file(output_path, payload) + return { + "coin": args.coin, + "interval": args.interval, + "hours": args.hours, + "output_path": str(output_path), + "summary": payload["summary"], + "schema_version": payload["schema_version"], + } + + +def render_dexs(data: Dict[str, Any]) -> str: + rows = [ + { + "label": item["label"], + "full_name": item["full_name"], + "deployer": _short_address(item["deployer"]), + "asset_caps": item["asset_caps"], + } + for item in data["dexs"] + ] + return "\n".join( + [ + f"API: {data['api_url']}", + f"Perp dexs: {data['count']}", + "", + _render_table( + [ + ("Dex", "label"), + ("Full Name", "full_name"), + ("Deployer", "deployer"), + ("Asset Caps", "asset_caps"), + ], + rows, + ), + ] + ) + + +def render_markets(data: Dict[str, Any]) -> str: + rows = [ + { + "coin": item["coin"], + "mark_px": _format_price(item["mark_px"]), + "change_pct": _format_percent(item["change_pct"]), + "funding": _format_fraction_percent(item["funding"]), + "open_interest": _compact_number(item["open_interest"]), + "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]), + } + for item in data["markets"] + ] + lines = [ + f"Dex: {data['dex'] or 'first-perp-dex'}", + f"Markets returned: {len(data['markets'])} of {data['count']}", + "", + _render_table( + [ + ("Coin", "coin"), + ("Mark", "mark_px"), + ("Chg", "change_pct"), + ("Funding", "funding"), + ("OI", "open_interest"), + ("24h Vol", "day_ntl_vlm"), + ], + rows, + ), + ] + return "\n".join(lines) + + +def render_spots(data: Dict[str, Any]) -> str: + rows = [ + { + "pair": item["display_name"], + "mark_px": _format_price(item["mark_px"]), + "change_pct": _format_percent(item["change_pct"]), + "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]), + } + for item in data["pairs"] + ] + return "\n".join( + [ + f"Spot pairs returned: {len(data['pairs'])} of {data['count']}", + "", + _render_table( + [ + ("Pair", "pair"), + ("Mark", "mark_px"), + ("Chg", "change_pct"), + ("24h Vol", "day_ntl_vlm"), + ], + rows, + ), + ] + ) + + +def render_candles(data: Dict[str, Any]) -> str: + rows = [ + { + "time": _format_timestamp_ms(item["time"]), + "open": _format_price(item["open"]), + "high": _format_price(item["high"]), + "low": _format_price(item["low"]), + "close": _format_price(item["close"]), + "volume": _compact_number(item["volume"]), + } + for item in data["candles"] + ] + summary = data.get("summary") or {} + lines = [ + f"Coin: {data['coin']}", + f"Interval: {data['interval']}", + f"Hours: {data['hours']}", + f"Candles returned: {len(data['candles'])} of {data['count']}", + ] + if summary: + lines.extend( + [ + f"Open -> Close: {_format_price(summary.get('open'))} -> {_format_price(summary.get('close'))}", + f"Range: {_format_price(summary.get('low'))} to {_format_price(summary.get('high'))}", + f"Change: {_format_percent(summary.get('change_pct'))}", + ] + ) + lines.extend( + [ + "", + _render_table( + [ + ("Time", "time"), + ("Open", "open"), + ("High", "high"), + ("Low", "low"), + ("Close", "close"), + ("Volume", "volume"), + ], + rows, + ), + ] + ) + return "\n".join(lines) + + +def render_funding(data: Dict[str, Any]) -> str: + rows = [ + { + "time": _format_timestamp_ms(item["time"]), + "coin": item["coin"], + "funding": _format_fraction_percent(item["funding_rate"]), + "premium": _format_fraction_percent(item["premium"]), + } + for item in data["history"] + ] + lines = [ + f"Coin: {data['coin']}", + f"Hours: {data['hours']}", + f"Entries returned: {len(data['history'])} of {data['count']}", + f"Average funding: {_format_fraction_percent(data['average_funding_rate'])}", + "", + _render_table( + [ + ("Time", "time"), + ("Coin", "coin"), + ("Funding", "funding"), + ("Premium", "premium"), + ], + rows, + ), + ] + return "\n".join(lines) + + +def render_l2(data: Dict[str, Any]) -> str: + bid_rows = [ + {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"} + for item in data["bids"] + ] + ask_rows = [ + {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"} + for item in data["asks"] + ] + lines = [ + f"Coin: {data['coin']}", + f"Book time: {_format_timestamp_ms(data['time'])}", + "", + "Bids", + _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], bid_rows), + "", + "Asks", + _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], ask_rows), + ] + return "\n".join(lines) + + +def render_state(data: Dict[str, Any]) -> str: + summary = data["summary"] + position_rows = [ + { + "coin": item["coin"], + "size": item["size"], + "entry_px": _format_price(item["entry_px"]), + "position_value": _compact_number(item["position_value"]), + "unrealized_pnl": _compact_number(item["unrealized_pnl"]), + "roe": _format_fraction_percent(item["return_on_equity"], 2), + "liq": _format_price(item["liquidation_px"]), + "lev": f"{item['leverage'] or '-'}x", + } + for item in data["positions"] + ] + + lines = [ + f"User: {data['user']}", + f"Dex: {data['dex'] or 'first-perp-dex'}", + f"Account value: {summary.get('account_value') or '-'}", + f"Total notional position: {summary.get('total_ntl_pos') or '-'}", + f"Withdrawable: {summary.get('withdrawable') or '-'}", + f"Positions: {len(data['positions'])}", + ] + if position_rows: + lines.extend( + [ + "", + _render_table( + [ + ("Coin", "coin"), + ("Size", "size"), + ("Entry", "entry_px"), + ("Pos Val", "position_value"), + ("uPnL", "unrealized_pnl"), + ("ROE", "roe"), + ("Liq", "liq"), + ("Lev", "lev"), + ], + position_rows, + ), + ] + ) + return "\n".join(lines) + + +def render_spot_balances(data: Dict[str, Any]) -> str: + rows = [ + { + "coin": item["coin"], + "total": _compact_number(item["total"]), + "hold": _compact_number(item["hold"]), + "entry_ntl": _compact_number(item["entry_ntl"]), + } + for item in data["balances"] + ] + return "\n".join( + [ + f"User: {data['user']}", + f"Balances returned: {len(data['balances'])} of {data['count']}", + "", + _render_table( + [ + ("Coin", "coin"), + ("Total", "total"), + ("Hold", "hold"), + ("Entry Ntl", "entry_ntl"), + ], + rows, + ), + ] + ) + + +def render_fills(data: Dict[str, Any]) -> str: + rows = [ + { + "time": _format_timestamp_ms(item["time"]), + "coin": item["coin"], + "dir": item["dir"], + "px": _format_price(item["px"]), + "sz": _compact_number(item["sz"]), + "closed_pnl": _compact_number(item["closed_pnl"]), + "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(), + } + for item in data["fills"] + ] + lines = [ + f"User: {data['user']}", + f"Aggregate by time: {data['aggregate_by_time']}", + f"Fills returned: {len(data['fills'])} of {data['count']}", + "", + _render_table( + [ + ("Time", "time"), + ("Coin", "coin"), + ("Dir", "dir"), + ("Px", "px"), + ("Sz", "sz"), + ("Closed PnL", "closed_pnl"), + ("Fee", "fee"), + ], + rows, + ), + ] + return "\n".join(lines) + + +def render_orders(data: Dict[str, Any]) -> str: + rows = [ + { + "time": _format_timestamp_ms(item["timestamp"]), + "coin": item["coin"], + "side": item["side"], + "limit_px": _format_price(item["limit_px"]), + "size": _compact_number(item["size"]), + "status": item["status"], + "oid": item["oid"] or "-", + } + for item in data["orders"] + ] + return "\n".join( + [ + f"User: {data['user']}", + f"Orders returned: {len(data['orders'])} of {data['count']}", + "", + _render_table( + [ + ("Time", "time"), + ("Coin", "coin"), + ("Side", "side"), + ("Px", "limit_px"), + ("Sz", "size"), + ("Status", "status"), + ("OID", "oid"), + ], + rows, + ), + ] + ) + + +def render_review(data: Dict[str, Any]) -> str: + summary = data["summary"] + coin_rows = [ + { + "coin": item["coin"], + "fills": item["fill_count"], + "net": _compact_number(item["net_after_fees"]), + "win_rate": _format_percent(item["win_rate_pct"]), + "trend": _format_percent(item["market_context"].get("price_change_pct")), + "funding": _format_fraction_percent(item["market_context"].get("average_funding_rate")), + "bias": item["open_bias"], + } + for item in data["coin_reviews"] + ] + recent_rows = [ + { + "time": _format_timestamp_ms(item["time"]), + "coin": item["coin"], + "dir": item["dir"], + "px": _format_price(item["px"]), + "sz": _compact_number(item["sz"]), + "closed_pnl": _compact_number(item["closed_pnl"]), + "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(), + } + for item in data["recent_fills"] + ] + + lines = [ + f"User: {data['user']}", + f"Review window: {data['hours']} hours", + f"Coin filter: {data['coin_filter'] or 'all traded coins'}", + f"Fills analyzed: {summary['fill_count']}", + f"Unique coins: {summary['unique_coins']}", + f"Realized PnL: {_compact_number(summary['realized_pnl'])}", + f"Fees: {_compact_number(summary['total_fees'])}", + f"Net after fees: {_compact_number(summary['net_after_fees'])}", + f"Win rate: {_format_percent(summary['win_rate_pct'])}", + ] + + if data["findings"]: + lines.extend(["", "Findings"]) + for finding in data["findings"]: + lines.append(f"- {finding}") + + if coin_rows: + lines.extend( + [ + "", + "Coin Breakdown", + _render_table( + [ + ("Coin", "coin"), + ("Fills", "fills"), + ("Net", "net"), + ("Win Rate", "win_rate"), + ("Trend", "trend"), + ("Funding", "funding"), + ("Bias", "bias"), + ], + coin_rows, + ), + ] + ) + + if recent_rows: + lines.extend( + [ + "", + "Recent Fills", + _render_table( + [ + ("Time", "time"), + ("Coin", "coin"), + ("Dir", "dir"), + ("Px", "px"), + ("Sz", "sz"), + ("Closed PnL", "closed_pnl"), + ("Fee", "fee"), + ], + recent_rows, + ), + ] + ) + + return "\n".join(lines) + + +def render_export(data: Dict[str, Any]) -> str: + summary = data["summary"] + return "\n".join( + [ + f"Coin: {data['coin']}", + f"Interval: {data['interval']}", + f"Hours: {data['hours']}", + f"Schema: {data['schema_version']}", + f"Output: {data['output_path']}", + f"Candles: {summary['candle_count']}", + f"Funding samples: {summary['funding_count']}", + f"Window open -> close: {_format_price(summary.get('window_open'))} -> {_format_price(summary.get('window_close'))}", + f"Price change: {_format_percent(summary.get('price_change_pct'))}", + f"Average funding: {_format_fraction_percent(summary.get('average_funding_rate'))}", + ] + ) + + +def _add_json_flag(parser: argparse.ArgumentParser) -> None: + parser.add_argument("--json", action="store_true", help="Print raw JSON output") + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description="Hyperliquid CLI Tool for Hermes Agent") + subparsers = parser.add_subparsers(dest="command", required=True) + + dexs = subparsers.add_parser("dexs", help="List available perpetual dexs") + _add_json_flag(dexs) + dexs.set_defaults(func=run_dexs, renderer=render_dexs) + + markets = subparsers.add_parser("markets", help="List perpetual market contexts") + markets.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex") + markets.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + markets.add_argument( + "--sort", + choices=["volume", "oi", "funding_abs", "change_abs", "name"], + default="volume", + help="Sort mode", + ) + _add_json_flag(markets) + markets.set_defaults(func=run_markets, renderer=render_markets) + + spots = subparsers.add_parser("spots", help="List spot market contexts") + spots.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + spots.add_argument( + "--sort", + choices=["volume", "change_abs", "name"], + default="volume", + help="Sort mode", + ) + _add_json_flag(spots) + spots.set_defaults(func=run_spots, renderer=render_spots) + + candles = subparsers.add_parser("candles", help="Fetch candle history for a market") + candles.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"') + candles.add_argument("--interval", default="1h", help="Candle interval, e.g. 1m, 15m, 1h, 4h, 1d") + candles.add_argument("--hours", type=float, default=24.0, help="Lookback window in hours") + candles.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + _add_json_flag(candles) + candles.set_defaults(func=run_candles, renderer=render_candles) + + funding = subparsers.add_parser("funding", help="Fetch funding history for a perp market") + funding.add_argument("coin", help='Coin name, e.g. "BTC" or "mydex:COIN"') + funding.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours") + funding.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + _add_json_flag(funding) + funding.set_defaults(func=run_funding, renderer=render_funding) + + l2 = subparsers.add_parser("l2", help="Inspect the current L2 book for a market") + l2.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC"') + l2.add_argument("--levels", type=int, default=10, help="Levels per side to display") + l2.add_argument("--n-sig-figs", type=int, default=None, help="Optional server-side book aggregation") + l2.add_argument("--mantissa", type=int, default=None, help="Optional mantissa when using nSigFigs") + _add_json_flag(l2) + l2.set_defaults(func=run_l2, renderer=render_l2) + + state = subparsers.add_parser("state", help="Inspect a user's perp account state") + state.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}") + state.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex") + _add_json_flag(state) + state.set_defaults(func=run_state, renderer=render_state) + + spot_balances = subparsers.add_parser("spot-balances", help="Inspect a user's spot token balances") + spot_balances.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}") + spot_balances.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + _add_json_flag(spot_balances) + spot_balances.set_defaults(func=run_spot_balances, renderer=render_spot_balances) + + fills = subparsers.add_parser("fills", help="Inspect a user's recent fills") + fills.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}") + fills.add_argument("--hours", type=float, default=None, help="Optional time window; uses userFillsByTime") + fills.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + fills.add_argument( + "--aggregate-by-time", + action="store_true", + help="Aggregate partial fills when the API supports it", + ) + _add_json_flag(fills) + fills.set_defaults(func=run_fills, renderer=render_fills) + + orders = subparsers.add_parser("orders", help="Inspect a user's historical orders") + orders.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}") + orders.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all") + _add_json_flag(orders) + orders.set_defaults(func=run_orders, renderer=render_orders) + + review = subparsers.add_parser("review", help="Generate a lightweight post-trade review from recent fills") + review.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}") + review.add_argument("--coin", default="", help="Optional exact coin filter, e.g. BTC or PURR/USDC") + review.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours") + review.add_argument("--fills", type=int, default=50, help="Maximum fills to analyze") + review.add_argument("--recent", type=int, default=10, help="Recent fills to display in the review") + review.add_argument("--interval", default="1h", help="Candle interval for market context") + review.add_argument( + "--aggregate-by-time", + action="store_true", + help="Aggregate partial fills when the API supports it", + ) + _add_json_flag(review) + review.set_defaults(func=run_review, renderer=render_review) + + export = subparsers.add_parser("export", help="Export normalized candles and funding history to a JSON file") + export.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"') + export.add_argument("--interval", default="1h", help="Candle interval for the exported dataset") + export.add_argument("--hours", type=float, default=168.0, help="Lookback window in hours") + export.add_argument("--end-time-ms", type=int, default=None, help="Optional fixed end time for reproducible exports") + export.add_argument("--output", default="", help="Path to the JSON export file") + _add_json_flag(export) + export.set_defaults(func=run_export, renderer=render_export) + + return parser + + +def main(argv: Optional[List[str]] = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + + payload = args.func(args) + if args.json: + print(json.dumps(payload, indent=2)) + else: + print(args.renderer(payload)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/optional-skills/creative/ai-presenter-video/LICENSE b/optional-skills/creative/ai-presenter-video/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..f5be3d70a1274e873026c32c0b1d0052ceb48f0a --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 lanshu + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/optional-skills/creative/ai-presenter-video/SKILL.md b/optional-skills/creative/ai-presenter-video/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..018fd69d0331842fe31ec5333d7a415bad4a3445 --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/SKILL.md @@ -0,0 +1,196 @@ +--- +name: ai-presenter-video +description: "Make a verified AI presenter video from script + image." +version: 1.0.0 +author: cclank (https://github.com/cclank/lanshu-create-ai-presenter-video), ported by Hermes Agent +license: MIT +platforms: [linux, macos] +required_commands: [ffmpeg, ffprobe, python3] +metadata: + hermes: + tags: [video, presenter, avatar, lipsync, tts, captions, creative] + category: creative + homepage: https://github.com/cclank/lanshu-create-ai-presenter-video + related_skills: [hyperframes, kanban-video-orchestrator, comfyui] +--- + +# AI Presenter Video + +Turn a topic (or finished script) plus ONE authorized adult presenter image +into a complete, publish-ready presenter-led video: locked narration, avatar +generation with lip-sync QA, captions, deterministic editing, loudness-normalized +master/share encodes, and machine + visual acceptance reports. + +Use this skill for new presenter videos AND for continuing, revising, +captioning, lip-sync-repairing, or re-exporting an existing presenter-video +job. The workflow is provider-neutral: pick generation capabilities from what +is actually available in the session (FAL video/image models via +`image_generate` and the video-gen plugin, TTS via `text_to_speech`, ASR via +the whisper/STT tooling, ffmpeg for everything deterministic). + +> Ported from cclank/lanshu-create-ai-presenter-video (MIT). Upstream body +> kept substantively verbatim in `references/`; Hermes adaptations live in +> this hub file. Scripts are deterministic (no network, no credentials). + +## Hermes adaptations (read first) + +- **Skill dir resolution** — upstream hardcoded its own agent's skills path. + In Hermes the loader expands `${HERMES_SKILL_DIR}` to this skill's installed + directory, so every command below uses that token directly: + + ```bash + SKILL_DIR="${HERMES_SKILL_DIR}" + ``` + + Shell variables do not persist between tool calls — re-paste the assignment + (or the expanded path) in each terminal call that uses it. +- **Capability mapping** — where the references say "a voice generation + capability", use `text_to_speech` (OpenAI/Edge/ElevenLabs per user config); + "presenter/avatar generation" → FAL image-to-video families (Kling, Wan, + MiniMax H3 etc.) through the configured video tooling, or an avatar/lipsync + endpoint the user has access to; "word-timestamp ASR" → whisper via the STT + tooling or `faster-whisper` in a venv; "deterministic compositor" → ffmpeg + filtergraphs, or the `hyperframes` skill when installed (the editing + reference has a HyperFrames section that maps directly onto it). +- **Visual QA** — do the "normal-speed visual review" steps with + `vision_analyze` on the generated contact sheet plus sampled frames + (identity, mouth timing, hands, blinking, continuity). Numeric checks come + from the scripts' ffprobe output. +- **Paid-generation consent** — remote avatar/TTS generation is billable. + Follow the upstream operating rules: before the first paid call state the + uploaded assets, requested seconds, known cost, pilot size, and retry + ceiling, and get the user's explicit go-ahead. Never upload the presenter + image to a remote provider before `remote_upload_approved` is true in + `job.json`. +- **Consent flags live under `input`** — `rights_confirmed`, + `adult_presenter_confirmed`, `remote_upload_approved`, and + `voice_clone_approved` sit inside the `input` object of `job.json` (init + flags set them; hand-editing must target `input.*`, not the job root). + `manual_input_review.*` sits at the root. `preflight.py` distinguishes + `errors` (block everything) from `remote_blockers` (block only remote + generation) — local script/audio work may proceed while remote is blocked. + +## Workflow + +1. **Start or resume a job.** New job: + + ```bash + python3 "$SKILL_DIR/scripts/init_job.py" \ + --job-dir ~/Videos/my-presenter-video \ + --presenter-image /path/to/presenter.png \ + --topic "explain context engineering in one minute" \ + --duration 60 --aspect 9:16 \ + --rights-confirmed --adult-presenter-confirmed + ``` + + Use `--script` for an existing script file; other flags: `--voice-sample`, + `--supporting-media`, `--width`, `--height`, `--fps`, `--watermark`, + `--cta`. For an existing job, read `job.json` + QA reports and resume from + the earliest unfinished state — never regenerate accepted work. + +2. **Manual input review.** Actually look at the presenter image + (`vision_analyze`) and listen to any voice sample; record findings by + setting the `manual_input_review` booleans in `job.json`, e.g.: + + ```bash + python3 - <<'PY' + import json + p = "~/Videos/my-presenter-video/job.json" # expand ~ or use an absolute path + import os; p = os.path.expanduser(p) + j = json.load(open(p)) + j["manual_input_review"].update(image_viewed=True, single_clear_face=True, + image_has_no_unwanted_text=True) + json.dump(j, open(p, "w"), indent=2) + PY + ``` + + Then gate: + + ```bash + python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json + ``` + + Proceed only when `ok: true`; do remote generation only when + `remote_ready: true`. Note: preflight also updates `job.json` in place + (records the report path) — re-read it after running rather than editing + a stale copy. + +3. **Lock content and audio** — read `references/generation.md`. Script → + full narration via `text_to_speech` → ASR-verify the narration against the + script → record real durations. The locked audio is the master clock for + everything downstream. + +4. **Plan and generate the presenter** — read `references/generation.md`. + Short low-cost pilot first; full run only after the pilot passes identity + and mouth-timing review. + +5. **Edit** — read `references/editing.md`. Deterministic timeline driven by + the locked audio; captions and keyword callouts only after audio and media + are final. + +6. **Verify and deliver** — read `references/qa-recovery.md`, render, then: + + ```bash + bash "$SKILL_DIR/scripts/finalize_delivery.sh" \ + ~/Videos/my-presenter-video/renders/rendered.mp4 \ + ~/Videos/my-presenter-video/outputs my-video + ``` + + The finalizer preserves aspect ratio, runs two-pass loudness normalization + (program ≈ −16 LUFS), produces master + share encodes, decode-verifies + both, writes a delivery report JSON, and emits a nine-frame contact sheet. + Inspect the contact sheet with `vision_analyze` before claiming completion. + +## Operating rules (non-negotiable) + +- Confirm image rights, adult status, remote-upload approval, and + voice-cloning authorization before the relevant remote action. +- Never infer or clone a real person's voice from an image; use an authorized + sample or a stock TTS voice. +- Lock the complete narration before presenter generation, caption timing, or + final scene boundaries. +- Mute video sources in the final composition; only the approved narration + and intentional mix tracks carry audio. +- Preserve provider request bodies and task IDs (minus credentials/expiring + URLs). Poll interrupted work before resubmitting — avoid double billing. +- Stop after three rejected paid candidates and summarize the failure mode. +- Do not claim completion until the final files fully decode and the contact + sheet or full playback has been reviewed. + +## Defaults for minimal input + +9:16, 1080×1920, 30fps; topic-derived videos target 45–75s; stock voice when +no authorized sample; presenter-led layout with hook → 2–4 beats → close; +no music/CTA unless requested; language inferred from the request. + +## Reference routing + +- `references/generation.md` — intake, content, voice, capability selection, + presenter prompts, paid generation, provider changes. +- `references/editing.md` — timeline contract, openings/closes, captions, + keyword-callout presets, HyperFrames composition, exports. +- `references/qa-recovery.md` — technical acceptance, visual acceptance, and + recovery for lip-sync/identity/hands/exposure/freeze/caption/audio faults. + +## Pitfalls + +- `preflight.py` requires ffprobe; on a bare box install ffmpeg first. +- The consent booleans set by init flags land under `input.*`; editing them + at the job-json root silently does nothing (preflight keeps blocking). +- `finalize_delivery.sh` needs bash + jq + awk and a fully decodable input — + a truncated render fails the decode check by design, not by accident. +- Long avatar clips drift: prefer one continuous presenter source sliced on + the audio timeline over many regenerated chapter clips (identity drift + across regenerations is the #1 visual-QA failure). +- FAL i2v endpoints cap duration (typically 5–15s); plan chapter-level + presenter segments accordingly and reuse the pilot's seed/params for + consistency where the endpoint supports it. + +## Verification + +Validated hands-on (Aug 2026): `init_job.py` → `job.json` with correct state +machine; `preflight.py` correctly blocked on unreviewed inputs, flipped to +`ok: true` after review booleans, and kept `remote_ready: false` until +`input.remote_upload_approved`; `finalize_delivery.sh` on a synthetic 5s +1080×1920 render produced decode-verified master (631kbit/s) + share encodes, +delivery-report JSON, and a 9-frame contact sheet, exit 0. diff --git a/optional-skills/creative/ai-presenter-video/assets/job.template.json b/optional-skills/creative/ai-presenter-video/assets/job.template.json new file mode 100644 index 0000000000000000000000000000000000000000..be6ffc3f4d8f8d77970abcebfb6e21bb40695c66 --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/assets/job.template.json @@ -0,0 +1,83 @@ +{ + "schema_version": 1, + "job_id": "replace-me", + "state": "intake", + "mode": "automation", + "input": { + "topic": "", + "script_path": "", + "presenter_image": "", + "voice_sample": "", + "supporting_media": [], + "rights_confirmed": false, + "adult_presenter_confirmed": false, + "remote_upload_approved": false, + "voice_clone_approved": false + }, + "creative": { + "language": "auto", + "audience": "general", + "goal": "explain clearly", + "duration_target_s": 60, + "aspect": "9:16", + "width": 1080, + "height": 1920, + "fps": 30, + "style": "credible contemporary presenter", + "watermark": "", + "cta": "" + }, + "voice": { + "strategy": "auto", + "voice_id": "", + "rate": 1.06, + "segment_lufs": -17, + "program_lufs": -16 + }, + "plan": { + "status": "draft", + "opening_target_s": 4, + "closing_target_s": 5, + "chapters": [], + "requested_generation_seconds": 0, + "estimated_cost": null, + "price_evidence_date": "", + "pilot_approved": false, + "paid_generation_approved": false, + "retry_ceiling": 3 + }, + "capabilities": { + "voice_generation": {}, + "main_presenter": {}, + "short_motion": {}, + "lipsync_repair": {}, + "word_timestamp_asr": {}, + "timeline_compositor": {}, + "encoder_qa": {} + }, + "manual_input_review": { + "image_viewed": false, + "single_clear_face": false, + "image_has_no_unwanted_text": false, + "voice_sample_listened": false, + "single_clear_speaker": false + }, + "artifacts": { + "script": "", + "beat_sheet": "", + "timeline": "", + "storyboard": "", + "final_audio": "", + "caption_json": "", + "rendered": "", + "master": "", + "share": "" + }, + "qa": { + "preflight_report": "", + "asr_report": "", + "composition_report": "", + "delivery_report": "", + "manual_visual_review": "" + } +} diff --git a/optional-skills/creative/ai-presenter-video/references/editing.md b/optional-skills/creative/ai-presenter-video/references/editing.md new file mode 100644 index 0000000000000000000000000000000000000000..0fb74a3d82b71570a54fb0babeb66485bef47593 --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/references/editing.md @@ -0,0 +1,65 @@ +# Editing + +Read this file for the visual plan, deterministic timeline, openings, closes, screen demos, captions, keyword callouts, covers, previews, and exports. + +## Visual routes + +- **Presenter-led:** the presenter carries the explanation; add one concise visual idea per beat. +- **Screen-demo:** preserve real UI readability; introduce the presenter large at chapter starts, then shrink the same continuous video into a verified safe region. +- **Mixed explainer:** assign supporting media only where it proves or clarifies narration. + +Do not fabricate product evidence. Label conceptual visuals clearly. + +## Timeline contract + +The locked narration defines duration and semantic boundaries. Every clip keeps three independent values: + +- authored start in the final video; +- authored duration; +- source-media start. + +When an opening changes length, shift authored starts while preserving presenter source offsets. Keep video sources muted and use approved external narration as the program clock. Prefer one continuous presenter source and source-time slices over regenerated chapter clips. + +Use hard cuts at settled semantic pauses. Add transitions only when they clarify structure. Preserve a quiet tail so the last word, gesture, and mouth position finish naturally. + +## Opening, body, and close + +- Establish the topic and payoff within the first few seconds. +- Design the time-zero frame as a deliberate cover frame. +- Keep opening copy away from eyes, mouth, and the hand-motion path. +- Use the same visual system across the cover, chapters, captions, keywords, progress, and close. +- End with a conclusion or one requested next step. Do not add promotional copy without a brief requirement. + +## Captions + +Generate word timestamps from the final audio. Split into short semantic phrases, normally one readable line. A practical baseline is about `40ms` visual lead and `120ms` tail hold when neighboring phrases allow it. + +Keep captions clear of the face, UI, watermark, progress line, and platform controls. Highlight one meaningful term per phrase. Make entrances and exits quick enough to preserve reading stability. + +## Presenter-side keyword presets + +Use keyword callouts to amplify selected spoken beats. Avoid repeating one identical card throughout the video. + +Rotate a small family of presets such as: + +- radial burst; +- tilted ribbon or sticker; +- hand-drawn circle or marker stroke; +- large/small type contrast; +- staggered word-chip cluster; +- double-layer outline lockup. + +Bind each callout to a real spoken stress or ASR word anchor. Separate the entry timing of the kicker, main word, secondary word, marker, rays, and outline by a few frames. Let the callout settle briefly, then collapse before the next idea. Keep it inside a consistent presenter-side safe region and verify the complete motion path does not cover the face or hands. + +## Composition and preview + +Use a deterministic compositor available in the environment. For HyperFrames: + +1. load the current HyperFrames workflow and domain instructions; +2. give all timed media explicit start, duration, track, and source offset; +3. run the required composition check with representative emphasis and transition samples; +4. inspect time zero, chapter cuts, layout changes, keyword beats, captions, close, and final frame; +5. open the final Studio preview and obtain approval before rendering; +6. render at delivery quality only after approval. + +Measure the assembled stereo program after rendering. Mono narration duplicated into stereo can measure about 3 LU louder, so perform final program normalization from the rendered file. diff --git a/optional-skills/creative/ai-presenter-video/references/generation.md b/optional-skills/creative/ai-presenter-video/references/generation.md new file mode 100644 index 0000000000000000000000000000000000000000..694c5875e19c08026d05e0364a40448f83b21f1d --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/references/generation.md @@ -0,0 +1,83 @@ +# Generation + +Read this file for intake, content, narration, capability selection, paid generation, presenter prompts, or provider changes. + +## Inputs and authorization + +Required: + +- a topic or script; +- one local presenter image with one clear adult face; +- confirmed image rights before remote upload; +- confirmed adult status from the user. + +Optional: + +- authorized voice sample; +- screen recordings, B-roll, images, charts, brand assets, or source links; +- audience, duration, language, aspect, style, watermark, music, CTA, provider preference, or previous episode. + +Inspect the real image. Record visible anchors only: framing, hair, glasses, clothing, accessories, hands, furniture, background geometry, camera height, crop, light, exposure, white balance, embedded text, logos, occlusion, multiple faces, and resolution. Do not infer sensitive traits. + +When a voice sample exists, listen for one speaker, audible speech duration, language, noise, echo, clipping, music, silence, and codec damage. Record whether cloning is authorized. Keep the original unchanged. + +## Content and narration + +For a topic, use one clear spine: + +```text +hook → promise → 2–4 useful beats → synthesis → close +``` + +For a supplied script, preserve factual meaning while improving breath, pronunciation, sentence length, and transitions. Flag material factual edits for approval. + +Generate the complete approved narration before visual work. Keep one voice identity and one synthesis configuration. Split only for operational limits or clean semantic sections. Preserve raw and normalized copies. + +Run ASR against final audio. Review names, numbers, English tokens, omitted words, repeated words, and tail speech. Use actual audio durations for every later cut. + +## Capability routing + +Resolve capabilities at execution time: + +| Capability | Acceptance priority | +|---|---| +| Voice generation | authorization, identity, pronunciation, rate control, clean audio | +| Main presenter | exact audio support, semantic lip sync, identity stability, required duration | +| Short motion | stable face, one controllable gesture, fixed camera, economical retry | +| Lip-sync repair | preserves accepted motion while replacing mouth timing with exact audio | +| Word-timestamp ASR | accurate word start/end times and reviewable output | +| Timeline compositor | explicit source offsets, frame-accurate seek, deterministic render | +| Encoder and QA | local probe, loudness, decode, black-frame and contact-sheet support | + +Inspect current installed tools and official documentation when availability, duration, pricing, or request fields may have changed. Prefer a user-selected provider when it passes the gates. Otherwise choose the simplest available capability that does. + +Record the actual provider, model, version, region, parameters, price evidence date, task ID, and sanitized request body in `job.json`. Ask before a provider change that affects cost, privacy, voice, appearance, or quality. + +## Billing and pilot gate + +Before the first remote or paid call, state: + +- files or data being uploaded; +- capability and selected tool; +- requested seconds or units; +- known price or that the cost is unknown; +- pilot duration and retry ceiling; +- expected output and main risks. + +Generate the smallest useful pilot. Continue to a full run only after technical checks and visual review pass. Do not generate a long clip when the edit uses only a short range. + +## Presenter prompt structure + +Write prompts in this order: + +1. Bind the user image as the sole presenter and scene reference. +2. List only visible identity, clothing, accessory, camera, framing, background, light, exposure, and white-balance anchors. +3. Request realistic skin, hair, eye moisture, fabric, breathing, bilateral blinking, and restrained head motion. +4. Supply exact dialogue through the tool's supported audio or dialogue field. +5. Tie one physically plausible gesture to one phrase and approximate time. +6. Reserve a settled, closed-mouth tail. +7. Exclude identity, face, glasses, hair, wardrobe, skin tone, background, camera, lighting, finger, hand, dialogue, text, logo, watermark, and extra-person drift. + +For the main presenter, prioritize mouth timing and identity. Keep hands low or outside frame. For an opening or close, one small gesture may carry the hook or CTA. Keep hands below the collarbone, away from the face and lens, and end the movement before the tail hold. + +If the body performance is accepted but mouth timing is visibly late, preserve the motion plate and apply lip-sync repair with the exact locked audio and no duration extension. diff --git a/optional-skills/creative/ai-presenter-video/references/qa-recovery.md b/optional-skills/creative/ai-presenter-video/references/qa-recovery.md new file mode 100644 index 0000000000000000000000000000000000000000..00b301be9fc827ab56b8aaf63a5206c6fb83277d --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/references/qa-recovery.md @@ -0,0 +1,73 @@ +# QA and recovery + +Read this file before accepting generated media or delivery, and whenever a production fault appears. + +## Acceptance gates + +### Inputs + +- Topic or script exists. +- Presenter image decodes and contains one reviewed adult face. +- Image rights, adult confirmation, and remote-upload permission are recorded. +- Any voice sample contains one authorized speaker. +- Supporting media is probed and its provenance is recorded. + +### Audio + +- Final ASR matches the intended script once, without material omissions or additions. +- Sections have consistent loudness, commonly near `-17 LUFS`. +- Assembled program loudness is commonly `-16 ± 0.5 LUFS` unless the destination specifies another target. +- No clipped words, doubled tracks, echo, clicks, unexpected silence, or truncated tail. +- Measure the final stereo file; section measurements alone are insufficient. + +### Presenter + +- Expected resolution, frame rate, duration, and decodable streams. +- No black frames, long exact-frame freezes, progressive darkening, or duration extension. +- Identity, face geometry, hair, glasses, clothing, accessories, background, crop, exposure, and white balance remain coherent. +- Mouth follows names, numbers, English tokens, plosives, and phrase endings. +- Blinks are sparse and bilateral; gestures occur once and settle; hands remain plausible and away from the face. +- Tail ends with a settled face and resting mouth. + +### Composition and delivery + +- No flash, duplicate presenter, source-time reset, missing overlay, overflow, face obstruction, caption collision, or unreadable UI. +- Opening, callouts, captions, watermark, progress, and platform safe zones remain compatible. +- Master and share files have the expected duration, dimensions, frame rate, codec, pixel format, and audio rate. +- Both files fully decode. +- Contact sheet covers opening, chapters, emphasis graphics, close, and final frame. +- Watch the complete video at normal speed before delivery. + +## Recovery rules + +### Interrupted remote task + +Poll the saved task ID and download a succeeded result. Resubmit only after a confirmed failure or cancellation. + +### Voice identity or loudness changes + +Confirm one synthesis identity and configuration. Regenerate the mismatching section, normalize again, and rerun ASR. If the final render is louder than the source, confirm video is muted and apply whole-program two-pass loudness correction. + +### Presenter changes between chapters + +Use one continuous audio-driven source with source-time slices. When splitting is unavoidable, lock identity, framing, parameters, light, and quiet edge holds. + +### Body motion works but mouth is late + +Keep the accepted motion plate. Apply lip-sync repair with the exact locked audio and no duration extension. Check speech anchors at numbers, plosives, English tokens, and final syllables. + +### Face, glasses, hands, or light drift + +Retry from the original image with reduced motion and explicit camera, exposure, and white-balance locks. Simplify the gesture and keep hands low. Structural face or finger faults require regeneration; grading cannot correct them. + +### Frozen picture-in-picture + +Confirm the layout uses moving video, source offsets advance continuously, and no poster frame or identical-frame padding replaced the presenter. + +### Captions or keyword graphics feel wrong + +Regenerate timings from the final audio. Split by meaning, shorten visible phrases, and adjust small lead/hold margins. Bind keyword motion to actual spoken anchors and verify its complete path against the face, hands, UI, and captions. + +### Three rejected paid candidates + +Stop. Preserve candidates, prompts, task IDs, cost, and rejection notes. Summarize the recurring failure, remaining options, expected additional cost, and the single variable proposed for the next attempt. diff --git a/optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh b/optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh new file mode 100644 index 0000000000000000000000000000000000000000..063e65606637d971bacded7df7ada17debcbd181 --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh @@ -0,0 +1,166 @@ +#!/usr/bin/env bash + +set -euo pipefail + +usage() { + printf 'Usage: %s rendered.mp4 output-dir output-stem\n' "$(basename "$0")" >&2 +} + +die() { + printf 'ERROR: %s\n' "$*" >&2 + exit 1 +} + +[[ "$#" -eq 3 ]] || { usage; exit 64; } + +INPUT="$1" +OUTPUT_DIR="$2" +STEM="$3" + +[[ -f "$INPUT" && -s "$INPUT" ]] || die "input render is missing or empty: $INPUT" +[[ "$STEM" =~ ^[A-Za-z0-9._-]+$ ]] || die "output stem contains unsupported characters: $STEM" + +for command in ffmpeg ffprobe jq mktemp awk sed; do + command -v "$command" >/dev/null 2>&1 || die "required command unavailable: $command" +done + +mkdir -p "$OUTPUT_DIR" +OUTPUT_DIR="$(cd "$OUTPUT_DIR" && pwd -P)" +INPUT="$(cd "$(dirname "$INPUT")" && pwd -P)/$(basename "$INPUT")" + +MASTER="$OUTPUT_DIR/${STEM}-master.mp4" +SHARE="$OUTPUT_DIR/${STEM}-share.mp4" +REPORT="$OUTPUT_DIR/${STEM}-delivery-report.json" +CONTACT="$OUTPUT_DIR/${STEM}-contact-sheet.png" + +# Keep shared reports portable and avoid exposing the developer machine path. +INPUT_REPORT="$(basename "$INPUT")" +MASTER_REPORT="$(basename "$MASTER")" +SHARE_REPORT="$(basename "$SHARE")" +CONTACT_REPORT="$(basename "$CONTACT")" + +for output in "$MASTER" "$SHARE" "$REPORT" "$CONTACT"; do + [[ ! -e "$output" ]] || die "refusing to overwrite existing output: $output" +done + +TMP_ROOT="${TMPDIR:-/tmp}" +TMP_DIR="$(mktemp -d "${TMP_ROOT%/}/presenter-finalize.XXXXXX")" +trap 'rm -rf -- "$TMP_DIR"' EXIT INT TERM + +STREAM_JSON="$TMP_DIR/source-probe.json" +ffprobe -v error -show_streams -show_format -of json "$INPUT" >"$STREAM_JSON" +jq -e '.streams | any(.codec_type == "video") and any(.codec_type == "audio")' "$STREAM_JSON" >/dev/null \ + || die "input must contain decodable video and audio streams" + +WIDTH="$(jq -r '[.streams[] | select(.codec_type == "video")][0].width' "$STREAM_JSON")" +HEIGHT="$(jq -r '[.streams[] | select(.codec_type == "video")][0].height' "$STREAM_JSON")" +FPS="$(jq -r '[.streams[] | select(.codec_type == "video")][0].avg_frame_rate' "$STREAM_JSON")" +[[ "$FPS" != "0/0" && -n "$FPS" ]] || FPS="30" + +MEASURE_LOG="$TMP_DIR/loudnorm-pass1.log" +ffmpeg -hide_banner -nostdin -nostats -i "$INPUT" \ + -map 0:a:0 -vn \ + -af 'loudnorm=I=-16:TP=-1.5:LRA=9:print_format=json' \ + -f null - >/dev/null 2>"$MEASURE_LOG" + +MEASURE_JSON="$TMP_DIR/measure.json" +sed -n '/^{/,/^}/p' "$MEASURE_LOG" >"$MEASURE_JSON" +jq -e . "$MEASURE_JSON" >/dev/null || die "could not parse loudness measurement" + +MEASURED_I="$(jq -r .input_i "$MEASURE_JSON")" +MEASURED_TP="$(jq -r .input_tp "$MEASURE_JSON")" +MEASURED_LRA="$(jq -r .input_lra "$MEASURE_JSON")" +MEASURED_THRESH="$(jq -r .input_thresh "$MEASURE_JSON")" +OFFSET="$(jq -r .target_offset "$MEASURE_JSON")" + +LOUDNORM="loudnorm=I=-16:TP=-1.5:LRA=9:measured_I=${MEASURED_I}:measured_TP=${MEASURED_TP}:measured_LRA=${MEASURED_LRA}:measured_thresh=${MEASURED_THRESH}:offset=${OFFSET}:linear=true:print_format=summary" +VIDEO_FILTER="scale=trunc(iw/2)*2:trunc(ih/2)*2:flags=lanczos,setsar=1,fps=${FPS},format=yuv420p" + +encode() { + local crf="$1" + local preset="$2" + local audio_bitrate="$3" + local destination="$4" + local temporary="$5" + + ffmpeg -hide_banner -nostdin -loglevel warning -stats -i "$INPUT" \ + -map 0:v:0 -map 0:a:0 -sn -dn \ + -vf "$VIDEO_FILTER" -af "$LOUDNORM" \ + -c:v libx264 -preset "$preset" -crf "$crf" -profile:v high \ + -pix_fmt yuv420p -tag:v avc1 -fps_mode cfr \ + -color_primaries bt709 -color_trc bt709 -colorspace bt709 \ + -c:a aac -b:a "$audio_bitrate" -ar 48000 -ac 2 \ + -map_metadata -1 -map_chapters -1 -movflags +faststart \ + "$temporary" + [[ -s "$temporary" ]] || die "encoder produced an empty output" + mv -- "$temporary" "$destination" +} + +encode 16 slow 256k "$MASTER" "$TMP_DIR/master.mp4" +encode 24 medium 160k "$SHARE" "$TMP_DIR/share.mp4" + +for file in "$MASTER" "$SHARE"; do + ffmpeg -hide_banner -nostdin -v error -xerror -i "$file" \ + -map 0:v:0 -map 0:a:0 -f null - >/dev/null +done + +ffprobe -v error -show_streams -show_format -of json "$MASTER" >"$TMP_DIR/master-probe.json" +ffprobe -v error -show_streams -show_format -of json "$SHARE" >"$TMP_DIR/share-probe.json" + +for probe_file in "$STREAM_JSON" "$TMP_DIR/master-probe.json" "$TMP_DIR/share-probe.json"; do + jq 'if .format.filename? then .format.filename = (.format.filename | split("/") | last) else . end' \ + "$probe_file" >"${probe_file}.portable" + mv -- "${probe_file}.portable" "$probe_file" +done + +ffmpeg -hide_banner -nostdin -i "$MASTER" \ + -vf 'blackdetect=d=0.10:pix_th=0.02' -an -f null - \ + >/dev/null 2>"$TMP_DIR/blackdetect.log" +BLACK_EVENTS="$(grep -c 'black_start:' "$TMP_DIR/blackdetect.log" || true)" + +DURATION="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$MASTER")" +awk -v duration="$DURATION" 'BEGIN { + p[1]=0.2; p[2]=duration*0.125; p[3]=duration*0.25; p[4]=duration*0.375; + p[5]=duration*0.5; p[6]=duration*0.625; p[7]=duration*0.75; + p[8]=duration*0.875; p[9]=duration-0.2; + for(i=1;i<=9;i++) printf "%.6f\n", p[i] +}' >"$TMP_DIR/timestamps.txt" + +if (( WIDTH > HEIGHT )); then + CONTACT_FRAME_FILTER='scale=480:270:force_original_aspect_ratio=decrease:flags=lanczos,pad=480:270:(ow-iw)/2:(oh-ih)/2:color=black' +elif (( HEIGHT > WIDTH )); then + CONTACT_FRAME_FILTER='scale=270:480:force_original_aspect_ratio=decrease:flags=lanczos,pad=270:480:(ow-iw)/2:(oh-ih)/2:color=black' +else + CONTACT_FRAME_FILTER='scale=360:360:force_original_aspect_ratio=decrease:flags=lanczos,pad=360:360:(ow-iw)/2:(oh-ih)/2:color=black' +fi + +index=0 +while IFS= read -r timestamp; do + index=$((index + 1)) + printf -v frame '%s/frame-%02d.png' "$TMP_DIR" "$index" + ffmpeg -hide_banner -nostdin -loglevel error -ss "$timestamp" -i "$MASTER" \ + -frames:v 1 -vf "$CONTACT_FRAME_FILTER" -update 1 "$frame" +done <"$TMP_DIR/timestamps.txt" + +ffmpeg -hide_banner -nostdin -loglevel error -framerate 1 -start_number 1 \ + -i "$TMP_DIR/frame-%02d.png" -frames:v 1 \ + -vf 'tile=3x3:padding=12:margin=12:color=0x101218' -update 1 "$TMP_DIR/contact.png" +mv -- "$TMP_DIR/contact.png" "$CONTACT" + +jq -n \ + --arg status verified \ + --arg input "$INPUT_REPORT" \ + --arg master "$MASTER_REPORT" \ + --arg share "$SHARE_REPORT" \ + --arg contact "$CONTACT_REPORT" \ + --arg duration "$DURATION" \ + --argjson black_events "$BLACK_EVENTS" \ + --slurpfile measured "$MEASURE_JSON" \ + --slurpfile source_probe "$STREAM_JSON" \ + --slurpfile master_probe "$TMP_DIR/master-probe.json" \ + --slurpfile share_probe "$TMP_DIR/share-probe.json" \ + '{status:$status,input:$input,master:$master,share:$share,contact_sheet:$contact,duration_s:($duration|tonumber),source_loudness:$measured[0],source_probe:$source_probe[0],master_probe:$master_probe[0],share_probe:$share_probe[0],full_decode_passed:true,black_frame_events:$black_events}' \ + >"$TMP_DIR/report.json" +mv -- "$TMP_DIR/report.json" "$REPORT" + +printf 'Master: %s\nShare: %s\nReport: %s\nContact: %s\n' "$MASTER" "$SHARE" "$REPORT" "$CONTACT" diff --git a/optional-skills/creative/ai-presenter-video/scripts/init_job.py b/optional-skills/creative/ai-presenter-video/scripts/init_job.py new file mode 100644 index 0000000000000000000000000000000000000000..9fed4f29f0ab8a9e9f71bfbb51fe04500298628f --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/scripts/init_job.py @@ -0,0 +1,151 @@ +#!/usr/bin/env python3 +"""Create a non-overwriting presenter-video job from minimal inputs.""" + +from __future__ import annotations + +import argparse +import json +import re +import sys +from pathlib import Path + + +SKILL_DIR = Path(__file__).resolve().parent.parent +TEMPLATE = SKILL_DIR / "assets" / "job.template.json" +ASPECT_DEFAULTS = { + "9:16": (1080, 1920), + "16:9": (1920, 1080), + "1:1": (1080, 1080), + "4:5": (1080, 1350), +} + + +def absolute_existing(path_text: str, label: str) -> str: + path = Path(path_text).expanduser().resolve() + if not path.is_file(): + raise ValueError(f"{label} does not exist or is not a file: {path}") + return str(path) + + +def slugify(value: str) -> str: + slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-") + return slug or "presenter-video" + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--job-dir", required=True) + parser.add_argument("--presenter-image", required=True) + source = parser.add_mutually_exclusive_group(required=True) + source.add_argument("--topic") + source.add_argument("--script", help="Existing local script file") + parser.add_argument("--voice-sample") + parser.add_argument("--supporting-media", action="append", default=[]) + parser.add_argument("--language", default="auto") + parser.add_argument("--audience", default="general") + parser.add_argument("--duration", type=float, default=60.0) + parser.add_argument("--aspect", choices=sorted(ASPECT_DEFAULTS), default="9:16") + parser.add_argument("--width", type=int) + parser.add_argument("--height", type=int) + parser.add_argument("--fps", type=int, choices=(24, 25, 30, 50, 60), default=30) + parser.add_argument("--style", default="credible contemporary presenter") + parser.add_argument("--watermark", default="") + parser.add_argument("--cta", default="") + parser.add_argument("--rights-confirmed", action="store_true") + parser.add_argument("--adult-presenter-confirmed", action="store_true") + parser.add_argument("--remote-upload-approved", action="store_true") + parser.add_argument("--voice-clone-approved", action="store_true") + return parser.parse_args() + + +def main() -> int: + args = parse_args() + if not 5 <= args.duration <= 1800: + raise ValueError("--duration must be between 5 and 1800 seconds") + if (args.width is None) != (args.height is None): + raise ValueError("--width and --height must be supplied together") + + width, height = ASPECT_DEFAULTS[args.aspect] + if args.width is not None and args.height is not None: + width, height = args.width, args.height + if min(width, height) < 256 or max(width, height) > 7680: + raise ValueError("custom dimensions must be between 256 and 7680 pixels") + + job_dir = Path(args.job_dir).expanduser().resolve() + if job_dir.exists() and any(job_dir.iterdir()): + raise ValueError(f"job directory must be absent or empty: {job_dir}") + job_dir.mkdir(parents=True, exist_ok=True) + + manifest = json.loads(TEMPLATE.read_text(encoding="utf-8")) + manifest["job_id"] = slugify(job_dir.name) + manifest["input"]["topic"] = (args.topic or "").strip() + manifest["input"]["script_path"] = ( + absolute_existing(args.script, "script") if args.script else "" + ) + manifest["input"]["presenter_image"] = absolute_existing( + args.presenter_image, "presenter image" + ) + manifest["input"]["voice_sample"] = ( + absolute_existing(args.voice_sample, "voice sample") + if args.voice_sample + else "" + ) + manifest["input"]["supporting_media"] = [ + absolute_existing(item, "supporting media") for item in args.supporting_media + ] + manifest["input"]["rights_confirmed"] = args.rights_confirmed + manifest["input"]["adult_presenter_confirmed"] = args.adult_presenter_confirmed + manifest["input"]["remote_upload_approved"] = args.remote_upload_approved + manifest["input"]["voice_clone_approved"] = args.voice_clone_approved + + creative = manifest["creative"] + creative.update( + { + "language": args.language, + "audience": args.audience, + "duration_target_s": args.duration, + "aspect": args.aspect, + "width": width, + "height": height, + "fps": args.fps, + "style": args.style, + "watermark": args.watermark, + "cta": args.cta, + } + ) + + directories = [ + "docs", + "assets/source", + "assets/audio/reference", + "assets/audio/raw", + "assets/audio/final", + "assets/video/candidates", + "assets/video/selected", + "assets/video/render", + "assets/captions", + "qa/requests", + "qa/asr", + "qa/contacts", + "qa/reports", + "renders", + "outputs", + ] + for relative in directories: + (job_dir / relative).mkdir(parents=True, exist_ok=True) + + job_path = job_dir / "job.json" + job_path.write_text( + json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + print(json.dumps({"job": str(job_path), "state": "intake"}, ensure_ascii=False)) + return 0 + + +if __name__ == "__main__": + try: + raise SystemExit(main()) + except ValueError as exc: + print(f"ERROR: {exc}", file=sys.stderr) + raise SystemExit(2) diff --git a/optional-skills/creative/ai-presenter-video/scripts/preflight.py b/optional-skills/creative/ai-presenter-video/scripts/preflight.py new file mode 100644 index 0000000000000000000000000000000000000000..ef4905be31afadb4c6e4f5ce815f434083f52690 --- /dev/null +++ b/optional-skills/creative/ai-presenter-video/scripts/preflight.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +"""Validate a presenter-video job and write a machine-readable preflight report.""" + +from __future__ import annotations + +import json +import shutil +import subprocess +import sys +from pathlib import Path +from typing import Any + + +def probe(path: Path) -> dict[str, Any]: + result = subprocess.run( + [ + "ffprobe", + "-v", + "error", + "-show_entries", + "stream=index,codec_type,codec_name,width,height,pix_fmt,sample_rate,channels,r_frame_rate:format=duration,size,bit_rate", + "-of", + "json", + str(path), + ], + check=True, + capture_output=True, + text=True, + ) + return json.loads(result.stdout) + + +def require_file(value: str, label: str, errors: list[str]) -> Path | None: + if not value: + errors.append(f"missing {label}") + return None + path = Path(value).expanduser().resolve() + if not path.is_file(): + errors.append(f"{label} is not a file: {path}") + return None + return path + + +def write_atomic(path: Path, text: str) -> None: + temporary = path.with_suffix(path.suffix + ".tmp") + temporary.write_text(text, encoding="utf-8") + temporary.replace(path) + + +def main() -> int: + if len(sys.argv) != 2: + print("Usage: preflight.py ~/Videos/my-presenter-video/job.json", file=sys.stderr) + return 64 + if not shutil.which("ffprobe"): + print("ERROR: ffprobe is required", file=sys.stderr) + return 2 + + job_path = Path(sys.argv[1]).expanduser().resolve() + if not job_path.is_file(): + print(f"ERROR: job manifest does not exist: {job_path}", file=sys.stderr) + return 2 + job = json.loads(job_path.read_text(encoding="utf-8")) + job_dir = job_path.parent + errors: list[str] = [] + remote_blockers: list[str] = [] + warnings: list[str] = [] + media: dict[str, Any] = {} + + input_data = job.get("input", {}) + topic = str(input_data.get("topic", "")).strip() + script_text = str(input_data.get("script_path", "")).strip() + if not topic and not script_text: + errors.append("topic or script_path is required") + if script_text: + require_file(script_text, "script", errors) + + image = require_file(str(input_data.get("presenter_image", "")), "presenter image", errors) + if image: + try: + media["presenter_image"] = probe(image) + streams = [ + stream + for stream in media["presenter_image"].get("streams", []) + if stream.get("codec_type") == "video" + ] + if not streams: + errors.append("presenter image has no decodable image/video stream") + else: + width = int(streams[0].get("width") or 0) + height = int(streams[0].get("height") or 0) + if min(width, height) < 512: + warnings.append(f"presenter image is low resolution: {width}x{height}") + except (subprocess.CalledProcessError, json.JSONDecodeError) as exc: + errors.append(f"could not decode presenter image: {exc}") + + voice_value = str(input_data.get("voice_sample", "")).strip() + if voice_value: + voice = require_file(voice_value, "voice sample", errors) + if voice: + try: + media["voice_sample"] = probe(voice) + streams = [ + stream + for stream in media["voice_sample"].get("streams", []) + if stream.get("codec_type") == "audio" + ] + if not streams: + errors.append("voice sample has no audio stream") + duration = float(media["voice_sample"].get("format", {}).get("duration") or 0) + if duration < 4: + warnings.append(f"voice sample is short: {duration:.3f}s") + if duration > 60: + warnings.append(f"voice sample is unusually long: {duration:.3f}s") + except (subprocess.CalledProcessError, json.JSONDecodeError, ValueError) as exc: + errors.append(f"could not decode voice sample: {exc}") + if not input_data.get("voice_clone_approved"): + remote_blockers.append("voice_clone_approved must be true before voice cloning") + else: + warnings.append("no voice sample supplied; use and record a stock voice") + + supporting_reports = [] + for value in input_data.get("supporting_media", []): + path = require_file(str(value), "supporting media", errors) + if path: + try: + supporting_reports.append({"file": path.name, "probe": probe(path)}) + except (subprocess.CalledProcessError, json.JSONDecodeError) as exc: + errors.append(f"could not decode supporting media {path}: {exc}") + media["supporting_media"] = supporting_reports + + if not input_data.get("rights_confirmed"): + remote_blockers.append("rights_confirmed must be true before presenter synthesis") + if not input_data.get("adult_presenter_confirmed"): + remote_blockers.append("adult_presenter_confirmed must be true before presenter synthesis") + if not input_data.get("remote_upload_approved"): + remote_blockers.append("remote_upload_approved must be true before remote generation") + + manual = job.get("manual_input_review", {}) + for key in ("image_viewed", "single_clear_face", "image_has_no_unwanted_text"): + if not manual.get(key): + errors.append(f"manual_input_review.{key} must be true") + if voice_value: + for key in ("voice_sample_listened", "single_clear_speaker"): + if not manual.get(key): + errors.append(f"manual_input_review.{key} must be true") + + creative = job.get("creative", {}) + duration = float(creative.get("duration_target_s") or 0) + if not 5 <= duration <= 1800: + errors.append("creative.duration_target_s must be between 5 and 1800") + width = int(creative.get("width") or 0) + height = int(creative.get("height") or 0) + if min(width, height) < 256 or max(width, height) > 7680: + errors.append("creative width/height must be between 256 and 7680") + if int(creative.get("fps") or 0) not in (24, 25, 30, 50, 60): + errors.append("creative.fps must be one of 24, 25, 30, 50, or 60") + + report_path = job_dir / "qa" / "reports" / "preflight.json" + report_path.parent.mkdir(parents=True, exist_ok=True) + report = { + "ok": not errors, + "remote_ready": not errors and not remote_blockers, + "job": job_path.name, + "errors": errors, + "remote_blockers": remote_blockers, + "warnings": warnings, + "media": media, + } + write_atomic(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n") + job.setdefault("qa", {})["preflight_report"] = "qa/reports/preflight.json" + write_atomic(job_path, json.dumps(job, ensure_ascii=False, indent=2) + "\n") + print(json.dumps(report, ensure_ascii=False, indent=2)) + return 0 if not errors else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/optional-skills/creative/archify/SKILL.md b/optional-skills/creative/archify/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..30c67129f468d4ae83631db2d8fc537e05fa740f --- /dev/null +++ b/optional-skills/creative/archify/SKILL.md @@ -0,0 +1,52 @@ +--- +name: archify +description: Validated interactive HTML diagrams, upstream-maintained. +version: 2.17.0 +author: tt-a1i +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [diagram, architecture, workflow, sequence, dataflow, state-machine, mermaid, html, svg] + category: creative + related_skills: [architecture-diagram, excalidraw, concept-diagrams] + upstream: + repo: tt-a1i/archify + path: archify +--- + +# Archify (upstream-maintained) + +> **Catalog stub.** This entry is maintained upstream at +> [tt-a1i/archify](https://github.com/tt-a1i/archify): the project ships a +> self-contained skill directory (`archify/`) with the Node CLI, schemas, +> renderers, examples and references. `hermes skills install +> official/creative/archify` pulls the current tree live from that repo +> (quarantined and scanned like any hub install) — this directory holds only +> the catalog metadata, so the vendored copy can never go stale. + +Archify turns a small typed JSON spec into a self-contained, explorable HTML +diagram: `architecture`, `workflow`, `sequence`, `dataflow` and `lifecycle` +(state machine) types, dark/light themes, pan/zoom, search, relationship +tracing, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. It accepts +plain-language requirements or pasted Mermaid (`flowchart`, `sequenceDiagram`, +`stateDiagram`) and can read repository evidence when the diagram must reflect +real code. Every candidate goes through a 9-check `validate` / `deliver` +receipt, so the output is verifiable rather than eyeballed. + +## Prerequisites + +- Node.js 18+ on `PATH` (`node bin/archify.mjs doctor` confirms the install; + no `npm install` is needed inside the skill package). +- Installs pull ~200 files (~8 MB, mostly upstream tests and examples) from + GitHub; the fetch is pinned to one tree SHA, recorded in the bundle metadata. +- Upstream's "Update awareness" step runs `scripts/check-update.mjs`, which + reads a release manifest from GitHub and only prints a notice — it never + downloads or installs anything. Skip it if outbound calls are unwanted. + +After install, the bundled `architecture-diagram` skill remains the +zero-dependency fallback (it ports the same Cocoon AI lineage archify grew out +of); prefer archify when the user wants validated receipts, Mermaid conversion, +sequence/lifecycle types, or export beyond a single HTML file. + +Full documentation: https://github.com/tt-a1i/archify#readme diff --git a/optional-skills/creative/ascii-art/SKILL.md b/optional-skills/creative/ascii-art/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..dd9a88b8c3f0c1e89089d11cf92cbbd51265f4a4 --- /dev/null +++ b/optional-skills/creative/ascii-art/SKILL.md @@ -0,0 +1,322 @@ +--- +name: ascii-art +description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii." +version: 4.0.0 +author: 0xbyt4, Hermes Agent +license: MIT +dependencies: [] +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [ASCII, Art, Banners, Creative, Unicode, Text-Art, pyfiglet, figlet, cowsay, boxes] + related_skills: [excalidraw] + +--- + +# ASCII Art Skill + +Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required. + +## Tool 1: Text Banners (pyfiglet — local) + +Render text as large ASCII art banners. 571 built-in fonts. + +### Setup + +```bash +pip install pyfiglet --break-system-packages -q +``` + +### Usage + +```bash +python -m pyfiglet "YOUR TEXT" -f slant +python -m pyfiglet "TEXT" -f doom -w 80 # Set width +python -m pyfiglet --list_fonts # List all 571 fonts +``` + +### Recommended fonts + +| Style | Font | Best for | +|-------|------|----------| +| Clean & modern | `slant` | Project names, headers | +| Bold & blocky | `doom` | Titles, logos | +| Big & readable | `big` | Banners | +| Classic banner | `banner3` | Wide displays | +| Compact | `small` | Subtitles | +| Cyberpunk | `cyberlarge` | Tech themes | +| 3D effect | `3-d` | Splash screens | +| Gothic | `gothic` | Dramatic text | + +### Tips + +- Preview 2-3 fonts and let the user pick their favorite +- Short text (1-8 chars) works best with detailed fonts like `doom` or `block` +- Long text works better with compact fonts like `small` or `mini` + +## Tool 2: Text Banners (asciified API — remote, no install) + +Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative. + +### Usage (via terminal curl) + +```bash +# Basic text banner (default font) +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World" + +# With a specific font +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3" + +# List all available fonts (returns JSON array) +curl -s "https://asciified.thelicato.io/api/v2/fonts" +``` + +### Tips + +- URL-encode spaces as `+` in the text parameter +- The response is plain text ASCII art — no JSON wrapping, ready to display +- Font names are case-sensitive; use the fonts endpoint to get exact names +- Works from any terminal with curl — no Python or pip needed + +## Tool 3: Cowsay (Message Art) + +Classic tool that wraps text in a speech bubble with an ASCII character. + +### Setup + +```bash +sudo apt install cowsay -y # Debian/Ubuntu +# brew install cowsay # macOS +``` + +### Usage + +```bash +cowsay "Hello World" +cowsay -f tux "Linux rules" # Tux the penguin +cowsay -f dragon "Rawr!" # Dragon +cowsay -f stegosaurus "Roar!" # Stegosaurus +cowthink "Hmm..." # Thought bubble +cowsay -l # List all characters +``` + +### Available characters (50+) + +`beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`, +`dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`, +`hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`, +`meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`, +`stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`, +`turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www` + +### Eye/tongue modifiers + +```bash +cowsay -b "Borg" # =_= eyes +cowsay -d "Dead" # x_x eyes +cowsay -g "Greedy" # $_$ eyes +cowsay -p "Paranoid" # @_@ eyes +cowsay -s "Stoned" # *_* eyes +cowsay -w "Wired" # O_O eyes +cowsay -e "OO" "Msg" # Custom eyes +cowsay -T "U " "Msg" # Custom tongue +``` + +## Tool 4: Boxes (Decorative Borders) + +Draw decorative ASCII art borders/frames around any text. 70+ built-in designs. + +### Setup + +```bash +sudo apt install boxes -y # Debian/Ubuntu +# brew install boxes # macOS +``` + +### Usage + +```bash +echo "Hello World" | boxes # Default box +echo "Hello World" | boxes -d stone # Stone border +echo "Hello World" | boxes -d parchment # Parchment scroll +echo "Hello World" | boxes -d cat # Cat border +echo "Hello World" | boxes -d dog # Dog border +echo "Hello World" | boxes -d unicornsay # Unicorn +echo "Hello World" | boxes -d diamonds # Diamond pattern +echo "Hello World" | boxes -d c-cmt # C-style comment +echo "Hello World" | boxes -d html-cmt # HTML comment +echo "Hello World" | boxes -a c # Center text +boxes -l # List all 70+ designs +``` + +### Combine with pyfiglet or asciified + +```bash +python -m pyfiglet "HERMES" -f slant | boxes -d stone +# Or without pyfiglet installed: +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone +``` + +## Tool 5: TOIlet (Colored Text Art) + +Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy. + +### Setup + +```bash +sudo apt install toilet toilet-fonts -y # Debian/Ubuntu +# brew install toilet # macOS +``` + +### Usage + +```bash +toilet "Hello World" # Basic text art +toilet -f bigmono12 "Hello" # Specific font +toilet --gay "Rainbow!" # Rainbow coloring +toilet --metal "Metal!" # Metallic effect +toilet -F border "Bordered" # Add border +toilet -F border --gay "Fancy!" # Combined effects +toilet -f pagga "Block" # Block-style font (unique to toilet) +toilet -F list # List available filters +``` + +### Filters + +`crop`, `gay` (rainbow), `metal`, `flip`, `flop`, `180`, `left`, `right`, `border` + +**Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms). + +## Tool 6: Image to ASCII Art + +Convert images (PNG, JPEG, GIF, WEBP) to ASCII art. + +### Option A: ascii-image-converter (recommended, modern) + +```bash +# Install +sudo snap install ascii-image-converter +# OR: go install github.com/TheZoraiz/ascii-image-converter@latest +``` + +```bash +ascii-image-converter image.png # Basic +ascii-image-converter image.png -C # Color output +ascii-image-converter image.png -d 60,30 # Set dimensions +ascii-image-converter image.png -b # Braille characters +ascii-image-converter image.png -n # Negative/inverted +ascii-image-converter https://url/image.jpg # Direct URL +ascii-image-converter image.png --save-txt out # Save as text +``` + +### Option B: jp2a (lightweight, JPEG only) + +```bash +sudo apt install jp2a -y +jp2a --width=80 image.jpg +jp2a --colors image.jpg # Colorized +``` + +## Tool 7: Search Pre-Made ASCII Art + +Search curated ASCII art from the web. Use `terminal` with `curl`. + +### Source A: ascii.co.uk (recommended for pre-made art) + +Large collection of classic ASCII art organized by subject. Art is inside HTML `
` tags. Fetch the page with curl, then extract art with a small Python snippet.
+
+**URL pattern:** `https://ascii.co.uk/art/{subject}`
+
+**Step 1 — Fetch the page:**
+
+```bash
+curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
+```
+
+**Step 2 — Extract art from pre tags:**
+
+```python
+import re, html
+with open('/tmp/ascii_art.html') as f:
+    text = f.read()
+arts = re.findall(r']*>(.*?)
', text, re.DOTALL) +for art in arts: + clean = re.sub(r'<[^>]+>', '', art) + clean = html.unescape(clean).strip() + if len(clean) > 30: + print(clean) + print('\n---\n') +``` + +**Available subjects** (use as URL path): +- Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle` +- Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key` +- Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow` +- Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien` +- Holidays: `christmas`, `halloween`, `valentine` + +**Tips:** +- Preserve artist signatures/initials — important etiquette +- Multiple art pieces per page — pick the best one for the user +- Works reliably via curl, no JavaScript needed + +### Source B: GitHub Octocat API (fun easter egg) + +Returns a random GitHub Octocat with a wise quote. No auth needed. + +```bash +curl -s https://api.github.com/octocat +``` + +## Tool 8: Fun ASCII Utilities (via curl) + +These free services return ASCII art directly — great for fun extras. + +### QR Codes as ASCII Art + +```bash +curl -s "qrenco.de/Hello+World" +curl -s "qrenco.de/https://example.com" +``` + +### Weather as ASCII Art + +```bash +curl -s "wttr.in/London" # Full weather report with ASCII graphics +curl -s "wttr.in/Moon" # Moon phase in ASCII art +curl -s "v2.wttr.in/London" # Detailed version +``` + +## Tool 9: LLM-Generated Custom Art (Fallback) + +When tools above don't have what's needed, generate ASCII art directly using these Unicode characters: + +### Character Palette + +**Box Drawing:** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯` + +**Block Elements:** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞` + +**Geometric & Symbols:** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂` + +### Rules + +- Max width: 60 characters per line (terminal-safe) +- Max height: 15 lines for banners, 25 for scenes +- Monospace only: output must render correctly in fixed-width fonts + +## Decision Flow + +1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl +2. **Wrap a message in fun character art** → cowsay +3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified) +4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing +5. **Convert an image to ASCII** → ascii-image-converter or jp2a +6. **QR code** → qrenco.de via curl +7. **Weather/moon art** → wttr.in via curl +8. **Something custom/creative** → LLM generation with Unicode palette +9. **Any tool not installed** → install it, or fall back to next option diff --git a/optional-skills/creative/audiocraft-audio-generation/SKILL.md b/optional-skills/creative/audiocraft-audio-generation/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..be5075c2f226d529334314605850384e74e631c3 --- /dev/null +++ b/optional-skills/creative/audiocraft-audio-generation/SKILL.md @@ -0,0 +1,569 @@ +--- +name: audiocraft-audio-generation +description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound." +version: 1.0.0 +author: Orchestra Research +license: MIT +dependencies: [audiocraft, torch>=2.0.0, transformers>=4.30.0] +platforms: [linux, macos] +metadata: + hermes: + tags: [Multimodal, Audio Generation, Text-to-Music, Text-to-Audio, MusicGen] + related_skills: [heartmula, songwriting-and-ai-music] + +--- + +# AudioCraft: Audio Generation + +Guide to using Meta's AudioCraft for text-to-music and text-to-audio generation with MusicGen, AudioGen, and EnCodec. + +## When to use AudioCraft + +**Use AudioCraft when:** +- Need to generate music from text descriptions +- Creating sound effects and environmental audio +- Building music generation applications +- Need melody-conditioned music generation +- Want stereo audio output +- Require controllable music generation with style transfer + +**Key features:** +- **MusicGen**: Text-to-music generation with melody conditioning +- **AudioGen**: Text-to-sound effects generation +- **EnCodec**: High-fidelity neural audio codec +- **Multiple model sizes**: Small (300M) to Large (3.3B) +- **Stereo support**: Full stereo audio generation +- **Style conditioning**: MusicGen-Style for reference-based generation + +**Use alternatives instead:** +- **Stable Audio**: For longer commercial music generation +- **Bark**: For text-to-speech with music/sound effects +- **Riffusion**: For spectogram-based music generation +- **OpenAI Jukebox**: For raw audio generation with lyrics + +## Quick start + +### Installation + +```bash +# From PyPI +pip install audiocraft + +# From GitHub (latest) +pip install git+https://github.com/facebookresearch/audiocraft.git + +# Or use HuggingFace Transformers +pip install transformers torch torchaudio +``` + +### Basic text-to-music (AudioCraft) + +```python +import torchaudio +from audiocraft.models import MusicGen + +# Load model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Set generation parameters +model.set_generation_params( + duration=8, # seconds + top_k=250, + temperature=1.0 +) + +# Generate from text +descriptions = ["happy upbeat electronic dance music with synths"] +wav = model.generate(descriptions) + +# Save audio +torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000) +``` + +### Using HuggingFace Transformers + +```python +from transformers import AutoProcessor, MusicgenForConditionalGeneration +import scipy + +# Load model and processor +processor = AutoProcessor.from_pretrained("facebook/musicgen-small") +model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small") +model.to("cuda") + +# Generate music +inputs = processor( + text=["80s pop track with bassy drums and synth"], + padding=True, + return_tensors="pt" +).to("cuda") + +audio_values = model.generate( + **inputs, + do_sample=True, + guidance_scale=3, + max_new_tokens=256 +) + +# Save +sampling_rate = model.config.audio_encoder.sampling_rate +scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy()) +``` + +### Text-to-sound with AudioGen + +```python +from audiocraft.models import AudioGen + +# Load AudioGen +model = AudioGen.get_pretrained('facebook/audiogen-medium') + +model.set_generation_params(duration=5) + +# Generate sound effects +descriptions = ["dog barking in a park with birds chirping"] +wav = model.generate(descriptions) + +torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000) +``` + +## Core concepts + +### Architecture overview + +``` +AudioCraft Architecture: +┌──────────────────────────────────────────────────────────────┐ +│ Text Encoder (T5) │ +│ │ │ +│ Text Embeddings │ +└────────────────────────┬─────────────────────────────────────┘ + │ +┌────────────────────────▼─────────────────────────────────────┐ +│ Transformer Decoder (LM) │ +│ Auto-regressively generates audio tokens │ +│ Using efficient token interleaving patterns │ +└────────────────────────┬─────────────────────────────────────┘ + │ +┌────────────────────────▼─────────────────────────────────────┐ +│ EnCodec Audio Decoder │ +│ Converts tokens back to audio waveform │ +└──────────────────────────────────────────────────────────────┘ +``` + +### Model variants + +| Model | Size | Description | Use Case | +|-------|------|-------------|----------| +| `musicgen-small` | 300M | Text-to-music | Quick generation | +| `musicgen-medium` | 1.5B | Text-to-music | Balanced | +| `musicgen-large` | 3.3B | Text-to-music | Best quality | +| `musicgen-melody` | 1.5B | Text + melody | Melody conditioning | +| `musicgen-melody-large` | 3.3B | Text + melody | Best melody | +| `musicgen-stereo-*` | Varies | Stereo output | Stereo generation | +| `musicgen-style` | 1.5B | Style transfer | Reference-based | +| `audiogen-medium` | 1.5B | Text-to-sound | Sound effects | + +### Generation parameters + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `duration` | 8.0 | Length in seconds (1-120) | +| `top_k` | 250 | Top-k sampling | +| `top_p` | 0.0 | Nucleus sampling (0 = disabled) | +| `temperature` | 1.0 | Sampling temperature | +| `cfg_coef` | 3.0 | Classifier-free guidance | + +## MusicGen usage + +### Text-to-music generation + +```python +from audiocraft.models import MusicGen +import torchaudio + +model = MusicGen.get_pretrained('facebook/musicgen-medium') + +# Configure generation +model.set_generation_params( + duration=30, # Up to 30 seconds + top_k=250, # Sampling diversity + top_p=0.0, # 0 = use top_k only + temperature=1.0, # Creativity (higher = more varied) + cfg_coef=3.0 # Text adherence (higher = stricter) +) + +# Generate multiple samples +descriptions = [ + "epic orchestral soundtrack with strings and brass", + "chill lo-fi hip hop beat with jazzy piano", + "energetic rock song with electric guitar" +] + +# Generate (returns [batch, channels, samples]) +wav = model.generate(descriptions) + +# Save each +for i, audio in enumerate(wav): + torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000) +``` + +### Melody-conditioned generation + +```python +from audiocraft.models import MusicGen +import torchaudio + +# Load melody model +model = MusicGen.get_pretrained('facebook/musicgen-melody') +model.set_generation_params(duration=30) + +# Load melody audio +melody, sr = torchaudio.load("melody.wav") + +# Generate with melody conditioning +descriptions = ["acoustic guitar folk song"] +wav = model.generate_with_chroma(descriptions, melody, sr) + +torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000) +``` + +### Stereo generation + +```python +from audiocraft.models import MusicGen + +# Load stereo model +model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium') +model.set_generation_params(duration=15) + +descriptions = ["ambient electronic music with wide stereo panning"] +wav = model.generate(descriptions) + +# wav shape: [batch, 2, samples] for stereo +print(f"Stereo shape: {wav.shape}") # [1, 2, 480000] +torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000) +``` + +### Audio continuation + +```python +from transformers import AutoProcessor, MusicgenForConditionalGeneration + +processor = AutoProcessor.from_pretrained("facebook/musicgen-medium") +model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium") + +# Load audio to continue +import torchaudio +audio, sr = torchaudio.load("intro.wav") + +# Process with text and audio +inputs = processor( + audio=audio.squeeze().numpy(), + sampling_rate=sr, + text=["continue with a epic chorus"], + padding=True, + return_tensors="pt" +) + +# Generate continuation +audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512) +``` + +## MusicGen-Style usage + +### Style-conditioned generation + +```python +from audiocraft.models import MusicGen + +# Load style model +model = MusicGen.get_pretrained('facebook/musicgen-style') + +# Configure generation with style +model.set_generation_params( + duration=30, + cfg_coef=3.0, + cfg_coef_beta=5.0 # Style influence +) + +# Configure style conditioner +model.set_style_conditioner_params( + eval_q=3, # RVQ quantizers (1-6) + excerpt_length=3.0 # Style excerpt length +) + +# Load style reference +style_audio, sr = torchaudio.load("reference_style.wav") + +# Generate with text + style +descriptions = ["upbeat dance track"] +wav = model.generate_with_style(descriptions, style_audio, sr) +``` + +### Style-only generation (no text) + +```python +# Generate matching style without text prompt +model.set_generation_params( + duration=30, + cfg_coef=3.0, + cfg_coef_beta=None # Disable double CFG for style-only +) + +wav = model.generate_with_style([None], style_audio, sr) +``` + +## AudioGen usage + +### Sound effect generation + +```python +from audiocraft.models import AudioGen +import torchaudio + +model = AudioGen.get_pretrained('facebook/audiogen-medium') +model.set_generation_params(duration=10) + +# Generate various sounds +descriptions = [ + "thunderstorm with heavy rain and lightning", + "busy city traffic with car horns", + "ocean waves crashing on rocks", + "crackling campfire in forest" +] + +wav = model.generate(descriptions) + +for i, audio in enumerate(wav): + torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000) +``` + +## EnCodec usage + +### Audio compression + +```python +from audiocraft.models import CompressionModel +import torch +import torchaudio + +# Load EnCodec +model = CompressionModel.get_pretrained('facebook/encodec_32khz') + +# Load audio +wav, sr = torchaudio.load("audio.wav") + +# Ensure correct sample rate +if sr != 32000: + resampler = torchaudio.transforms.Resample(sr, 32000) + wav = resampler(wav) + +# Encode to tokens +with torch.no_grad(): + encoded = model.encode(wav.unsqueeze(0)) + codes = encoded[0] # Audio codes + +# Decode back to audio +with torch.no_grad(): + decoded = model.decode(codes) + +torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000) +``` + +## Common workflows + +### Workflow 1: Music generation pipeline + +```python +import torch +import torchaudio +from audiocraft.models import MusicGen + +class MusicGenerator: + def __init__(self, model_name="facebook/musicgen-medium"): + self.model = MusicGen.get_pretrained(model_name) + self.sample_rate = 32000 + + def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0): + self.model.set_generation_params( + duration=duration, + top_k=250, + temperature=temperature, + cfg_coef=cfg + ) + + with torch.no_grad(): + wav = self.model.generate([prompt]) + + return wav[0].cpu() + + def generate_batch(self, prompts, duration=30): + self.model.set_generation_params(duration=duration) + + with torch.no_grad(): + wav = self.model.generate(prompts) + + return wav.cpu() + + def save(self, audio, path): + torchaudio.save(path, audio, sample_rate=self.sample_rate) + +# Usage +generator = MusicGenerator() +audio = generator.generate( + "epic cinematic orchestral music", + duration=30, + temperature=1.0 +) +generator.save(audio, "epic_music.wav") +``` + +### Workflow 2: Sound design batch processing + +```python +import json +from pathlib import Path +from audiocraft.models import AudioGen +import torchaudio + +def batch_generate_sounds(sound_specs, output_dir): + """ + Generate multiple sounds from specifications. + + Args: + sound_specs: list of {"name": str, "description": str, "duration": float} + output_dir: output directory path + """ + model = AudioGen.get_pretrained('facebook/audiogen-medium') + output_dir = Path(output_dir) + output_dir.mkdir(exist_ok=True) + + results = [] + + for spec in sound_specs: + model.set_generation_params(duration=spec.get("duration", 5)) + + wav = model.generate([spec["description"]]) + + output_path = output_dir / f"{spec['name']}.wav" + torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000) + + results.append({ + "name": spec["name"], + "path": str(output_path), + "description": spec["description"] + }) + + return results + +# Usage +sounds = [ + {"name": "explosion", "description": "massive explosion with debris", "duration": 3}, + {"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5}, + {"name": "door", "description": "wooden door creaking and closing", "duration": 2} +] + +results = batch_generate_sounds(sounds, "sound_effects/") +``` + +### Workflow 3: Gradio demo + +```python +import gradio as gr +import torch +import torchaudio +from audiocraft.models import MusicGen + +model = MusicGen.get_pretrained('facebook/musicgen-small') + +def generate_music(prompt, duration, temperature, cfg_coef): + model.set_generation_params( + duration=duration, + temperature=temperature, + cfg_coef=cfg_coef + ) + + with torch.no_grad(): + wav = model.generate([prompt]) + + # Save to temp file + path = "temp_output.wav" + torchaudio.save(path, wav[0].cpu(), sample_rate=32000) + return path + +demo = gr.Interface( + fn=generate_music, + inputs=[ + gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"), + gr.Slider(1, 30, value=8, label="Duration (seconds)"), + gr.Slider(0.5, 2.0, value=1.0, label="Temperature"), + gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient") + ], + outputs=gr.Audio(label="Generated Music"), + title="MusicGen Demo" +) + +demo.launch() +``` + +## Performance optimization + +### Memory optimization + +```python +# Use smaller model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Clear cache between generations +torch.cuda.empty_cache() + +# Generate shorter durations +model.set_generation_params(duration=10) # Instead of 30 + +# Use half precision +model = model.half() +``` + +### Batch processing efficiency + +```python +# Process multiple prompts at once (more efficient) +descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"] +wav = model.generate(descriptions) # Single batch + +# Instead of +for desc in descriptions: + wav = model.generate([desc]) # Multiple batches (slower) +``` + +### GPU memory requirements + +| Model | FP32 VRAM | FP16 VRAM | +|-------|-----------|-----------| +| musicgen-small | ~4GB | ~2GB | +| musicgen-medium | ~8GB | ~4GB | +| musicgen-large | ~16GB | ~8GB | + +## Common issues + +| Issue | Solution | +|-------|----------| +| CUDA OOM | Use smaller model, reduce duration | +| Poor quality | Increase cfg_coef, better prompts | +| Generation too short | Check max duration setting | +| Audio artifacts | Try different temperature | +| Stereo not working | Use stereo model variant | + +## References + +- **[Advanced Usage](references/advanced-usage.md)** - Training, fine-tuning, deployment +- **[Troubleshooting](references/troubleshooting.md)** - Common issues and solutions + +## Resources + +- **GitHub**: https://github.com/facebookresearch/audiocraft +- **Paper (MusicGen)**: https://arxiv.org/abs/2306.05284 +- **Paper (AudioGen)**: https://arxiv.org/abs/2209.15352 +- **HuggingFace**: https://huggingface.co/facebook/musicgen-small +- **Demo**: https://huggingface.co/spaces/facebook/MusicGen diff --git a/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md b/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md new file mode 100644 index 0000000000000000000000000000000000000000..953be2b4a560cd5d33f6f5675d2f1f3733371ad0 --- /dev/null +++ b/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md @@ -0,0 +1,666 @@ +# AudioCraft Advanced Usage Guide + +## Fine-tuning MusicGen + +### Custom dataset preparation + +```python +import os +import json +from pathlib import Path +import torchaudio + +def prepare_dataset(audio_dir, output_dir, metadata_file): + """ + Prepare dataset for MusicGen fine-tuning. + + Directory structure: + output_dir/ + ├── audio/ + │ ├── 0001.wav + │ ├── 0002.wav + │ └── ... + └── metadata.json + """ + output_dir = Path(output_dir) + audio_output = output_dir / "audio" + audio_output.mkdir(parents=True, exist_ok=True) + + # Load metadata (format: {"path": "...", "description": "..."}) + with open(metadata_file) as f: + metadata = json.load(f) + + processed = [] + + for idx, item in enumerate(metadata): + audio_path = Path(audio_dir) / item["path"] + + # Load and resample to 32kHz + wav, sr = torchaudio.load(str(audio_path)) + if sr != 32000: + resampler = torchaudio.transforms.Resample(sr, 32000) + wav = resampler(wav) + + # Convert to mono if stereo + if wav.shape[0] > 1: + wav = wav.mean(dim=0, keepdim=True) + + # Save processed audio + output_path = audio_output / f"{idx:04d}.wav" + torchaudio.save(str(output_path), wav, sample_rate=32000) + + processed.append({ + "path": str(output_path.relative_to(output_dir)), + "description": item["description"], + "duration": wav.shape[1] / 32000 + }) + + # Save processed metadata + with open(output_dir / "metadata.json", "w") as f: + json.dump(processed, f, indent=2) + + print(f"Processed {len(processed)} samples") + return processed +``` + +### Fine-tuning with dora + +```bash +# AudioCraft uses dora for experiment management +# Install dora +pip install dora-search + +# Clone AudioCraft +git clone https://github.com/facebookresearch/audiocraft.git +cd audiocraft + +# Create config for fine-tuning +cat > config/solver/musicgen/finetune.yaml << 'EOF' +defaults: + - musicgen/musicgen_base + - /model: lm/musicgen_lm + - /conditioner: cond_base + +solver: musicgen +autocast: true +autocast_dtype: float16 + +optim: + epochs: 100 + batch_size: 4 + lr: 1e-4 + ema: 0.999 + optimizer: adamw + +dataset: + batch_size: 4 + num_workers: 4 + train: + - dset: your_dataset + root: /path/to/dataset + valid: + - dset: your_dataset + root: /path/to/dataset + +checkpoint: + save_every: 10 + keep_every_states: null +EOF + +# Run fine-tuning +dora run solver=musicgen/finetune +``` + +### LoRA fine-tuning + +```python +from peft import LoraConfig, get_peft_model +from audiocraft.models import MusicGen +import torch + +# Load base model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Get the language model component +lm = model.lm + +# Configure LoRA +lora_config = LoraConfig( + r=8, + lora_alpha=16, + target_modules=["q_proj", "v_proj", "k_proj", "out_proj"], + lora_dropout=0.05, + bias="none" +) + +# Apply LoRA +lm = get_peft_model(lm, lora_config) +lm.print_trainable_parameters() +``` + +## Multi-GPU Training + +### DataParallel + +```python +import torch +import torch.nn as nn +from audiocraft.models import MusicGen + +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Wrap LM with DataParallel +if torch.cuda.device_count() > 1: + model.lm = nn.DataParallel(model.lm) + +model.to("cuda") +``` + +### DistributedDataParallel + +```python +import torch.distributed as dist +from torch.nn.parallel import DistributedDataParallel as DDP + +def setup(rank, world_size): + dist.init_process_group("nccl", rank=rank, world_size=world_size) + torch.cuda.set_device(rank) + +def train(rank, world_size): + setup(rank, world_size) + + model = MusicGen.get_pretrained('facebook/musicgen-small') + model.lm = model.lm.to(rank) + model.lm = DDP(model.lm, device_ids=[rank]) + + # Training loop + # ... + + dist.destroy_process_group() +``` + +## Custom Conditioning + +### Adding new conditioners + +```python +from audiocraft.modules.conditioners import BaseConditioner +import torch + +class CustomConditioner(BaseConditioner): + """Custom conditioner for additional control signals.""" + + def __init__(self, dim, output_dim): + super().__init__(dim, output_dim) + self.embed = torch.nn.Linear(dim, output_dim) + + def forward(self, x): + return self.embed(x) + + def tokenize(self, x): + # Tokenize input for conditioning + return x + +# Use with MusicGen +from audiocraft.models.builders import get_lm_model + +# Modify model config to include custom conditioner +# This requires editing the model configuration +``` + +### Melody conditioning internals + +```python +from audiocraft.models import MusicGen +from audiocraft.modules.codebooks_patterns import DelayedPatternProvider +import torch + +model = MusicGen.get_pretrained('facebook/musicgen-melody') + +# Access chroma extractor +chroma_extractor = model.lm.condition_provider.conditioners.get('chroma') + +# Manual chroma extraction +def extract_chroma(audio, sr): + """Extract chroma features from audio.""" + import librosa + + # Compute chroma + chroma = librosa.feature.chroma_cqt(y=audio.numpy(), sr=sr) + + return torch.from_numpy(chroma).float() + +# Use extracted chroma for conditioning +chroma = extract_chroma(melody_audio, sample_rate) +``` + +## EnCodec Deep Dive + +### Custom compression settings + +```python +from audiocraft.models import CompressionModel +import torch + +# Load EnCodec +encodec = CompressionModel.get_pretrained('facebook/encodec_32khz') + +# Access codec parameters +print(f"Sample rate: {encodec.sample_rate}") +print(f"Channels: {encodec.channels}") +print(f"Cardinality: {encodec.cardinality}") # Codebook size +print(f"Num codebooks: {encodec.num_codebooks}") +print(f"Frame rate: {encodec.frame_rate}") + +# Encode with specific bandwidth +# Lower bandwidth = more compression, lower quality +encodec.set_target_bandwidth(6.0) # 6 kbps + +audio = torch.randn(1, 1, 32000) # 1 second +encoded = encodec.encode(audio) +decoded = encodec.decode(encoded[0]) +``` + +### Streaming encoding + +```python +import torch +from audiocraft.models import CompressionModel + +encodec = CompressionModel.get_pretrained('facebook/encodec_32khz') + +def encode_streaming(audio_stream, chunk_size=32000): + """Encode audio in streaming fashion.""" + all_codes = [] + + for chunk in audio_stream: + # Ensure chunk is right shape + if chunk.dim() == 1: + chunk = chunk.unsqueeze(0).unsqueeze(0) + + with torch.no_grad(): + codes = encodec.encode(chunk)[0] + all_codes.append(codes) + + return torch.cat(all_codes, dim=-1) + +def decode_streaming(codes_stream, output_stream): + """Decode codes in streaming fashion.""" + for codes in codes_stream: + with torch.no_grad(): + audio = encodec.decode(codes) + output_stream.write(audio.cpu().numpy()) +``` + +## MultiBand Diffusion + +### Using MBD for enhanced quality + +```python +from audiocraft.models import MusicGen, MultiBandDiffusion + +# Load MusicGen +model = MusicGen.get_pretrained('facebook/musicgen-medium') + +# Load MultiBand Diffusion +mbd = MultiBandDiffusion.get_mbd_musicgen() + +model.set_generation_params(duration=10) + +# Generate with standard decoder +descriptions = ["epic orchestral music"] +wav_standard = model.generate(descriptions) + +# Generate tokens and use MBD decoder +with torch.no_grad(): + # Get tokens + gen_tokens = model.generate_tokens(descriptions) + + # Decode with MBD + wav_mbd = mbd.tokens_to_wav(gen_tokens) + +# Compare quality +print(f"Standard shape: {wav_standard.shape}") +print(f"MBD shape: {wav_mbd.shape}") +``` + +## API Server Deployment + +### FastAPI server + +```python +from fastapi import FastAPI, HTTPException +from pydantic import BaseModel +import torch +import torchaudio +from audiocraft.models import MusicGen +import io +import base64 + +app = FastAPI() + +# Load model at startup +model = None + +@app.on_event("startup") +async def load_model(): + global model + model = MusicGen.get_pretrained('facebook/musicgen-small') + model.set_generation_params(duration=10) + +class GenerateRequest(BaseModel): + prompt: str + duration: float = 10.0 + temperature: float = 1.0 + cfg_coef: float = 3.0 + +class GenerateResponse(BaseModel): + audio_base64: str + sample_rate: int + duration: float + +@app.post("/generate", response_model=GenerateResponse) +async def generate(request: GenerateRequest): + if model is None: + raise HTTPException(status_code=500, detail="Model not loaded") + + try: + model.set_generation_params( + duration=min(request.duration, 30), + temperature=request.temperature, + cfg_coef=request.cfg_coef + ) + + with torch.no_grad(): + wav = model.generate([request.prompt]) + + # Convert to bytes + buffer = io.BytesIO() + torchaudio.save(buffer, wav[0].cpu(), sample_rate=32000, format="wav") + buffer.seek(0) + + audio_base64 = base64.b64encode(buffer.read()).decode() + + return GenerateResponse( + audio_base64=audio_base64, + sample_rate=32000, + duration=wav.shape[-1] / 32000 + ) + + except Exception as e: + raise HTTPException(status_code=500, detail=str(e)) + +@app.get("/health") +async def health(): + return {"status": "ok", "model_loaded": model is not None} + +# Run: uvicorn server:app --host 0.0.0.0 --port 8000 +``` + +### Batch processing service + +```python +import asyncio +from concurrent.futures import ThreadPoolExecutor +import torch +from audiocraft.models import MusicGen + +class MusicGenService: + def __init__(self, model_name='facebook/musicgen-small', max_workers=2): + self.model = MusicGen.get_pretrained(model_name) + self.executor = ThreadPoolExecutor(max_workers=max_workers) + self.lock = asyncio.Lock() + + async def generate_async(self, prompt, duration=10): + """Async generation with thread pool.""" + loop = asyncio.get_event_loop() + + def _generate(): + with torch.no_grad(): + self.model.set_generation_params(duration=duration) + return self.model.generate([prompt]) + + # Run in thread pool + wav = await loop.run_in_executor(self.executor, _generate) + return wav[0].cpu() + + async def generate_batch_async(self, prompts, duration=10): + """Process multiple prompts concurrently.""" + tasks = [self.generate_async(p, duration) for p in prompts] + return await asyncio.gather(*tasks) + +# Usage +service = MusicGenService() + +async def main(): + prompts = ["jazz piano", "rock guitar", "electronic beats"] + results = await service.generate_batch_async(prompts) + return results +``` + +## Integration Patterns + +### LangChain tool + +```python +from langchain.tools import BaseTool +import torch +import torchaudio +from audiocraft.models import MusicGen +import tempfile + +class MusicGeneratorTool(BaseTool): + name = "music_generator" + description = "Generate music from a text description. Input should be a detailed description of the music style, mood, and instruments." + + def __init__(self): + super().__init__() + self.model = MusicGen.get_pretrained('facebook/musicgen-small') + self.model.set_generation_params(duration=15) + + def _run(self, description: str) -> str: + with torch.no_grad(): + wav = self.model.generate([description]) + + # Save to temp file + with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f: + torchaudio.save(f.name, wav[0].cpu(), sample_rate=32000) + return f"Generated music saved to: {f.name}" + + async def _arun(self, description: str) -> str: + return self._run(description) +``` + +### Gradio with advanced controls + +```python +import gradio as gr +import torch +import torchaudio +from audiocraft.models import MusicGen + +models = {} + +def load_model(model_size): + if model_size not in models: + model_name = f"facebook/musicgen-{model_size}" + models[model_size] = MusicGen.get_pretrained(model_name) + return models[model_size] + +def generate(prompt, duration, temperature, cfg_coef, top_k, model_size): + model = load_model(model_size) + + model.set_generation_params( + duration=duration, + temperature=temperature, + cfg_coef=cfg_coef, + top_k=top_k + ) + + with torch.no_grad(): + wav = model.generate([prompt]) + + # Save + path = "output.wav" + torchaudio.save(path, wav[0].cpu(), sample_rate=32000) + return path + +demo = gr.Interface( + fn=generate, + inputs=[ + gr.Textbox(label="Prompt", lines=3), + gr.Slider(1, 30, value=10, label="Duration (s)"), + gr.Slider(0.1, 2.0, value=1.0, label="Temperature"), + gr.Slider(0.5, 10.0, value=3.0, label="CFG Coefficient"), + gr.Slider(50, 500, value=250, step=50, label="Top-K"), + gr.Dropdown(["small", "medium", "large"], value="small", label="Model Size") + ], + outputs=gr.Audio(label="Generated Music"), + title="MusicGen Advanced", + allow_flagging="never" +) + +demo.launch(share=True) +``` + +## Audio Processing Pipeline + +### Post-processing chain + +```python +import torch +import torchaudio +import torchaudio.transforms as T +import numpy as np + +class AudioPostProcessor: + def __init__(self, sample_rate=32000): + self.sample_rate = sample_rate + + def normalize(self, audio, target_db=-14.0): + """Normalize audio to target loudness.""" + rms = torch.sqrt(torch.mean(audio ** 2)) + target_rms = 10 ** (target_db / 20) + gain = target_rms / (rms + 1e-8) + return audio * gain + + def fade_in_out(self, audio, fade_duration=0.1): + """Apply fade in/out.""" + fade_samples = int(fade_duration * self.sample_rate) + + # Create fade curves + fade_in = torch.linspace(0, 1, fade_samples) + fade_out = torch.linspace(1, 0, fade_samples) + + # Apply fades + audio[..., :fade_samples] *= fade_in + audio[..., -fade_samples:] *= fade_out + + return audio + + def apply_reverb(self, audio, decay=0.5): + """Apply simple reverb effect.""" + impulse = torch.zeros(int(self.sample_rate * 0.5)) + impulse[0] = 1.0 + impulse[int(self.sample_rate * 0.1)] = decay * 0.5 + impulse[int(self.sample_rate * 0.2)] = decay * 0.25 + + # Convolve + audio = torch.nn.functional.conv1d( + audio.unsqueeze(0), + impulse.unsqueeze(0).unsqueeze(0), + padding=len(impulse) // 2 + ).squeeze(0) + + return audio + + def process(self, audio): + """Full processing pipeline.""" + audio = self.normalize(audio) + audio = self.fade_in_out(audio) + return audio + +# Usage with MusicGen +from audiocraft.models import MusicGen + +model = MusicGen.get_pretrained('facebook/musicgen-small') +model.set_generation_params(duration=10) + +wav = model.generate(["chill ambient music"]) +processor = AudioPostProcessor() +wav_processed = processor.process(wav[0].cpu()) + +torchaudio.save("processed.wav", wav_processed, sample_rate=32000) +``` + +## Evaluation + +### Audio quality metrics + +```python +import torch +from audiocraft.metrics import CLAPTextConsistencyMetric +from audiocraft.data.audio import audio_read + +def evaluate_generation(audio_path, text_prompt): + """Evaluate generated audio quality.""" + # Load audio + wav, sr = audio_read(audio_path) + + # CLAP consistency (text-audio alignment) + clap_metric = CLAPTextConsistencyMetric() + clap_score = clap_metric.compute(wav, [text_prompt]) + + return { + "clap_score": clap_score, + "duration": wav.shape[-1] / sr + } + +# Batch evaluation +def evaluate_batch(generations): + """Evaluate multiple generations.""" + results = [] + for gen in generations: + result = evaluate_generation(gen["path"], gen["prompt"]) + result["prompt"] = gen["prompt"] + results.append(result) + + # Aggregate + avg_clap = sum(r["clap_score"] for r in results) / len(results) + return { + "individual": results, + "average_clap": avg_clap + } +``` + +## Model Comparison + +### MusicGen variants benchmark + +| Model | CLAP Score | Generation Time (10s) | VRAM | +|-------|------------|----------------------|------| +| musicgen-small | 0.35 | ~5s | 2GB | +| musicgen-medium | 0.42 | ~15s | 4GB | +| musicgen-large | 0.48 | ~30s | 8GB | +| musicgen-melody | 0.45 | ~15s | 4GB | +| musicgen-stereo-medium | 0.41 | ~18s | 5GB | + +### Prompt engineering tips + +```python +# Good prompts - specific and descriptive +good_prompts = [ + "upbeat electronic dance music with synthesizer leads and punchy drums at 128 bpm", + "melancholic piano ballad with strings, slow tempo, emotional and cinematic", + "funky disco groove with slap bass, brass section, and rhythmic guitar" +] + +# Bad prompts - too vague +bad_prompts = [ + "nice music", + "song", + "good beat" +] + +# Structure: [mood] [genre] with [instruments] at [tempo/style] +``` diff --git a/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md b/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md new file mode 100644 index 0000000000000000000000000000000000000000..7b83e863d65186c80fcd139e425629baddd13bb8 --- /dev/null +++ b/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md @@ -0,0 +1,504 @@ +# AudioCraft Troubleshooting Guide + +## Installation Issues + +### Import errors + +**Error**: `ModuleNotFoundError: No module named 'audiocraft'` + +**Solutions**: +```bash +# Install from PyPI +pip install audiocraft + +# Or from GitHub +pip install git+https://github.com/facebookresearch/audiocraft.git + +# Verify installation +python -c "from audiocraft.models import MusicGen; print('OK')" +``` + +### FFmpeg not found + +**Error**: `RuntimeError: ffmpeg not found` + +**Solutions**: +```bash +# Ubuntu/Debian +sudo apt-get install ffmpeg + +# macOS +brew install ffmpeg + +# Windows (using conda) +conda install -c conda-forge ffmpeg + +# Verify +ffmpeg -version +``` + +### PyTorch CUDA mismatch + +**Error**: `RuntimeError: CUDA error: no kernel image is available` + +**Solutions**: +```bash +# Check CUDA version +nvcc --version +python -c "import torch; print(torch.version.cuda)" + +# Install matching PyTorch +pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121 + +# For CUDA 11.8 +pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118 +``` + +### xformers issues + +**Error**: `ImportError: xformers` related errors + +**Solutions**: +```bash +# Install xformers for memory efficiency +pip install xformers + +# Or disable xformers +export AUDIOCRAFT_USE_XFORMERS=0 + +# In Python +import os +os.environ["AUDIOCRAFT_USE_XFORMERS"] = "0" +from audiocraft.models import MusicGen +``` + +## Model Loading Issues + +### Out of memory during load + +**Error**: `torch.cuda.OutOfMemoryError` during model loading + +**Solutions**: +```python +# Use smaller model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Force CPU loading first +import torch +device = "cpu" +model = MusicGen.get_pretrained('facebook/musicgen-small', device=device) +model = model.to("cuda") + +# Use HuggingFace with device_map +from transformers import MusicgenForConditionalGeneration +model = MusicgenForConditionalGeneration.from_pretrained( + "facebook/musicgen-small", + device_map="auto" +) +``` + +### Download failures + +**Error**: Connection errors or incomplete downloads + +**Solutions**: +```python +# Set cache directory +import os +os.environ["AUDIOCRAFT_CACHE_DIR"] = "/path/to/cache" + +# Or for HuggingFace +os.environ["HF_HOME"] = "/path/to/hf_cache" + +# Resume download +from huggingface_hub import snapshot_download +snapshot_download("facebook/musicgen-small", resume_download=True) + +# Use local files +model = MusicGen.get_pretrained('/local/path/to/model') +``` + +### Wrong model type + +**Error**: Loading wrong model for task + +**Solutions**: +```python +# For text-to-music: use MusicGen +from audiocraft.models import MusicGen +model = MusicGen.get_pretrained('facebook/musicgen-medium') + +# For text-to-sound: use AudioGen +from audiocraft.models import AudioGen +model = AudioGen.get_pretrained('facebook/audiogen-medium') + +# For melody conditioning: use melody variant +model = MusicGen.get_pretrained('facebook/musicgen-melody') + +# For stereo: use stereo variant +model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium') +``` + +## Generation Issues + +### Empty or silent output + +**Problem**: Generated audio is silent or very quiet + +**Solutions**: +```python +import torch + +# Check output +wav = model.generate(["upbeat music"]) +print(f"Shape: {wav.shape}") +print(f"Max amplitude: {wav.abs().max().item()}") +print(f"Mean amplitude: {wav.abs().mean().item()}") + +# If too quiet, normalize +def normalize_audio(audio, target_db=-14.0): + rms = torch.sqrt(torch.mean(audio ** 2)) + target_rms = 10 ** (target_db / 20) + gain = target_rms / (rms + 1e-8) + return audio * gain + +wav_normalized = normalize_audio(wav) +``` + +### Poor quality output + +**Problem**: Generated music sounds bad or noisy + +**Solutions**: +```python +# Use larger model +model = MusicGen.get_pretrained('facebook/musicgen-large') + +# Adjust generation parameters +model.set_generation_params( + duration=15, + top_k=250, # Increase for more diversity + temperature=0.8, # Lower for more focused output + cfg_coef=4.0 # Increase for better text adherence +) + +# Use better prompts +# Bad: "music" +# Good: "upbeat electronic dance music with synthesizers and punchy drums" + +# Try MultiBand Diffusion +from audiocraft.models import MultiBandDiffusion +mbd = MultiBandDiffusion.get_mbd_musicgen() +tokens = model.generate_tokens(["prompt"]) +wav = mbd.tokens_to_wav(tokens) +``` + +### Generation too short + +**Problem**: Audio shorter than expected + +**Solutions**: +```python +# Check duration setting +model.set_generation_params(duration=30) # Set before generate + +# Verify in generation +print(f"Duration setting: {model.generation_params}") + +# Check output shape +wav = model.generate(["prompt"]) +actual_duration = wav.shape[-1] / 32000 +print(f"Actual duration: {actual_duration}s") + +# Note: max duration is typically 30s +``` + +### Melody conditioning fails + +**Error**: Issues with melody-conditioned generation + +**Solutions**: +```python +import torchaudio +from audiocraft.models import MusicGen + +# Load melody model (not base model) +model = MusicGen.get_pretrained('facebook/musicgen-melody') + +# Load and prepare melody +melody, sr = torchaudio.load("melody.wav") + +# Resample to model sample rate if needed +if sr != 32000: + resampler = torchaudio.transforms.Resample(sr, 32000) + melody = resampler(melody) + +# Ensure correct shape [batch, channels, samples] +if melody.dim() == 1: + melody = melody.unsqueeze(0).unsqueeze(0) +elif melody.dim() == 2: + melody = melody.unsqueeze(0) + +# Convert stereo to mono +if melody.shape[1] > 1: + melody = melody.mean(dim=1, keepdim=True) + +# Generate with melody +model.set_generation_params(duration=min(melody.shape[-1] / 32000, 30)) +wav = model.generate_with_chroma(["piano cover"], melody, 32000) +``` + +## Memory Issues + +### CUDA out of memory + +**Error**: `torch.cuda.OutOfMemoryError: CUDA out of memory` + +**Solutions**: +```python +import torch + +# Clear cache before generation +torch.cuda.empty_cache() + +# Use smaller model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Reduce duration +model.set_generation_params(duration=10) # Instead of 30 + +# Generate one at a time +for prompt in prompts: + wav = model.generate([prompt]) + save_audio(wav) + torch.cuda.empty_cache() + +# Use CPU for very large generations +model = MusicGen.get_pretrained('facebook/musicgen-small', device="cpu") +``` + +### Memory leak during batch processing + +**Problem**: Memory grows over time + +**Solutions**: +```python +import gc +import torch + +def generate_with_cleanup(model, prompts): + results = [] + + for prompt in prompts: + with torch.no_grad(): + wav = model.generate([prompt]) + results.append(wav.cpu()) + + # Cleanup + del wav + gc.collect() + torch.cuda.empty_cache() + + return results + +# Use context manager +with torch.inference_mode(): + wav = model.generate(["prompt"]) +``` + +## Audio Format Issues + +### Wrong sample rate + +**Problem**: Audio plays at wrong speed + +**Solutions**: +```python +import torchaudio + +# MusicGen outputs at 32kHz +sample_rate = 32000 + +# AudioGen outputs at 16kHz +sample_rate = 16000 + +# Always use correct rate when saving +torchaudio.save("output.wav", wav[0].cpu(), sample_rate=sample_rate) + +# Resample if needed +resampler = torchaudio.transforms.Resample(32000, 44100) +wav_resampled = resampler(wav) +``` + +### Stereo/mono mismatch + +**Problem**: Wrong number of channels + +**Solutions**: +```python +# Check model type +print(f"Audio channels: {wav.shape}") +# Mono: [batch, 1, samples] +# Stereo: [batch, 2, samples] + +# Convert mono to stereo +if wav.shape[1] == 1: + wav_stereo = wav.repeat(1, 2, 1) + +# Convert stereo to mono +if wav.shape[1] == 2: + wav_mono = wav.mean(dim=1, keepdim=True) + +# Use stereo model for stereo output +model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium') +``` + +### Clipping and distortion + +**Problem**: Audio has clipping or distortion + +**Solutions**: +```python +import torch + +# Check for clipping +max_val = wav.abs().max().item() +print(f"Max amplitude: {max_val}") + +# Normalize to prevent clipping +if max_val > 1.0: + wav = wav / max_val + +# Apply soft clipping +def soft_clip(x, threshold=0.9): + return torch.tanh(x / threshold) * threshold + +wav_clipped = soft_clip(wav) + +# Lower temperature during generation +model.set_generation_params(temperature=0.7) # More controlled +``` + +## HuggingFace Transformers Issues + +### Processor errors + +**Error**: Issues with MusicgenProcessor + +**Solutions**: +```python +from transformers import AutoProcessor, MusicgenForConditionalGeneration + +# Load matching processor and model +processor = AutoProcessor.from_pretrained("facebook/musicgen-small") +model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small") + +# Ensure inputs are on same device +inputs = processor( + text=["prompt"], + padding=True, + return_tensors="pt" +).to("cuda") + +# Check processor configuration +print(processor.tokenizer) +print(processor.feature_extractor) +``` + +### Generation parameter errors + +**Error**: Invalid generation parameters + +**Solutions**: +```python +# HuggingFace uses different parameter names +audio_values = model.generate( + **inputs, + do_sample=True, # Enable sampling + guidance_scale=3.0, # CFG (not cfg_coef) + max_new_tokens=256, # Token limit (not duration) + temperature=1.0 +) + +# Calculate tokens from duration +# ~50 tokens per second +duration_seconds = 10 +max_tokens = duration_seconds * 50 +audio_values = model.generate(**inputs, max_new_tokens=max_tokens) +``` + +## Performance Issues + +### Slow generation + +**Problem**: Generation takes too long + +**Solutions**: +```python +# Use smaller model +model = MusicGen.get_pretrained('facebook/musicgen-small') + +# Reduce duration +model.set_generation_params(duration=10) + +# Use GPU +model.to("cuda") + +# Enable flash attention if available +# (requires compatible hardware) + +# Batch multiple prompts +prompts = ["prompt1", "prompt2", "prompt3"] +wav = model.generate(prompts) # Single batch is faster than loop + +# Use compile (PyTorch 2.0+) +model.lm = torch.compile(model.lm) +``` + +### CPU fallback + +**Problem**: Generation running on CPU instead of GPU + +**Solutions**: +```python +import torch + +# Check CUDA availability +print(f"CUDA available: {torch.cuda.is_available()}") +print(f"CUDA device: {torch.cuda.get_device_name(0)}") + +# Explicitly move to GPU +model = MusicGen.get_pretrained('facebook/musicgen-small') +model.to("cuda") + +# Verify model device +print(f"Model device: {next(model.lm.parameters()).device}") +``` + +## Common Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| `CUDA out of memory` | Model too large | Use smaller model, reduce duration | +| `ffmpeg not found` | FFmpeg not installed | Install FFmpeg | +| `No module named 'audiocraft'` | Not installed | `pip install audiocraft` | +| `RuntimeError: Expected 3D tensor` | Wrong input shape | Check tensor dimensions | +| `KeyError: 'melody'` | Wrong model for melody | Use musicgen-melody | +| `Sample rate mismatch` | Wrong audio format | Resample to model rate | + +## Getting Help + +1. **GitHub Issues**: https://github.com/facebookresearch/audiocraft/issues +2. **HuggingFace Forums**: https://discuss.huggingface.co +3. **Paper**: https://arxiv.org/abs/2306.05284 + +### Reporting Issues + +Include: +- Python version +- PyTorch version +- CUDA version +- AudioCraft version: `pip show audiocraft` +- Full error traceback +- Minimal reproducible code +- Hardware (GPU model, VRAM) diff --git a/optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md b/optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md new file mode 100644 index 0000000000000000000000000000000000000000..d81dbc9ed83232eb5596e4f2423c92c8b44d1c7d --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md @@ -0,0 +1,48 @@ +# Port Notes — baoyu-article-illustrator + +Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0. + +## Changes from upstream + +`SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` were adapted. The 23 style files and 4 palette files are verbatim copies. The `references/config/` directory was removed entirely. + +### Adaptations + +| Change | Upstream | Hermes | +|--------|----------|--------| +| Metadata namespace | `openclaw` | `hermes` | +| Trigger | `/baoyu-article-illustrator` slash command + CLI flags | Natural language skill matching | +| User config | EXTEND.md (project/user/XDG paths) + first-time-setup | Removed — not part of Hermes infra | +| User prompts | `AskUserQuestion` (batched, multi-question) | `clarify` tool (one question at a time) | +| Image generation | `baoyu-imagine` (Bun/TypeScript, multi-provider, accepts `--ref`, writes to local path) | `image_generate` (returns URL only; agent downloads via `terminal`/`curl`) | +| Backend selection | User picks provider via CLI flags | Not agent-selectable — `image_generate` uses the user-configured FAL model. Removed hardcoded "nano banana pro" line from `prompts/system.md`. | +| Reference images | Passed to backend via `--ref`, copied via shell | `vision_analyze` extracts a textual description (binary never touched by `write_file`/`read_file`); description is embedded in prompts. Optional `terminal cp` for a local record. | +| Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only | +| File operations | Bash commands | Hermes file tools: `write_file`/`read_file` for text, `terminal` for binaries and URL downloads, `vision_analyze` for reading images | +| Watermark | Driven by EXTEND.md `watermark.enabled` | Optional — user asks for it per-article | +| Output directory | EXTEND.md `default_output_dir` (imgs-subdir / same-dir / illustrations-subdir / independent) | Defaults based on input type; user overrides in request | + +### What was preserved + +- Type × Style × Palette three-dimension framework +- All style definitions (23 files, verbatim) +- All palette definitions (4 files, verbatim) +- Core reference files (workflow, prompt-construction, styles, style-presets) — adapted for Hermes tooling +- Core principles and workflow structure (analyze → confirm → outline → prompts → generate) +- Prompt-file-as-reproducibility-record discipline +- Author, version, homepage attribution + +## Syncing with upstream + +To pull upstream updates: + +```bash +# Compare versions +curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5 +# Look for version: line + +# Diff style/palette files (safe to overwrite — unchanged from upstream) +diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md +``` + +`references/styles/*` and `references/palettes/*` can be overwritten directly. `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` must be manually merged since they contain Hermes-specific adaptations (tool wiring, backend neutrality, removed EXTEND.md references). diff --git a/optional-skills/creative/baoyu-article-illustrator/SKILL.md b/optional-skills/creative/baoyu-article-illustrator/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..6adbebf0e98c8c8f8e3a4a14c7aec35ea2bf6a24 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/SKILL.md @@ -0,0 +1,207 @@ +--- +name: baoyu-article-illustrator +description: "Article illustrations: type × style × palette consistency." +version: 1.57.0 +author: 宝玉 (JimLiu) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [article-illustration, creative, image-generation] + category: creative + homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator +--- + +# Article Illustrator + +Adapted from [baoyu-article-illustrator](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem. + +Analyze articles, identify illustration positions, generate images with **Type × Style × Palette** consistency. + +## When to Use + +Trigger this skill when the user asks to illustrate an article, add images to an article, generate illustrations for content, or uses phrases like "为文章配图", "illustrate article", or "add images". The user provides an article (file path or pasted content) and optionally specifies type, style, palette, or density. + +## Three Dimensions + +| Dimension | Controls | Examples | +|-----------|----------|----------| +| **Type** | Information structure | infographic, scene, flowchart, comparison, framework, timeline | +| **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant | +| **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors | + +Combine freely: `type=infographic, style=vector-illustration, palette=macaron`. + +Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](references/style-presets.md). + +## Types + +| Type | Best For | +|------|----------| +| `infographic` | Data, metrics, technical | +| `scene` | Narratives, emotional | +| `flowchart` | Processes, workflows | +| `comparison` | Side-by-side, options | +| `framework` | Models, architecture | +| `timeline` | History, evolution | + +## Styles + +See [references/styles.md](references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility. + +## Output Structure + +``` +{output-dir}/ +├── source-{slug}.{ext} # Only for pasted content +├── outline.md +├── prompts/ +│ └── NN-{type}-{slug}.md +└── NN-{type}-{slug}.png +``` + +**Default output directory**: + +| Input | Output Directory | Markdown Insert Path | +|-------|------------------|----------------------| +| Article file path | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` | +| Pasted content | `illustrations/{topic-slug}/` (cwd) | `illustrations/{topic-slug}/NN-{type}-{slug}.png` | + +If the user asks for a different layout (e.g., images alongside the article, or a `illustrations/` subdirectory), honor that. + +**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`. + +## Core Principles + +- **Visualize concepts, not metaphors** — if the article uses a metaphor (e.g., "电锯切西瓜"), illustrate the underlying concept, not the literal image. +- **Labels use article data** — actual numbers, terms, and quotes from the article, not generic placeholders. +- **Prompt files are reproducibility records** — every illustration must have a saved prompt file under `prompts/` before any image is generated. +- **Strip secrets** — scan source content for API keys, tokens, or credentials before writing anything to disk. + +## Workflow + +``` +- [ ] Step 1: Detect reference images (if provided) +- [ ] Step 2: Analyze content +- [ ] Step 3: Confirm settings (clarify tool, one question at a time) +- [ ] Step 4: Generate outline +- [ ] Step 5: Generate prompts +- [ ] Step 6: Generate images (image_generate) +- [ ] Step 7: Finalize +``` + +### Step 1: Detect Reference Images + +If the user supplies reference images (paths pasted inline, attachments, or a URL): + +1. For each reference, call `vision_analyze` with the path/URL and a question asking for style, palette, composition, and subject. Record the returned description in `{output-dir}/references/NN-ref-{slug}.md` via `write_file`. +2. **Do not** try to copy the binary via `write_file` / `read_file` — those are text-only. If you want a local copy for the record, use `terminal` (`cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"`). The skill itself never needs to read the binary; it works off the vision description. +3. Since `image_generate` doesn't take image inputs, the vision description is what gets embedded in prompts during Step 5. + +Full procedures: [references/workflow.md](references/workflow.md#step-1-detect-reference-images). + +### Step 2: Analyze + +| Analysis | Output | +|----------|--------| +| Content type | Technical / Tutorial / Methodology / Narrative | +| Purpose | information / visualization / imagination | +| Core arguments | 2-5 main points | +| Positions | Where illustrations add value | + +Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`. + +Full procedures: [references/workflow.md](references/workflow.md#step-2-analyze). + +### Step 3: Confirm Settings + +Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question whose answer is already present in the user's request. + +| Order | Question | Options | +|-------|----------|---------| +| Q1 | **Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed | +| Q2 | **Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) | +| Q3 | **Style** *(skip if preset chosen in Q1)* | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster | +| Q4 | **Palette** *(optional)* | Default (style colors), macaron, warm, neon | +| Q5 | **Language** *(only if article language is ambiguous)* | article language / user language | + +Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely. + +Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings). + +### Step 4: Generate Outline → `outline.md` + +Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, density, style, palette, image_count) and one entry per illustration: + +```yaml +## Illustration 1 +**Position**: [section/paragraph] +**Purpose**: [why] +**Visual Content**: [what to show] +**Filename**: 01-infographic-concept-name.png +``` + +Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline). + +### Step 5: Generate Prompts + +**BLOCKING**: Every illustration must have a saved prompt file before any image is generated — the prompt file is the reproducibility record. + +For each illustration: + +1. Create a prompt file per [references/prompt-construction.md](references/prompt-construction.md). +2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter. +3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT). +4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes. +5. Process references (`direct`/`style`/`palette`) per prompt frontmatter — for `direct` usage, embed a textual description of the reference in the prompt (since `image_generate` doesn't take reference-image inputs). + +### Step 6: Generate Images + +For each prompt file: + +1. Call `image_generate(prompt=..., aspect_ratio=...)`. `image_generate` returns a JSON result containing an image URL; it does NOT write to disk and does NOT accept an output path. +2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect. +3. Download the returned URL to `{output-dir}/NN-{type}-{slug}.png` via `terminal` (e.g. `curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{url}"`). +4. On generation failure, auto-retry once. + +Note: the underlying image-generation backend is user-configured (default: FAL FLUX 2 Klein 9B) and is NOT agent-selectable via `image_generate`. Do not write model names into prompts expecting them to route. + +### Step 7: Finalize + +Insert `![description]({relative-path}/NN-{type}-{slug}.png)` after the corresponding paragraph. Alt text: concise description in the article's language. + +Report: + +``` +Article Illustration Complete! +Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default] +Images: X/N generated +``` + +## Modification + +| Action | Steps | +|--------|-------| +| Edit | Update prompt → Regenerate → Update reference | +| Add | Position → Prompt → Generate → Update outline → Insert | +| Delete | Delete files → Remove reference → Update outline | + +## References + +| File | Content | +|------|---------| +| [references/workflow.md](references/workflow.md) | Detailed procedures | +| [references/usage.md](references/usage.md) | Invocation examples | +| [references/styles.md](references/styles.md) | Style gallery + Palette gallery | +| [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) | +| [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates | + +## Pitfalls + +1. **Data integrity is paramount** — never summarize, paraphrase, or alter source statistics. "73% increase" stays "73% increase". +2. **Strip secrets** — scan source content for API keys, tokens, or credentials before including in any output file. +3. **Don't illustrate metaphors literally** — visualize the underlying concept. +4. **Prompt files are mandatory** — no image generation without a saved prompt file. The file is what lets you regenerate or switch backends later. +5. **`image_generate` aspect ratios** — the tool supports `landscape`, `portrait`, and `square`. Custom ratios map to the nearest option. +6. **`image_generate` returns a URL, not a local file** — always download via `terminal` (`curl`) before inserting local image paths into the article. +7. **No backend selection from the agent** — `image_generate` uses whatever model the user configured (default: FAL FLUX 2 Klein 9B). Don't write `"use to generate this"` into prompts expecting it to route. diff --git a/optional-skills/creative/baoyu-article-illustrator/prompts/system.md b/optional-skills/creative/baoyu-article-illustrator/prompts/system.md new file mode 100644 index 0000000000000000000000000000000000000000..3320564c4d4670f5ae7a43645a2a01abb1c40666 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/prompts/system.md @@ -0,0 +1,32 @@ +Create a cartoon-style infographic illustration following these guidelines: + +## Image Specifications + +- **Type**: Infographic illustration +- **Orientation**: Landscape (horizontal) +- **Aspect Ratio**: 16:9 +- **Style**: Hand-drawn illustration + +## Core Principles + +- Hand-drawn quality throughout - NO realistic or photographic elements +- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate +- Keep information concise, highlight keywords and core concepts +- Use ample whitespace for easy visual scanning +- Maintain clear visual hierarchy + +## Text Style (When Text Included) + +- **ALL text MUST be hand-drawn style** +- Text should be readable and complement the visual +- Font style harmonizes with illustration style +- **DO NOT use realistic or computer-generated fonts** + +## Language + +- Use the same language as the content provided below for any text elements +- Match punctuation style to the content language + +--- + +Generate the illustration based on the content provided below: diff --git a/optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md b/optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md new file mode 100644 index 0000000000000000000000000000000000000000..e7d7a6bac9505d5563264a47701d3384af12db1c --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md @@ -0,0 +1,33 @@ +# macaron + +Soft macaron pastel color blocks on warm cream + +## Background + +- Color: Warm Cream (#F5F0E8) +- Texture: Subtle warm paper grain + +## Colors + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Background | Warm Cream | #F5F0E8 | Primary background | +| Primary Text | Deep Charcoal | #2D2D2D | Headlines, main text, outlines | +| Macaron Blue | Sky Blue | #A8D8EA | Info block fill, cool-toned zones | +| Macaron Mint | Mint Green | #B5E5CF | Info block fill, growth/positive zones | +| Macaron Lavender | Lavender | #D5C6E0 | Info block fill, abstract/concept zones | +| Macaron Peach | Peach | #FFD5C2 | Info block fill, warm-toned zones | +| Accent | Coral Red | #E8655A | Key data, warnings, emphasis | +| Muted Text | Warm Gray | #6B6B6B | Secondary annotations, small labels | + +## Accent + +Coral Red (#E8655A) for key data, warnings, and emphasis highlights. Use sparingly — one or two elements per illustration. + +## Semantic Constraint + +Soft pastel macaron color palette. Use block colors as rounded card backgrounds for distinct information sections. Accent coral red sparingly for emphasis on key terms only. Do NOT render color names, hex codes, or role labels as visible text in the image. + +## Best For + +Educational content, knowledge sharing, concept explainers, tutorials, tech summaries, onboarding materials diff --git a/optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md b/optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md new file mode 100644 index 0000000000000000000000000000000000000000..88132f960a7822020e64f9d8326031fbbe236a10 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md @@ -0,0 +1,42 @@ +# mono-ink + +Black ink on pure white with sparse semantic accent colors + +## Background + +- Color: Pure White (#FFFFFF) +- Texture: Clean, no grain, no tint + +## Colors + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Background | Pure White | #FFFFFF | Canvas | +| Primary | Near Black | #1A1A1A | All lines, text, figures, arrows | +| Accent (risk/emphasis) | Coral Red | #E8655A | Risk, problem, gap, key emphasis | +| Accent (positive) | Muted Teal | #5FA8A8 | Positive, solution, "after" state | +| Accent (neutral tag) | Dusty Lavender | #9B8AB5 | Neutral tags, category labels | +| Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) | + +## Accent + +Use black ink for all structural elements — lines, text, figures. Accent colors appear only for semantic highlighting: coral red for risks/gaps/problems, muted teal for positive/solution/after-states, dusty lavender for neutral category tags. Total colored pixels must remain under 10% of canvas. Pale gray may back a subtle zone but must never dominate. + +## Semantic Constraint + +Black ink on white canvas. Accent colors for semantic highlighting only — total colored pixels under 10% of canvas. Do NOT render color names, hex codes, or role labels as visible text in the image. + +## Compatible With + +- `ink-notes` (primary, default pairing) +- `minimal` (strict monochrome variation, drops the style's built-in accent) +- `sketch` (pencil + ink hybrid look) + +## Not Recommended With + +- `sketch-notes` — its "no pure white backgrounds" rule conflicts +- `warm`, `elegant`, `watercolor`, `fantasy-animation` — color-heavy by design, mono-ink strips their identity + +## Best For + +Professional visual notes, Before/After essays, tech manifestos, framework analogies, whiteboard-presentation explainers diff --git a/optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md b/optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md new file mode 100644 index 0000000000000000000000000000000000000000..d863d676da29452f690d54780b6e264dd23c8e4e --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md @@ -0,0 +1,33 @@ +# neon + +Vibrant neon colors on dark backgrounds + +## Background + +- Color: Deep Purple (#2D1B4E) +- Texture: Subtle grid pattern or solid dark + +## Colors + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Background | Deep Purple | #2D1B4E | Primary background | +| Alt Background | Dark Teal | #0F4C5C | Alternative sections | +| Primary | Hot Pink | #FF1493 | Main accent | +| Secondary | Electric Cyan | #00FFFF | Supporting elements | +| Tertiary | Neon Yellow | #FFFF00 | Highlights | +| Accent 1 | Lime Green | #32CD32 | Energy, success | +| Accent 2 | Orange | #FF6B35 | Warmth | +| Text | White | #FFFFFF | Text elements | + +## Accent + +Hot Pink (#FF1493) for primary emphasis. High contrast neon-on-dark creates immediate visual impact. + +## Semantic Constraint + +Vibrant neon-on-dark palette. High contrast, immediate visual impact. Do NOT render color names, hex codes, or role labels as visible text in the image. + +## Best For + +Gaming, retro tech, 80s/90s nostalgic content, bold editorial, trend and pop culture diff --git a/optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md b/optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md new file mode 100644 index 0000000000000000000000000000000000000000..c2e7afa026e8acc70b97927f681f71613ca9fee0 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md @@ -0,0 +1,32 @@ +# warm + +Warm earth tones on soft peach, no cool colors + +## Background + +- Color: Soft Peach (#FFECD2) +- Texture: Warm paper texture + +## Colors + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Background | Soft Peach | #FFECD2 | Primary background | +| Outlines | Deep Charcoal | #2D2D2D | All element outlines | +| Primary | Warm Orange | #ED8936 | Main accent color | +| Secondary | Terracotta | #C05621 | Warm depth | +| Tertiary | Golden Yellow | #F6AD55 | Highlights, energy | +| Accent | Deep Brown | #744210 | Grounding, anchoring | +| Text | Warm Charcoal | #4A4A4A | Text elements | + +## Accent + +Warm Orange (#ED8936) for primary emphasis. Warm-only palette — no cool colors (no green, blue, purple). Modern-retro feel. + +## Semantic Constraint + +Warm earth tone palette. Warm-only — no cool colors (no green, blue, purple). Do NOT render color names, hex codes, or role labels as visible text in the image. + +## Best For + +Product showcases, team introductions, feature grids, brand content, personal growth, lifestyle diff --git a/optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md b/optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md new file mode 100644 index 0000000000000000000000000000000000000000..611359eb168381a90b63078cbbb939aa78794df7 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md @@ -0,0 +1,426 @@ +# Prompt Construction + +## Prompt File Format + +Each prompt file uses YAML frontmatter + content: + +```yaml +--- +illustration_id: 01 +type: infographic +style: blueprint +references: # ⚠️ ONLY if files EXIST in references/ directory + - ref_id: 01 + filename: 01-ref-diagram.png + usage: direct # direct | style | palette +--- + +[Type-specific template content below...] +``` + +**⚠️ CRITICAL - When to include `references` field**: + +| Situation | Action | +|-----------|--------| +| Reference file saved to `references/` | Include in frontmatter ✓ | +| Style extracted verbally (no file) | DO NOT include in frontmatter, append to prompt body instead | +| File path in frontmatter but file doesn't exist | ERROR - remove references field | + +**Reference Usage Types** (only when file exists): + +| Usage | Description | Generation Action | +|-------|-------------|-------------------| +| `direct` | Primary visual reference | Describe the reference (composition, subject, style, palette) in prompt text — `image_generate` does not accept reference-image inputs | +| `style` | Style characteristics only | Describe style in prompt text | +| `palette` | Color palette extraction | Include colors in prompt | + +**If no reference file but style/palette extracted verbally**, append directly to prompt body: +``` +COLORS (from reference): +- Primary: #E8756D coral +- Secondary: #7ECFC0 mint +... + +STYLE (from reference): +- Clean lines, minimal shadows +- Gradient backgrounds +... +``` + +--- + +## Default Composition Requirements + +**Apply to ALL prompts by default**: + +| Requirement | Description | +|-------------|-------------| +| **Clean composition** | Simple layouts, no visual clutter | +| **White space** | Generous margins, breathing room around elements | +| **No complex backgrounds** | Solid colors or subtle gradients only, avoid busy textures | +| **Centered or content-appropriate** | Main visual elements centered or positioned by content needs | +| **Matching graphics** | Use graphic elements that align with content theme | +| **Highlight core info** | White space draws attention to key information | + +**Add to ALL prompts**: +> Clean composition with generous white space. Simple or no background. Main elements centered or positioned by content needs. + +--- + +## Color Specification Rules + +Colors in prompts use hex codes for **rendering guidance only** — they tell the model which colors to use, NOT what text to display. + +**⚠️ CRITICAL**: Image generation models sometimes render color names and hex values as visible text labels in the image (e.g., painting "Macaron Blue #A8D8EA" as a label). This must be prevented. + +**Add to ALL prompts that contain a COLORS section**: +> Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image. + +--- + +## Character Rendering + +When depicting people: + +| Guideline | Description | +|-----------|-------------| +| **Style** | Simplified cartoon silhouettes or symbolic expressions | +| **Avoid** | Realistic human portrayals, detailed faces | +| **Diversity** | Varied body types when showing multiple people | +| **Emotion** | Express through posture and simple gestures | + +**Add to ALL prompts with human figures**: +> Human figures: simplified stylized silhouettes or symbolic representations, not photorealistic. + +--- + +## Text in Illustrations + +| Element | Guideline | +|---------|-----------| +| **Size** | Large, prominent, immediately readable | +| **Style** | Handwritten fonts preferred for warmth | +| **Content** | Concise keywords and core concepts only | +| **Language** | Match article language | + +**Add to prompts with text**: +> Text should be large and prominent with handwritten-style fonts. Keep minimal, focus on keywords. + +--- + +## Principles + +Good prompts must include: + +1. **Layout Structure First**: Describe composition, zones, flow direction +2. **Specific Data/Labels**: Use actual numbers, terms from article +3. **Visual Relationships**: How elements connect +4. **Semantic Colors**: Meaning-based color choices (red=warning, green=efficient) +5. **Style Characteristics**: Line treatment, texture, mood +6. **Aspect Ratio**: End with ratio and complexity level + +## Type-Specific Templates + +### Infographic + +``` +[Title] - Data Visualization + +Layout: [grid/radial/hierarchical] + +ZONES: +- Zone 1: [data point with specific values] +- Zone 2: [comparison with metrics] +- Zone 3: [summary/conclusion] + +LABELS: [specific numbers, percentages, terms from article] +COLORS: [semantic color mapping] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +**Infographic + vector-illustration**: +``` +Flat vector illustration infographic. Clean black outlines on all elements. +COLORS: Cream background (#F5F0E6), Coral Red (#E07A5F), Mint Green (#81B29A), Mustard Yellow (#F2CC8F) +ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements (dots, stars) +``` + +**Infographic + vector-illustration + warm palette**: +``` +Flat vector illustration infographic. Clean black outlines on all elements. +PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors. +COLORS: Soft Peach background (#FFECD2), Warm Orange (#ED8936), + Terracotta (#C05621), Golden Yellow (#F6AD55), Deep Brown (#744210) +ELEMENTS: Geometric simplified icons, no gradients, rounded corners, + modular card layout, consistent icon style +``` + +### Scene + +``` +[Title] - Atmospheric Scene + +FOCAL POINT: [main subject] +ATMOSPHERE: [lighting, mood, environment] +MOOD: [emotion to convey] +COLOR TEMPERATURE: [warm/cool/neutral] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +### Flowchart + +``` +[Title] - Process Flow + +Layout: [left-right/top-down/circular] + +STEPS: +1. [Step name] - [brief description] +2. [Step name] - [brief description] +... + +CONNECTIONS: [arrow types, decision points] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +**Flowchart + vector-illustration**: +``` +Flat vector flowchart with bold arrows and geometric step containers. +COLORS: Cream background (#F5F0E6), steps in Coral/Mint/Mustard, black outlines +ELEMENTS: Rounded rectangles, thick arrows, simple icons per step +``` + +**Flowchart + sketch-notes + macaron palette**: +``` +Hand-drawn educational flowchart on warm cream paper. Slight wobble on all lines. +PALETTE: macaron — soft pastel color blocks +COLORS: Warm Cream background (#F5F0E8), zone fills in Macaron Blue (#A8D8EA), + Lavender (#D5C6E0), Mint (#B5E5CF), Coral Red (#E8655A) for emphasis +ELEMENTS: Rounded cards with dashed/solid borders, wavy hand-drawn arrows with labels, + simple stick-figure characters, doodle decorations (stars, underlines) +STYLE: Color fills don't completely fill outlines, hand-drawn lettering, generous white space +``` + +**Flowchart + ink-notes + mono-ink palette**: +``` +Professional hand-drawn visual-note flowchart on pure white. Black ink line work +with slight wobble, à la Mike Rohde sketchnoting. +PALETTE: mono-ink — black ink dominant, sparse semantic accents +COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines, + text, and figures; Coral Red (#E8655A) only for risk/emphasis, + Muted Teal (#5FA8A8) only for positive/solution states +ELEMENTS: Left-to-right stage boxes with rounded-rect frames, wavy hand-drawn + arrows between stages, simple stick-figure characters with role + labels above (e.g., "ML Engineer", "Team Lead"), dashed-border box + for future/empty stage, small doodle icons per stage +STYLE: Hand-lettered titles (bold, oversized), handwritten stage labels and + annotations, generous white space, bottom tagline summarizing takeaway +``` + +### Comparison + +``` +[Title] - Comparison View + +LEFT SIDE - [Option A]: +- [Point 1] +- [Point 2] + +RIGHT SIDE - [Option B]: +- [Point 1] +- [Point 2] + +DIVIDER: [visual separator] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +**Comparison + vector-illustration**: +``` +Flat vector comparison with split layout. Clear visual separation. +COLORS: Left side Coral (#E07A5F), Right side Mint (#81B29A), cream background +ELEMENTS: Bold icons, black outlines, centered divider line +``` + +**Comparison + vector-illustration + warm palette**: +``` +Flat vector comparison with split layout. Clear visual separation. +PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors. +COLORS: Left side Warm Orange (#ED8936), Right side Terracotta (#C05621), + Soft Peach background (#FFECD2), Deep Brown (#744210) accents +ELEMENTS: Bold icons, black outlines, centered divider line +``` + +**Comparison + ink-notes + mono-ink palette** (Before/After, Traditional vs New): +``` +Professional hand-drawn sketchnote comparison on pure white. Black ink line work +with slight wobble, à la Mike Rohde sketchnoting. +PALETTE: mono-ink — black ink dominant, sparse semantic accents +COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all outlines, + text, figures, arrows; Coral Red (#E8655A) reserved for risks/gaps + (left/Before side); Muted Teal (#5FA8A8) reserved for positives + (right/After side). Color accents under 10% of canvas. +LAYOUT: Left | Right split with vertical hand-drawn divider. Hand-lettered + "Before" label (top-left) and "After" label (top-right). +LEFT SIDE: Stick figure(s) with role label above, speech bubble showing the + pain point, bulleted pain-point list in handwritten text. +RIGHT SIDE: Stick figure(s) showing the new state, bulleted improvement list, + small positive-action icons. +BRIDGE: Curved hand-drawn "mindset shift" arrow bridging left → right with + small inline label describing the shift. +BOTTOM: Single-line hand-lettered tagline summarizing the takeaway. +STYLE: Hand-lettered headings (bold, oversized), handwritten body annotations, + generous white space, no computer fonts, no gradients, no shadows. +``` + +### Framework + +``` +[Title] - Conceptual Framework + +STRUCTURE: [hierarchical/network/matrix] + +NODES: +- [Concept 1] - [role] +- [Concept 2] - [role] + +RELATIONSHIPS: [how nodes connect] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +**Framework + vector-illustration**: +``` +Flat vector framework diagram with geometric nodes and bold connectors. +COLORS: Cream background (#F5F0E6), nodes in Coral/Mint/Mustard/Blue, black outlines +ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines +``` + +**Framework + vector-illustration + warm palette**: +``` +Flat vector framework diagram with geometric nodes and bold connectors. +PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors. +COLORS: Soft Peach background (#FFECD2), nodes in Warm Orange (#ED8936), + Terracotta (#C05621), Golden Yellow (#F6AD55), black outlines +ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines +``` + +**Framework + ink-notes + mono-ink palette** (command center, OS analogy): +``` +Professional hand-drawn sketchnote framework on pure white. Black ink line work +with slight wobble, à la Mike Rohde sketchnoting. +PALETTE: mono-ink — black ink dominant, sparse semantic accents +COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines, + text, figures; Dusty Lavender (#9B8AB5) for neutral category tags only; + Coral Red (#E8655A) for emphasis sparingly. Color accents under 10%. +STRUCTURE: Central rounded-rectangle frame as "the system" with hand-lettered + title inside. Inner layer of labeled sub-components (node labels + above each). Outer layer of feeder arrows from stick-figure + operators/users with role labels. +ELEMENTS: Stick figures at the edges with role tags ("Team Lead", "Operator"), + wavy hand-drawn connector arrows with small inline labels, small + doodle icons per component, dashed-border placeholder(s) for + future/empty capabilities. +BOTTOM: Single-line hand-lettered tagline. +STYLE: Hand-lettered headings, handwritten annotations, generous white space, + no computer fonts, no gradients. +``` + +### Timeline + +``` +[Title] - Chronological View + +DIRECTION: [horizontal/vertical] + +EVENTS: +- [Date/Period 1]: [milestone] +- [Date/Period 2]: [milestone] + +MARKERS: [visual indicators] +STYLE: [style characteristics] +ASPECT: 16:9 +``` + +### Screen-Print Style Override + +When `style: screen-print`, replace standard style instructions with: + +``` +Screen print / silkscreen poster art. Flat color blocks, NO gradients. +COLORS: 2-5 colors maximum. [Choose from style palette or duotone pair] +TEXTURE: Halftone dot patterns, slight color layer misregistration, paper grain +COMPOSITION: Bold silhouettes, geometric framing, negative space as storytelling element +FIGURES: Silhouettes only, no detailed faces, stencil-cut edges +TYPOGRAPHY: Bold condensed sans-serif integrated into composition (not overlaid) +``` + +**Scene + screen-print**: +``` +Conceptual poster scene. Single symbolic focal point, NOT literal illustration. +COLORS: Duotone pair (e.g., Burnt Orange #E8751A + Deep Teal #0A6E6E) on Off-Black #121212 +COMPOSITION: Centered silhouette or geometric frame, 60%+ negative space +TEXTURE: Halftone dots, paper grain, slight print misregistration +``` + +**Comparison + screen-print**: +``` +Split poster composition. Each side dominated by one color from duotone pair. +LEFT: [Color A] side with silhouette/icon for [Option A] +RIGHT: [Color B] side with silhouette/icon for [Option B] +DIVIDER: Geometric shape or negative space boundary +TEXTURE: Halftone transitions between sides +``` + +--- + +## Palette Override + +When a palette is specified (via `--palette` or preset), it overrides the style's default colors: + +1. Read style file → get rendering rules (Visual Elements, Style Rules, line treatment) +2. Read palette file (`palettes/.md`) → get Colors + Background +3. Palette Colors **replace** style's default Color Palette in prompt +4. Palette Background **replaces** style's Background color (keep style's texture description) +5. Build prompt: style rendering instructions + palette colors + +**Prompt frontmatter** includes palette when specified: +```yaml +--- +illustration_id: 01 +type: infographic +style: vector-illustration +palette: macaron +--- +``` + +**Example**: `vector-illustration` + `macaron` palette: +``` +Flat vector illustration infographic. Clean black outlines on all elements. +PALETTE: macaron — soft pastel color blocks +COLORS: Warm Cream background (#F5F0E8), Macaron Blue (#A8D8EA), Mint (#B5E5CF), + Lavender (#D5C6E0), Peach (#FFD5C2), Coral Red (#E8655A) for emphasis +ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements +``` + +When no palette is specified, use the style's built-in Color Palette as before. + +--- + +## What to Avoid + +- Vague descriptions ("a nice image") +- Literal metaphor illustrations +- Missing concrete labels/annotations +- Generic decorative elements + +## Watermark Integration (optional) + +If the user asks for a watermark, append: + +``` +Include a subtle watermark "[content]" positioned at [position]. +``` diff --git a/optional-skills/creative/baoyu-article-illustrator/references/style-presets.md b/optional-skills/creative/baoyu-article-illustrator/references/style-presets.md new file mode 100644 index 0000000000000000000000000000000000000000..5e0777f5ae1b40642c477427f3100dc3e840fb5c --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/style-presets.md @@ -0,0 +1,80 @@ +# Style Presets + +A preset expands to a type + style + optional palette combination. Users can override any dimension in their request. + +## By Category + +### Technical & Engineering + +| Preset | Type | Style | Palette | Best For | +|----------|------|-------|---------|----------| +| `tech-explainer` | `infographic` | `blueprint` | — | API docs, system metrics, technical deep-dives | +| `system-design` | `framework` | `blueprint` | — | Architecture diagrams, system design | +| `architecture` | `framework` | `vector-illustration` | — | Component relationships, module structure | +| `science-paper` | `infographic` | `scientific` | — | Research findings, lab results, academic | + +### Knowledge & Education + +| Preset | Type | Style | Palette | Best For | +|----------|------|-------|---------|----------| +| `knowledge-base` | `infographic` | `vector-illustration` | — | Concept explainers, tutorials, how-to | +| `saas-guide` | `infographic` | `notion` | — | Product guides, SaaS docs, tool walkthroughs | +| `tutorial` | `flowchart` | `vector-illustration` | — | Step-by-step tutorials, setup guides | +| `process-flow` | `flowchart` | `notion` | — | Workflow documentation, onboarding flows | +| `warm-knowledge` | `infographic` | `vector-illustration` | `warm` | Product showcases, team intros, feature cards, brand content | +| `edu-visual` | `infographic` | `vector-illustration` | `macaron` | Knowledge summaries, concept explainers, educational articles | +| `hand-drawn-edu` | `flowchart` | `sketch-notes` | `macaron` | Hand-drawn educational diagrams, process explainers, onboarding visuals | +| `ink-notes-compare` | `comparison` | `ink-notes` | `mono-ink` | Before/After essays, Traditional vs New, OS-style comparisons, mindset-shift narratives | +| `ink-notes-flow` | `flowchart` | `ink-notes` | `mono-ink` | Professional process explainers, workforce pipelines, hand-drawn technical walkthroughs | +| `ink-notes-framework` | `framework` | `ink-notes` | `mono-ink` | System analogies, command-center diagrams, architecture-as-metaphor, tech manifestos | + +### Data & Analysis + +| Preset | Type | Style | Palette | Best For | +|----------|------|-------|---------|----------| +| `data-report` | `infographic` | `editorial` | — | Data journalism, metrics reports, dashboards | +| `versus` | `comparison` | `vector-illustration` | — | Tech comparisons, framework shootouts | +| `business-compare` | `comparison` | `elegant` | — | Product evaluations, strategy options | + +### Narrative & Creative + +| Preset | Type | Style | Palette | Best For | +|----------|------|-------|---------|----------| +| `storytelling` | `scene` | `warm` | — | Personal essays, reflections, growth stories | +| `lifestyle` | `scene` | `watercolor` | — | Travel, wellness, lifestyle, creative | +| `history` | `timeline` | `elegant` | — | Historical overviews, milestones | +| `evolution` | `timeline` | `warm` | — | Progress narratives, growth journeys | + +### Editorial & Opinion + +| Preset | Type | Style | Palette | Best For | +|----------|------|-------|---------|----------| +| `opinion-piece` | `scene` | `screen-print` | — | Op-eds, commentary, critical essays | +| `editorial-poster` | `comparison` | `screen-print` | — | Debate, contrasting viewpoints | +| `cinematic` | `scene` | `screen-print` | — | Dramatic narratives, cultural essays | + +## Content Type → Preset Recommendations + +Use this table during Step 3 to recommend presets based on Step 2 content analysis: + +| Content Type (Step 2) | Primary Preset | Alternatives | +|------------------------|----------------|--------------| +| Technical | `tech-explainer` | `system-design`, `architecture` | +| Tutorial | `tutorial` | `process-flow`, `knowledge-base`, `edu-visual` | +| Methodology / Framework | `system-design` | `architecture`, `process-flow` | +| Data / Metrics | `data-report` | `versus`, `tech-explainer` | +| Comparison / Review | `versus` | `business-compare`, `editorial-poster`, `ink-notes-compare` | +| Manifesto / Mindset shift / Professional visual note | `ink-notes-compare` | `ink-notes-framework`, `ink-notes-flow` | +| Narrative / Personal | `storytelling` | `lifestyle`, `evolution` | +| Opinion / Editorial | `opinion-piece` | `cinematic`, `editorial-poster` | +| Historical / Timeline | `history` | `evolution` | +| Academic / Research | `science-paper` | `tech-explainer`, `data-report` | +| SaaS / Product | `saas-guide` | `knowledge-base`, `process-flow`, `warm-knowledge` | +| Education / Knowledge | `edu-visual` | `knowledge-base`, `tutorial`, `hand-drawn-edu` | + +## Override Examples + +- "use the tech-explainer preset but swap the style for notion" = infographic type with notion style +- "storytelling preset with timeline type" = timeline type with warm style + +Explicit type/style/palette mentions in the user's request always override preset values. diff --git a/optional-skills/creative/baoyu-article-illustrator/references/styles.md b/optional-skills/creative/baoyu-article-illustrator/references/styles.md new file mode 100644 index 0000000000000000000000000000000000000000..75631e98c8c961408e19aeb1cc546494b702bad3 --- /dev/null +++ b/optional-skills/creative/baoyu-article-illustrator/references/styles.md @@ -0,0 +1,224 @@ +# Style Reference + +## Core Styles + +Simplified style tier for quick selection: + +| Core Style | Maps To | Best For | +|------------|---------|----------| +| `vector` | vector-illustration | Knowledge articles, tutorials, tech content | +| `minimal-flat` | notion | General, knowledge sharing, SaaS | +| `sci-fi` | blueprint | AI, frontier tech, system design | +| `hand-drawn` | sketch/warm | Relaxed, reflective, casual content | +| `editorial` | editorial | Processes, data, journalism | +| `scene` | warm/watercolor | Narratives, emotional, lifestyle | +| `poster` | screen-print | Opinion, editorial, cultural, cinematic | + +Use Core Styles for most cases. See full Style Gallery below for granular control. + +--- + +## Style Gallery + +| Style | Description | Best For | +|-------|-------------|----------| +| `vector-illustration` | Clean flat vector art with bold shapes | Knowledge articles, tutorials, tech content | +| `notion` | Minimalist hand-drawn line art | Knowledge sharing, SaaS, productivity | +| `elegant` | Refined, sophisticated | Business, thought leadership | +| `warm` | Friendly, approachable | Personal growth, lifestyle, education | +| `minimal` | Ultra-clean, zen-like | Philosophy, minimalism, core concepts | +| `blueprint` | Technical schematics | Architecture, system design, engineering | +| `watercolor` | Soft artistic with natural warmth | Lifestyle, travel, creative | +| `editorial` | Magazine-style infographic | Tech explainers, journalism | +| `scientific` | Academic precise diagrams | Biology, chemistry, technical research | +| `chalkboard` | Classroom chalk drawing style | Education, teaching, explanations | +| `fantasy-animation` | Ghibli/Disney-inspired hand-drawn | Storybook, magical, emotional | +| `flat` | Modern bold geometric shapes | Modern digital, contemporary | +| `flat-doodle` | Cute flat with bold outlines | Cute, friendly, approachable | +| `intuition-machine` | Technical briefing with aged paper | Technical briefings, academic | +| `nature` | Organic earthy illustration | Environmental, wellness | +| `pixel-art` | Retro 8-bit gaming aesthetic | Gaming, retro tech | +| `playful` | Whimsical pastel doodles | Fun, casual, educational | +| `retro` | 80s/90s neon geometric | 80s/90s nostalgic, bold | +| `sketch` | Raw pencil notebook style | Brainstorming, creative exploration | +| `screen-print` | Bold poster art, halftone textures, limited colors | Opinion, editorial, cultural, cinematic | +| `sketch-notes` | Soft hand-drawn warm notes | Educational, warm notes | +| `ink-notes` | Black ink on pure white, sparse semantic accents, hand-lettered (à la Mike Rohde's sketchnoting) | Before/After essays, tech manifestos, framework analogies | +| `vintage` | Aged parchment historical | Historical, heritage | + +Full specifications: `references/styles/ + + +
+

+

+ +
+ + diff --git a/optional-skills/creative/dream-loop/LICENSE.txt b/optional-skills/creative/dream-loop/LICENSE.txt new file mode 100644 index 0000000000000000000000000000000000000000..dd54a3e60d5fe9e2296c4745c5b826d74158c852 --- /dev/null +++ b/optional-skills/creative/dream-loop/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Anshu Chimala + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/optional-skills/creative/excalidraw/SKILL.md b/optional-skills/creative/excalidraw/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..898aaa979e0b144a337d0f0c21787efbeab5cf1d --- /dev/null +++ b/optional-skills/creative/excalidraw/SKILL.md @@ -0,0 +1,199 @@ +--- +name: excalidraw +description: "Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)." +version: 1.0.1 +author: Hermes Agent +license: MIT +dependencies: [] +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [Excalidraw, Diagrams, Flowcharts, Architecture, Visualization, JSON] + related_skills: [] + +--- + +# Excalidraw Diagram Skill + +Create diagrams by writing standard Excalidraw element JSON and saving as `.excalidraw` files. These files can be drag-and-dropped onto [excalidraw.com](https://excalidraw.com) for viewing and editing. No accounts, no API keys, no rendering libraries -- just JSON. + +## When to use + +Generate `.excalidraw` files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. + +## Workflow + +1. **Load this skill** (you already did) +2. **Write the elements JSON** -- an array of Excalidraw element objects +3. **Save the file** using `write_file` to create a `.excalidraw` file +4. **Optionally upload** for a shareable link using `scripts/upload.py` via `terminal` + +### Saving a Diagram + +Wrap your elements array in the standard `.excalidraw` envelope and save with `write_file`: + +```json +{ + "type": "excalidraw", + "version": 2, + "source": "hermes-agent", + "elements": [ ...your elements array here... ], + "appState": { + "viewBackgroundColor": "#ffffff" + } +} +``` + +Save to any path, e.g. `~/diagrams/my_diagram.excalidraw`. + +### Uploading for a Shareable Link + +Run the upload script (located in this skill's `scripts/` directory) via terminal: + +```bash +python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw +``` + +This uploads to excalidraw.com (no account needed) and prints a shareable URL. Requires the `cryptography` pip package (`pip install cryptography`). + +--- + +## Element Format Reference + +### Required Fields (all elements) +`type`, `id` (unique string), `x`, `y`, `width`, `height` + +### Defaults (skip these -- they're applied automatically) +- `strokeColor`: `"#1e1e1e"` +- `backgroundColor`: `"transparent"` +- `fillStyle`: `"solid"` +- `strokeWidth`: `2` +- `roughness`: `1` (hand-drawn look) +- `opacity`: `100` + +Canvas background is white. + +### Element Types + +**Rectangle**: +```json +{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 } +``` +- `roundness: { "type": 3 }` for rounded corners +- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` for filled + +**Ellipse**: +```json +{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 } +``` + +**Diamond**: +```json +{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 } +``` + +**Labeled shape (container binding)** -- create a text element bound to the shape: + +> **WARNING:** Do NOT use `"label": { "text": "..." }` on shapes. This is NOT a valid +> Excalidraw property and will be silently ignored, producing blank shapes. You MUST +> use the container binding approach below. + +The shape needs `boundElements` listing the text, and the text needs `containerId` pointing back: +```json +{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80, + "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid", + "boundElements": [{ "id": "t_r1", "type": "text" }] }, +{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25, + "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e", + "textAlign": "center", "verticalAlign": "middle", + "containerId": "r1", "originalText": "Hello", "autoResize": true } +``` +- Works on rectangle, ellipse, diamond +- Text is auto-centered by Excalidraw when `containerId` is set +- The text `x`/`y`/`width`/`height` are approximate -- Excalidraw recalculates them on load +- `originalText` should match `text` +- Always include `fontFamily: 1` (Virgil/hand-drawn font) + +**Labeled arrow** -- same container binding approach: +```json +{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, + "points": [[0,0],[200,0]], "endArrowhead": "arrow", + "boundElements": [{ "id": "t_a1", "type": "text" }] }, +{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20, + "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e", + "textAlign": "center", "verticalAlign": "middle", + "containerId": "a1", "originalText": "connects", "autoResize": true } +``` + +**Standalone text** (titles and annotations only -- no container): +```json +{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20, + "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true } +``` +- `x` is the LEFT edge. To center at position `cx`: `x = cx - (text.length * fontSize * 0.5) / 2` +- Do NOT rely on `textAlign` or `width` for positioning + +**Arrow**: +```json +{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, + "points": [[0,0],[200,0]], "endArrowhead": "arrow" } +``` +- `points`: `[dx, dy]` offsets from element `x`, `y` +- `endArrowhead`: `null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"` +- `strokeStyle`: `"solid"` (default) | `"dashed"` | `"dotted"` + +### Arrow Bindings (connect arrows to shapes) + +```json +{ + "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0, + "points": [[0,0],[150,0]], "endArrowhead": "arrow", + "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] }, + "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] } +} +``` + +`fixedPoint` coordinates: `top=[0.5,0]`, `bottom=[0.5,1]`, `left=[0,0.5]`, `right=[1,0.5]` + +### Drawing Order (z-order) +- Array order = z-order (first = back, last = front) +- Emit progressively: background zones → shape → its bound text → its arrows → next shape +- BAD: all rectangles, then all texts, then all arrows +- GOOD: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ... +- Always place the bound text element immediately after its container shape + +### Sizing Guidelines + +**Font sizes:** +- Minimum `fontSize`: **16** for body text, labels, descriptions +- Minimum `fontSize`: **20** for titles and headings +- Minimum `fontSize`: **14** for secondary annotations only (sparingly) +- NEVER use `fontSize` below 14 + +**Element sizes:** +- Minimum shape size: 120x60 for labeled rectangles/ellipses +- Leave 20-30px gaps between elements minimum +- Prefer fewer, larger elements over many tiny ones + +### Color Palette + +See `references/colors.md` for full color tables. Quick reference: + +| Use | Fill Color | Hex | +|-----|-----------|-----| +| Primary / Input | Light Blue | `#a5d8ff` | +| Success / Output | Light Green | `#b2f2bb` | +| Warning / External | Light Orange | `#ffd8a8` | +| Processing / Special | Light Purple | `#d0bfff` | +| Error / Critical | Light Red | `#ffc9c9` | +| Notes / Decisions | Light Yellow | `#fff3bf` | +| Storage / Data | Light Teal | `#c3fae8` | + +### Tips +- Use the color palette consistently across the diagram +- **Text contrast is CRITICAL** -- never use light gray on white backgrounds. Minimum text color on white: `#757575` +- Do NOT use emoji in text -- they don't render in Excalidraw's font +- For dark mode diagrams, see `references/dark-mode.md` +- For larger examples, see `references/examples.md` + + diff --git a/optional-skills/creative/excalidraw/references/colors.md b/optional-skills/creative/excalidraw/references/colors.md new file mode 100644 index 0000000000000000000000000000000000000000..fc0116704b856e2848b9b34fe511247f2695ef8e --- /dev/null +++ b/optional-skills/creative/excalidraw/references/colors.md @@ -0,0 +1,44 @@ +# Excalidraw Color Palette + +Use these colors consistently across diagrams. + +## Primary Colors (for strokes, arrows, and accents) + +| Name | Hex | Use | +|------|-----|-----| +| Blue | `#4a9eed` | Primary actions, links, data series 1 | +| Amber | `#f59e0b` | Warnings, highlights, data series 2 | +| Green | `#22c55e` | Success, positive, data series 3 | +| Red | `#ef4444` | Errors, negative, data series 4 | +| Purple | `#8b5cf6` | Accents, special items, data series 5 | +| Pink | `#ec4899` | Decorative, data series 6 | +| Cyan | `#06b6d4` | Info, secondary, data series 7 | +| Lime | `#84cc16` | Extra, data series 8 | + +## Pastel Fills (for shape backgrounds) + +| Color | Hex | Good For | +|-------|-----|----------| +| Light Blue | `#a5d8ff` | Input, sources, primary nodes | +| Light Green | `#b2f2bb` | Success, output, completed | +| Light Orange | `#ffd8a8` | Warning, pending, external | +| Light Purple | `#d0bfff` | Processing, middleware, special | +| Light Red | `#ffc9c9` | Error, critical, alerts | +| Light Yellow | `#fff3bf` | Notes, decisions, planning | +| Light Teal | `#c3fae8` | Storage, data, memory | +| Light Pink | `#eebefa` | Analytics, metrics | + +## Background Zones (use with opacity: 30-35 for layered diagrams) + +| Color | Hex | Good For | +|-------|-----|----------| +| Blue zone | `#dbe4ff` | UI / frontend layer | +| Purple zone | `#e5dbff` | Logic / agent layer | +| Green zone | `#d3f9d8` | Data / tool layer | + +## Text Contrast Rules + +- **On white backgrounds**: minimum text color is `#757575`. Default `#1e1e1e` is best. +- **Colored text on light fills**: use dark variants (`#15803d` not `#22c55e`, `#2563eb` not `#4a9eed`) +- **White text**: only on dark backgrounds (`#9a5030` not `#c4795b`) +- **Never**: light gray (`#b0b0b0`, `#999`) on white -- unreadable diff --git a/optional-skills/creative/excalidraw/references/dark-mode.md b/optional-skills/creative/excalidraw/references/dark-mode.md new file mode 100644 index 0000000000000000000000000000000000000000..79bf4b581aaac33558f888476f011f0356d6ea37 --- /dev/null +++ b/optional-skills/creative/excalidraw/references/dark-mode.md @@ -0,0 +1,68 @@ +# Excalidraw Dark Mode Diagrams + +To create a dark-themed diagram, use a massive dark background rectangle as the **first element** in the array. Make it large enough to cover any viewport: + +```json +{ + "type": "rectangle", "id": "darkbg", + "x": -4000, "y": -3000, "width": 10000, "height": 7500, + "backgroundColor": "#1e1e2e", "fillStyle": "solid", + "strokeColor": "transparent", "strokeWidth": 0 +} +``` + +Then use the following color palettes for elements on the dark background. + +## Text Colors (on dark) + +| Color | Hex | Use | +|-------|-----|-----| +| White | `#e5e5e5` | Primary text, titles | +| Muted | `#a0a0a0` | Secondary text, annotations | +| NEVER | `#555` or darker | Invisible on dark bg! | + +## Shape Fills (on dark) + +| Color | Hex | Good For | +|-------|-----|----------| +| Dark Blue | `#1e3a5f` | Primary nodes | +| Dark Green | `#1a4d2e` | Success, output | +| Dark Purple | `#2d1b69` | Processing, special | +| Dark Orange | `#5c3d1a` | Warning, pending | +| Dark Red | `#5c1a1a` | Error, critical | +| Dark Teal | `#1a4d4d` | Storage, data | + +## Stroke and Arrow Colors (on dark) + +Use the standard Primary Colors from the main color palette -- they're bright enough on dark backgrounds: +- Blue `#4a9eed`, Amber `#f59e0b`, Green `#22c55e`, Red `#ef4444`, Purple `#8b5cf6` + +For subtle shape borders, use `#555555`. + +## Example: Dark mode labeled rectangle + +Use container binding (NOT the `"label"` property, which doesn't work). On dark backgrounds, set text `strokeColor` to `"#e5e5e5"` so it's visible: + +```json +[ + { + "type": "rectangle", "id": "r1", + "x": 100, "y": 100, "width": 200, "height": 80, + "backgroundColor": "#1e3a5f", "fillStyle": "solid", + "strokeColor": "#4a9eed", "strokeWidth": 2, + "roundness": { "type": 3 }, + "boundElements": [{ "id": "t_r1", "type": "text" }] + }, + { + "type": "text", "id": "t_r1", + "x": 105, "y": 120, "width": 190, "height": 25, + "text": "Dark Node", "fontSize": 20, "fontFamily": 1, + "strokeColor": "#e5e5e5", + "textAlign": "center", "verticalAlign": "middle", + "containerId": "r1", "originalText": "Dark Node", "autoResize": true + } +] +``` + +Note: For standalone text elements on dark backgrounds, always set `"strokeColor": "#e5e5e5"` explicitly. The default `#1e1e1e` is invisible on dark. + diff --git a/optional-skills/creative/excalidraw/references/examples.md b/optional-skills/creative/excalidraw/references/examples.md new file mode 100644 index 0000000000000000000000000000000000000000..d8bade5db151d1ac4c3ca00f5ad8b33eb2333b0c --- /dev/null +++ b/optional-skills/creative/excalidraw/references/examples.md @@ -0,0 +1,141 @@ +# Excalidraw Diagram Examples + +Complete, copy-pasteable examples. Wrap each in the `.excalidraw` envelope before saving: + +```json +{ + "type": "excalidraw", + "version": 2, + "source": "hermes-agent", + "elements": [ ...elements from examples below... ], + "appState": { "viewBackgroundColor": "#ffffff" } +} +``` + +> **IMPORTANT:** All text labels on shapes and arrows use container binding (`containerId` + `boundElements`). +> Do NOT use the non-existent `"label"` property -- it will be silently ignored, producing blank shapes. + +--- + +## Example 1: Two Connected Labeled Boxes + +A minimal flowchart with two boxes and an arrow between them. + +```json +[ + { "type": "text", "id": "title", "x": 280, "y": 30, "text": "Simple Flow", "fontSize": 28, "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Simple Flow", "autoResize": true }, + { "type": "rectangle", "id": "b1", "x": 100, "y": 100, "width": 200, "height": 100, "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid", "boundElements": [{ "id": "t_b1", "type": "text" }, { "id": "a1", "type": "arrow" }] }, + { "type": "text", "id": "t_b1", "x": 105, "y": 130, "width": 190, "height": 25, "text": "Start", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e", "textAlign": "center", "verticalAlign": "middle", "containerId": "b1", "originalText": "Start", "autoResize": true }, + { "type": "rectangle", "id": "b2", "x": 450, "y": 100, "width": 200, "height": 100, "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid", "boundElements": [{ "id": "t_b2", "type": "text" }, { "id": "a1", "type": "arrow" }] }, + { "type": "text", "id": "t_b2", "x": 455, "y": 130, "width": 190, "height": 25, "text": "End", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e", "textAlign": "center", "verticalAlign": "middle", "containerId": "b2", "originalText": "End", "autoResize": true }, + { "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0, "points": [[0,0],[150,0]], "endArrowhead": "arrow", "startBinding": { "elementId": "b1", "fixedPoint": [1, 0.5] }, "endBinding": { "elementId": "b2", "fixedPoint": [0, 0.5] } } +] +``` + +--- + +## Example 2: Photosynthesis Process Diagram + +A larger diagram with background zones, multiple nodes, and directional arrows showing inputs/outputs. + +```json +[ + {"type":"text","id":"ti","x":280,"y":10,"text":"Photosynthesis","fontSize":28,"fontFamily":1,"strokeColor":"#1e1e1e","originalText":"Photosynthesis","autoResize":true}, + {"type":"text","id":"fo","x":245,"y":48,"text":"6CO2 + 6H2O --> C6H12O6 + 6O2","fontSize":16,"fontFamily":1,"strokeColor":"#757575","originalText":"6CO2 + 6H2O --> C6H12O6 + 6O2","autoResize":true}, + {"type":"rectangle","id":"lf","x":150,"y":90,"width":520,"height":380,"backgroundColor":"#d3f9d8","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#22c55e","strokeWidth":1,"opacity":35}, + {"type":"text","id":"lfl","x":170,"y":96,"text":"Inside the Leaf","fontSize":16,"fontFamily":1,"strokeColor":"#15803d","originalText":"Inside the Leaf","autoResize":true}, + + {"type":"rectangle","id":"lr","x":190,"y":190,"width":160,"height":70,"backgroundColor":"#fff3bf","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#f59e0b","boundElements":[{"id":"t_lr","type":"text"},{"id":"a1","type":"arrow"},{"id":"a2","type":"arrow"},{"id":"a3","type":"arrow"},{"id":"a5","type":"arrow"}]}, + {"type":"text","id":"t_lr","x":195,"y":205,"width":150,"height":20,"text":"Light Reactions","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"lr","originalText":"Light Reactions","autoResize":true}, + + {"type":"arrow","id":"a1","x":350,"y":225,"width":120,"height":0,"points":[[0,0],[120,0]],"strokeColor":"#1e1e1e","strokeWidth":2,"endArrowhead":"arrow","boundElements":[{"id":"t_a1","type":"text"}]}, + {"type":"text","id":"t_a1","x":390,"y":205,"width":40,"height":20,"text":"ATP","fontSize":14,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"a1","originalText":"ATP","autoResize":true}, + + {"type":"rectangle","id":"cc","x":470,"y":190,"width":160,"height":70,"backgroundColor":"#d0bfff","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#8b5cf6","boundElements":[{"id":"t_cc","type":"text"},{"id":"a1","type":"arrow"},{"id":"a4","type":"arrow"},{"id":"a6","type":"arrow"}]}, + {"type":"text","id":"t_cc","x":475,"y":205,"width":150,"height":20,"text":"Calvin Cycle","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"cc","originalText":"Calvin Cycle","autoResize":true}, + + {"type":"rectangle","id":"sl","x":10,"y":200,"width":120,"height":50,"backgroundColor":"#fff3bf","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#f59e0b","boundElements":[{"id":"t_sl","type":"text"},{"id":"a2","type":"arrow"}]}, + {"type":"text","id":"t_sl","x":15,"y":210,"width":110,"height":20,"text":"Sunlight","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"sl","originalText":"Sunlight","autoResize":true}, + + {"type":"arrow","id":"a2","x":130,"y":225,"width":60,"height":0,"points":[[0,0],[60,0]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":"arrow"}, + + {"type":"rectangle","id":"wa","x":200,"y":360,"width":140,"height":50,"backgroundColor":"#a5d8ff","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#4a9eed","boundElements":[{"id":"t_wa","type":"text"},{"id":"a3","type":"arrow"}]}, + {"type":"text","id":"t_wa","x":205,"y":370,"width":130,"height":20,"text":"Water (H2O)","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"wa","originalText":"Water (H2O)","autoResize":true}, + + {"type":"arrow","id":"a3","x":270,"y":360,"width":0,"height":-100,"points":[[0,0],[0,-100]],"strokeColor":"#4a9eed","strokeWidth":2,"endArrowhead":"arrow"}, + + {"type":"rectangle","id":"co","x":480,"y":360,"width":130,"height":50,"backgroundColor":"#ffd8a8","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#f59e0b","boundElements":[{"id":"t_co","type":"text"},{"id":"a4","type":"arrow"}]}, + {"type":"text","id":"t_co","x":485,"y":370,"width":120,"height":20,"text":"CO2","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"co","originalText":"CO2","autoResize":true}, + + {"type":"arrow","id":"a4","x":545,"y":360,"width":0,"height":-100,"points":[[0,0],[0,-100]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":"arrow"}, + + {"type":"rectangle","id":"ox","x":540,"y":100,"width":100,"height":40,"backgroundColor":"#ffc9c9","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#ef4444","boundElements":[{"id":"t_ox","type":"text"},{"id":"a5","type":"arrow"}]}, + {"type":"text","id":"t_ox","x":545,"y":105,"width":90,"height":20,"text":"O2","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"ox","originalText":"O2","autoResize":true}, + + {"type":"arrow","id":"a5","x":310,"y":190,"width":230,"height":-50,"points":[[0,0],[230,-50]],"strokeColor":"#ef4444","strokeWidth":2,"endArrowhead":"arrow"}, + + {"type":"rectangle","id":"gl","x":690,"y":195,"width":120,"height":60,"backgroundColor":"#c3fae8","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#22c55e","boundElements":[{"id":"t_gl","type":"text"},{"id":"a6","type":"arrow"}]}, + {"type":"text","id":"t_gl","x":695,"y":210,"width":110,"height":25,"text":"Glucose","fontSize":18,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"gl","originalText":"Glucose","autoResize":true}, + + {"type":"arrow","id":"a6","x":630,"y":225,"width":60,"height":0,"points":[[0,0],[60,0]],"strokeColor":"#22c55e","strokeWidth":2,"endArrowhead":"arrow"}, + + {"type":"ellipse","id":"sun","x":30,"y":110,"width":50,"height":50,"backgroundColor":"#fff3bf","fillStyle":"solid","strokeColor":"#f59e0b","strokeWidth":2}, + {"type":"arrow","id":"r1","x":55,"y":108,"width":0,"height":-14,"points":[[0,0],[0,-14]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":null,"startArrowhead":null}, + {"type":"arrow","id":"r2","x":55,"y":162,"width":0,"height":14,"points":[[0,0],[0,14]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":null,"startArrowhead":null}, + {"type":"arrow","id":"r3","x":28,"y":135,"width":-14,"height":0,"points":[[0,0],[-14,0]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":null,"startArrowhead":null}, + {"type":"arrow","id":"r4","x":82,"y":135,"width":14,"height":0,"points":[[0,0],[14,0]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":null,"startArrowhead":null} +] +``` + +--- + +## Example 3: Sequence Diagram (UML-style) + +Demonstrates a sequence diagram with actors, dashed lifelines, and message arrows. + +```json +[ + {"type":"text","id":"title","x":200,"y":15,"text":"MCP Apps -- Sequence Flow","fontSize":24,"fontFamily":1,"strokeColor":"#1e1e1e","originalText":"MCP Apps -- Sequence Flow","autoResize":true}, + + {"type":"rectangle","id":"uHead","x":60,"y":60,"width":100,"height":40,"backgroundColor":"#a5d8ff","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#4a9eed","strokeWidth":2,"boundElements":[{"id":"t_uHead","type":"text"}]}, + {"type":"text","id":"t_uHead","x":65,"y":65,"width":90,"height":20,"text":"User","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"uHead","originalText":"User","autoResize":true}, + + {"type":"arrow","id":"uLine","x":110,"y":100,"width":0,"height":400,"points":[[0,0],[0,400]],"strokeColor":"#b0b0b0","strokeWidth":1,"strokeStyle":"dashed","endArrowhead":null}, + + {"type":"rectangle","id":"aHead","x":230,"y":60,"width":100,"height":40,"backgroundColor":"#d0bfff","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#8b5cf6","strokeWidth":2,"boundElements":[{"id":"t_aHead","type":"text"}]}, + {"type":"text","id":"t_aHead","x":235,"y":65,"width":90,"height":20,"text":"Agent","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"aHead","originalText":"Agent","autoResize":true}, + + {"type":"arrow","id":"aLine","x":280,"y":100,"width":0,"height":400,"points":[[0,0],[0,400]],"strokeColor":"#b0b0b0","strokeWidth":1,"strokeStyle":"dashed","endArrowhead":null}, + + {"type":"rectangle","id":"sHead","x":420,"y":60,"width":130,"height":40,"backgroundColor":"#ffd8a8","fillStyle":"solid","roundness":{"type":3},"strokeColor":"#f59e0b","strokeWidth":2,"boundElements":[{"id":"t_sHead","type":"text"}]}, + {"type":"text","id":"t_sHead","x":425,"y":65,"width":120,"height":20,"text":"Server","fontSize":16,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"sHead","originalText":"Server","autoResize":true}, + + {"type":"arrow","id":"sLine","x":485,"y":100,"width":0,"height":400,"points":[[0,0],[0,400]],"strokeColor":"#b0b0b0","strokeWidth":1,"strokeStyle":"dashed","endArrowhead":null}, + + {"type":"arrow","id":"m1","x":110,"y":150,"width":170,"height":0,"points":[[0,0],[170,0]],"strokeColor":"#1e1e1e","strokeWidth":2,"endArrowhead":"arrow","boundElements":[{"id":"t_m1","type":"text"}]}, + {"type":"text","id":"t_m1","x":165,"y":130,"width":60,"height":20,"text":"request","fontSize":14,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"m1","originalText":"request","autoResize":true}, + + {"type":"arrow","id":"m2","x":280,"y":200,"width":205,"height":0,"points":[[0,0],[205,0]],"strokeColor":"#8b5cf6","strokeWidth":2,"endArrowhead":"arrow","boundElements":[{"id":"t_m2","type":"text"}]}, + {"type":"text","id":"t_m2","x":352,"y":180,"width":60,"height":20,"text":"tools/call","fontSize":14,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"m2","originalText":"tools/call","autoResize":true}, + + {"type":"arrow","id":"m3","x":485,"y":260,"width":-205,"height":0,"points":[[0,0],[-205,0]],"strokeColor":"#f59e0b","strokeWidth":2,"endArrowhead":"arrow","strokeStyle":"dashed","boundElements":[{"id":"t_m3","type":"text"}]}, + {"type":"text","id":"t_m3","x":352,"y":240,"width":60,"height":20,"text":"result","fontSize":14,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"m3","originalText":"result","autoResize":true}, + + {"type":"arrow","id":"m4","x":280,"y":320,"width":-170,"height":0,"points":[[0,0],[-170,0]],"strokeColor":"#8b5cf6","strokeWidth":2,"endArrowhead":"arrow","strokeStyle":"dashed","boundElements":[{"id":"t_m4","type":"text"}]}, + {"type":"text","id":"t_m4","x":165,"y":300,"width":60,"height":20,"text":"response","fontSize":14,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center","verticalAlign":"middle","containerId":"m4","originalText":"response","autoResize":true} +] +``` + +--- + +## Common Mistakes to Avoid + +- **Do NOT use `"label"` property** -- this is the #1 mistake. It is NOT part of the Excalidraw file format and will be silently ignored, producing blank shapes with no visible text. Always use container binding (`containerId` + `boundElements`) as shown in the examples above. +- **Every bound text needs both sides linked** -- the shape needs `boundElements: [{"id": "t_xxx", "type": "text"}]` AND the text needs `containerId: "shape_id"`. If either is missing, the binding won't work. +- **Include `originalText` and `autoResize: true`** on all text elements -- Excalidraw uses these for proper text reflow. +- **Include `fontFamily: 1`** on all text elements -- without it, text may not render with the expected hand-drawn font. +- **Elements overlap when y-coordinates are close** -- always check that text, boxes, and labels don't stack on top of each other +- **Arrow labels need space** -- long labels like "ATP + NADPH" overflow short arrows. Keep labels short or make arrows wider +- **Center titles relative to the diagram** -- estimate total width and center the title text over it +- **Draw decorations LAST** -- cute illustrations (sun, stars, icons) should appear at the end of the array so they're drawn on top + diff --git a/optional-skills/creative/excalidraw/scripts/upload.py b/optional-skills/creative/excalidraw/scripts/upload.py new file mode 100644 index 0000000000000000000000000000000000000000..d1a40ff62da1b840c71e88fb5c2e0577b3c518eb --- /dev/null +++ b/optional-skills/creative/excalidraw/scripts/upload.py @@ -0,0 +1,133 @@ +#!/usr/bin/env python3 +""" +Upload an .excalidraw file to excalidraw.com and print a shareable URL. + +No account required. The diagram is encrypted client-side (AES-GCM) before +upload -- the encryption key is embedded in the URL fragment, so the server +never sees plaintext. + +Requirements: + pip install cryptography + +Usage: + python upload.py + +Example: + python upload.py ~/diagrams/architecture.excalidraw + # prints: https://excalidraw.com/#json=abc123,encryptionKeyHere +""" + +import json +import os +import struct +import sys +import zlib +import base64 +import urllib.request + +try: + from cryptography.hazmat.primitives.ciphers.aead import AESGCM +except ImportError: + print("Error: 'cryptography' package is required for upload.") + print("Install it with: pip install cryptography") + sys.exit(1) + +# Excalidraw public upload endpoint (no auth needed) +UPLOAD_URL = "https://json.excalidraw.com/api/v2/post/" + + +def concat_buffers(*buffers: bytes) -> bytes: + """ + Build the Excalidraw v2 concat-buffers binary format. + + Layout: [version=1 (4B big-endian)] then for each buffer: + [length (4B big-endian)] [data bytes] + """ + parts = [struct.pack(">I", 1)] # version = 1 + for buf in buffers: + parts.append(struct.pack(">I", len(buf))) + parts.append(buf) + return b"".join(parts) + + +def upload(excalidraw_json: str) -> str: + """ + Encrypt and upload Excalidraw JSON to excalidraw.com. + + Args: + excalidraw_json: The full .excalidraw file content as a string. + + Returns: + Shareable URL string. + """ + # 1. Inner payload: concat_buffers(file_metadata, data) + file_metadata = json.dumps({}).encode("utf-8") + data_bytes = excalidraw_json.encode("utf-8") + inner_payload = concat_buffers(file_metadata, data_bytes) + + # 2. Compress with zlib + compressed = zlib.compress(inner_payload) + + # 3. AES-GCM 128-bit encrypt + raw_key = os.urandom(16) # 128-bit key + iv = os.urandom(12) # 12-byte nonce + aesgcm = AESGCM(raw_key) + encrypted = aesgcm.encrypt(iv, compressed, None) + + # 4. Encoding metadata + encoding_meta = json.dumps({ + "version": 2, + "compression": "pako@1", + "encryption": "AES-GCM", + }).encode("utf-8") + + # 5. Outer payload: concat_buffers(encoding_meta, iv, encrypted) + payload = concat_buffers(encoding_meta, iv, encrypted) + + # 6. Upload + req = urllib.request.Request(UPLOAD_URL, data=payload, method="POST") + with urllib.request.urlopen(req, timeout=30) as resp: + if resp.status != 200: + raise RuntimeError(f"Upload failed with HTTP {resp.status}") + result = json.loads(resp.read().decode("utf-8")) + + file_id = result.get("id") + if not file_id: + raise RuntimeError(f"Upload returned no file ID. Response: {result}") + + # 7. Key as base64url (JWK 'k' format, no padding) + key_b64 = base64.urlsafe_b64encode(raw_key).rstrip(b"=").decode("ascii") + + return f"https://excalidraw.com/#json={file_id},{key_b64}" + + +def main(): + if len(sys.argv) < 2: + print("Usage: python upload.py ") + sys.exit(1) + + file_path = sys.argv[1] + + if not os.path.isfile(file_path): + print(f"Error: File not found: {file_path}") + sys.exit(1) + + with open(file_path, "r", encoding="utf-8") as f: + content = f.read() + + # Basic validation: should be valid JSON with an "elements" key + try: + doc = json.loads(content) + except json.JSONDecodeError as e: + print(f"Error: File is not valid JSON: {e}") + sys.exit(1) + + if "elements" not in doc: + print("Warning: File does not contain an 'elements' key. Uploading anyway.") + + url = upload(content) + print(url) + + +if __name__ == "__main__": + main() diff --git a/optional-skills/creative/kanban-video-orchestrator/SKILL.md b/optional-skills/creative/kanban-video-orchestrator/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..d1ad9a3347db6334a794f137a04df2107ccba2e3 --- /dev/null +++ b/optional-skills/creative/kanban-video-orchestrator/SKILL.md @@ -0,0 +1,208 @@ +--- +name: kanban-video-orchestrator +description: Plan and run multi-agent video production pipelines. +version: 1.0.0 +author: [SHL0MS, alt-glitch] +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [video, kanban, multi-agent, orchestration, production-pipeline] + related_skills: [ascii-video, manim-video, p5js, comfyui, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, youtube-content, claude-design, excalidraw, architecture-diagram, concept-diagrams, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation] + credits: | + The single-project workspace layout, profile-config patching pattern, + SOUL.md-per-profile model, TEAM.md task-graph convention, and + `--workspace dir:/abs/path` discipline are adapted from alt-glitch's + original multi-agent video pipeline at + https://github.com/NousResearch/kanban-video-pipeline. +--- + +# Kanban Video Orchestrator + +Wrap any video request — from a 15-second product teaser to a 5-minute narrative +short to a music video to an ASCII loop — in a Hermes Kanban pipeline that +decomposes the work to specialized agent profiles. + +This skill does **not** render anything itself. It is a meta-pipeline that: + +1. **Scopes** the request through targeted discovery +2. **Designs** an appropriate team (which roles, which tools per role) based on the style +3. **Generates** a setup script that creates Hermes profiles, project workspace, and the initial kanban task +4. **Hands off** to the director profile, which decomposes via the kanban +5. **Monitors** execution, helps intervene when tasks stall or fail + +The actual rendering happens inside the kanban once it's running, via whichever +existing skills + tools fit the scenes — `ascii-video`, `manim-video`, `p5js`, +`comfyui`, `touchdesigner-mcp`, `songwriting-and-ai-music`, +`heartmula`, external APIs, or plain Python with PIL + ffmpeg. + +## When NOT to use this skill + +- The video is one continuous procedural project that needs no specialists. Just write the code directly. +- The user wants a quick one-shot conversion (e.g. "convert this mp4 to a GIF") — use ffmpeg directly. +- The output is a static image, GIF, or audio-only artifact — use the matching specific skill (`ascii-art`, `gifs`, `meme-generation`, `songwriting-and-ai-music`). +- The work fits a single existing skill cleanly (e.g. a pure ASCII video — just use `ascii-video`). + +## Workflow + +``` +DISCOVER → BRIEF → TEAM DESIGN → SETUP → EXECUTE → MONITOR +``` + +### Step 1 — Discover (ask the right questions) + +The discovery process is **adaptive**: ask only what is actually needed. Always +start with three questions to identify the broad shape: + +- **What is the video?** (one-sentence brief) +- **How long?** (5-30s teaser / 30-90s short / 90s-3min explainer / 3-10min film / longer) +- **What aspect ratio + target platform?** (1:1 / 9:16 / 16:9; X, IG, YouTube, internal, etc.) + +From the answer, classify the style category. The style determines which +follow-up questions to ask. **Do not ask all questions at once.** Ask 2-4 at a +time, listen, then proceed. Make reasonable assumptions whenever the user +implies an answer. + +For complete intake patterns and per-style question banks, see +**[references/intake.md](references/intake.md)**. + +### Step 2 — Brief + +Once enough is known, produce a structured `brief.md` using the template in +`assets/brief.md.tmpl`. Stages: + +1. **Concept** — the one-sentence pitch + emotional north star +2. **Scope** — duration, aspect, platform, deadline +3. **Style** — visual references, brand constraints, tone +4. **Scenes** — beat-by-beat breakdown (durations, content, target tool) +5. **Audio** — narration / music / SFX / silent (per scene if needed) +6. **Deliverables** — file format, resolution, optional alternates (vertical cut, GIF, etc.) + +Show the brief to the user for confirmation before designing the team. **The +brief is the contract** — every downstream task references it. + +### Step 3 — Team design + +Pick role archetypes from the library that fit this video. **Compose, don't +clone.** Most videos need 4-7 profiles. The director is always present; the +rest are picked by what the brief actually requires. + +For the role library and per-style team compositions, see +**[references/role-archetypes.md](references/role-archetypes.md)**. + +For mapping role → which Hermes skills + toolsets it loads, see +**[references/tool-matrix.md](references/tool-matrix.md)**. + +### Step 4 — Setup + +Generate a setup script (`setup.sh`) and run it. The script: + +1. Creates the project workspace (`~/projects/video-pipeline//`) +2. Copies any provided assets into `taste/`, `audio/`, `assets/` +3. Creates each Hermes profile via `hermes profile create --clone` +4. Writes per-profile `SOUL.md` (personality + role definition) +5. Configures profile YAML (toolsets, always_load skills, cwd) +6. Writes `brief.md`, `TEAM.md`, and `taste/` content +7. Fires the initial `hermes kanban create` task assigned to the director + +Use `scripts/bootstrap_pipeline.py` to generate setup.sh from a brief + +team-design JSON. See **[references/kanban-setup.md](references/kanban-setup.md)** +for the setup script structure, profile config patterns, and the critical +"shared workspace" rule. + +### Step 5 — Execute + +Run `setup.sh`. Then provide the user with monitoring commands: + +```bash +hermes kanban watch --tenant # live events +hermes kanban list --tenant # board snapshot +hermes dashboard # visual board UI +``` + +The director profile takes over from here, decomposing the work and routing +tasks to specialist profiles via the kanban toolset. + +### Step 6 — Monitor and intervene + +Stay engaged — the kanban runs autonomously but a stuck task or bad output +needs human (or AI) judgment. + +Monitoring patterns: poll `kanban list` periodically, inspect any RUNNING task +that exceeds its expected duration with `kanban show `, and check +heartbeats. When a worker's output fails review, the standard interventions are: + +1. Comment on the worker's task with specific feedback (`kanban_comment`) +2. Create a re-run task with the original as parent +3. Adjust the brief's scope and let the director re-decompose + +For diagnostic patterns, intervention recipes, and the "task is stuck" +playbook, see **[references/monitoring.md](references/monitoring.md)**. + +## Reference: worked examples + +Six concrete pipelines covering very different video styles — narrative film, +product/marketing, music video, math/algorithm explainer, ASCII video, real-time +installation — showing how the same workflow yields very different teams and +task graphs. See **[references/examples.md](references/examples.md)**. + +## Critical rules + +1. **Discovery before action.** Never start generating a brief or team without + asking at least the three baseline questions. A bad brief cascades through + the entire pipeline. + +2. **Match the team to the video.** Don't reuse the same 4-profile setup for + every job. A music video that doesn't have a beat-analysis profile will + misfire. A narrative film that doesn't have a writer profile will produce + incoherent scenes. See `references/role-archetypes.md`. + +3. **One workspace per project.** All profiles for a given video share the same + `dir:` workspace. Tasks pass artifacts via shared filesystem and structured + handoffs. **Every** `kanban_create` call passes + `workspace_kind="dir"` + `workspace_path=""`. + +4. **Tenant every project.** Use a project-specific tenant + (`--tenant `). Keeps the dashboard scoped and prevents + cross-pollination with other ongoing kanbans. + +5. **Respect existing skills.** When a scene fits an existing skill, the + relevant renderer should load that skill via `--skill ` on its task + or `always_load` in its profile. Do not re-derive what a skill already + provides. + +6. **The director never executes.** Even with the full `kanban + terminal + + file` toolset, the director's `SOUL.md` rules forbid it from executing + work itself. It decomposes and routes only — every concrete task becomes + a `hermes kanban create` call to a specialist profile. The kanban + orchestration guidance auto-injected into every kanban worker's system + prompt spells this out further. + +7. **Don't over-decompose.** A 30-second product video does NOT need 20 tasks. + Aim for the smallest task graph that still parallelizes well and exposes the + right human-review gates. + +8. **Verify API keys BEFORE firing.** External APIs (TTS, image-gen, + image-to-video) need keys in `${HERMES_HOME:-~/.hermes}/.env` or the user's secret store. + A worker that hits a missing-key error wastes a task slot. The setup + script's `check_key` helper aborts cleanly if a required key is missing. + +## File map + +``` +SKILL.md ← this file (workflow + rules) +references/ + intake.md ← discovery question banks per style + role-archetypes.md ← role library (writer, designer, animator, …) + tool-matrix.md ← skill + toolset mapping per role + kanban-setup.md ← setup script structure & profile config + monitoring.md ← watch + intervene patterns + examples.md ← six worked pipelines +assets/ + brief.md.tmpl ← brief skeleton + setup.sh.tmpl ← setup script skeleton + soul.md.tmpl ← profile personality skeleton +scripts/ + bootstrap_pipeline.py ← generate setup.sh from brief + team JSON + monitor.py ← polling + intervention helpers +``` diff --git a/optional-skills/creative/kanban-video-orchestrator/assets/brief.md.tmpl b/optional-skills/creative/kanban-video-orchestrator/assets/brief.md.tmpl new file mode 100644 index 0000000000000000000000000000000000000000..fbe8d8cbfb5edca55951755641bcabf2aebbefc5 --- /dev/null +++ b/optional-skills/creative/kanban-video-orchestrator/assets/brief.md.tmpl @@ -0,0 +1,79 @@ +# Video Brief — {{TITLE}} + +> Slug: `{{SLUG}}` · Tenant: `{{TENANT}}` · Project workspace: `{{WORKSPACE}}` + +## 1. Concept + +**One-line pitch.** {{ONE_LINE_PITCH}} + +**Emotional north star.** {{EMOTIONAL_NORTH_STAR}} +*(What should the viewer feel walking away?)* + +## 2. Scope + +| | | +|---|---| +| Duration | {{DURATION_S}} seconds | +| Aspect ratio | {{ASPECT}} | +| Resolution | {{RESOLUTION}} | +| Frame rate | {{FPS}} fps | +| Target platforms | {{PLATFORMS}} | +| Deadline | {{DEADLINE}} | +| Quality bar | {{QUALITY_BAR}} *(rough draft / polished / archival)* | + +## 3. Style + +**Visual references.** {{VISUAL_REFS}} + +**Tone.** {{TONE}} + +**Brand constraints.** {{BRAND_CONSTRAINTS}} +*(colors, typography, motion language; or "n/a")* + +**Aesthetic rules.** +{{AESTHETIC_RULES}} + +## 4. Scenes + +Beat-by-beat breakdown. Each scene gets a row. + +| # | Time | Content | Target tool / skill | Audio | Notes | +|---|------|---------|---------------------|-------|-------| +| 1 | 0:00–0:0X | {{SCENE_1_CONTENT}} | {{SCENE_1_TOOL}} | {{SCENE_1_AUDIO}} | {{SCENE_1_NOTES}} | +| 2 | 0:0X–0:0Y | ... | ... | ... | ... | + +## 5. Audio + +**Approach.** {{AUDIO_APPROACH}} +*(narration / music-only / synced to track / silent / mixed)* + +**Voiceover.** {{VO_DETAILS}} +*(provider, voice, language, script source — "n/a" if no VO)* + +**Music.** {{MUSIC_DETAILS}} +*(provided track path / commission via Suno / commission via heartmula / +license-free / "n/a")* + +**SFX.** {{SFX_DETAILS}} +*(generated, library, or "n/a")* + +## 6. Deliverables + +| Format | Resolution | Notes | +|--------|-----------|-------| +| {{PRIMARY_FORMAT}} | {{PRIMARY_RES}} | The main output | +| {{ALT_FORMAT_1}} | {{ALT_RES_1}} | {{ALT_NOTES_1}} | + +**Final filename.** `output/final.mp4` +*(plus optional `output/final-9x16.mp4`, `output/captions.srt`, etc.)* + +## 7. Constraints + +- API keys required: {{API_KEYS_REQUIRED}} +- External dependencies: {{EXT_DEPS}} +- Source assets to incorporate: {{SOURCE_ASSETS}} + +--- + +**This brief is the contract. The director and every downstream profile read +it. If the brief changes, the kanban must be re-fired — don't edit live.** diff --git a/optional-skills/creative/kanban-video-orchestrator/assets/setup.sh.tmpl b/optional-skills/creative/kanban-video-orchestrator/assets/setup.sh.tmpl new file mode 100644 index 0000000000000000000000000000000000000000..c6a95848c6d99ff0e948d24d7eda273fe390f2a7 --- /dev/null +++ b/optional-skills/creative/kanban-video-orchestrator/assets/setup.sh.tmpl @@ -0,0 +1,186 @@ +#!/usr/bin/env bash +# ═══════════════════════════════════════════════════════════════════════ +# Video Pipeline Setup — {{TITLE}} +# +# Generated by kanban-video-orchestrator skill. +# +# Slug: {{SLUG}} +# Workspace: {{WORKSPACE}} +# Tenant: {{TENANT}} +# ═══════════════════════════════════════════════════════════════════════ +set -euo pipefail + +PROJECT_SLUG="{{SLUG}}" +WORKSPACE="$HOME/projects/video-pipeline/${PROJECT_SLUG}" +TENANT="{{TENANT}}" + +# ───────────────────────────────────────────────────────────────────── +# 1. Verify required API keys +# ───────────────────────────────────────────────────────────────────── +echo "═══ Checking required API keys ═══" + +check_key() { + local var="$1" + local kc_account="${2:-hermes}" + local kc_service="${3:-$1}" + local _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env" + if grep -q "^${var}=" "$_hermes_env" 2>/dev/null && \ + [ -n "$(grep "^${var}=" "$_hermes_env" | cut -d= -f2-)" ]; then + echo " ✓ ${var} (env)" + return 0 + fi + if command -v security >/dev/null 2>&1 && \ + security find-generic-password -a "${kc_account}" -s "${kc_service}" -w >/dev/null 2>&1; then + echo " ✓ ${var} (Keychain ${kc_account}/${kc_service})" + return 0 + fi + echo " ✗ ${var} not set in ${_hermes_env} or Keychain (${kc_account}/${kc_service})" + return 1 +} + +# Customize this list per project — only check keys actually used: +{{KEY_CHECKS}} + +# ───────────────────────────────────────────────────────────────────── +# 2. Create project workspace +# ───────────────────────────────────────────────────────────────────── +echo "═══ Creating project workspace ═══" +mkdir -p "$WORKSPACE"/{taste,audio/{voiceover,sfx},assets,scenes,checkpoints,tools,output} +{{SCENE_DIRS}} +echo " ✓ $WORKSPACE" + +# ───────────────────────────────────────────────────────────────────── +# 3. Create Hermes profiles +# ───────────────────────────────────────────────────────────────────── +echo "═══ Creating Hermes profiles ═══" + +{{PROFILE_CREATE_COMMANDS}} + +# ───────────────────────────────────────────────────────────────────── +# 4. Configure profiles (toolsets, skills, cwd) +# ───────────────────────────────────────────────────────────────────── +echo "═══ Configuring profiles ═══" + +configure_profile() { + local profile="$1" + local toolsets_json="$2" # JSON array string, e.g. '["kanban","terminal","file"]' + local skills_json="$3" # JSON array string, e.g. '["ascii-video"]' + python3 - "$profile" "$toolsets_json" "$skills_json" "$WORKSPACE" <<'PY' +"""Patch a Hermes profile config.yaml using PyYAML so we don't depend on the +exact default-config string format. Validates the patch took effect and exits +non-zero if anything's off.""" +import json +import os +import sys + +try: + import yaml +except ImportError: + print("ERROR: PyYAML required. pip install pyyaml", file=sys.stderr) + sys.exit(1) + +profile, toolsets_json, skills_json, workspace = sys.argv[1:5] +toolsets = json.loads(toolsets_json) +skills = json.loads(skills_json) + +p = os.path.expanduser(f"~/.hermes/profiles/{profile}/config.yaml") +if not os.path.exists(p): + print(f" ✗ profile config not found: {p}", file=sys.stderr) + sys.exit(1) + +with open(p) as f: + cfg = yaml.safe_load(f) or {} + +# Apply our changes — only the keys we actually want to set. +cfg["toolsets"] = toolsets +cfg.setdefault("skills", {}) +cfg["skills"]["always_load"] = skills + +# Note: we do NOT touch cfg["approvals"] — that's a security-sensitive +# setting (manual confirmation of tool calls). Workspace cwd is overridden +# per-task by `--workspace dir:` on `hermes kanban create`, so we +# don't need to mutate cfg["terminal"]["cwd"] either. + +with open(p, "w") as f: + yaml.safe_dump(cfg, f, sort_keys=False) + +# Validate +with open(p) as f: + after = yaml.safe_load(f) +errors = [] +if after.get("toolsets") != toolsets: + errors.append(f"toolsets mismatch: {after.get('toolsets')!r}") +if after.get("skills", {}).get("always_load") != skills: + errors.append(f"skills.always_load mismatch: {after.get('skills', {}).get('always_load')!r}") +if errors: + print(f" ✗ {profile}: " + "; ".join(errors), file=sys.stderr) + sys.exit(1) +PY + if [ $? -ne 0 ]; then + echo " ✗ failed to configure ${profile}" >&2 + exit 1 + fi + echo " ✓ ${profile}" +} + +{{PROFILE_CONFIG_COMMANDS}} + +# ───────────────────────────────────────────────────────────────────── +# 5. Write SOUL.md per profile +# ───────────────────────────────────────────────────────────────────── +echo "═══ Writing profile personalities ═══" + +{{SOUL_WRITES}} + +# ───────────────────────────────────────────────────────────────────── +# 6. Copy brief, TEAM.md, and any provided assets +# ───────────────────────────────────────────────────────────────────── +echo "═══ Writing brief + taste ═══" + +cat > "$WORKSPACE/brief.md" <<'BRIEF_EOF' +{{BRIEF_CONTENTS}} +BRIEF_EOF + +cat > "$WORKSPACE/TEAM.md" <<'TEAM_EOF' +{{TEAM_CONTENTS}} +TEAM_EOF + +{{TASTE_WRITES}} + +{{ASSET_COPIES}} + +# ───────────────────────────────────────────────────────────────────── +# 7. Fire the initial kanban task +# ───────────────────────────────────────────────────────────────────── +echo "═══ Firing initial kanban task ═══" + +hermes kanban create "Direct production of {{TITLE}}" \ + --assignee director \ + --workspace dir:"$WORKSPACE" \ + --tenant "$TENANT" \ + --priority 2 \ + --max-runtime 4h \ + --body "$(cat < **Credit:** the single-project-workspace layout, profile-config patching +> approach, SOUL.md-per-profile convention, and `--workspace dir:` rule +> are adapted from alt-glitch's original multi-agent video pipeline: +> [NousResearch/kanban-video-pipeline](https://github.com/NousResearch/kanban-video-pipeline). +> This skill generalizes those patterns across video styles and replaces the +> string-replacement config patcher with a PyYAML-based one. + +## Project workspace structure + +Every video project gets one workspace under `~/projects/video-pipeline//`: + +``` +~/projects/video-pipeline// +├── brief.md ← the contract; all tasks reference +├── TEAM.md ← team composition + task graph (director reads this) +├── taste/ +│ ├── brand-guide.md ← color, typography, motion rules +│ ├── emotional-dna.md ← what the piece should FEEL like +│ └── style-frames/ ← optional: visual references +├── audio/ +│ ├── track.mp3 ← provided music (if any) +│ ├── voiceover/ ← per-line TTS clips +│ └── sfx/ ← sound effects +├── assets/ +│ ├── logos/ +│ ├── fonts/ +│ └── existing-footage/ ← reusable provided clips +├── scenes/ +│ ├── scene-01/ +│ │ ├── VISUAL_SPEC.md ← cinematographer's per-scene spec +│ │ ├── render.py ← renderer's code (or sketch.html, etc.) +│ │ ├── checkpoints/ ← preview frames for QA +│ │ └── clip.mp4 ← the deliverable for this scene +│ ├── scene-02/... +│ └── ... +├── checkpoints/ ← global review frames +├── tools/ ← optional project-local helpers +└── output/ + ├── final.mp4 ← stitched + audio + ├── final-noaudio.mp4 + ├── final-9x16.mp4 ← optional: vertical alternate + └── captions.srt ← optional: subtitle file +``` + +**The slug** is derived from the brief title: lowercase, hyphen-separated. +Example: `q3-product-teaser`, `ascii-mood-loop`, `interview-cut-2026-q1`. + +## The setup.sh script + +The setup script does six things in order: + +1. **Create workspace tree** — all directories above +2. **Create profiles** — `hermes profile create --clone` +3. **Configure profiles** — patch each profile's + `~/.hermes/profiles//config.yaml` to set toolsets, always_load skills, + and `cwd` +4. **Write SOUL.md per profile** — the personality + role definition +5. **Copy any provided assets + write `brief.md`, `TEAM.md`, and `taste/`** +6. **Fire the initial kanban task** — `hermes kanban create` assigned to the director + +See `assets/setup.sh.tmpl` for the skeleton. + +### Profile creation pattern + +```bash +hermes profile create director --clone 2>/dev/null || true +``` + +The `--clone` flag clones from the active profile (preserving model, base +config). The `|| true` makes the script idempotent — re-running won't error if +the profile already exists. + +### Profile config patching + +Each profile has a YAML config at `~/.hermes/profiles//config.yaml`. The +setup script edits exactly two keys: + +1. `toolsets:` — replace the default with the role's required toolsets +2. `skills.always_load:` — list the role's must-load skills (may be empty) + +**Do NOT** modify `approvals.mode` (controls user-confirmation of tool calls +— a security setting that must stay as the user configured it). **Do NOT** +modify `terminal.cwd` — the kanban dispatcher overrides cwd per-task via +`--workspace dir:`, so the profile's cwd is irrelevant to the kanban +work and changing it could break the user's interactive use of the profile. + +Use **PyYAML**, not string replacement, so the patch is robust against +default-config schema drift: + +```bash +configure_profile() { + local profile="$1" + local toolsets_json="$2" # JSON array, e.g. '["kanban","terminal","file"]' + local skills_json="$3" # JSON array, e.g. '["ascii-video"]' + python3 - "$profile" "$toolsets_json" "$skills_json" <<'PY' +import json, os, sys, yaml +profile, ts_json, sk_json = sys.argv[1:4] +p = os.path.expanduser(f"~/.hermes/profiles/{profile}/config.yaml") +with open(p) as f: + cfg = yaml.safe_load(f) or {} +cfg["toolsets"] = json.loads(ts_json) +cfg.setdefault("skills", {})["always_load"] = json.loads(sk_json) +with open(p, "w") as f: + yaml.safe_dump(cfg, f, sort_keys=False) +PY +} +``` + +PyYAML must be installed in the user's Python (it ships with most Hermes +installs). If absent: `pip install pyyaml`. + +The setup script should also **validate** the patch by re-reading the file +and comparing — see `assets/setup.sh.tmpl` for the validation pattern. + +### SOUL.md per profile + +Each profile gets a `SOUL.md` at `~/.hermes/profiles//SOUL.md` that +defines its role, voice, and rules. See `assets/soul.md.tmpl` for the +template. Customize per role and per project. + +The director's SOUL.md should be the most opinionated — its voice flavors +the entire production. **Critical content for the director's SOUL.md:** + +- **Anti-temptation rules:** "Do not execute the work yourself. For every + concrete task, create a kanban task and assign it. Decompose, route, comment, + approve — that's the whole job." (The kanban orchestration guidance is + auto-injected into every kanban worker's system prompt — no skill to load.) +- **Decomposition steps:** Read `brief.md`, `TEAM.md`, `taste/`. Use the team + graph in `TEAM.md` to fan out tasks. +- **The workspace_path rule** (see below). + +Other profiles' SOUL.md is briefer; mostly mechanical: who you are, what you +read, what you produce, what skills/tools to use, where to write outputs. +The kanban lifecycle guidance is auto-injected into every kanban worker's +system prompt, so no profile needs to load a kanban skill. + +### Initial kanban task + +The final action of setup.sh is firing the kanban: + +```bash +hermes kanban create "Direct production of