gspark-agent 0.4.0__tar.gz

gspark_agent-0.4.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: gspark-agent
+Version: 0.4.0
+Summary: G-spark / HUB Agent tools: CLI + MCP for /v1 API
+Author: G-spark
+License: Proprietary
+Project-URL: Homepage, https://api.g-spark.cn
+Project-URL: Documentation, https://api.g-spark.cn/api/agent
+Keywords: gspark,hub,cli,mcp,agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+
+# gspark-agent
+
+面向 AI Agent 的 G-spark / HUB 接入工具：**CLI + MCP**，共用同一套 `/v1` 客户端。
+
+## 安装
+
+```bash
+pip install "gspark-agent[mcp]"
+# 或隔离安装
+pipx install "gspark-agent[mcp]"
+```
+
+开发（本仓库）：
+
+```bash
+pip install "./packages/gspark-agent[mcp]"
+```
+
+## 配置
+
+```bash
+export GSPARK_API_KEY=sk_xxxx
+export GSPARK_BASE_URL=https://api.g-spark.cn   # 或其他节点，如 https://api.hqszh.com
+```
+
+兼容别名：`HUB_API_KEY`、`HUB_BASE_URL`。
+
+## CLI
+
+```bash
+gspark apps list --json
+gspark apps show video_01 --json
+gspark tasks estimate --app video_01 --input prompt="hello" --json
+gspark tasks run --app video_01 --input prompt="hello" --wait --json
+gspark tasks get <task_id> --json
+gspark account balance --json
+gspark account ledger --page 1 --size 20 --json
+```
+
+- `--json`：紧凑单行 JSON（便于 Agent / 管道）
+- 默认：缩进 JSON；`account ledger` 默认为表格
+
+`--input` 支持 JSON 数组/对象，例如：`--input tags='["a","b"]'`、`--input meta='{"k":1}'`。
+
+## MCP（Cursor）
+
+见 `agent_pack/mcp-config.example.json`；控制台「Agent 接入」页可下载完整接入包。
+
+```bash
+gspark-mcp
+```
+
+## Agent Skill
+
+`agent_pack/SKILL.md` 为全站通用说明书，配合 CLI 使用；无需为每个应用单独复制文档。
+
+## 许可
+
+Proprietary — 允许安装使用；勿再分发改牌。

gspark_agent-0.4.0/README.md

@@ -0,0 +1,59 @@
+# gspark-agent
+
+面向 AI Agent 的 G-spark / HUB 接入工具：**CLI + MCP**，共用同一套 `/v1` 客户端。
+
+## 安装
+
+```bash
+pip install "gspark-agent[mcp]"
+# 或隔离安装
+pipx install "gspark-agent[mcp]"
+```
+
+开发（本仓库）：
+
+```bash
+pip install "./packages/gspark-agent[mcp]"
+```
+
+## 配置
+
+```bash
+export GSPARK_API_KEY=sk_xxxx
+export GSPARK_BASE_URL=https://api.g-spark.cn   # 或其他节点，如 https://api.hqszh.com
+```
+
+兼容别名：`HUB_API_KEY`、`HUB_BASE_URL`。
+
+## CLI
+
+```bash
+gspark apps list --json
+gspark apps show video_01 --json
+gspark tasks estimate --app video_01 --input prompt="hello" --json
+gspark tasks run --app video_01 --input prompt="hello" --wait --json
+gspark tasks get <task_id> --json
+gspark account balance --json
+gspark account ledger --page 1 --size 20 --json
+```
+
+- `--json`：紧凑单行 JSON（便于 Agent / 管道）
+- 默认：缩进 JSON；`account ledger` 默认为表格
+
+`--input` 支持 JSON 数组/对象，例如：`--input tags='["a","b"]'`、`--input meta='{"k":1}'`。
+
+## MCP（Cursor）
+
+见 `agent_pack/mcp-config.example.json`；控制台「Agent 接入」页可下载完整接入包。
+
+```bash
+gspark-mcp
+```
+
+## Agent Skill
+
+`agent_pack/SKILL.md` 为全站通用说明书，配合 CLI 使用；无需为每个应用单独复制文档。
+
+## 许可
+
+Proprietary — 允许安装使用；勿再分发改牌。

