aiman-labs/ergouzi-agent-skills / skills/ergouzi-image-gen
ergouzi-image-gen
VerifiedSubmit 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.6 KB |
| agents/openai.yaml | config | 208 B |
| references/ai-guide.md | markdown | 932 B |
| references/model-reference.md | markdown | 5.2 KB |
| scripts/client.py | script | 20.1 KB |
| scripts/configure.py | script | 2.1 KB |
| scripts/media.py | script | 5.8 KB |
| scripts/run.py | script | 18.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |