Skip to content

aiman-labs/ergouzi-agent-skills / skills/ergouzi-image-gen

ergouzi-image-gen

Verified

Submit and complete Ergouzi image generation, editing, virtual try-on, upscaling, and background-removal tasks through ergouzi.life, including tasks that use local image files or HTTPS URLs. Use when Codex must call an ergouzi/e-image* or ergouzi/e-rmbg model, poll the asynchronous task, download its outputs, resume a task ID, or cancel an image task.

FileKindSize
SKILL.mdskill md6.6 KB
agents/openai.yamlconfig208 B
references/ai-guide.mdmarkdown932 B
references/model-reference.mdmarkdown5.2 KB
scripts/client.pyscript20.1 KB
scripts/configure.pyscript2.1 KB
scripts/media.pyscript5.8 KB
scripts/run.pyscript18.2 KB

scripts/run.py

View on GitHub
#!/usr/bin/env python3
"""Run and resume Ergouzi image prediction tasks."""

from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import sys
import time
import uuid
from pathlib import Path
from typing import Any
from urllib.parse import quote

from client import (
    ApiError,
    ClientError,
    Credentials,
    api_json,
    download_outputs,
    load_credentials,
)
from media import LOCAL_FILE_KEY, resolve_media_inputs


ALLOWED_MODELS = {
    "ergouzi/e-image",
    "ergouzi/e-image-edit",
    "ergouzi/e-image-ideogram",
    "ergouzi/e-image-try-on",
    "ergouzi/e-image-upscale",
    "ergouzi/e-rmbg",
}
VERSION_PREDICTION_IDS = {
    "ergouzi/e-rmbg": "a029dff38972b5fda4ec5d75d7d1cd25aeff621d2cf4946a41055d7db66b80bc",
}
TASK_ID_PATTERN = re.compile(r"^task_[A-Za-z0-9_-]+$")
PROMPT_MODELS = ALLOWED_MODELS - {"ergouzi/e-image-upscale", "ergouzi/e-rmbg"}
DEFAULT_OUTPUT_DIR = "output/ergouzi-image-gen"
TERMINAL_STATUSES = {"succeeded", "failed", "canceled", "unknown"}
TRANSIENT_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
MAX_INPUT_BYTES = 4 * 1024 * 1024
IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")


class PredictionTimeout(ClientError):
    def __init__(self, task_id: str):
        super().__init__(f"Prediction timed out; resume task {task_id} with the status command")
        self.task_id = task_id


def _print_json(value: dict[str, Any]) -> None:
    print(json.dumps(value, ensure_ascii=False, indent=2))


def _model_path(model: str) -> str:
    if model not in ALLOWED_MODELS:
        raise ClientError(f"Unsupported image model: {model}")
    owner, name = model.split("/", 1)
    return f"/customer/v1/models/{quote(owner, safe='')}/{quote(name, safe='')}/predictions"


def _prediction_request(model: str, model_input: dict[str, Any]) -> tuple[str, dict[str, Any]]:
    version = VERSION_PREDICTION_IDS.get(model)
    if version:
        return "/customer/v1/predictions", {"version": version, "input": model_input}
    return _model_path(model), {"input": model_input}


def _validate_task_id(task_id: str) -> str:
    if not TASK_ID_PATTERN.fullmatch(task_id):
        raise ClientError("task_id must be a task_ identifier")
    return task_id


def _media_argument(value: str) -> Any:
    if value.startswith(("https://", "data:")):
        return value
    return {LOCAL_FILE_KEY: value}