gspark_agent-0.4.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gspark-agent"
+version = "0.4.0"
+description = "G-spark / HUB Agent tools: CLI + MCP for /v1 API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "G-spark" }]
+keywords = ["gspark", "hub", "cli", "mcp", "agent"]
+dependencies = [
+  "httpx>=0.27",
+  "typer>=0.12",
+  "rich>=13",
+]
+
+[project.urls]
+Homepage = "https://api.g-spark.cn"
+Documentation = "https://api.g-spark.cn/api/agent"
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.2"]
+
+[project.scripts]
+gspark = "gspark_agent.cli:app"
+gspark-mcp = "gspark_agent.mcp_server:cli_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gspark_agent-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gspark_agent-0.4.0/src/gspark_agent/__init__.py

@@ -0,0 +1,3 @@
+"""G-spark / HUB agent integration: shared client, CLI, MCP."""
+
+__version__ = "0.4.0"

gspark_agent-0.4.0/src/gspark_agent/cli.py

@@ -0,0 +1,440 @@
+"""G-spark CLI — discover apps dynamically, run tasks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from gspark_agent.cli_util import coerce_value, dumps_payload, ensure_idempotency_key
+from gspark_agent.client import GsparkClient, GsparkError
+
+app = typer.Typer(no_args_is_help=True, help="G-spark / HUB Agent CLI")
+apps_app = typer.Typer(help="应用目录与 Schema")
+models_app = typer.Typer(help="模型目录（app_kind=model）")
+skills_app = typer.Typer(help="Skill 库（授权后可读正文）")
+tasks_app = typer.Typer(help="任务创建、查询、等待")
+account_app = typer.Typer(help="账户余额与流水")
+app.add_typer(apps_app, name="apps")
+app.add_typer(models_app, name="models")
+app.add_typer(skills_app, name="skills")
+app.add_typer(tasks_app, name="tasks")
+data_app = typer.Typer(help="数据中心（社媒数据 API）")
+app.add_typer(data_app, name="data")
+
+
+def _parse_inputs(pairs: list[str] | None) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for raw in pairs or []:
+        if "=" not in raw:
+            raise typer.BadParameter(f"无效 --input，需要 key=value: {raw}")
+        k, v = raw.split("=", 1)
+        k = k.strip()
+        if not k:
+            raise typer.BadParameter(f"无效 --input: {raw}")
+        out[k] = coerce_value(v)
+    return out
+
+
+def _coerce_value(v: str) -> Any:
+    """Backward-compatible alias for tests / callers."""
+    return coerce_value(v)
+
+
+def _ensure_idempotency_key(key: str) -> str:
+    return ensure_idempotency_key(key)
+
+
+def _emit(data: Any, *, as_json: bool) -> None:
+    typer.echo(dumps_payload(data, as_json=as_json))
+
+
+def _client() -> GsparkClient:
+    try:
+        return GsparkClient.from_env()
+    except GsparkError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(2) from e
+
+
+@apps_app.command("list")
+def apps_list(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(50, min=1, max=100),
+    app_kind: str = typer.Option("", "--kind", help="workflow | model | 空=全部"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """列出已发布应用（后台新上架会自动出现）。"""
+    c = _client()
+    try:
+        kind = (app_kind or "").strip() or None
+        _emit(c.list_apps(page=page, size=size, app_kind=kind), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@models_app.command("list")
+def models_list(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(50, min=1, max=100),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """列出已发布模型（等价于 apps list --kind model）。"""
+    c = _client()
+    try:
+        _emit(c.list_models(page=page, size=size), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@apps_app.command("show")
+def apps_show(
+    app_code: str = typer.Argument(..., help="应用 app_code"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """查看应用详情、inputs 字段 Schema 与定价。"""
+    c = _client()
+    try:
+        _emit(c.get_app(app_code), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@skills_app.command("list")
+def skills_list(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(50, min=1, max=100),
+    usable_only: bool = typer.Option(False, "--usable-only", help="仅已授权"),
+    q: str = typer.Option("", "--q", help="搜索"),
+    access_type: str = typer.Option("", "--access-type", help="free|membership|paid"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """列出 Skill 库（元数据；不含未授权正文）。"""
+    c = _client()
+    try:
+        _emit(
+            c.list_skills(
+                page=page,
+                size=size,
+                usable_only=usable_only,
+                q=q,
+                access_type=access_type,
+            ),
+            as_json=json_out,
+        )
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@skills_app.command("show")
+def skills_show(
+    skill_code: str = typer.Argument(..., help="Skill code"),
+    include_content: bool = typer.Option(
+        False,
+        "--include-content",
+        help="无权限时强制要求正文（会 403）；有权限时 show 默认已含 sections",
+    ),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """查看 Skill；已授权时响应含 sections 正文。"""
+    c = _client()
+    try:
+        _emit(c.get_skill(skill_code, include_content=include_content), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("estimate")
+def tasks_estimate(
+    app: str = typer.Option(..., "--app", help="app_code"),
+    input: list[str] = typer.Option(None, "--input", "-i", help="字段 key=value，可重复"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """预估费用（不扣费）。"""
+    c = _client()
+    inputs = _parse_inputs(input)
+    try:
+        _emit(c.estimate(app, inputs), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("create")
+def tasks_create(
+    app: str = typer.Option(..., "--app"),
+    input: list[str] = typer.Option(None, "--input", "-i"),
+    idempotency_key: str = typer.Option("", "--idempotency-key"),
+    client_ref: str = typer.Option("", "--client-ref"),
+    webhook_url: str = typer.Option("", "--webhook-url"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """创建任务（预扣），不等待完成。"""
+    c = _client()
+    inputs = _parse_inputs(input)
+    key = _ensure_idempotency_key(idempotency_key)
+    try:
+        _emit(
+            c.create_task(
+                app,
+                inputs,
+                idempotency_key=key,
+                client_ref=client_ref,
+                webhook_url=webhook_url,
+            ),
+            as_json=json_out,
+        )
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("run")
+def tasks_run(
+    app: str = typer.Option(..., "--app"),
+    input: list[str] = typer.Option(None, "--input", "-i"),
+    wait: bool = typer.Option(True, "--wait/--no-wait"),
+    timeout: float = typer.Option(600.0, "--timeout", help="等待终态秒数"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval"),
+    idempotency_key: str = typer.Option("", "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """创建任务并可选等待终态（推荐 Agent 使用）。"""
+    c = _client()
+    inputs = _parse_inputs(input)
+    key = _ensure_idempotency_key(idempotency_key)
+    try:
+        if wait:
+            _emit(
+                c.run_task(
+                    app,
+                    inputs,
+                    wait=True,
+                    timeout=timeout,
+                    poll_interval=poll_interval,
+                    idempotency_key=key,
+                ),
+                as_json=json_out,
+            )
+        else:
+            _emit(
+                c.create_task(app, inputs, idempotency_key=key),
+                as_json=json_out,
+            )
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("get")
+def tasks_get(
+    task_id: str = typer.Argument(...),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """查询任务状态与 outputs。"""
+    c = _client()
+    try:
+        _emit(c.get_task(task_id), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("list")
+def tasks_list(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(20, min=1, max=100),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """任务列表。"""
+    c = _client()
+    try:
+        _emit(c.list_tasks(page=page, size=size), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("cancel")
+def tasks_cancel(
+    task_id: str = typer.Argument(...),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """取消任务。"""
+    c = _client()
+    try:
+        _emit(c.cancel_task(task_id), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@tasks_app.command("wait")
+def tasks_wait(
+    task_id: str = typer.Argument(...),
+    timeout: float = typer.Option(600.0, "--timeout"),
+    poll_interval: float = typer.Option(2.0, "--poll-interval"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """轮询直到任务进入终态。"""
+    c = _client()
+    try:
+        _emit(c.wait_task(task_id, timeout=timeout, poll_interval=poll_interval), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@data_app.command("list")
+def data_list(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(50, min=1, max=100),
+    category: str = typer.Option("", "--category"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    c = _client()
+    try:
+        _emit(c.list_data_apis(page=page, size=size, category=category), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@data_app.command("show")
+def data_show(api_code: str, json_out: bool = typer.Option(False, "--json")) -> None:
+    c = _client()
+    try:
+        _emit(c.get_data_api(api_code), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@data_app.command("estimate")
+def data_estimate(
+    api: str = typer.Option(..., "--api"),
+    input: list[str] = typer.Option(None, "--input"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    c = _client()
+    try:
+        _emit(c.estimate_data_api(api, _parse_inputs(input)), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@data_app.command("invoke")
+def data_invoke(
+    api: str = typer.Option(..., "--api"),
+    input: list[str] = typer.Option(None, "--input"),
+    idempotency_key: str = typer.Option("", "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    c = _client()
+    try:
+        _emit(
+            c.invoke_data_api(
+                api,
+                _parse_inputs(input),
+                idempotency_key=_ensure_idempotency_key(idempotency_key),
+            ),
+            as_json=json_out,
+        )
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@data_app.command("run")
+def data_run(
+    api: str = typer.Option(..., "--api"),
+    input: list[str] = typer.Option(None, "--input"),
+    wait: bool = typer.Option(True, "--wait/--no-wait"),
+    idempotency_key: str = typer.Option("", "--idempotency-key"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    c = _client()
+    try:
+        _emit(
+            c.run_data_api(
+                api,
+                _parse_inputs(input),
+                wait=wait,
+                idempotency_key=_ensure_idempotency_key(idempotency_key),
+            ),
+            as_json=json_out,
+        )
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@account_app.command("balance")
+def account_balance(json_out: bool = typer.Option(False, "--json")) -> None:
+    """查询余额与短欠。"""
+    c = _client()
+    try:
+        _emit(c.balance(), as_json=json_out)
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+@account_app.command("ledger")
+def account_ledger(
+    page: int = typer.Option(1, min=1),
+    size: int = typer.Option(20, min=1, max=100),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """查询账户流水（充值、扣费、退款等，按时间倒序）。"""
+    c = _client()
+    try:
+        data = c.ledger(page=page, size=size)
+        if json_out:
+            _emit(data, as_json=True)
+            return
+        items = data.get("items") if isinstance(data, dict) else None
+        if not isinstance(items, list) or not items:
+            typer.echo(f"暂无流水（共 {data.get('total', 0) if isinstance(data, dict) else 0} 条）")
+            return
+        total = data.get("total", 0)
+        currency = data.get("currency") or "CNY"
+        typer.echo(f"流水 第 {data.get('page', page)} 页 / 共 {total} 条（{currency}）")
+        typer.echo(f"{'时间':<22} {'变动':>10} {'余额后':>10}  {'原因':<18} 关联")
+        typer.echo("-" * 78)
+        for row in items:
+            if not isinstance(row, dict):
+                continue
+            created = str(row.get("created_at") or "")[:19].replace("T", " ")
+            delta = row.get("delta")
+            if delta is None and row.get("delta_cents") is not None:
+                try:
+                    delta = round(int(row["delta_cents"]) / 100.0, 2)
+                except (TypeError, ValueError):
+                    delta = row.get("delta_cents")
+            after = row.get("balance_after")
+            if after is None and row.get("balance_after_cents") is not None:
+                try:
+                    after = round(int(row["balance_after_cents"]) / 100.0, 2)
+                except (TypeError, ValueError):
+                    after = row.get("balance_after_cents")
+            reason = str(row.get("reason") or "")[:18]
+            ref = f"{row.get('ref_type') or ''}:{row.get('ref_id') or ''}".strip(":")
+            typer.echo(f"{created:<22} {delta!s:>10} {after!s:>10}  {reason:<18} {ref}")
+    except GsparkError as e:
+        typer.secho(f"{e.code}: {e}" if e.code else str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

gspark_agent-0.4.0/src/gspark_agent/cli_util.py

@@ -0,0 +1,38 @@
+"""Shared CLI helpers (no Typer dependency — easy to unit-test)."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+
+def coerce_value(v: str) -> Any:
+    s = v.strip()
+    if s.lower() in {"true", "false"}:
+        return s.lower() == "true"
+    if s.lower() == "null":
+        return None
+    if (s.startswith("[") and s.endswith("]")) or (s.startswith("{") and s.endswith("}")):
+        try:
+            return json.loads(s)
+        except json.JSONDecodeError:
+            return v
+    try:
+        if "." in s:
+            return float(s)
+        return int(s)
+    except ValueError:
+        return v
+
+
+def ensure_idempotency_key(key: str) -> str:
+    """If empty, mint a UUID for this call. Retries must pass the same key explicitly."""
+    return (key or "").strip() or str(uuid.uuid4())
+
+
+def dumps_payload(data: Any, *, as_json: bool) -> str:
+    """--json → compact one-line; default → indented."""
+    if as_json:
+        return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+    return json.dumps(data, ensure_ascii=False, indent=2)