sv-cli 0.3.0__py3-none-any.whl

sv_cli/tasks.py

@@ -0,0 +1,168 @@
+"""Async task helpers.
+
+The public API root currently advertises tool endpoints, not a separate task
+endpoint. This module therefore keeps task handling generic: task-creating tool
+commands record the tool that produced a task ID, then task status/result calls
+use that tool endpoint with status/result actions unless a future definition
+states otherwise.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from .api_client import APIClient
+from .definitions import DefinitionsManager
+from .errors import ConfigError, TimeoutError
+from .utils import app_dir, read_json_file, write_json_file
+
+TASK_ID_KEYS = ("task_id", "taskId", "task", "id", "job_id", "jobId")
+STATUS_KEYS = ("status", "state", "task_status")
+DONE_STATES = {"done", "complete", "completed", "success", "succeeded", "finished", "ready"}
+ERROR_STATES = {"error", "failed", "failure", "cancelled", "canceled"}
+
+
+def tasks_path() -> Path:
+    return app_dir() / "tasks.json"
+
+
+def load_tasks() -> dict[str, Any]:
+    return read_json_file(tasks_path(), {}) or {}
+
+
+def save_task(task_id: str, tool: str, endpoint: str | None = None) -> None:
+    tasks = load_tasks()
+    tasks[task_id] = {"tool": tool, "endpoint": endpoint, "created_at": int(time.time())}
+    write_json_file(tasks_path(), tasks)
+
+
+def get_task_tool(task_id: str, tool: str | None = None) -> str:
+    if tool:
+        return tool
+    tasks = load_tasks()
+    entry = tasks.get(task_id)
+    if entry and entry.get("tool"):
+        return str(entry["tool"])
+    raise ConfigError(
+        f'No local tool mapping found for task "{task_id}". Re-run with --tool, for example: '
+        f"sv task status {task_id} --tool seogpt2"
+    )
+
+
+def extract_task_id(data: Any) -> str | None:
+    if isinstance(data, dict):
+        for key in TASK_ID_KEYS:
+            value = data.get(key)
+            if value:
+                return str(value)
+        for value in data.values():
+            found = extract_task_id(value)
+            if found:
+                return found
+    if isinstance(data, list):
+        for item in data:
+            found = extract_task_id(item)
+            if found:
+                return found
+    return None
+
+
+def extract_status(data: Any) -> str | None:
+    if isinstance(data, dict):
+        for key in STATUS_KEYS:
+            value = data.get(key)
+            if value:
+                return str(value).lower()
+        for value in data.values():
+            found = extract_status(value)
+            if found:
+                return found
+    return None
+
+
+def has_result(data: Any) -> bool:
+    # "data" is deliberately excluded: it's SV API's universal response envelope key,
+    # present on every response including in-progress status checks, so treating it as
+    # a completion signal made poll_once() below declare victory on the very first poll
+    # regardless of actual task status.
+    if isinstance(data, dict):
+        return any(key in data for key in ("result", "results", "output", "content"))
+    return data is not None
+
+
+def status_payload(task_id: str) -> dict[str, Any]:
+    return {"action": "getTaskStatus", "task_id": task_id}
+
+
+def result_payload(task_id: str) -> dict[str, Any]:
+    return {"action": "getResult", "task_id": task_id}
+
+
+def wait_for_task(
+    *,
+    task_id: str,
+    tool: str,
+    api_key: str,
+    definitions: DefinitionsManager,
+    client: APIClient,
+    timeout_seconds: int = 600,
+    poll_interval: int = 5,
+    no_progress: bool = False,
+    console: Console | None = None,
+) -> Any:
+    console = console or Console(stderr=True)
+    entry = definitions.get_tool(tool)
+    endpoint = entry.get("endpoint")
+    if not endpoint:
+        raise ConfigError(f'Tool "{tool}" does not have an endpoint in definitions cache.')
+
+    deadline = time.monotonic() + timeout_seconds
+
+    def poll_once() -> Any:
+        status_response = client.request_tool(
+            endpoint=str(endpoint), payload=status_payload(task_id), api_key=api_key, timeout=poll_interval + 30
+        ).data
+        status = extract_status(status_response)
+        if status in ERROR_STATES:
+            return status_response
+        if status in DONE_STATES or has_result(status_response):
+            # Some APIs return the result directly from status. If not, ask for result.
+            if any(key in status_response for key in ("result", "results", "output", "content")):
+                return status_response
+            return client.request_tool(endpoint=str(endpoint), payload=result_payload(task_id), api_key=api_key).data
+        return None
+
+    if no_progress:
+        while time.monotonic() < deadline:
+            result = poll_once()
+            if result is not None:
+                return result
+            time.sleep(poll_interval)
+    else:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("Polling task {task.fields[task_id]}"),
+            TimeElapsedColumn(),
+            console=console,
+            transient=True,
+        ) as progress:
+            progress_task = progress.add_task("poll", task_id=task_id, total=None)
+            while time.monotonic() < deadline:
+                result = poll_once()
+                if result is not None:
+                    progress.update(progress_task, completed=1)
+                    return result
+                time.sleep(poll_interval)
+
+    raise TimeoutError(
+        "The task is still running.\n"
+        f"Task ID:\n{task_id}\n"
+        "Check later with:\n"
+        f"sv task status {task_id}\n"
+        f"sv task result {task_id}"
+    )

sv_cli/utils.py

@@ -0,0 +1,204 @@
+"""Shared utility functions."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+_SECRET_KEYS = {"k", "key", "api_key", "apikey", "apiKey", "token", "authorization", "Authorization"}
+
+
+def app_dir() -> Path:
+    """Return the CLI state directory, overridable for tests.
+
+    SV_HOME is the current override. SEOVENDOR_HOME is accepted as a legacy
+    fallback so existing automation can migrate without losing local state.
+    """
+
+    override = os.environ.get("SV_HOME") or os.environ.get("SEOVENDOR_HOME")
+    return Path(override).expanduser() if override else Path.home() / ".sv"
+
+
+def legacy_app_dir() -> Path:
+    """Return the pre-brand-change state directory."""
+
+    return Path.home() / ".seovendor"
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def read_json_file(path: Path, default: Any = None) -> Any:
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+def write_json_file(path: Path, data: Any) -> None:
+    ensure_parent(path)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+def mask_secret(value: Any, visible: int = 4) -> Any:
+    if value is None:
+        return None
+    text = str(value)
+    if len(text) <= visible:
+        return "***masked***"
+    return f"***masked***{text[-visible:]}"
+
+
+def mask_mapping(data: Any) -> Any:
+    """Return a deep-copy-like structure with common secret fields masked."""
+
+    if isinstance(data, dict):
+        masked: dict[str, Any] = {}
+        for key, value in data.items():
+            if key in _SECRET_KEYS or key.lower() in _SECRET_KEYS:
+                masked[key] = mask_secret(value)
+            else:
+                masked[key] = mask_mapping(value)
+        return masked
+    if isinstance(data, list):
+        return [mask_mapping(item) for item in data]
+    return data
+
+
+def normalize_text(value: Any) -> str:
+    """Normalize text according to the spec's enum matching rules."""
+
+    text = str(value).lower().strip()
+    text = text.replace("_", " ").replace("-", " ")
+    text = re.sub(r"[^\w\s]", " ", text, flags=re.UNICODE)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def compact_text(value: Any) -> str:
+    return normalize_text(value).replace(" ", "")
+
+
+def slugify(value: Any) -> str:
+    text = normalize_text(value)
+    return re.sub(r"\s+", "-", text).strip("-")
+
+
+def parse_key_value_args(args: Iterable[str]) -> dict[str, Any]:
+    """Parse unknown CLI args such as --foo bar, --foo=bar, and --flag.
+
+    Hyphenated option names are converted to underscores because the API definitions
+    overwhelmingly use compact/snake names, while the command line should remain human-friendly.
+    """
+
+    result: dict[str, Any] = {}
+    args = list(args)
+    i = 0
+    while i < len(args):
+        token = args[i]
+        if not token.startswith("--"):
+            i += 1
+            continue
+        key = token[2:]
+        value: Any = True
+        if "=" in key:
+            key, value = key.split("=", 1)
+        elif i + 1 < len(args) and not args[i + 1].startswith("--"):
+            value = args[i + 1]
+            i += 1
+        key = key.strip().replace("-", "_")
+        if key:
+            if key in result:
+                existing = result[key]
+                if isinstance(existing, list):
+                    existing.append(value)
+                else:
+                    result[key] = [existing, value]
+            else:
+                result[key] = value
+        i += 1
+    return result
+
+
+def read_text_source(
+    *,
+    text: str | None = None,
+    file_path: str | None = None,
+    use_stdin: bool = False,
+    field_name: str = "text",
+) -> tuple[str, str] | None:
+    """Read text from explicit text, file, or stdin.
+
+    Returns (field_name, content) when data is present.
+    """
+
+    supplied = [text is not None, file_path is not None, use_stdin]
+    if sum(bool(x) for x in supplied) > 1:
+        raise ValueError(f"Use only one of --{field_name}, --file, or --stdin")
+    if text is not None:
+        return field_name, text
+    if file_path is not None:
+        return field_name, Path(file_path).expanduser().read_text(encoding="utf-8")
+    if use_stdin:
+        return field_name, sys.stdin.read()
+    return None
+
+
+def maybe_read_file_value(value: str | None) -> str | None:
+    """If value names an existing file, return its contents; otherwise return the value."""
+
+    if not value:
+        return value
+    path = Path(value).expanduser()
+    if path.exists() and path.is_file():
+        return path.read_text(encoding="utf-8")
+    return value
+
+
+def coerce_jsonish(value: str) -> Any:
+    """Best-effort conversion for extra params."""
+
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered == "null":
+        return None
+    try:
+        if re.fullmatch(r"-?\d+", value):
+            return int(value)
+        if re.fullmatch(r"-?\d+\.\d+", value):
+            return float(value)
+    except ValueError:
+        pass
+    if value.startswith("{") or value.startswith("["):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def coerce_mapping_values(data: dict[str, Any]) -> dict[str, Any]:
+    coerced: dict[str, Any] = {}
+    for key, value in data.items():
+        if isinstance(value, list):
+            coerced[key] = [coerce_jsonish(v) if isinstance(v, str) else v for v in value]
+        elif isinstance(value, str):
+            coerced[key] = coerce_jsonish(value)
+        else:
+            coerced[key] = value
+    return coerced

