venice-cli 0.14.0__py3-none-any.whl

venice/commands/_shared.py

@@ -0,0 +1,132 @@
+"""Shared UX/budget rails for spend-incurring commands.
+
+Extracted from `image` so it, `upscale`, and `bg-remove` share one copy of the
+estimate/confirm/status/write plumbing rather than each carrying its own. These
+helpers take primitive args (cost, max_spend, err, byte blobs) so they stay
+independent of any one command's argument shape.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from .. import billing
+from ..client import VeniceAPIError
+
+
+def resolve_output(arg_output: Optional[Path], default_name: str) -> Path:
+    """Pick an output path: an explicit file, a file inside an explicit dir, or
+    `default_name` in the cwd."""
+    if arg_output is None:
+        return Path.cwd() / default_name
+    if arg_output.is_dir():
+        return arg_output / default_name
+    return arg_output
+
+
+def print_estimate(cost: Optional[float], label: str) -> None:
+    if cost is None:
+        print(f"Estimated cost: (unknown — {label})", file=sys.stderr)
+    else:
+        print(
+            f"Estimated cost: {billing.format_usd(cost)} ({label})",
+            file=sys.stderr,
+        )
+
+
+def print_balance_and_remaining(client, cost: Optional[float], *, show: bool) -> None:
+    if not show:
+        return
+    try:
+        info = billing.fetch_balance(client)
+    except VeniceAPIError:
+        info = None
+    if not info or info.get("total") is None:
+        return
+    print(f"Balance:        {billing.format_balance_breakdown(info)}", file=sys.stderr)
+    if cost is not None:
+        try:
+            remaining = float(info["total"]) - float(cost)
+            print(f"After charge:   {billing.format_usd(remaining)}", file=sys.stderr)
+        except (TypeError, ValueError):
+            pass
+
+
+def over_budget(cost: Optional[float], max_spend: Optional[float]) -> bool:
+    if max_spend is None or cost is None:
+        return False
+    try:
+        return float(cost) > float(max_spend)
+    except (TypeError, ValueError):
+        return False
+
+
+def confirm_or_exit(yes: bool) -> Optional[int]:
+    if yes:
+        return None
+    if not sys.stdin.isatty():
+        print("non-interactive; pass --yes to confirm the charge.", file=sys.stderr)
+        return 1
+    try:
+        ans = input("Proceed? [y/N] ").strip().lower()
+    except EOFError:
+        ans = ""
+    if ans not in ("y", "yes"):
+        print("aborted by user", file=sys.stderr)
+        return 1
+    return None
+
+
+def status_to_exit(err: VeniceAPIError) -> int:
+    s = err.status
+    if s == 400:
+        return 2
+    if s == 402:
+        return 1  # insufficient balance ~ declined
+    if s == 422:
+        return 3
+    if s == 429:
+        return 4
+    if s == 503:
+        return 5
+    if 500 <= s < 600:
+        return 5
+    if s == 404:
+        return 6
+    if s == 0:
+        return 8
+    return 2
+
+
+def write_bytes_outputs(blobs: List[bytes], paths: List[Path]) -> Optional[int]:
+    """Write byte blobs to paths. Returns an exit code on failure, else None."""
+    for data, path in zip(blobs, paths):
+        try:
+            path.write_bytes(data)
+        except OSError as e:
+            print(f"could not write {path}: {e}", file=sys.stderr)
+            return 9
+        abs_path = path.resolve()
+        print(str(abs_path))
+        print(f"wrote {len(data)} bytes to {abs_path}", file=sys.stderr)
+    return None
+
+
+def post_binary_op(client, endpoint: str, body: dict, out_path: Path, label: str) -> int:
+    """POST a JSON body to an endpoint that returns raw image bytes and write
+    them to `out_path`.
+
+    Returns an exit code (0 on success). API errors map through
+    `status_to_exit`; a JSON (non-image) 200 is treated as an unexpected
+    server response. `label` prefixes error messages (e.g. "upscale").
+    """
+    try:
+        _ctype, payload = client.post_for_bytes_or_json(endpoint, body)
+    except VeniceAPIError as e:
+        print(f"{label} failed: {e}", file=sys.stderr)
+        return status_to_exit(e)
+    if isinstance(payload, (bytes, bytearray)):
+        return write_bytes_outputs([bytes(payload)], [out_path]) or 0
+    print(f"{label}: unexpected non-image response: {payload!r}", file=sys.stderr)
+    return 5

venice/commands/balance.py

@@ -0,0 +1,124 @@
+"""`venice balance` -- show current account balance and tier."""
+from __future__ import annotations
+
+import json
+import sys
+
+from .. import auth
+from ..billing import SPEND_ORDER, fetch_balance, format_balance_breakdown, format_usd
+from ..client import VeniceAPIError
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser(
+        "balance",
+        help="Show current spendable balance (USD + DIEM credit).",
+        description=(
+            "Queries /api_keys/rate_limits. Spendable balance = USD + DIEM "
+            "(1 DIEM = $1 of purchasing power). Default: prints combined "
+            "total '$X.XX USD' to stdout. --json for raw, --verbose for "
+            "tier + breakdown + epoch. --min sets a floor: exits 1 if total "
+            "is below it (script-friendly)."
+        ),
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="Dump raw {USD, DIEM, tier, next_epoch, key_expires} to stdout.",
+    )
+    p.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Print a human-readable multi-line summary.",
+    )
+    p.add_argument(
+        "--min",
+        type=float,
+        default=None,
+        metavar="USD",
+        help="Exit 1 if balance is below this USD threshold.",
+    )
+    p.set_defaults(handler=_run)
+
+
+def _run(args) -> int:
+    try:
+        from ..client import build_client_from_auth
+        client = build_client_from_auth()
+    except auth.AuthError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    try:
+        info = fetch_balance(client)
+    except VeniceAPIError as e:
+        print(f"balance: API error: {e}", file=sys.stderr)
+        if e.status == 401:
+            return 2
+        if e.status == 429:
+            return 4
+        return 5
+
+    if info is None:
+        print("balance: API returned no data block", file=sys.stderr)
+        return 5
+
+    usd = info.get("usd")
+    diem = info.get("diem")
+    total = info.get("total")
+    tier = info.get("tier")
+    next_epoch = info.get("next_epoch")
+    key_exp = info.get("key_expires")
+
+    if args.json:
+        json.dump(
+            {
+                "USD": usd,
+                "DIEM": diem,
+                "total_usd_equiv": total,
+                "tier": tier,
+                "next_epoch": next_epoch,
+                "key_expires": key_exp,
+                "spend_order": list(SPEND_ORDER),
+                "notes": {
+                    "DIEM": "epoch allowance from staked DIEM; resets at next_epoch",
+                    "BUNDLED_CREDITS": "monthly bundle; drains before USD cash; not exposed via inference key",
+                    "VCU": "tier compute units; not exposed via inference key",
+                },
+            },
+            sys.stdout,
+            indent=2,
+        )
+        sys.stdout.write("\n")
+    elif args.verbose:
+        print(f"Tier:           {tier or 'unknown'}")
+        print(f"Spendable:      {format_balance_breakdown(info)}")
+        if diem is not None:
+            try:
+                print(
+                    f"  DIEM allow.:  {float(diem):.4f}  "
+                    f"(this epoch; resets {next_epoch or '?'})"
+                )
+            except (TypeError, ValueError):
+                print(f"  DIEM allow.:  {diem}")
+        print(f"  monthly:      (not exposed via inference key; drains before cash)")
+        print(f"  USD cash:     {format_usd(usd)}")
+        print(f"Spend order:    {' -> '.join(SPEND_ORDER)}")
+        print(f"Key expires:    {key_exp or 'never'}")
+    else:
+        print(format_usd(total))
+
+    if args.min is not None and total is not None:
+        try:
+            if float(total) < float(args.min):
+                print(
+                    f"balance: total {format_usd(total)} is below floor "
+                    f"{format_usd(args.min)}",
+                    file=sys.stderr,
+                )
+                return 1
+        except (TypeError, ValueError):
+            pass
+
+    return 0

venice/commands/bg_remove.py

@@ -0,0 +1,126 @@
+"""`venice bg-remove` -- strip an image's background via /image/background-remove.
+
+Venice's generate call treats `background: transparent` as a no-op, so
+transparent assets (e.g. rank insignia) are made opaque then run through this
+endpoint, which returns a PNG with a transparent background. The source is
+either a local file (sent as base64 in a JSON body) or an image URL. The
+response is raw image/png bytes, so we use the client's bytes-or-json path.
+Pricing is dynamic ($0.001-$10.00/call); the balance is shown and you confirm.
+"""
+from __future__ import annotations
+
+import base64
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .. import auth
+from ..client import build_client_from_auth
+from ._shared import (
+    confirm_or_exit,
+    over_budget,
+    post_binary_op,
+    print_balance_and_remaining,
+    print_estimate,
+    resolve_output,
+)
+
+ENDPOINT = "/image/background-remove"
+MAX_INPUT_BYTES = 25 * 1024 * 1024  # API limit: input file < 25 MB
+URL_DEFAULT_NAME = "venice-nobg.png"
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser(
+        "bg-remove",
+        help="Remove an image's background via /image/background-remove.",
+        description=(
+            "Returns a PNG with a transparent background. Source is a local file "
+            "(positional) or --image-url. Use for assets that need alpha, e.g. "
+            "`venice bg-remove insignia.png`. Pricing is dynamic; the balance is "
+            "shown and you confirm before the charge."
+        ),
+    )
+    src = p.add_mutually_exclusive_group()
+    src.add_argument("input", type=Path, nargs="?", default=None,
+                     help="Image file whose background to remove.")
+    src.add_argument("--image-url", default=None, metavar="URL",
+                     help="Remove the background from an image at this URL instead.")
+    p.add_argument("--output", "-o", type=Path, default=None,
+                   help="Output file or directory. Default: cwd/<input>-nobg.png "
+                   f"(or {URL_DEFAULT_NAME} for --image-url).")
+    p.add_argument("--yes", "-y", action="store_true")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Show the planned output and exit; don't call the API.")
+    p.add_argument(
+        "--max-spend",
+        type=float,
+        default=None,
+        metavar="USD",
+        help="Refuse if the estimated cost exceeds this cap. Note: bg-remove "
+        "pricing is dynamic, so no pre-charge estimate is available.",
+    )
+    p.add_argument("--no-balance", action="store_true",
+                   help="Skip the upfront balance display.")
+    p.set_defaults(handler=_run)
+
+
+def _validate(args) -> Optional[int]:
+    if (args.input is None) == (args.image_url is None):
+        print("bg-remove: provide exactly one of INPUT file or --image-url",
+              file=sys.stderr)
+        return 2
+    if args.input is not None:
+        inp = args.input
+        if not inp.is_file():
+            print(f"bg-remove: input file not found: {inp}", file=sys.stderr)
+            return 2
+        size = inp.stat().st_size
+        if size == 0:
+            print(f"bg-remove: input {inp} is empty", file=sys.stderr)
+            return 2
+        if size > MAX_INPUT_BYTES:
+            print(f"bg-remove: input {inp} is {size} bytes; must be < 25 MB",
+                  file=sys.stderr)
+            return 2
+    return None
+
+
+def _build_body(args) -> dict:
+    if args.input is not None:
+        b64 = base64.b64encode(args.input.read_bytes()).decode("ascii")
+        return {"image": b64}
+    return {"image_url": args.image_url}
+
+
+def _run(args) -> int:
+    rc = _validate(args)
+    if rc is not None:
+        return rc
+
+    try:
+        client = build_client_from_auth()
+    except auth.AuthError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    cost = None  # dynamic pricing -- no reliable upfront quote
+    print_estimate(cost, "background removal; dynamic $0.001-$10.00/call")
+    print_balance_and_remaining(client, cost, show=not args.no_balance)
+    if over_budget(cost, args.max_spend):  # no-op while cost is unknown
+        return 1
+
+    default_name = (
+        f"{args.input.stem}-nobg.png" if args.input is not None else URL_DEFAULT_NAME
+    )
+    out_path = resolve_output(args.output, default_name)
+    if args.dry_run:
+        print(f"would write: {out_path.resolve()}", file=sys.stderr)
+        return 0
+
+    rc = confirm_or_exit(args.yes)
+    if rc is not None:
+        return rc
+
+    body = _build_body(args)
+    return post_binary_op(client, ENDPOINT, body, out_path, "bg-remove")

venice/commands/chat.py

@@ -0,0 +1,263 @@
+"""`venice chat` -- one-shot /chat/completions.
+
+Built on the official `openai` SDK (Venice is OpenAI-compatible; the SDK is
+lazy-imported so the rest of the stdlib-only CLI works without it). Venice's
+own chat extensions -- web search, characters, thinking control, etc. -- are
+surfaced as flags and passed through `extra_body={"venice_parameters": ...}`.
+
+The free `/models?type=text` catalog GET (via the lean urllib client) is used to
+validate `--model` and resolve a default before the paid completion call --
+mirrors the guard pattern in `venice music`.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+from .. import auth
+from ..client import build_client_from_auth
+from . import _models, _openai
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser(
+        "chat",
+        help="One-shot chat completion (/chat/completions).",
+        description=(
+            "Send a single message to a Venice text model and print the reply. "
+            "Reads the message from the argument, or from stdin when it is '-' "
+            "or piped. Supports Venice extensions: web search, characters, and "
+            "reasoning-model thinking control."
+        ),
+    )
+    p.add_argument(
+        "message",
+        nargs="?",
+        help="User message. Use '-' (or pipe stdin) to read from stdin.",
+    )
+    p.add_argument("--system", "-s", default=None, help="Optional system prompt.")
+    p.add_argument(
+        "--model",
+        "-m",
+        default=None,
+        help="Text model id (default: the catalog's 'default'-trait model).",
+    )
+    p.add_argument("--temperature", "-t", type=float, default=None)
+    p.add_argument("--max-tokens", type=int, default=None, dest="max_tokens")
+
+    stream_grp = p.add_mutually_exclusive_group()
+    stream_grp.add_argument(
+        "--stream", dest="stream", action="store_true", default=True,
+        help="Stream the reply incrementally (default).",
+    )
+    stream_grp.add_argument(
+        "--no-stream", dest="stream", action="store_false",
+        help="Wait for the full reply, then print it.",
+    )
+    p.add_argument(
+        "--json", action="store_true",
+        help="Print the raw response object (forces --no-stream).",
+    )
+
+    # --- Venice extensions -> venice_parameters ---
+    ext = p.add_argument_group("Venice extensions")
+    ext.add_argument(
+        "--web-search", choices=("auto", "on", "off"), default=None,
+        dest="web_search", help="Enable Venice web search (default: off).",
+    )
+    ext.add_argument(
+        "--web-citations", action="store_true", dest="web_citations",
+        help="Ask the model to cite web sources (with --web-search).",
+    )
+    ext.add_argument(
+        "--web-scraping", action="store_true", dest="web_scraping",
+        help="Scrape URLs in the message via Firecrawl.",
+    )
+    ext.add_argument(
+        "--character", default=None, metavar="SLUG",
+        help="Use a public Venice character (its Public ID slug).",
+    )
+    ext.add_argument(
+        "--no-venice-system-prompt", action="store_true",
+        dest="no_venice_system_prompt",
+        help="Omit Venice's supplied system prompt (default: included).",
+    )
+    ext.add_argument(
+        "--strip-thinking", action="store_true", dest="strip_thinking",
+        help="Strip <think> blocks from reasoning-model output.",
+    )
+    ext.add_argument(
+        "--no-thinking", action="store_true", dest="no_thinking",
+        help="Disable thinking on supported reasoning models.",
+    )
+    ext.add_argument(
+        "--x-search", action="store_true", dest="x_search",
+        help="Enable xAI web+X search (extra ~$0.01/search; grok models).",
+    )
+    p.set_defaults(handler=_run)
+
+
+def _resolve_message(args) -> Optional[str]:
+    """Positional message, or stdin when '-' / piped. None if nothing given."""
+    msg = args.message
+    if msg == "-" or (msg is None and not sys.stdin.isatty()):
+        data = sys.stdin.read().strip()
+        return data or None
+    return msg
+
+
+def _venice_parameters(args) -> dict:
+    """Assemble venice_parameters from the extension flags (only set keys)."""
+    vp: dict = {}
+    if args.web_search is not None:
+        vp["enable_web_search"] = args.web_search
+    if args.web_citations:
+        vp["enable_web_citations"] = True
+    if args.web_scraping:
+        vp["enable_web_scraping"] = True
+    if args.character:
+        vp["character_slug"] = args.character
+    if args.no_venice_system_prompt:
+        vp["include_venice_system_prompt"] = False
+    if args.strip_thinking:
+        vp["strip_thinking_response"] = True
+    if args.no_thinking:
+        vp["disable_thinking"] = True
+    if args.x_search:
+        vp["enable_x_search"] = True
+    return vp
+
+
+def _build_kwargs(args, model: str, message: str) -> dict:
+    messages = []
+    if args.system:
+        messages.append({"role": "system", "content": args.system})
+    messages.append({"role": "user", "content": message})
+
+    kwargs: dict = {"model": model, "messages": messages}
+    if args.temperature is not None:
+        kwargs["temperature"] = args.temperature
+    if args.max_tokens is not None:
+        kwargs["max_tokens"] = args.max_tokens
+    vp = _venice_parameters(args)
+    if vp:
+        kwargs["extra_body"] = {"venice_parameters": vp}
+    return kwargs
+
+
+def _as_dict(value) -> Optional[dict]:
+    if value is None:
+        return None
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if isinstance(value, dict):
+        return value
+    return None
+
+
+def _print_citations(venice_params) -> None:
+    vp = _as_dict(venice_params)
+    if not vp:
+        return
+    cites = vp.get("web_search_citations")
+    if not isinstance(cites, list) or not cites:
+        return
+    print("\nSources:", file=sys.stderr)
+    for i, c in enumerate(cites, 1):
+        cd = _as_dict(c) or {}
+        title = cd.get("title", "")
+        url = cd.get("url", "")
+        date = cd.get("date")
+        line = f"  [{i}] {title} -- {url}"
+        if date:
+            line += f" ({date})"
+        print(line, file=sys.stderr)
+
+
+def _print_usage(usage) -> None:
+    u = _as_dict(usage)
+    if not u:
+        return
+    pt = u.get("prompt_tokens")
+    ct = u.get("completion_tokens")
+    tt = u.get("total_tokens")
+    if tt is not None:
+        print(f"usage: prompt={pt} completion={ct} total={tt}", file=sys.stderr)
+
+
+def _run(args) -> int:
+    message = _resolve_message(args)
+    if not message:
+        print("chat: no message (pass an argument or pipe stdin)", file=sys.stderr)
+        return 2
+
+    openai = _openai.import_openai("chat")
+    if openai is None:
+        return 2
+
+    try:
+        client = build_client_from_auth()
+    except auth.AuthError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    models = _models.catalog(client, "text")
+    model, rc = _models.resolve_model(
+        args.model, models, label="chat", noun="text model"
+    )
+    if rc is not None:
+        return rc
+
+    oai = _openai.build_openai(openai, client)
+    kwargs = _build_kwargs(args, model, message)
+
+    stream = args.stream and not args.json
+    try:
+        if stream:
+            return _run_stream(oai, kwargs)
+        return _run_once(oai, kwargs, args.json)
+    except openai.OpenAIError as e:
+        return _openai.status_to_exit(openai, e, "chat")
+
+
+def _run_once(oai, kwargs: dict, as_json: bool) -> int:
+    resp = oai.chat.completions.create(**kwargs)
+    if as_json:
+        json.dump(resp.model_dump(), sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return 0
+    content = ""
+    if resp.choices:
+        content = resp.choices[0].message.content or ""
+    print(content)
+    _print_citations(getattr(resp, "venice_parameters", None))
+    return 0
+
+
+def _run_stream(oai, kwargs: dict) -> int:
+    kwargs = dict(kwargs)
+    kwargs["stream"] = True
+    kwargs["stream_options"] = {"include_usage": True}
+    stream = oai.chat.completions.create(**kwargs)
+
+    citations = None
+    usage = None
+    wrote_any = False
+    for chunk in stream:
+        vp = getattr(chunk, "venice_parameters", None)
+        if vp is not None and citations is None:
+            citations = vp
+        if getattr(chunk, "usage", None):
+            usage = chunk.usage
+        if chunk.choices:
+            piece = getattr(chunk.choices[0].delta, "content", None)
+            if piece:
+                sys.stdout.write(piece)
+                sys.stdout.flush()
+                wrote_any = True
+    if wrote_any:
+        sys.stdout.write("\n")
+    _print_citations(citations)
+    _print_usage(usage)
+    return 0