@petercjl/seedaudiocli 0.0.0-bootstrap.0 → 0.1.1

package/seedaudiocli/evolink.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from .config import seedaudio_api_key, seedaudio_base_url
+
+
+class SeedAudioError(RuntimeError):
+    def __init__(self, message: str, code: str = "PROVIDER_FAILURE"):
+        super().__init__(message)
+        self.code = code
+
+
+def _headers(json_body: bool = True) -> dict[str, str]:
+    key = seedaudio_api_key()
+    if not key:
+        raise SeedAudioError("Run seedaudiocli setup to import a configuration file.", "CONFIG_REQUIRED")
+    headers = {"Authorization": f"Bearer {key}"}
+    if json_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def api_root() -> str:
+    return seedaudio_base_url()
+
+
+def create_url() -> str:
+    return f"{api_root()}/v1/audios/generations"
+
+
+def task_url(task_id: str) -> str:
+    return f"{api_root()}/v1/tasks/{task_id}"
+
+
+def _request(method: str, url: str, body: dict[str, Any] | None = None, timeout: int = 120) -> dict[str, Any]:
+    data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, headers=_headers(json_body=body is not None), method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            text = resp.read().decode("utf-8")
+            if not text:
+                return {}
+            return json.loads(text)
+    except urllib.error.HTTPError as e:
+        text = e.read().decode("utf-8", errors="replace")
+        if e.code in {401, 403}:
+            raise SeedAudioError("Provider rejected authorization. Check key validity and account permissions.", "AUTH_REQUIRED") from e
+        raise SeedAudioError(f"HTTP {e.code}: {text}") from e
+    except urllib.error.URLError as e:
+        raise SeedAudioError(f"Network error: {e}") from e
+    except json.JSONDecodeError as e:
+        raise SeedAudioError(f"Non-JSON response from EvoLink: {e}") from e
+
+
+def _request_with_retry(method: str, url: str, body: dict[str, Any] | None = None, timeout: int = 120) -> dict[str, Any]:
+    last_error: SeedAudioError | None = None
+    for attempt in range(1, 4):
+        try:
+            return _request(method, url, body, timeout)
+        except SeedAudioError as e:
+            last_error = e
+            if attempt < 3:
+                time.sleep(min(2 * attempt, 8))
+    raise last_error or SeedAudioError("Request failed")
+
+
+def create_task(payload: dict[str, Any]) -> dict[str, Any]:
+    return _request("POST", create_url(), payload)
+
+
+def get_task(task_id: str) -> dict[str, Any]:
+    return _request_with_retry("GET", task_url(task_id), None, timeout=60)
+
+
+def extract_task_id(response: dict[str, Any]) -> str | None:
+    for key in ("id", "task_id", "taskId"):
+        value = response.get(key)
+        if value:
+            return str(value)
+    return None
+
+
+def extract_status(response: dict[str, Any]) -> str:
+    value = response.get("status")
+    return str(value).lower() if value else "unknown"
+
+
+def extract_audio_urls(response: dict[str, Any]) -> list[str]:
+    urls: list[str] = []
+    result_data = response.get("result_data")
+    if isinstance(result_data, list):
+        for item in result_data:
+            if isinstance(item, dict):
+                value = item.get("audio_url")
+                if isinstance(value, str) and value.startswith(("http://", "https://")):
+                    urls.append(value)
+    results = response.get("results")
+    if isinstance(results, list):
+        for value in results:
+            if isinstance(value, str) and value.startswith(("http://", "https://")):
+                urls.append(value)
+    seen: list[str] = []
+    for url in urls:
+        if url not in seen:
+            seen.append(url)
+    return seen
+
+
+def infer_extension(url: str, output_format: str | None = None) -> str:
+    match = re.search(r"\.(mp3|wav|ogg|opus|pcm)(\?|$)", url, re.I)
+    if match:
+        ext = match.group(1).lower()
+        return "ogg_opus" if ext == "opus" else ext
+    return output_format or "mp3"
+
+
+def wait_for_task(task_id: str, interval: int = 5, timeout: int = 1800) -> dict[str, Any]:
+    deadline = time.time() + timeout
+    last_response: dict[str, Any] = {}
+    while time.time() < deadline:
+        last_response = get_task(task_id)
+        status = extract_status(last_response)
+        if status in {"completed", "failed", "cancelled", "canceled", "expired"}:
+            return last_response
+        time.sleep(interval)
+    raise SeedAudioError(f"Timed out waiting for task {task_id}. Last response: {json.dumps(last_response, ensure_ascii=False)}")
+
+
+def download_url(url: str, out: Path) -> Path:
+    out.parent.mkdir(parents=True, exist_ok=True)
+    req = urllib.request.Request(url, headers={"User-Agent": "seedaudiocli/0.1"})
+    last_error: urllib.error.URLError | None = None
+    for attempt in range(1, 4):
+        try:
+            with urllib.request.urlopen(req, timeout=300) as resp:
+                out.write_bytes(resp.read())
+            return out
+        except urllib.error.URLError as e:
+            last_error = e
+            if attempt < 3:
+                time.sleep(min(2 * attempt, 8))
+    raise SeedAudioError(f"Download failed: {last_error}") from last_error