def _read_input(args: argparse.Namespace) -> dict[str, Any]:
    value: dict[str, Any] = {}
    if args.input_file:
        if args.input_file == "-":
            raw = sys.stdin.buffer.read(MAX_INPUT_BYTES + 1)
        else:
            path = Path(args.input_file).expanduser()
            if path.stat().st_size > MAX_INPUT_BYTES:
                raise ClientError("Input JSON exceeds 4 MiB")
            raw = path.read_bytes()
    elif args.input_json:
        raw = args.input_json.encode("utf-8")
    else:
        raw = b""
    if raw:
        if len(raw) > MAX_INPUT_BYTES:
            raise ClientError("Input JSON exceeds 4 MiB")
        try:
            decoded = json.loads(raw.decode("utf-8-sig"))
        except (UnicodeDecodeError, json.JSONDecodeError) as error:
            raise ClientError("Input must be a UTF-8 JSON object") from error
        if not isinstance(decoded, dict):
            raise ClientError("Input must be a JSON object")
        value.update(decoded)
    if args.prompt is not None and args.model not in PROMPT_MODELS:
        raise ClientError(f"--prompt is not valid for {args.model}")
    if args.prompt is not None:
        value["prompt"] = args.prompt
    if args.image:
        if args.model == "ergouzi/e-image-edit":
            value["images"] = [_media_argument(item) for item in args.image]
        elif args.model in {"ergouzi/e-image-upscale", "ergouzi/e-rmbg"} and len(args.image) == 1:
            value["image"] = _media_argument(args.image[0])
        else:
            raise ClientError(f"--image is not valid for {args.model}")
    for argument, field in (
        (args.person_image, "person_image"),
        (args.reference_pose, "reference_pose"),
    ):
        if argument:
            if args.model != "ergouzi/e-image-try-on":
                raise ClientError(f"--{field.replace('_', '-')} is only valid for ergouzi/e-image-try-on")
            value[field] = _media_argument(argument)
    if args.garment_image:
        if args.model != "ergouzi/e-image-try-on":
            raise ClientError("--garment-image is only valid for ergouzi/e-image-try-on")
        value["garment_images"] = [_media_argument(item) for item in args.garment_image]
    value = resolve_media_inputs(args.model, value)
    expanded = json.dumps(value, ensure_ascii=False).encode("utf-8")
    if len(expanded) > MAX_INPUT_BYTES:
        raise ClientError("Expanded input JSON exceeds 4 MiB")
    return value


def _output_path(value: str | None) -> Path | None:
    if not value:
        return None
    path = Path(value).expanduser().resolve()
    if path.suffix.lower() not in {".jpg", ".jpeg", ".png", ".webp"}:
        raise ClientError("Image output path must end in .jpg, .jpeg, .png, or .webp")
    if path.exists():
        raise ClientError(f"Output file already exists: {path}")
    return path


def _receipt_path(output_dir: Path, task_id: str) -> Path:
    safe_id = re.sub(r"[^A-Za-z0-9_-]", "_", task_id)
    return output_dir / f"{safe_id}.json"


def _write_receipt(
    output_dir: Path,
    task_id: str,
    model: str,
    status: str,
    files: list[Path] | None = None,
    idempotency_key: str | None = None,
) -> Path:
    output_dir.mkdir(parents=True, exist_ok=True)
    path = _receipt_path(output_dir, task_id)
    if idempotency_key is None and path.exists():
        try:
            previous = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            previous = {}
        if isinstance(previous, dict) and isinstance(previous.get("idempotency_key"), str):
            idempotency_key = previous["idempotency_key"]
    receipt = {
        "task_id": task_id,
        "model": model,
        "status": status,
        "files": [str(item) for item in files or []],
    }
    if idempotency_key:
        receipt["idempotency_key"] = idempotency_key
    temporary = path.with_suffix(".json.tmp")
    with temporary.open("w", encoding="utf-8") as handle:
        json.dump(receipt, handle, ensure_ascii=False, indent=2)
        handle.write("\n")
        handle.flush()
        os.fsync(handle.fileno())
    temporary.replace(path)
    return path.resolve()


def _input_fingerprint(model_input: dict[str, Any]) -> str:
    encoded = json.dumps(
        model_input, ensure_ascii=False, sort_keys=True, separators=(",", ":")
    ).encode("utf-8")
    return hashlib.sha256(encoded).hexdigest()


def _validate_idempotency_key(value: str) -> str:
    if not IDEMPOTENCY_KEY_PATTERN.fullmatch(value):
        raise ClientError(
            "idempotency key must be 1-128 ASCII letters, digits, ., _, :, or -"
        )
    return value


def _pending_path(output_dir: Path, idempotency_key: str) -> Path:
    digest = hashlib.sha256(idempotency_key.encode("ascii")).hexdigest()
    return output_dir / f".pending-{digest}.json"


def _find_pending(output_dir: Path, model: str, fingerprint: str) -> dict[str, str] | None:
    for path in output_dir.glob(".pending-*.json"):
        try:
            pending = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            continue
        if (
            isinstance(pending, dict)
            and pending.get("model") == model
            and pending.get("input_sha256") == fingerprint
            and isinstance(pending.get("idempotency_key"), str)
        ):
            return pending
    return None


def _write_pending(
    output_dir: Path, model: str, idempotency_key: str, fingerprint: str
) -> Path:
    output_dir.mkdir(parents=True, exist_ok=True)
    path = _pending_path(output_dir, idempotency_key)
    if path.exists():
        try:
            pending = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError) as error:
            raise ClientError(f"Pending submission record is invalid: {path}") from error
        if not (
            isinstance(pending, dict)
            and pending.get("model") == model
            and pending.get("input_sha256") == fingerprint
        ):
            raise ClientError("Idempotency key is already associated with another submission")
        return path
    temporary = path.with_suffix(".json.tmp")
    with temporary.open("w", encoding="utf-8") as handle:
        json.dump(
            {
                "model": model,
                "idempotency_key": idempotency_key,
                "input_sha256": fingerprint,
            },
            handle,
            indent=2,
        )
        handle.write("\n")
        handle.flush()
        os.fsync(handle.fileno())
    temporary.replace(path)
    return path