sv_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: sv-cli
+Version: 0.3.0
+Summary: Open-source, definition-driven command-line client for SV AI API tools.
+Project-URL: Homepage, https://github.com/seovendorco/sv-cli
+Project-URL: Issues, https://github.com/seovendorco/sv-cli/issues
+Author: SV CLI Contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,cli,seo,sv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.6
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+```
+███████╗██╗   ██╗     ██████╗██╗     ██╗
+██╔════╝██║   ██║    ██╔════╝██║     ██║
+███████╗██║   ██║    ██║     ██║     ██║
+╚════██║╚██╗ ██╔╝    ██║     ██║     ██║
+███████║ ╚████╔╝     ╚██████╗███████╗██║
+╚══════╝  ╚═══╝       ╚═════╝╚══════╝╚═╝
+
+Agentic SEO & GEO from the command line
+```
+# SV CLI
+
+SV CLI is an open-source command-line client for agentic SEO and GEO workflows using the SV API (SEO VENDOR API). It is designed as a definition-driven resolver layer: humans can use friendly commands, slugs, aliases, and presets, while scripts and AI agents can use strict enum IDs and raw JSON calls.
+
+The CLI discovers available tools from the API root and fetches each tool's definitions endpoint at runtime. Definitions are cached locally for speed, refreshed automatically after 24 hours by default, and can be refreshed or cleared manually.
+
+## Install
+
+```bash
+pip install sv-cli
+```
+
+For local development:
+
+```bash
+git clone https://github.com/seovendor/sv-cli.git
+cd sv-cli
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+sv --help
+```
+
+## API key setup
+
+An API key is required for API calls. Resolution order:
+
+1. `--api-key` flag
+2. `SV_API_KEY` environment variable
+3. Stored profile config from `sv auth set`
+4. Interactive prompt when allowed
+
+`SV_API_KEY` is the current environment variable. `SEOVENDOR_API_KEY` is still accepted as a legacy fallback during migration.
+
+Recommended setup:
+
+```bash
+sv auth set
+sv auth status
+```
+
+CI setup:
+
+```bash
+export SV_API_KEY="your-key-here"
+sv seogpt generate --type 18 --keyword "white label seo" --strict --format json --non-interactive
+```
+
+Avoid passing real keys with `--api-key` in shared shells because shell history may store the value. Debug output masks keys.
+
+### Brand migration notes
+
+The package, repository, executable, Python package, and local state directory now use the SV brand:
+
+- PyPI package: `sv-cli`
+- Executable: `sv`
+- Python package: `sv_cli`
+- Default local state directory: `~/.sv`
+- Preferred environment variables: `SV_API_KEY` and `SV_HOME`
+
+For migration safety, `SEOVENDOR_API_KEY`, `SEOVENDOR_HOME`, and an existing `~/.seovendor/config.json` are still accepted as fallbacks. New saves are written to `~/.sv`.
+
+## Dynamic definitions cache
+
+```bash
+sv definitions refresh
+sv definitions list
+sv definitions show seogpt
+sv definitions clear
+```
+
+Cache location:
+
+```text
+~/.sv/cache/definitions.json
+```
+
+The old `~/.seovendor/config.json` file is read as a migration fallback when `~/.sv/config.json` does not exist. New writes go to `~/.sv`.
+
+Default behavior:
+
+- Use local cache when present.
+- Refresh automatically if the cache is older than 24 hours.
+- Use stale cache with a warning if refresh fails.
+- Error clearly if no cache exists and definitions cannot be fetched.
+
+## Quick start
+
+```bash
+sv keywords research --keyword "white label seo"
+sv seogpt generate --type 18 --keyword "white label seo" --url https://example.com
+sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo" --wait
+sv image generate --keyword "white label seo" --type blog-header-image
+sv top-competitors analyze --keyword "white label seo"
+sv marketplace-services search --search "seo audit" --price 500 --category SEO
+sv content-quality analyze --keyword "white label seo" --url https://example.com
+```
+
+Presets (shorthand commands for common seogpt operations):
+
+```bash
+sv meta  --keyword "white label seo" --url https://example.com
+sv title --keyword "white label seo" --url https://example.com
+```
+
+> **Note:** `sv keywords`, `sv audit`, and `sv image` are group aliases, not standalone commands. They require an action: `sv keywords research --keyword "..."`, `sv audit create-task --url "..."`, `sv image generate --keyword "..."`.
+
+## Supported tools
+
+| Friendly command | Aliases | API tool key |
+| --- | --- | --- |
+| `better-keywords` | `keywords` | `better-keywords` |
+| `content-transformer` | `transform` | `content-transformer` |
+| `core-analysis` | `core` | `core-analysis` |
+| `geo-audit` | `geogpt-audit`, `audit` | `geogptaudit` |
+| `insight-igniter` | `insights` | `insight-igniter` |
+| `preliminary-audit` | `prelim-audit` | `preliminaryaudit` |
+| `ranklens` | | `ranklens` |
+| `seo-image` | `image` | `seo-image` |
+| `seogpt` | `seo-gpt` | `seogpt` |
+| `seogpt2` | `seo-gpt2` | `seogpt2` |
+| `seogpt-compare` | `compare` | `seogptcompare` |
+| `seo-mapping` | `mapping` | `seogptmapping` |
+| `topical-authority` | `topical` | `topical-authority` |
+| `top-competitors` | `competitors` | `top-competitors` |
+| `marketplace-services` | `marketplace`, `services` | `marketplace-services` |
+| `content-quality` | `quality`, `hcu-quality`, `eeat-quality` | `content-quality` |
+
+The canonical API tool keys are discovered from the live API root; local aliases are only a human-friendly layer. For newly released tools, the CLI can also use adapter-provided endpoint hints until the API root advertises those tools. Root-discovered metadata still takes precedence.
+
+## Enum resolution
+
+For enum-heavy fields such as content type, language, engine, image type, theme, background, color, and size, the CLI resolves values in this order:
+
+1. Numeric ID exact match
+2. Exact slug match
+3. Exact canonical API value
+4. Exact alias match
+5. Exact label match
+6. Normalized exact match
+7. Prefix match
+8. Contains match
+9. Fuzzy match with safe thresholds
+
+Examples that all resolve to Meta Description (id 18):
+
+```bash
+--type 18
+--type meta-description
+--type "Meta Description"
+--type "meta desc"
+```
+
+> **Note:** Fuzzy matching is enabled by default. Use `--strict --no-fuzzy` in scripts to require exact ID or slug and avoid unintended matches.
+
+Agent-safe mode:
+
+```bash
+sv seogpt generate --type 18 --keyword "white label seo" --strict --no-fuzzy --non-interactive --format json
+```
+
+## Options discovery
+
+```bash
+sv options list
+sv options seogpt
+sv options seogpt type --search meta
+sv options seogpt contenttype --search meta
+sv seogpt types --search meta
+sv seogpt languages
+sv seogpt engines
+sv image themes --search wild
+sv image types --search blog
+```
+
+## Raw API calls
+
+Raw calls use live definitions only to find the selected tool endpoint. The payload is otherwise passed through unchanged except that `k` is injected when no API-key field already exists.
+
+```bash
+sv --format json call seogpt --json '{"action":"generate","kw":"white label seo","type":18}'
+sv --format json call seogpt --file payload.json
+cat payload.json | sv --format json call seogpt --stdin
+```
+
+The per-tool `raw` sub-command works the same way:
+
+```bash
+sv --format json seogpt raw --json '{"action":"generate","kw":"white label seo","type":18}'
+```
+
+> **Note:** `--format` must be placed before the tool name for both `sv call` and `sv TOOL raw` — it is a global flag owned by the root `sv` command, not by `call` or `raw`.
+
+## Async task handling
+
+For tools that return task IDs:
+
+```bash
+sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo" --wait
+sv task status TASK_ID --tool geo-audit
+sv task result TASK_ID --tool geo-audit
+```
+
+`seogpt2` is another async tool. Its required field is `Topic` (a title or subject), mapped via `--keyword`:
+
+```bash
+sv seogpt2 create-task --keyword "White Label SEO for Agencies" --type on-page-blog-article --wait
+```
+
+See available types with `sv seogpt2 types`, lengths with `sv seogpt2 lengths`, engines with `sv seogpt2 engines`.
+
+Manual 3-step flow (without `--wait`):
+
+```bash
+sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo"
+sv geo-audit get-task-status --task_id TASK_ID
+sv geo-audit get-result --task_id TASK_ID
+```
+
+> **Note:** `--format` is not available on `sv task status` or `sv task result` directly. Place it before `task` as a global flag:
+>
+> ```bash
+> sv --format json task status TASK_ID
+> sv --format json task result TASK_ID
+> ```
+
+If a task is created through the CLI, its tool mapping is stored in `~/.sv/tasks.json`, so `--tool` is usually optional later.
+
+## Output formats
+
+```bash
+--format pretty     # default rich terminal output
+--format json       # raw JSON (always works for any response)
+--format table      # column table (list responses only)
+--format csv        # CSV (list responses only)
+--format markdown   # Markdown
+--format text       # plain text (content/article responses)
+```
+
+Which format to use:
+
+| Response type | Recommended formats |
+|---|---|
+| List results (keywords, competitors, services) | `table`, `csv` |
+| Content / articles / generated text | `text`, `markdown` |
+| Audit / analysis / nested data | `json`, `markdown` |
+| Async task ID responses | `pretty` (default) |
+| Any response | `json` (always safe) |
+
+**Placement:** For tool commands (`sv seogpt generate`, `sv keywords research`, etc.), `--format` can go anywhere. For `sv call`, `sv options`, and `sv task`, `--format` must come before the subcommand:
+
+```bash
+sv seogpt generate --keyword "white label seo" --type 18 --format json   # works
+sv --format json call seogpt --json '{"action":"generate","kw":"..."}'   # must be before call
+```
+
+Examples:
+
+```bash
+sv keywords research --keyword "white label seo" --format csv --output keywords.csv
+sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo" --wait --format markdown --output audit.md
+```
+
+## Profiles
+
+```bash
+sv profile create agency-a
+sv --profile agency-a auth set
+sv profile use agency-a
+sv profile list
+sv profile delete agency-a
+```
+
+Profile config is stored in `~/.sv/config.json`, not in project folders.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check .
+python -m build
+```
+
+Live tests should be opt-in only:
+
+```bash
+SV_API_KEY=... RUN_LIVE_TESTS=1 pytest -m live
+```
+
+## Security
+
+Never commit API keys, `.env`, or `~/.sv/config.json`. The repository `.gitignore` excludes common secret/config files. Report vulnerabilities using the process in `SECURITY.md`.