package/seedaudiocli/jobs.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from .config import job_store_path
+
+
+TERMINAL_STATES = {"completed", "failed", "cancelled", "canceled", "expired"}
+
+
+def append_job(record: dict[str, Any], path: Path | None = None) -> None:
+    path = path or job_store_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    record = {"created_at": int(time.time()), **record}
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def read_jobs(path: Path | None = None) -> list[dict[str, Any]]:
+    paths = [path or job_store_path()]
+    jobs: list[dict[str, Any]] = []
+    for read_path in paths:
+        if not read_path.exists():
+            continue
+        for line in read_path.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            try:
+                jobs.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return jobs
+
+
+def find_by_hash(request_hash: str) -> dict[str, Any] | None:
+    for job in reversed(read_jobs()):
+        if job.get("request_hash") == request_hash and job.get("task_id"):
+            return job
+    return None
+
+
+def append_status(task_id: str, status: str, response: dict[str, Any] | None = None) -> None:
+    append_job({"event": "status", "task_id": task_id, "status": status, "response": response or {}})

package/seedaudiocli/payloads.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from .config import default_format, default_sample_rate, seedaudio_model
+
+
+FORMATS = {"wav", "mp3", "pcm", "ogg_opus"}
+SAMPLE_RATES = {8000, 16000, 24000, 32000, 44100, 48000}
+
+
+def read_prompt(prompt: str | None, prompt_file: str | None) -> str:
+    if prompt and prompt_file:
+        raise ValueError("Use either --prompt or --prompt-file, not both.")
+    if prompt_file:
+        return Path(prompt_file).expanduser().read_text(encoding="utf-8").strip()
+    if prompt:
+        return prompt.strip()
+    raise ValueError("Missing --prompt or --prompt-file.")
+
+
+def build_payload(
+    *,
+    prompt: str,
+    model: str | None = None,
+    audio_references: list[str] | None = None,
+    image_urls: list[str] | None = None,
+    output_format: str | None = None,
+    sample_rate: int | None = None,
+    speech_rate: float | None = None,
+    loudness_rate: float | None = None,
+    pitch_rate: int | None = None,
+    callback_url: str | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "model": model or seedaudio_model(),
+        "prompt": prompt,
+        "format": output_format or default_format(),
+        "sample_rate": sample_rate or default_sample_rate(),
+    }
+    if audio_references:
+        payload["audio_references"] = audio_references
+    if image_urls:
+        payload["image_urls"] = image_urls
+    if speech_rate is not None:
+        payload["speech_rate"] = speech_rate
+    if loudness_rate is not None:
+        payload["loudness_rate"] = loudness_rate
+    if pitch_rate is not None:
+        payload["pitch_rate"] = pitch_rate
+    if callback_url:
+        payload["callback_url"] = callback_url
+    return payload
+
+
+def validate_payload(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    prompt = payload.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip():
+        errors.append("prompt is required.")
+    elif len(prompt) > 1500:
+        errors.append("prompt must be <= 1500 characters.")
+
+    if payload.get("model") != "doubao-seed-audio-1-0":
+        errors.append("model must be doubao-seed-audio-1-0 unless the gateway adds another compatible model.")
+
+    fmt = payload.get("format")
+    if fmt not in FORMATS:
+        errors.append(f"format must be one of {sorted(FORMATS)}.")
+
+    sample_rate = payload.get("sample_rate")
+    if sample_rate not in SAMPLE_RATES:
+        errors.append(f"sample_rate must be one of {sorted(SAMPLE_RATES)}.")
+
+    audio_refs = payload.get("audio_references")
+    image_urls = payload.get("image_urls")
+    if audio_refs and image_urls:
+        errors.append("audio_references and image_urls are mutually exclusive.")
+    if audio_refs is not None:
+        if not isinstance(audio_refs, list):
+            errors.append("audio_references must be a list.")
+        elif len(audio_refs) > 3:
+            errors.append("audio_references supports at most 3 items.")
+    if image_urls is not None:
+        if not isinstance(image_urls, list):
+            errors.append("image_urls must be a list.")
+        elif len(image_urls) > 1:
+            errors.append("image_urls supports at most 1 item.")
+
+    for key in ("speech_rate", "loudness_rate"):
+        if key in payload:
+            value = payload[key]
+            if not isinstance(value, (int, float)) or value < 0.5 or value > 2:
+                errors.append(f"{key} must be between 0.5 and 2.0.")
+    if "pitch_rate" in payload:
+        value = payload["pitch_rate"]
+        if not isinstance(value, int) or value < -12 or value > 12:
+            errors.append("pitch_rate must be an integer between -12 and 12.")
+    return errors
+
+
+def request_hash(payload: dict[str, Any]) -> str:
+    data = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(data).hexdigest()[:16]

package/seedaudiocli.config.example.json

@@ -0,0 +1,7 @@
+{
+  "SEEDAUDIO_API_KEY": "",
+  "SEEDAUDIO_BASE_URL": "https://api.evolink.ai",
+  "SEEDAUDIO_MODEL": "doubao-seed-audio-1-0",
+  "SEEDAUDIO_DEFAULT_FORMAT": "mp3",
+  "SEEDAUDIO_DEFAULT_SAMPLE_RATE": "44100"
+}

package/seedaudiocli.env.example

@@ -0,0 +1,10 @@
+# Copy to ~/.config/seedaudiocli/seedaudiocli.env or run:
+# seedaudiocli config init
+#
+# This is a local-only file. Do not commit real API keys.
+
+SEEDAUDIO_API_KEY=
+SEEDAUDIO_BASE_URL=https://api.evolink.ai
+SEEDAUDIO_MODEL=doubao-seed-audio-1-0
+SEEDAUDIO_DEFAULT_FORMAT=mp3
+SEEDAUDIO_DEFAULT_SAMPLE_RATE=44100

package/skills/seedaudiocli/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: seedaudiocli
+description: Generate audio through EvoLink Seed Audio using the seedaudiocli CLI; import configuration files, submit explicit audio requests, recover tasks, and download results.
+---
+
+# Seed Audio CLI
+
+This companion Skill documents the capability contract of `@petercjl/seedaudiocli`.
+Inputs are an explicit audio prompt, selected reference mode, output settings and a destination. Outputs are task IDs, status and downloaded audio paths. The calling application owns content strategy and audio acceptance; this Skill owns correct invocation and recovery.
+
+## Runtime and discovery
+
+Requires Node.js 22+, Python 3.9+ with SSL, network access to EvoLink, and an authorized API key. Run `seedaudiocli version`, `seedaudiocli capabilities --json` and `seedaudiocli doctor --json`. Resolve the canonical Skill with `seedaudiocli skill source --json`; the returned `source` directory belongs to the installed npm package.
+
+Use the current host's terminal execution capability. Its mapping is declared in [capabilities.json](capabilities.json) and the selected adapter: [Codex](adapters/codex.json) or [SealSeek](adapters/sealseek.json). Adapter mappings are implemented; host integration evidence is separate from CLI tests.
+
+## Main flow
+
+1. Check `seedaudiocli auth status`. This checks local configuration only and does not prove the key is accepted remotely.
+2. If configuration is missing, ask the user for the local path to the administrator-provided JSON or env configuration file. Import with `seedaudiocli config import "FILE"`. Pass the file path to the CLI without displaying or reading its secret contents into the conversation. If configuration already exists, preserve it; an explicitly requested replacement uses `--replace`, which creates a backup. After import, return to step 1. Interactive terminal users can run `seedaudiocli setup`.
+3. Preserve the caller's prompt, model, reference mode and output choices. Choose `generate text`, `generate audio-ref`, or `generate image-ref` according to those inputs. Prompts support at most 1500 characters; audio mode accepts up to three preset IDs or public audio URLs; image mode accepts exactly one public image URL. Local references need an authorized hosting step outside this CLI.
+4. Validate the intended request with `--dry-run`. Validation must succeed before paid submission. Configuration import and dry-run do not submit generation jobs.
+5. Execute the authorized request with `--wait --download "OUTPUT_DIRECTORY"` when local delivery is required. Save the returned task ID. Generation can incur service charges.
+6. Inspect status and actual output paths. A completed task without an audio file is incomplete delivery. Report the task ID, file and material limitations; content quality remains the caller's acceptance responsibility.
+
+## Invocation examples
+
+```bash
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --dry-run
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --wait --download ./audio
+seedaudiocli generate audio-ref --audio-reference zh_female_vv_uranus_bigtts --prompt "@audio1 今天的咖啡刚刚好。" --wait --download ./audio
+seedaudiocli generate image-ref --image-url "https://example.com/reference.jpg" --prompt "Generate audio matching the supplied reference." --dry-run
+seedaudiocli task get TASK_ID
+seedaudiocli task wait TASK_ID --download ./audio
+seedaudiocli task jobs --limit 20
+```
+
+Use `@audio1` through `@audio3` in prompts to address the corresponding audio references. Supported formats are mp3, wav, pcm and ogg_opus. Use the command help for sample-rate and other constraints. Explicit unsupported requests require caller resolution.
+
+## Error and recovery branches
+
+- `CONFIG_REQUIRED`: request the file path, import, then return to authentication check.
+- `CONFIG_INVALID` or `CONFIG_READ_FAILED`: request a corrected file/path. Preserve the saved configuration.
+- `CONFIG_EXISTS`: explain that configuration already exists; replace only when the user requests it.
+- `AUTH_REQUIRED`: the provider rejected credentials or permissions. Request a valid replacement or account correction, then resume the same intended operation.
+- `PYTHON_REQUIRED`: install a supported Python runtime in the host's managed environment; verify with `doctor` before returning to the main flow.
+- Network failure or polling timeout: retain configuration and recover using the existing task ID. Do not submit a duplicate paid job to fix a polling error.
+- Unknown submission outcome: inspect task history and provider evidence before any new explicitly authorized submission. `--force` intentionally bypasses local request deduplication and can charge again.
+- Provider failure: report it with the task ID. Changing prompt, references or model is a caller decision.
+
+## Installation and update
+
+`seedaudiocli skill install --agent codex` installs a managed copy. For SealSeek supply the actual discovery directory with `--root SKILLS_DIRECTORY` or `SEALSEEK_SKILLS_DIR`; installation refuses to guess the host's layout. Existing unmanaged Skills are preserved. `skill status` reports ownership and freshness; `skill update` backs up managed files and preserves customized UI metadata. Edited managed content requires reconciliation.
+
+Run `seedaudiocli update instructions` for the package update and Skill synchronization commands. Updates are explicit; configuration and history live outside the npm package and remain available afterward. Record recurring contract failures for a separately authorized package update.

package/skills/seedaudiocli/adapters/codex.json

@@ -0,0 +1,23 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "codex",
+  "mappings": [
+    {
+      "capability_id": "command.execute",
+      "status": "implemented",
+      "features": [
+        "argv",
+        "exit-code",
+        "stdout",
+        "local-files"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "command": "seedaudiocli",
+        "discovery": "PATH; verify version and capabilities --json. Invoke through the host advertised terminal tool.",
+        "result": "Parse JSON stdout and exit code; preserve task_id and downloaded_to. Nonzero is failure."
+      }
+    }
+  ]
+}