def _remove_pending(output_dir: Path, idempotency_key: str) -> None:
    _pending_path(output_dir, idempotency_key).unlink(missing_ok=True)


def _task_status(payload: dict[str, Any]) -> str:
    return str(payload.get("status", "")).strip().lower()


def _fetch(task_id: str) -> dict[str, Any]:
    task_id = _validate_task_id(task_id)
    credentials = load_credentials()
    payload, _ = api_json(
        credentials,
        "GET",
        f"/customer/v1/predictions/{quote(task_id, safe='')}",
    )
    return payload


def _poll(task_id: str, timeout_seconds: int, poll_interval: float) -> dict[str, Any]:
    deadline = time.monotonic() + timeout_seconds
    delay = poll_interval
    last_status = ""
    while time.monotonic() < deadline:
        try:
            payload = _fetch(task_id)
        except ApiError as error:
            if error.status is not None and error.status not in TRANSIENT_STATUS_CODES:
                raise
            time.sleep(min(delay, max(0.0, deadline - time.monotonic())))
            delay = min(delay * 1.5, 10.0)
            continue
        status = _task_status(payload)
        if status != last_status:
            print(f"Task {task_id}: {status or 'pending'}", file=sys.stderr)
            last_status = status
        if status in TERMINAL_STATUSES:
            return payload
        time.sleep(min(delay, max(0.0, deadline - time.monotonic())))
        delay = min(delay * 1.5, 10.0)
    raise PredictionTimeout(task_id)


def _submit(model: str, model_input: dict[str, Any], idempotency_key: str) -> dict[str, Any]:
    credentials = load_credentials()
    path, body = _prediction_request(model, model_input)
    delay = 0.5
    for attempt in range(3):
        try:
            payload, _ = api_json(
                credentials,
                "POST",
                path,
                body,
                {"Idempotency-Key": idempotency_key},
            )
            return payload
        except ApiError as error:
            retryable = error.status is None or error.status in TRANSIENT_STATUS_CODES
            if not retryable or attempt == 2:
                raise
            time.sleep(delay)
            delay *= 2
    raise ClientError("Prediction submission failed")


def _complete(
    payload: dict[str, Any],
    output_dir: Path,
    download: bool,
    output_path: Path | None = None,
) -> tuple[dict[str, Any], int]:
    credentials = load_credentials()
    task_id = str(payload.get("id", ""))
    model = str(payload.get("model", ""))
    status = _task_status(payload)
    files = (
        download_outputs(
            credentials,
            payload.get("output"),
            output_dir,
            output_path=output_path,
            expected_media_types=frozenset({"image/jpeg", "image/png", "image/webp"}),
        )
        if download and status == "succeeded"
        else []
    )
    receipt = _write_receipt(output_dir, task_id, model, status, files)
    result: dict[str, Any] = {
        "task_id": task_id,
        "model": model,
        "status": status,
        "files": [str(path) for path in files],
        "receipt": str(receipt),
    }
    if payload.get("error"):
        result["error"] = payload["error"]
    if not files and payload.get("output") is not None:
        result["output"] = payload["output"]
    return result, 0 if status == "succeeded" else 2


def _predict(args: argparse.Namespace) -> int:
    output_path = _output_path(args.output)
    model_input = _read_input(args)
    output_dir = output_path.parent if output_path else Path(args.output_dir).expanduser().resolve()
    fingerprint = _input_fingerprint(model_input)
    if args.idempotency_key is not None:
        idempotency_key = _validate_idempotency_key(args.idempotency_key)
    else:
        pending = _find_pending(output_dir, args.model, fingerprint)
        if pending:
            raise ClientError(
                "An unresolved submission already exists; retry with "
                f"--idempotency-key {pending['idempotency_key']}"
            )
        idempotency_key = f"ergouzi-skill-{uuid.uuid4()}"
    pending_path = _write_pending(output_dir, args.model, idempotency_key, fingerprint)
    print(f"Idempotency key: {idempotency_key}; pending record: {pending_path}", file=sys.stderr)
    try:
        payload = _submit(args.model, model_input, idempotency_key)
    except ClientError as error:
        if not isinstance(error, ApiError) or (
            error.status is not None and error.status not in TRANSIENT_STATUS_CODES
        ):
            _remove_pending(output_dir, idempotency_key)
        raise
    task_id = _validate_task_id(str(payload.get("id", "")))
    receipt = _write_receipt(
        output_dir, task_id, args.model, _task_status(payload), idempotency_key=idempotency_key
    )
    _remove_pending(output_dir, idempotency_key)
    print(f"Task created: {task_id}; receipt: {receipt}", file=sys.stderr)
    if args.no_wait:
        _print_json(
            {
                "task_id": task_id,
                "model": args.model,
                "status": _task_status(payload),
                "receipt": str(receipt),
            }
        )
        return 0
    completed = _poll(task_id, args.timeout_seconds, args.poll_interval)
    result, exit_code = _complete(completed, output_dir, not args.no_download, output_path)
    _print_json(result)
    return exit_code


