sophhub 0.1.0

package/skills/builtin/sophnet-image-edit/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sophnet-image-edit
+description: Use when a user requests Sophnet image editing (image-to-image), including multi-image editing tasks (composition, style transfer, region swap) where all uploaded image paths must be resolved from Media Understanding logs (usually media/inbound/images/*) and passed in order to model Qwen-Image-Edit-2509.
+metadata:
+  short-description: Edit Sophnet images with strict multi-image path/order handling
+---
+
+# Sophnet Image Edit
+
+## Overview
+
+Edit existing images with Python scripts that handle task polling and structured output.
+
+Script responsibilities:
+
+- `edit_image.py`: core API caller and polling loop, outputs `INPUT_IMAGE_COUNT`, `TASK_ID`, `STATUS`, and `IMAGE_URL`.
+- `edit_and_preview.sh`: wrapper for local use, calls `edit_image.py`, downloads first result, adds `PREVIEW_PATH`.
+
+## When to Use
+
+- User asks to edit or transform existing images with Sophnet.
+- Task uses one or more source images (URL or uploaded local files).
+- Task depends on image order/role, such as:
+  - put part of image-2 into image-1
+  - render image-2 with image-1 style
+  - blend/composite many images into one result
+- Do not use when the task is pure text-to-image generation; use `sophnet-image-generate`.
+
+## Image Path Resolution
+
+When users upload images in chat channels, files are usually saved under `media/inbound/images/` in the workspace. Use Media Understanding logs to get exact resolved paths.
+
+Typical log pattern:
+
+```
+[Media Understanding] Resolved relative path: "media/inbound/images/xxx.jpg" -> "/absolute/path/to/workspace/media/inbound/images/xxx.jpg"
+```
+
+Path rules:
+
+- `--image` accepts URL, data URI, or local file path.
+- Local file paths are auto-converted to data URI by the script.
+- For multi-image tasks, pass every image explicitly and in required order.
+
+## Multi-Image Rules
+
+1. Keep source image order stable and explicit.
+2. Bind prompt language to order (image-1, image-2, image-3...).
+3. Do not drop "reference" images; pass all images used by the prompt.
+4. Verify script output `INPUT_IMAGE_COUNT` equals expected image count before trusting results.
+
+Recommended prompt pattern for multi-image tasks:
+
+- `图1作为底图，图2提供主体元素，图3提供风格参考；将图2主体抠出放到图1右上角，并按图3风格整体渲染。`
+
+## Quick Reference
+
+| Goal                             | Command                                                                                                                                                                       |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Edit with one source             | `bash {baseDir}/scripts/edit_and_preview.sh --prompt "..." --image "https://example.com/source.jpg"`                                                                          |
+| Edit with two sources (ordered)  | `bash {baseDir}/scripts/edit_and_preview.sh --prompt "图1作为底图，将图2主体放入图1左下角" --image "media/inbound/images/img1.jpg" --image "media/inbound/images/img2.jpg"`   |
+| Style transfer across two images | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "使用图1的画风渲染图2内容" --image "/abs/path/style.jpg" --image "/abs/path/content.jpg"`         |
+| Many images via CSV              | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images "media/inbound/images/a.jpg,media/inbound/images/b.jpg,https://example.com/c.jpg"` |
+| Many images via list file        | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images-file "/tmp/image-list.txt"`                                                        |
+| Validate image count only        | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --prompt "..." --images-file "/tmp/image-list.txt" --dry-run`                                              |
+| Show options                     | `uv run --project {baseDir} python {baseDir}/scripts/edit_image.py --help`                                                                                                    |
+
+Notes:
+
+- `--dry-run` does not require API key and is for input-count verification only.
+- Prefer `--images-file` when handling many images or values that may contain commas.
+
+`/tmp/image-list.txt` format example:
+
+```text
+# One image reference per line
+media/inbound/images/base.jpg
+media/inbound/images/object.png
+https://example.com/style.jpg
+```
+
+## Script Output Fields
+
+The script outputs structured key=value lines. Parse all of them:
+
+| Field               | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `INPUT_IMAGE_COUNT` | Number of source images passed to the API                    |
+| `TASK_ID`           | API task identifier                                          |
+| `STATUS`            | `succeeded` or `failed`                                      |
+| `OUTPUT_COUNT`      | Number of result images                                      |
+| `IMAGE_URL`         | Publicly accessible signed URL for each result image         |
+| `PREVIEW_PATH`      | Local file path (only when OSS re-upload failed as fallback) |
+
+## Presenting Results to Users
+
+After a successful edit, present the results with context -- not just a bare URL. Include:
+
+1. What was done: mention the edit instruction / style applied.
+2. Input/output image counts.
+3. The result image URL(s): provide the `IMAGE_URL` so the user can view/download.
+4. If `PREVIEW_PATH` is present, mention the local file path.
+
+Example response pattern:
+
+```
+✅ 图片编辑完成！
+
+🎨 **编辑指令**：把图片变成水彩画风格
+🧾 **输入图片数**：1
+🖼️ **结果图片**：![image](IMAGE_URL)
+⚠️**提示**: 本内容有AI生成，图片保存24小时，请及时下载！
+```
+
+## Implementation
+
+1. Resolve all uploaded image paths from Media Understanding logs.
+2. If this edit step follows `sophnet-image-generate`, prefer upstream `IMAGE_URL` for handoff; use `PREVIEW_PATH` only when local-file input is explicitly intended.
+3. Build prompt with explicit image order semantics.
+4. Run script with one `--image` per image, or `--images`, or `--images-file`.
+5. For multi-image tasks, run once with `--dry-run` and confirm `INPUT_IMAGE_COUNT` matches intended image count.
+6. Parse ALL output fields (see table above) and present them to the user.
+7. Use `PREVIEW_PATH` when present.
+
+API payload shape:
+
+- `model`: `Qwen-Image-Edit-2509`
+- `input.prompt`: edit instruction with image-role semantics
+- `input.images[]`: all source image refs in strict order
+- `parameters`: `size`, `n`, `watermark`
+
+## Common Mistakes
+
+- Passing only one image for a multi-image prompt.
+- Mentioning image-2/image-3 in prompt but not passing those images.
+- Reordering `--image` arguments unintentionally.
+- Ignoring `INPUT_IMAGE_COUNT` mismatch.
+- Using non-existent local paths.
+- In generate→edit workflows, defaulting to `PREVIEW_PATH` instead of `IMAGE_URL` without reason.
+- Only showing a bare URL without context -- always present a summary with edit details.

package/skills/builtin/sophnet-image-edit/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "sophnet-image-edit"
+version = "1.0.0"
+description = "Sophnet image editing (image-to-image) with task polling"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28.0",
+    "sophnet-tools>=0.0.1",
+]

package/skills/builtin/sophnet-image-edit/scripts/edit_and_preview.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# Edit image and download the first result for preview.
+# Wrapper: calls edit_image.py via uv, downloads first result.
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+EDIT_SCRIPT="${SCRIPT_DIR}/edit_image.py"
+
+if [[ ! -f "$EDIT_SCRIPT" ]]; then
+  echo "Error: edit_image.py not found at ${EDIT_SCRIPT}" >&2
+  exit 1
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  echo "Error: curl not found." >&2
+  exit 1
+fi
+
+for arg in "$@"; do
+  if [[ "$arg" == "-h" || "$arg" == "--help" ]]; then
+    uv run --project "$SKILL_DIR" python "$EDIT_SCRIPT" --help
+    exit 0
+  fi
+done
+
+if ! output="$(uv run --project "$SKILL_DIR" python "$EDIT_SCRIPT" "$@" 2>&1)"; then
+  echo "$output" >&2
+  exit 1
+fi
+
+echo "$output"
+
+# Python already downloads and re-uploads the image; check if PREVIEW_PATH was produced
+preview_path="$(printf '%s\n' "$output" | awk '/^PREVIEW_PATH=/{print substr($0,14); exit}')"
+
+if [[ -n "$preview_path" && -f "$preview_path" ]]; then
+  exit 0
+fi
+
+# Fallback: download via curl if Python didn't produce a local file
+image_url="$(printf '%s\n' "$output" | awk '/^IMAGE_URL=/{print substr($0,11); exit}')"
+
+if [[ -z "$image_url" ]]; then
+  echo "Error: No image URL found in output" >&2
+  exit 1
+fi
+
+task_id="$(printf '%s\n' "$output" | awk '/^TASK_ID=/{print substr($0,9); exit}')"
+: "${task_id:=$(date +%s)}"
+
+path_no_query="${image_url%%\?*}"
+ext="${path_no_query##*.}"
+case "$ext" in
+  jpg|jpeg|png|gif|webp|bmp) ;;
+  *) ext="png" ;;
+esac
+temp_file="$(mktemp "/tmp/edited_${task_id}_XXXXXX.${ext}")"
+
+if curl -fsSL "$image_url" -o "$temp_file"; then
+  echo "PREVIEW_PATH=${temp_file}"
+else
+  rm -f "$temp_file"
+  echo "Warning: Failed to download image for preview" >&2
+fi

package/skills/builtin/sophnet-image-edit/scripts/edit_image.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""
+Sophnet image editing (image-to-image) with async task polling.
+Supports multiple source images via --image, --images (CSV), or --images-file.
+Outputs machine-friendly INPUT_IMAGE_COUNT, TASK_ID, STATUS, and IMAGE_URL lines.
+"""
+
+import argparse
+import base64
+import json
+import mimetypes
+import os
+import sys
+import tempfile
+import time
+
+import requests
+import sophnet_tools
+
+API_URL = "https://www.sophnet.com/api/open-apis/projects/easyllms/imagegenerator/task"
+VALID_MODELS = ["Qwen-Image-Edit-2509"]
+
+MIME_MAP = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+    ".png": "image/png", ".webp": "image/webp",
+    ".gif": "image/gif", ".bmp": "image/bmp",
+    ".avif": "image/avif",
+}
+
+
+def parse_bool(value):
+    if value.lower() in ("true", "1", "yes", "y"):
+        return True
+    if value.lower() in ("false", "0", "no", "n"):
+        return False
+    raise argparse.ArgumentTypeError(f"invalid boolean value: {value!r}")
+
+
+def is_remote_ref(ref):
+    return ref.startswith(("http://", "https://", "data:image/"))
+
+
+def path_to_data_uri(path):
+    ext = os.path.splitext(path)[1].lower()
+    mime = MIME_MAP.get(ext)
+    if not mime:
+        mime, _ = mimetypes.guess_type(path)
+        if not mime:
+            mime = "application/octet-stream"
+    with open(path, "rb") as f:
+        b64 = base64.b64encode(f.read()).decode("ascii")
+    return f"data:{mime};base64,{b64}"
+
+
+def resolve_image(raw):
+    ref = raw.lstrip("@")
+    if is_remote_ref(ref):
+        return ref
+    if os.path.isfile(ref):
+        return path_to_data_uri(ref)
+    print(f"Error: --image input not found: {raw}", file=sys.stderr)
+    print("Hint: for uploaded files, use the resolved path from Media Understanding logs, "
+          "usually under media/inbound/images/.", file=sys.stderr)
+    sys.exit(1)
+
+
+def load_images_csv(csv_str):
+    items = []
+    for item in csv_str.split(","):
+        item = item.strip()
+        if item:
+            items.append(item)
+    return items
+
+
+def load_images_file(path):
+    if not os.path.isfile(path):
+        print(f"Error: --images-file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    items = []
+    with open(path, "r") as f:
+        for line in f:
+            line = line.strip().rstrip("\r")
+            if not line or line.startswith("#"):
+                continue
+            items.append(line)
+    return items
+
+
+def create_task(api_key, prompt, model, image_refs,
+                size="1024*1024", n=1, watermark=False):
+    resolved = [resolve_image(ref) for ref in image_refs]
+    payload = {
+        "model": model,
+        "input": {"prompt": prompt, "images": resolved},
+        "parameters": {
+            "size": size,
+            "n": n,
+            "watermark": watermark,
+        },
+    }
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    resp = requests.post(API_URL, json=payload, headers=headers, timeout=120)
+    resp.raise_for_status()
+    data = resp.json()
+
+    for key in ("task_id", "taskId", "taskID", "id"):
+        if key in data:
+            return data[key]
+        if isinstance(data.get("output"), dict) and key in data["output"]:
+            return data["output"][key]
+
+    print("Error: task_id not found in response.", file=sys.stderr)
+    print(json.dumps(data, ensure_ascii=False), file=sys.stderr)
+    sys.exit(1)
+
+
+def poll_task(api_key, task_id, poll_interval=2, max_wait=300):
+    headers = {"Authorization": f"Bearer {api_key}"}
+    start = time.time()
+
+    while True:
+        elapsed = time.time() - start
+        if elapsed > max_wait:
+            print(f"Error: timed out after {max_wait}s.", file=sys.stderr)
+            sys.exit(1)
+
+        resp = requests.get(f"{API_URL}/{task_id}", headers=headers, timeout=60)
+        resp.raise_for_status()
+        data = resp.json()
+
+        status = None
+        for key in ("status", "taskStatus", "task_status"):
+            if key in data:
+                status = data[key]
+                break
+            if isinstance(data.get("output"), dict) and key in data["output"]:
+                status = data["output"][key]
+                break
+
+        if status and status.lower() in ("succeeded", "success"):
+            return data
+        if status and status.lower() in ("failed", "error"):
+            print("STATUS=failed", file=sys.stderr)
+            print(json.dumps(data, ensure_ascii=False), file=sys.stderr)
+            sys.exit(1)
+
+        time.sleep(poll_interval)
+
+
+def extract_urls(data):
+    urls = []
+
+    def _walk(obj):
+        if isinstance(obj, dict):
+            if "url" in obj and isinstance(obj["url"], str):
+                urls.append(obj["url"])
+            for v in obj.values():
+                _walk(v)
+        elif isinstance(obj, list):
+            for item in obj:
+                _walk(item)
+
+    _walk(data)
+    return urls
+
+
+def reupload_for_signed_url(api_key, raw_url):
+    """Download from raw API URL (using API auth) and re-upload
+    to Sophnet OSS to obtain a publicly accessible signed URL.
+    Returns (signed_url, local_path) or (None, None) on failure."""
+    headers = {"Authorization": f"Bearer {api_key}"}
+    try:
+        resp = requests.get(raw_url, headers=headers, timeout=120, stream=True)
+        resp.raise_for_status()
+    except requests.RequestException as e:
+        print(f"Warning: failed to download image: {e}", file=sys.stderr)
+        return None, None
+
+    ext = os.path.splitext(raw_url.split("?")[0])[-1] or ".png"
+    fd, tmp_path = tempfile.mkstemp(suffix=ext, prefix="img_reup_")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            for chunk in resp.iter_content(8192):
+                f.write(chunk)
+    except IOError as e:
+        print(f"Warning: failed to write temp file: {e}", file=sys.stderr)
+        os.unlink(tmp_path)
+        return None, None
+
+    signed_url = sophnet_tools.upload_oss(tmp_path)
+    if not signed_url:
+        print("Warning: upload_oss returned no signed URL, keeping local file", file=sys.stderr)
+        return None, tmp_path
+
+    return signed_url, tmp_path
+
+
+class AppendImageAction(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        items = getattr(namespace, self.dest, None) or []
+        items.append(values)
+        setattr(namespace, self.dest, items)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Sophnet image editing")
+    parser.add_argument("--prompt", required=True, help="Edit instruction prompt")
+    parser.add_argument("--image", dest="images", action=AppendImageAction, default=[],
+                        help="Source image (URL, data URI, or local path). Repeatable.")
+    parser.add_argument("--images", dest="images_csv", default=None,
+                        help="Comma-separated image refs")
+    parser.add_argument("--images-file", default=None,
+                        help="Read image refs from file, one per line")
+    parser.add_argument("--model", default="Qwen-Image-Edit-2509",
+                        choices=VALID_MODELS, help="Model name")
+    parser.add_argument("--size", default="1024*1024", help="Image size")
+    parser.add_argument("--n", type=int, default=1, help="Number of outputs")
+    parser.add_argument("--watermark", type=parse_bool, default=False)
+    parser.add_argument("--poll-interval", type=int, default=2)
+    parser.add_argument("--max-wait", type=int, default=300)
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Validate and print input count only")
+    args = parser.parse_args()
+
+    all_images = list(args.images)
+    if args.images_csv:
+        all_images.extend(load_images_csv(args.images_csv))
+    if args.images_file:
+        all_images.extend(load_images_file(args.images_file))
+
+    if not all_images:
+        print("Error: at least one --image is required.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.dry_run:
+        print(f"INPUT_IMAGE_COUNT={len(all_images)}")
+        print("STATUS=dry_run")
+        return
+
+    api_key = sophnet_tools.get_api_key()
+    if not api_key:
+        print("Error: No API key found.", file=sys.stderr)
+        sys.exit(1)
+
+    task_id = create_task(
+        api_key, args.prompt, args.model, all_images,
+        size=args.size, n=args.n, watermark=args.watermark,
+    )
+    print(f"INPUT_IMAGE_COUNT={len(all_images)}")
+    print(f"TASK_ID={task_id}")
+
+    result = poll_task(api_key, task_id, args.poll_interval, args.max_wait)
+
+    print("STATUS=succeeded")
+
+    raw_urls = extract_urls(result)
+    if not raw_urls:
+        print("Error: url not found in response.", file=sys.stderr)
+        print(json.dumps(result, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+    print(f"OUTPUT_COUNT={len(raw_urls)}")
+    for i, raw_url in enumerate(raw_urls, 1):
+        signed_url, local_path = reupload_for_signed_url(api_key, raw_url)
+        print(f"IMAGE_URL={signed_url or raw_url}")
+        if local_path:
+            if signed_url:
+                os.unlink(local_path)
+            else:
+                print(f"PREVIEW_PATH={local_path}")
+
+
+if __name__ == "__main__":
+    main()