package/skills/seedaudiocli/adapters/sealseek.json

@@ -0,0 +1,23 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "sealseek",
+  "mappings": [
+    {
+      "capability_id": "command.execute",
+      "status": "implemented",
+      "features": [
+        "argv",
+        "exit-code",
+        "stdout",
+        "local-files"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "command": "seedaudiocli",
+        "discovery": "PATH; verify version and capabilities --json. Invoke through the host advertised terminal tool.",
+        "result": "Parse JSON stdout and exit code; preserve task_id and downloaded_to. Nonzero is failure."
+      }
+    }
+  ]
+}

package/skills/seedaudiocli/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Seed Audio"
+  short_description: "Generate audio and manage Seed Audio tasks"

package/skills/seedaudiocli/capabilities.json

@@ -0,0 +1,40 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "target_platforms": [
+    "codex",
+    "sealseek"
+  ],
+  "capabilities": [
+    {
+      "id": "command.execute",
+      "purpose": "Execute the installed seedaudiocli contract and parse JSON results",
+      "required": true,
+      "required_features": [
+        "argv",
+        "exit-code",
+        "stdout",
+        "local-files"
+      ],
+      "input_fields": [
+        "arguments"
+      ],
+      "output_fields": [
+        "exit_code",
+        "stdout"
+      ],
+      "side_effects": {
+        "external_mutation": true,
+        "may_cost_money": true,
+        "authorization": "Configuration import writes local credentials; generation requires user-authorized paid service use."
+      },
+      "errors": [
+        "CONFIG_REQUIRED",
+        "CONFIG_INVALID",
+        "AUTH_REQUIRED",
+        "PYTHON_REQUIRED",
+        "PROVIDER_FAILURE"
+      ]
+    }
+  ]
+}