def _status(args: argparse.Namespace) -> int:
    payload = (
        _poll(args.task_id, args.timeout_seconds, args.poll_interval)
        if args.wait
        else _fetch(args.task_id)
    )
    output_path = _output_path(args.output)
    output_dir = output_path.parent if output_path else Path(args.output_dir).expanduser().resolve()
    result, exit_code = _complete(payload, output_dir, args.download, output_path)
    _print_json(result)
    return exit_code if _task_status(payload) in TERMINAL_STATUSES else 0


def _cancel(args: argparse.Namespace) -> int:
    task_id = _validate_task_id(args.task_id)
    credentials = load_credentials()
    payload, _ = api_json(
        credentials,
        "POST",
        f"/customer/v1/predictions/{quote(task_id, safe='')}/cancel",
    )
    _print_json(
        {
            "task_id": str(payload.get("id", task_id)),
            "model": str(payload.get("model", "")),
            "status": _task_status(payload),
        }
    )
    return 0


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    subparsers = parser.add_subparsers(dest="command", required=True)

    predict = subparsers.add_parser("predict", help="Submit, poll, and download a task")
    predict.add_argument("--model", required=True, choices=sorted(ALLOWED_MODELS))
    predict.add_argument("--prompt")
    source = predict.add_mutually_exclusive_group()
    source.add_argument(
        "--input-file", help="UTF-8 JSON object (BOM accepted), or - for stdin"
    )
    source.add_argument("--input-json", help="Inline JSON object")
    predict.add_argument("--image", action="append", default=[], help="Local path or HTTPS URL")
    predict.add_argument("--person-image", help="Try-on person image path or HTTPS URL")
    predict.add_argument("--garment-image", action="append", default=[], help="Try-on garment path or HTTPS URL")
    predict.add_argument("--reference-pose", help="Try-on pose path or HTTPS URL")
    predict.add_argument("--output-dir", default=DEFAULT_OUTPUT_DIR)
    predict.add_argument("--output", help="Exact .jpg, .jpeg, .png, or .webp output path")
    predict.add_argument("--timeout-seconds", type=int, default=1200)
    predict.add_argument("--poll-interval", type=float, default=2.0)
    predict.add_argument("--no-wait", action="store_true")
    predict.add_argument("--no-download", action="store_true")
    predict.add_argument("--idempotency-key", help="Stable key to safely retry one submission")
    predict.set_defaults(handler=_predict)

    status = subparsers.add_parser("status", help="Read or resume a task")
    status.add_argument("--task-id", required=True)
    status.add_argument("--wait", action="store_true", help="Poll until the task finishes")
    status.add_argument("--download", action="store_true")
    status.add_argument("--output-dir", default=DEFAULT_OUTPUT_DIR)
    status.add_argument("--output", help="Exact .jpg, .jpeg, .png, or .webp output path")
    status.add_argument("--timeout-seconds", type=int, default=1200)
    status.add_argument("--poll-interval", type=float, default=2.0)
    status.set_defaults(handler=_status)

    cancel = subparsers.add_parser("cancel", help="Cancel a task")
    cancel.add_argument("--task-id", required=True)
    cancel.set_defaults(handler=_cancel)
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    if getattr(args, "timeout_seconds", 1) <= 0:
        print("Error: --timeout-seconds must be positive", file=sys.stderr)
        return 1
    if getattr(args, "poll_interval", 1.0) <= 0:
        print("Error: --poll-interval must be positive", file=sys.stderr)
        return 1
    try:
        return args.handler(args)
    except PredictionTimeout as error:
        _print_json({"task_id": error.task_id, "status": "timeout", "error": str(error)})
        return 3
    except (ApiError, ClientError, OSError, ValueError) as error:
        print(f"Error: {error}", file=sys.stderr)
        return 1
    except KeyboardInterrupt:
        print("Interrupted; use the printed task ID with the status command.", file=sys.stderr)
        return 130


if __name__ == "__main__":
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall