japanfold 1.0.0__tar.gz

japanfold-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: japanfold
+Version: 1.0.0
+Summary: Command-line client for JapanFold: protein structure prediction, binder design and embeddings over an HTTP API.
+License-Expression: MIT
+Project-URL: Homepage, https://japanfold.aiand.com
+Project-URL: Documentation, https://japanfold.aiand.com/docs
+Keywords: protein,structure-prediction,boltz,esmfold,binder-design,bioinformatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# japanfold
+
+Command-line client for [JapanFold](https://japanfold.aiand.com), a hosted API for protein
+structure prediction, binder design and protein embeddings. No GPU and no model weights on your
+side; the models run on JapanFold's servers in Japan.
+
+```bash
+pip install japanfold
+export JAPANFOLD_API_KEY=jf_live_...       # from https://japanfold.aiand.com/account/token
+japanfold fold --sequence MKTAYIAKQRQISFVKSHFSRQ --wait --out ./out
+```
+
+It has no dependencies beyond the Python standard library (3.9+).
+
+## Key and endpoint
+
+Every call needs a key. Sign in at [japanfold.aiand.com/account/token](https://japanfold.aiand.com/account/token)
+to get one; a new account comes with $100 of credit. The CLI reads it from `--api-key`, then
+`$JAPANFOLD_API_KEY`, then `~/.config/japanfold/config.json` (written by `japanfold auth login`).
+
+The API lives at `https://api.japanfold.aiand.com`. Set `JAPANFOLD_BASE_URL` or `--base-url` to
+point somewhere else.
+
+## Commands
+
+```bash
+japanfold models                                   # every model and design protocol
+japanfold fold --sequence MKTAYIAK... --model boltz2 --wait --out ./out
+japanfold design spec.yaml --model boltzgen --protocol nanobody-anything --wait --out ./out
+japanfold design --model rfd3 --protocol rfd3-binder --structure target.pdb \
+    --contig 'A1-150,60-80' --wait --out ./out
+japanfold design --model pxdesign --protocol pxdesign-binder --structure target.pdb \
+    --chains A --binder-length 80 --hotspots A64,A65,A66 --wait --out ./out
+japanfold embed --sequence MKTAYIAK... --model esmc-600m --wait --out ./out
+japanfold wait JOB_ID --out ./out                  # wait for a job and download it
+japanfold credits                                  # balance left on the key
+japanfold jobs list
+```
+
+`--wait` submits, waits for the job and downloads the results in one foreground command.
+Without it a command prints the job id and returns; `japanfold wait JOB_ID` picks it up later
+and is safe to re-run. `fold` is the same command as `predict`, and `wait` the same as `download`.
+
+## For agents
+
+`--json` on any command prints machine-readable JSON on stdout and keeps human messages on
+stderr. `japanfold schema` prints the OpenAPI 3.1 contract. Exit codes say what went wrong
+without parsing text:
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | job failed or generic error |
+| 2 | missing or invalid key |
+| 3 | invalid input |
+| 4 | not found |
+| 5 | rate-limited or at capacity |
+| 6 | server unreachable |
+
+Agents that prefer plain HTTP can skip the CLI: the [docs](https://japanfold.aiand.com/docs/)
+cover the REST API, and the agent skill lives at
+[github.com/japanfold/japanfold](https://github.com/japanfold/japanfold).

japanfold-1.0.0/README.md

@@ -0,0 +1,62 @@
+# japanfold
+
+Command-line client for [JapanFold](https://japanfold.aiand.com), a hosted API for protein
+structure prediction, binder design and protein embeddings. No GPU and no model weights on your
+side; the models run on JapanFold's servers in Japan.
+
+```bash
+pip install japanfold
+export JAPANFOLD_API_KEY=jf_live_...       # from https://japanfold.aiand.com/account/token
+japanfold fold --sequence MKTAYIAKQRQISFVKSHFSRQ --wait --out ./out
+```
+
+It has no dependencies beyond the Python standard library (3.9+).
+
+## Key and endpoint
+
+Every call needs a key. Sign in at [japanfold.aiand.com/account/token](https://japanfold.aiand.com/account/token)
+to get one; a new account comes with $100 of credit. The CLI reads it from `--api-key`, then
+`$JAPANFOLD_API_KEY`, then `~/.config/japanfold/config.json` (written by `japanfold auth login`).
+
+The API lives at `https://api.japanfold.aiand.com`. Set `JAPANFOLD_BASE_URL` or `--base-url` to
+point somewhere else.
+
+## Commands
+
+```bash
+japanfold models                                   # every model and design protocol
+japanfold fold --sequence MKTAYIAK... --model boltz2 --wait --out ./out
+japanfold design spec.yaml --model boltzgen --protocol nanobody-anything --wait --out ./out
+japanfold design --model rfd3 --protocol rfd3-binder --structure target.pdb \
+    --contig 'A1-150,60-80' --wait --out ./out
+japanfold design --model pxdesign --protocol pxdesign-binder --structure target.pdb \
+    --chains A --binder-length 80 --hotspots A64,A65,A66 --wait --out ./out
+japanfold embed --sequence MKTAYIAK... --model esmc-600m --wait --out ./out
+japanfold wait JOB_ID --out ./out                  # wait for a job and download it
+japanfold credits                                  # balance left on the key
+japanfold jobs list
+```
+
+`--wait` submits, waits for the job and downloads the results in one foreground command.
+Without it a command prints the job id and returns; `japanfold wait JOB_ID` picks it up later
+and is safe to re-run. `fold` is the same command as `predict`, and `wait` the same as `download`.
+
+## For agents
+
+`--json` on any command prints machine-readable JSON on stdout and keeps human messages on
+stderr. `japanfold schema` prints the OpenAPI 3.1 contract. Exit codes say what went wrong
+without parsing text:
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | job failed or generic error |
+| 2 | missing or invalid key |
+| 3 | invalid input |
+| 4 | not found |
+| 5 | rate-limited or at capacity |
+| 6 | server unreachable |
+
+Agents that prefer plain HTTP can skip the CLI: the [docs](https://japanfold.aiand.com/docs/)
+cover the REST API, and the agent skill lives at
+[github.com/japanfold/japanfold](https://github.com/japanfold/japanfold).

japanfold-1.0.0/japanfold.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: japanfold
+Version: 1.0.0
+Summary: Command-line client for JapanFold: protein structure prediction, binder design and embeddings over an HTTP API.
+License-Expression: MIT
+Project-URL: Homepage, https://japanfold.aiand.com
+Project-URL: Documentation, https://japanfold.aiand.com/docs
+Keywords: protein,structure-prediction,boltz,esmfold,binder-design,bioinformatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# japanfold
+
+Command-line client for [JapanFold](https://japanfold.aiand.com), a hosted API for protein
+structure prediction, binder design and protein embeddings. No GPU and no model weights on your
+side; the models run on JapanFold's servers in Japan.
+
+```bash
+pip install japanfold
+export JAPANFOLD_API_KEY=jf_live_...       # from https://japanfold.aiand.com/account/token
+japanfold fold --sequence MKTAYIAKQRQISFVKSHFSRQ --wait --out ./out
+```
+
+It has no dependencies beyond the Python standard library (3.9+).
+
+## Key and endpoint
+
+Every call needs a key. Sign in at [japanfold.aiand.com/account/token](https://japanfold.aiand.com/account/token)
+to get one; a new account comes with $100 of credit. The CLI reads it from `--api-key`, then
+`$JAPANFOLD_API_KEY`, then `~/.config/japanfold/config.json` (written by `japanfold auth login`).
+
+The API lives at `https://api.japanfold.aiand.com`. Set `JAPANFOLD_BASE_URL` or `--base-url` to
+point somewhere else.
+
+## Commands
+
+```bash
+japanfold models                                   # every model and design protocol
+japanfold fold --sequence MKTAYIAK... --model boltz2 --wait --out ./out
+japanfold design spec.yaml --model boltzgen --protocol nanobody-anything --wait --out ./out
+japanfold design --model rfd3 --protocol rfd3-binder --structure target.pdb \
+    --contig 'A1-150,60-80' --wait --out ./out
+japanfold design --model pxdesign --protocol pxdesign-binder --structure target.pdb \
+    --chains A --binder-length 80 --hotspots A64,A65,A66 --wait --out ./out
+japanfold embed --sequence MKTAYIAK... --model esmc-600m --wait --out ./out
+japanfold wait JOB_ID --out ./out                  # wait for a job and download it
+japanfold credits                                  # balance left on the key
+japanfold jobs list
+```
+
+`--wait` submits, waits for the job and downloads the results in one foreground command.
+Without it a command prints the job id and returns; `japanfold wait JOB_ID` picks it up later
+and is safe to re-run. `fold` is the same command as `predict`, and `wait` the same as `download`.
+
+## For agents
+
+`--json` on any command prints machine-readable JSON on stdout and keeps human messages on
+stderr. `japanfold schema` prints the OpenAPI 3.1 contract. Exit codes say what went wrong
+without parsing text:
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | job failed or generic error |
+| 2 | missing or invalid key |
+| 3 | invalid input |
+| 4 | not found |
+| 5 | rate-limited or at capacity |
+| 6 | server unreachable |
+
+Agents that prefer plain HTTP can skip the CLI: the [docs](https://japanfold.aiand.com/docs/)
+cover the REST API, and the agent skill lives at
+[github.com/japanfold/japanfold](https://github.com/japanfold/japanfold).

japanfold-1.0.0/japanfold.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+japanfold_cli.py
+pyproject.toml
+japanfold.egg-info/PKG-INFO
+japanfold.egg-info/SOURCES.txt
+japanfold.egg-info/dependency_links.txt
+japanfold.egg-info/entry_points.txt
+japanfold.egg-info/top_level.txt

japanfold-1.0.0/japanfold.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

japanfold-1.0.0/japanfold.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+japanfold = japanfold_cli:main

japanfold-1.0.0/japanfold.egg-info/top_level.txt

@@ -0,0 +1 @@
+japanfold_cli

japanfold-1.0.0/japanfold_cli.py

@@ -0,0 +1,752 @@
+#!/usr/bin/env python3
+"""JapanFold CLI: biomolecular structure prediction and binder design.
+
+A dependency-free (stdlib-only) client for the JapanFold ``/v1`` API. Designed
+to be driven both by humans and by coding agents (Claude Code, Codex, Cursor,
+Gemini CLI): every command takes ``--json`` for machine output, auth comes from
+an env var for sandboxed agents, and ``--wait`` / ``wait`` run as a single
+foreground command (submit, poll, download), so an agent never has to
+background a process.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import math
+import os
+import shutil
+import sys
+import time
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://api.japanfold.aiand.com"
+CONFIG_PATH = Path(os.environ.get("JAPANFOLD_CONFIG",
+                                  Path.home() / ".config" / "japanfold" / "config.json"))
+TERMINAL = {"succeeded", "failed", "canceled"}
+
+
+# --------------------------------------------------------------------------- #
+# Config / auth
+# --------------------------------------------------------------------------- #
+_config_cache: dict | None = None
+
+
+def _load_config() -> dict:
+    # Read once per process: resolve_api_key + resolve_base_url both consult it
+    # for a single command. _save_config invalidates it.
+    global _config_cache
+    if _config_cache is None:
+        try:
+            _config_cache = json.loads(CONFIG_PATH.read_text())
+        except (OSError, ValueError):
+            _config_cache = {}
+    return _config_cache
+
+
+def _save_config(cfg: dict) -> None:
+    global _config_cache
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    tmp = CONFIG_PATH.with_suffix(".tmp")
+    tmp.write_text(json.dumps(cfg, indent=2))
+    tmp.chmod(0o600)
+    os.replace(tmp, CONFIG_PATH)
+    _config_cache = None  # next read reflects the write
+
+
+def resolve_api_key(args) -> str | None:
+    return getattr(args, "api_key", None) or os.environ.get("JAPANFOLD_API_KEY") \
+        or _load_config().get("api_key")
+
+
+def resolve_base_url(args) -> str:
+    return (getattr(args, "base_url", None) or os.environ.get("JAPANFOLD_BASE_URL")
+            or _load_config().get("base_url") or DEFAULT_BASE_URL).rstrip("/")
+
+
+# --------------------------------------------------------------------------- #
+# HTTP
+# --------------------------------------------------------------------------- #
+# Meaningful exit codes so an agent can branch on the failure mode without
+# parsing stderr. 0=ok; 1=job failed / generic; 2=auth; 3=invalid input/usage;
+# 4=not found; 5=rate-limited/capacity; 6=unreachable; 130=interrupted.
+EXIT_OK, EXIT_ERROR, EXIT_AUTH, EXIT_INPUT, EXIT_NOTFOUND, EXIT_RATE, EXIT_UNREACHABLE = 0, 1, 2, 3, 4, 5, 6
+_STATUS_EXIT = {0: EXIT_UNREACHABLE, 400: EXIT_INPUT, 401: EXIT_AUTH, 403: EXIT_AUTH,
+                404: EXIT_NOTFOUND, 422: EXIT_INPUT, 429: EXIT_RATE}
+
+
+class Done(Exception):
+    """Raised by a handler to exit with a specific code (e.g. a failed job)."""
+    def __init__(self, code):
+        self.code = code
+
+
+class ApiError(Exception):
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        if isinstance(body, dict):
+            msg = body.get("title") or body.get("error") or str(body)
+        else:
+            msg = str(body)
+        detail = body.get("detail") if isinstance(body, dict) else None
+        super().__init__(f"{status}: {msg}" + (f": {detail}" if detail else ""))
+
+    @property
+    def exit_code(self):
+        return _STATUS_EXIT.get(self.status, EXIT_ERROR)
+
+
+# A results bundle is the one response whose size is unbounded by the API, so it
+# does not share the 120 s default. 900 s covers the 475 MB bundle measured on the
+# service over a link as slow as 0.5 MB/s.
+_ARCHIVE_TIMEOUT = 900.0
+
+
+class _KeyStaysOnItsHost(urllib.request.HTTPRedirectHandler):
+    """Drop the key when a redirect leaves the API's host.
+
+    urllib copies every header onto the next hop, so without this a redirect to
+    storage (an artifact's short-lived link) would carry the customer's key to
+    another host, which then refuses a request with two credentials. curl,
+    requests and httpx already behave this way.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new is not None and new.host != req.host:
+            new.remove_header("Authorization")
+        return new
+
+
+_open = urllib.request.build_opener(_KeyStaysOnItsHost).open
+
+
+def _request(method, base, path, key, *, body=None, raw=False, timeout=120,
+             idempotency=None, sink=None):
+    url = base + path
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    # A real User-Agent: urllib's default ("Python-urllib/x.y") trips edge bot
+    # filters (e.g. Cloudflare 1010) that a named client clears.
+    req.add_header("User-Agent", f"japanfold-cli/{__version__}")
+    if key:
+        req.add_header("Authorization", f"Bearer {key}")
+    if data is not None:
+        req.add_header("Content-Type", "application/json")
+    if idempotency:
+        req.add_header("Idempotency-Key", idempotency)
+    try:
+        with _open(req, timeout=timeout) as resp:
+            if sink is not None:
+                # Stream to disk: a large bundle must not have to fit in memory.
+                sink.parent.mkdir(parents=True, exist_ok=True)
+                with open(sink, "wb") as fh:
+                    shutil.copyfileobj(resp, fh, 1 << 20)
+                return resp.status, sink, dict(resp.headers)
+            payload = resp.read()
+            if raw:
+                return resp.status, payload, dict(resp.headers)
+            return resp.status, (json.loads(payload) if payload else {}), dict(resp.headers)
+    except urllib.error.HTTPError as e:
+        payload = e.read()
+        try:
+            parsed = json.loads(payload)
+        except ValueError:
+            parsed = {"title": payload.decode(errors="replace")[:200] or e.reason, "status": e.code}
+        raise ApiError(e.code, parsed) from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, {"title": f"cannot reach {base}", "detail": str(e.reason)}) from None
+
+
+# --------------------------------------------------------------------------- #
+# Output helpers
+# --------------------------------------------------------------------------- #
+def _emit(obj, as_json):
+    if as_json:
+        print(json.dumps(obj, indent=2))
+
+
+def _err(msg):
+    print(f"japanfold: {msg}", file=sys.stderr)
+
+
+def _progress(job):
+    p = job.get("progress")
+    bar = f"{int(p * 100):3d}%" if isinstance(p, (int, float)) else "  · "
+    stage = job.get("stage") or ""
+    return f"[{bar}] {job.get('status'):9} {stage}".rstrip()
+
+
+# --------------------------------------------------------------------------- #
+# Input normalization
+# --------------------------------------------------------------------------- #
+def _read_input(positional, sequence, inp):
+    """Return a request field dict: {sequence|input|...}. Precedence: --sequence,
+    --input, then the positional (a file path or '-' for stdin)."""
+    if sequence:
+        return {"sequence": sequence}
+    if inp:
+        return {"input": inp}
+    if positional:
+        if positional == "-" or Path(positional).is_file():
+            text = sys.stdin.read() if positional == "-" else Path(positional).read_text()
+            # A file or pipe holding residues alone is a sequence, not a FASTA/YAML
+            # document: the API refuses bare residues sent as 'input'.
+            if text.strip() and "".join(text.split()).isalpha():
+                return {"sequence": "".join(text.split())}
+            return {"input": text}
+        # Not a file: treat a bare alphabetic token as a sequence, else raw input.
+        if positional.replace("\n", "").isalpha():
+            return {"sequence": positional}
+        return {"input": positional}
+    return {}
+
+
+def _read_text_arg(value):
+    """A flag that accepts a file path, '-' for stdin, or the text itself."""
+    if not value:
+        return value
+    if value == "-":
+        return sys.stdin.read()
+    p = Path(value)
+    if p.is_file():
+        return p.read_text()
+    return value
+
+
+def _collect_params(pairs, **explicit):
+    params = {}
+    for k, v in explicit.items():
+        if v is not None:
+            params[k] = v
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise SystemExit(f"--param must be key=value, got: {pair}")
+        k, v = pair.split("=", 1)
+        # coerce simple scalars
+        if v.lower() in ("true", "false"):
+            v = v.lower() == "true"
+        else:
+            try:
+                v = int(v)
+            except ValueError:
+                try:
+                    v = float(v)
+                except ValueError:
+                    pass
+        params[k] = v
+    return params
+
+
+# --------------------------------------------------------------------------- #
+# Poll + download
+# --------------------------------------------------------------------------- #
+def _poll_until_done(base, key, job_id, *, quiet=False, interval=5.0, max_interval=15.0):
+    last = None
+    while True:
+        _, job, _ = _request("GET", base, f"/v1/jobs/{job_id}", key)
+        line = _progress(job)
+        if not quiet and line != last:
+            print(f"  {job_id[:8]}  {line}", file=sys.stderr)
+            last = line
+        if job.get("status") in TERMINAL:
+            return job
+        time.sleep(interval)
+        interval = min(max_interval, interval * 1.3)
+
+
+def _download(base, key, job_id, out_dir, *, name=None):
+    """Fetch the results bundle and extract it. Resume-friendly: skips if already
+    extracted. Returns the output directory path."""
+    dest = Path(out_dir) / (name or job_id)
+    marker = dest / ".japanfold-complete"
+    if marker.exists():
+        return dest
+    # A results bundle can be hundreds of MB (475 MB measured on the service), so
+    # the archive gets its own long timeout and lands on disk rather than in
+    # memory. The shared 120 s default turned a slow link into the misleading
+    # "no results to download".
+    tmp = dest.with_suffix(".zip.part")
+    try:
+        _, blob, _ = _request("GET", base, f"/v1/jobs/{job_id}/archive", key, raw=True,
+                              timeout=_ARCHIVE_TIMEOUT, sink=tmp)
+    except ApiError as e:
+        tmp.unlink(missing_ok=True)
+        raise SystemExit(f"no results to download: {e}")
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        tmp.unlink(missing_ok=True)
+        raise SystemExit(f"results download failed after {_ARCHIVE_TIMEOUT:.0f}s: {e}")
+    dest.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(blob) as z:
+        for m in z.namelist():
+            # Skip engine bookkeeping files; keep structures + results.json only.
+            if m.endswith((".lock", ".tmp", ".bak")):
+                continue
+            z.extract(m, dest)
+    tmp.unlink(missing_ok=True)
+    # Persist the final job record + the /v1 results manifest under distinct names
+    # so they never clobber the engine's own results.json inside the bundle.
+    _, job, _ = _request("GET", base, f"/v1/jobs/{job_id}", key)
+    (dest / "job.json").write_text(json.dumps(job, indent=2))
+    try:
+        _, res, _ = _request("GET", base, f"/v1/jobs/{job_id}/results", key)
+        (dest / "japanfold_manifest.json").write_text(json.dumps(res, indent=2))
+    except ApiError:
+        pass
+    marker.write_text("ok")
+    return dest
+
+
+# --------------------------------------------------------------------------- #
+# Commands
+# --------------------------------------------------------------------------- #
+def _money(amount: float, currency: str = "usd") -> str:
+    """An amount the way the service renders it: two significant digits, never
+    fewer than two decimals and never more than six.
+
+    Six is one micro, where the ledger itself stops, so nothing non-zero reads
+    as $0.00 -- and sub-cent is ordinary here, because a twenty-second fold
+    costs a fraction of a cent. The rule lives in ``japanfold/pricing.py``; this
+    file ships standalone with no dependencies, so it carries the five lines instead.
+    """
+    a = abs(amount)
+    digits = 2 if a == 0 else max(2, min(6, 1 - math.floor(math.log10(a))))
+    body, sign = f"{a:,.{digits}f}", "-" if amount < 0 else ""
+    return f"{sign}${body}" if currency.lower() == "usd" else f"{sign}{body} {currency.upper()}"
+
+
+TOKEN_PAGE = "https://japanfold.aiand.com/account/token"
+
+
+def _account_line(acct: dict) -> str:
+    """The balance, in the account's own currency, and what an hour costs."""
+    cur = acct.get("currency") or "usd"
+    per_hour = (acct.get("rate") or {}).get("per_hour")
+    rate = f" at {_money(per_hour, cur)} per processor hour" if per_hour else ""
+    return f"{_money(acct.get('balance') or 0, cur)} left{rate}."
+
+
+def cmd_auth(args):
+    if args.auth_cmd == "login":
+        key = args.api_key or os.environ.get("JAPANFOLD_API_KEY")
+        if not key and sys.stdin.isatty():
+            key = input(f"API key from {TOKEN_PAGE}: ").strip()
+        if not key:
+            _err(f"no key provided (pass --api-key, set JAPANFOLD_API_KEY, or run interactively). "
+                 f"Get one at {TOKEN_PAGE}")
+            return EXIT_AUTH
+        base = resolve_base_url(args)
+        try:
+            _request("GET", base, "/v1/jobs?limit=1", key)
+        except ApiError as e:
+            _err(f"key rejected by {base}: {e}")
+            return EXIT_AUTH
+        cfg = _load_config()
+        cfg["api_key"] = key
+        cfg["base_url"] = base
+        _save_config(cfg)
+        print(f"Logged in to {base}. Credentials saved to {CONFIG_PATH}.")
+        return 0
+    if args.auth_cmd == "status":
+        key = resolve_api_key(args)
+        base = resolve_base_url(args)
+        if not key:
+            _err(f"no key. Get one at {TOKEN_PAGE}, then `japanfold auth login`.")
+            return EXIT_AUTH
+        try:
+            _, acct, _ = _request("GET", base, "/v1/account", key)
+        except ApiError as e:
+            print(f"Key present but not valid at {base}: {e}")
+            return EXIT_AUTH
+        if args.json:
+            _emit(acct, True)
+            return EXIT_OK
+        print(f"{base} (key {key[:12]}…)")
+        print(_account_line(acct))
+        return EXIT_OK
+    if args.auth_cmd == "logout":
+        cfg = _load_config()
+        cfg.pop("api_key", None)
+        _save_config(cfg)
+        print("Logged out.")
+        return EXIT_OK
+    return EXIT_INPUT
+
+
+def cmd_models(args):
+    base = resolve_base_url(args)
+    _, data, _ = _request("GET", base, "/v1/models", resolve_api_key(args))
+    if args.json:
+        _emit(data, True)
+        return 0
+    # A family card carries its variants in `checkpoints`, and those are the ids
+    # you actually pass to --model. Printing cards alone hid esmfold2-fast,
+    # opendde-abag and every ESMC/SaProt size except the first, so `japanfold
+    # models` did not list esmc-600m -- the default `japanfold embed --help`
+    # tells you to look here for. Nest them, the way design protocols already are.
+    def print_family(m):
+        cps = m.get("checkpoints") or []
+        if not cps:
+            print(f"  {m['id']:16} {m.get('tagline', '')}")
+            return
+        # The card is named after its first checkpoint, so printing the card id
+        # and then the checkpoints would print one id twice. Head the group with
+        # the family name and indent every id under it -- what you pass --model
+        # is always the indented thing.
+        print(f"  {m.get('name', m['id']):16} {m.get('tagline', '')}")
+        for cp in cps:
+            print(f"    {cp['id']:24} {cp.get('name', cp.get('label', ''))}")
+
+    print("Models:")
+    for m in data["models"]:
+        print_family(m)
+    # Grouped by design model, because that is the choice a user makes first:
+    # the protocol only exists inside one of the three models.
+    print("Design models and their protocols:")
+    dms = data.get("design_models") or [{"id": e, "name": e} for e in
+                                        dict.fromkeys(p.get("engine") for p in data["protocols"])]
+    for dm in dms:
+        tag = dm.get("tagline", "")
+        print(f"  {dm['id']:12} {dm.get('name', dm['id'])}{'  ' + tag if tag else ''}")
+        for p in data["protocols"]:
+            if p.get("engine") == dm["id"]:
+                print(f"    {p['id']:24} {p.get('name', '')}")
+    print("Embedding models:")
+    for m in data.get("embed_models", []):
+        print_family(m)
+    return 0
+
+
+def cmd_schema(args):
+    """Print the OpenAPI 3.1 contract (agent/tool introspection)."""
+    base = resolve_base_url(args)
+    _, spec, _ = _request("GET", base, "/v1/openapi.json", None)
+    print(json.dumps(spec, indent=2))
+    return 0
+
+
+def cmd_predict(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    fields = _read_input(args.input_pos, args.sequence, args.input)
+    if not fields:
+        _err("provide an input: a FASTA/YAML file, '-', --sequence, or --input")
+        return EXIT_INPUT
+    params = _collect_params(args.param, use_msa_server=args.use_msa_server,
+                             fast=args.fast,
+                             recycling_steps=args.recycling_steps,
+                             sampling_steps=args.sampling_steps,
+                             diffusion_samples=args.diffusion_samples,
+                             output_format=args.output_format,
+                             seed=args.seed, write_pae=args.write_pae,
+                             use_tfg_guidance=args.use_tfg_guidance)
+    body = {"model": args.model, "name": args.name, "params": params, **fields}
+    _, job, _ = _request("POST", base, "/v1/predictions", key, body=body,
+                         idempotency=args.idempotency_key)
+    return _after_submit(base, key, job, args)
+
+
+def cmd_design(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    params = _collect_params(args.param, num_designs=args.num_designs,
+                             budget=args.budget, num_timesteps=args.num_timesteps,
+                             n_step=args.n_step, fast=args.fast, seed=args.seed)
+    body = {"model": args.model, "protocol": args.protocol, "name": args.name, "params": params}
+    # Three input shapes, one per design model: BoltzGen takes a YAML spec,
+    # RFdiffusion3 a target structure plus a contig, PXDesign a target structure plus
+    # the chains to condition on. Route on what the caller supplied; the server is the
+    # authority on which the protocol needs.
+    if args.structure or args.contig or args.chains or args.binder_length:
+        body["structure"] = _read_text_arg(args.structure)
+        for key, val in (("contig", args.contig), ("chains", args.chains),
+                         ("binder_length", args.binder_length), ("hotspots", args.hotspots)):
+            if val is not None:
+                body[key] = val
+    else:
+        spec = _read_input(args.input_pos, None, args.spec).get("input")
+        if not spec:
+            _err("provide a design spec (a YAML file, '-', or --spec), "
+                 "--structure and --contig for an RFdiffusion3 protocol, or "
+                 "--structure, --chains and --binder-length for a PXDesign one")
+            return EXIT_INPUT
+        body["spec"] = spec
+    _, job, _ = _request("POST", base, "/v1/designs", key, body=body)
+    return _after_submit(base, key, job, args)
+
+
+def cmd_embed(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    fields = _read_input(args.input_pos, args.sequence, args.input)
+    if not fields:
+        _err("provide an input: a FASTA/YAML file, '-', --sequence, or --input")
+        return EXIT_INPUT
+    params = _collect_params(args.param, pool=args.pool, format=args.format,
+                             fast=args.fast)
+    body = {"model": args.model, "name": args.name, "params": params, **fields}
+    _, job, _ = _request("POST", base, "/v1/embeddings", key, body=body,
+                         idempotency=args.idempotency_key)
+    return _after_submit(base, key, job, args)
+
+
+def _after_submit(base, key, job, args):
+    job_id = job["id"]
+    _err(f"Submitted job {job_id}  ({job.get('kind')}, {job.get('model') or job.get('protocol')})")
+    if not args.wait:
+        _emit(job, args.json)
+        if not args.json:
+            print(job_id)
+        return 0
+    return _finish(base, key, job_id, args)
+
+
+def _finish(base, key, job_id, args):
+    """Poll a job to completion, download its results, and emit. Shared by
+    ``predict/design --wait`` and the standalone ``download`` command."""
+    final = _poll_until_done(base, key, job_id, quiet=args.json)
+    if final.get("status") != "succeeded":
+        _err(f"job {final.get('status')}: {final.get('error') or 'see logs'}")
+        _emit(final, args.json)
+        raise Done(1)
+    dest = _download(base, key, job_id, args.out or ".", name=args.name)
+    _err(f"Done. Results in {dest}")
+    _emit({**final, "output_dir": str(dest)}, args.json)
+    if not args.json:
+        print(str(dest))
+    return 0
+
+
+def cmd_jobs(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    if args.jobs_cmd == "list":
+        path = f"/v1/jobs?limit={args.limit}" + (f"&cursor={args.cursor}" if args.cursor else "")
+        _, data, _ = _request("GET", base, path, key)
+        if args.json:
+            _emit(data, True)
+            return 0
+        for j in data["data"]:
+            print(f"  {j['id']}  {j['status']:9} {j.get('kind'):7} {j.get('name', '')}")
+        if data.get("has_more"):
+            print(f"  … more (next cursor: {data['next_cursor']})", file=sys.stderr)
+        return 0
+    if args.jobs_cmd == "get":
+        _, job, _ = _request("GET", base, f"/v1/jobs/{args.job_id}", key)
+        if args.json:
+            _emit(job, True)
+        else:
+            print(f"{job['id']}  {_progress(job)}")
+        return 0 if job.get("status") != "failed" else 1
+    if args.jobs_cmd == "cancel":
+        _, res, _ = _request("POST", base, f"/v1/jobs/{args.job_id}/cancel", key)
+        _emit(res, args.json)
+        if not args.json:
+            print("canceled" if res.get("canceled") else "not canceled")
+        return 0
+    return EXIT_INPUT
+
+
+def cmd_credits(args):
+    args.auth_cmd = "status"
+    return cmd_auth(args)
+
+
+def cmd_download(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    return _finish(base, key, args.job_id, args)
+
+
+def cmd_logs(args):
+    base, key = resolve_base_url(args), resolve_api_key(args)
+    _, blob, _ = _request("GET", base, f"/v1/jobs/{args.job_id}/logs", key, raw=True)
+    sys.stdout.write(blob.decode(errors="replace"))
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# Argument parsing
+# --------------------------------------------------------------------------- #
+EPILOG = f"""\
+key:      JAPANFOLD_API_KEY (or --api-key, or `japanfold auth login`).
+          Get one at {TOKEN_PAGE}
+base URL: {DEFAULT_BASE_URL} (override with JAPANFOLD_BASE_URL or --base-url)
+
+examples:
+  japanfold fold --sequence MKTAYIAKQR... --wait --out ./out
+  japanfold design spec.yaml --model boltzgen --protocol nanobody-anything --wait --out ./out
+  japanfold embed --sequence MKTAYIAKQR... --wait --out ./out
+  japanfold wait JOB_ID --out ./out
+  japanfold credits
+
+`japanfold models` lists every model and design protocol; `japanfold <command> -h`
+shows its flags. Exit codes: 0 ok, 1 job failed, 2 auth, 3 bad input, 4 not found,
+5 rate-limited, 6 unreachable.
+"""
+
+def build_parser():
+    # Global flags live on a parent parser (with SUPPRESS defaults) added to the
+    # top parser AND every subparser, so `--json`/`--base-url`/`--api-key` work in
+    # any position, before OR after the subcommand, without clobbering.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--base-url", default=argparse.SUPPRESS,
+                        help=f"API base URL (default {DEFAULT_BASE_URL}).")
+    common.add_argument("--api-key", default=argparse.SUPPRESS, help="Override the API key.")
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
+                        help="Machine-readable JSON on stdout.")
+
+    def add(subparsers, name, **kw):
+        return subparsers.add_parser(name, parents=[common], **kw)
+
+    p = argparse.ArgumentParser(prog="japanfold", parents=[common],
+                                description=__doc__.splitlines()[0], epilog=EPILOG,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"japanfold {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    a = add(sub, "auth", help="Save a key / check the balance / log out.")
+    asub = a.add_subparsers(dest="auth_cmd", required=True)
+    add(asub, "login")
+    add(asub, "status")
+    add(asub, "logout")
+
+    add(sub, "models", help="List available models, protocols and limits.")
+    add(sub, "schema", help="Print the OpenAPI 3.1 contract (for tooling/agents).")
+
+    add(sub, "credits", help="Show the balance left on your key (same as `auth status`).")
+
+    pr = add(sub, "predict", aliases=["fold"], help="Predict a structure.")
+    pr.add_argument("input_pos", nargs="?", metavar="INPUT", help="FASTA/YAML file, or '-' for stdin.")
+    pr.add_argument("--sequence", help="A single protein sequence (convenience).")
+    pr.add_argument("--input", help="Inline FASTA/YAML string.")
+    pr.add_argument("--model", default="boltz2",
+                    help="Prediction model id (default boltz2). `japanfold models` lists them.")
+    pr.add_argument("--name")
+    # Both directions, or the CLI can only ever agree with the server default:
+    # --use-msa-server had no opposite, so a CLI user could not fold Protenix-v2 /
+    # OpenFold3 / OpenBind-0 / RoseTTAFold3 / OpenDDE single-sequence at all,
+    # though the web form and the raw API both offer it. Same for --fast on all
+    # three verbs. Unset stays absent from the body, which is what makes an
+    # omitted param take the catalog default.
+    pr.add_argument("--fast", action=argparse.BooleanOptionalAction, default=None,
+                    help="Higher throughput, may be slightly less accurate. Off unless given.")
+    pr.add_argument("--use-msa-server", action=argparse.BooleanOptionalAction,
+                    default=None, dest="use_msa_server",
+                    help="Build an MSA for the input. --no-use-msa-server folds single-sequence.")
+    pr.add_argument("--recycling-steps", type=int, dest="recycling_steps",
+                    help="Omit it and the model uses its own recommended value.")
+    pr.add_argument("--sampling-steps", type=int, dest="sampling_steps",
+                    help="Omit it and the model uses its own recommended value.")
+    pr.add_argument("--diffusion-samples", type=int, dest="diffusion_samples",
+                    help="Structures to sample per target.")
+    pr.add_argument("--output-format", choices=["cif", "pdb"], dest="output_format")
+    pr.add_argument("--seed", type=int, help="Diffusion noise seed. Default 0.")
+    pr.add_argument("--write-pae", action=argparse.BooleanOptionalAction, default=None,
+                    dest="write_pae",
+                    help="Also return the PAE matrix (models with the pae cap).")
+    pr.add_argument("--use-tfg-guidance", action=argparse.BooleanOptionalAction, default=None,
+                    dest="use_tfg_guidance",
+                    help="OpenDDE: steer sampling with the input's constraint: block "
+                         "(contact pairs or epitope residues).")
+    pr.add_argument("--param", action="append", help="Extra param key=value (repeatable).")
+    pr.add_argument("--idempotency-key", dest="idempotency_key")
+    pr.add_argument("--wait", action="store_true", help="Poll to completion and download results.")
+    pr.add_argument("--out", help="Output directory for --wait (default: cwd).")
+
+    de = add(sub, "design",
+             help="Design binders/proteins (BoltzGen, RFdiffusion3 or PXDesign).")
+    de.add_argument("input_pos", nargs="?", metavar="SPEC", help="YAML design spec file, or '-'.")
+    de.add_argument("--spec", help="Inline YAML design spec (BoltzGen protocols).")
+    de.add_argument("--model", dest="model",
+                    help="Design model: boltzgen, rfd3 or pxdesign. Must match the protocol; "
+                         "`japanfold models` groups the protocols by model.")
+    de.add_argument("--protocol", help="Design protocol id. `japanfold models` lists them.")
+    de.add_argument("--structure", help="Target structure (PDB/mmCIF file, '-' for stdin, or the "
+                                       "text itself). RFdiffusion3 and PXDesign protocols.")
+    de.add_argument("--contig", help="RFdiffusion3 contig, e.g. 'A1-150,60-80': what stays fixed "
+                                     "and what gets designed.")
+    de.add_argument("--chains", help="Target chain ids to design against, e.g. 'A' or 'A,B'. "
+                                     "PXDesign protocols only.")
+    de.add_argument("--binder-length", type=int, dest="binder_length",
+                    help="Residues in the designed binder, 8-200 (PXDesign).")
+    de.add_argument("--hotspots", help="Target residues to aim the binder at, e.g. 'A64,A65,A66' "
+                                       "(bare numbers when one chain is named). PXDesign, optional.")
+    de.add_argument("--name")
+    de.add_argument("--num-designs", type=int, dest="num_designs")
+    de.add_argument("--budget", type=int, help="Ranked designs to keep (BoltzGen).")
+    de.add_argument("--num-timesteps", type=int, dest="num_timesteps",
+                    help="Diffusion steps per design (RFdiffusion3).")
+    de.add_argument("--n-step", type=int, dest="n_step",
+                    help="Diffusion steps per design (PXDesign).")
+    de.add_argument("--fast", action=argparse.BooleanOptionalAction, default=None,
+                    help="Higher throughput, may be slightly less accurate. Off unless given.")
+    de.add_argument("--seed", type=int,
+                    help="Noise seed: the same seed and input give the same designs. "
+                         "BoltzGen draws fresh when omitted; RFdiffusion3 and PXDesign use 42.")
+    de.add_argument("--param", action="append")
+    de.add_argument("--wait", action="store_true")
+    de.add_argument("--out")
+
+    em = add(sub, "embed", help="Compute protein-language-model embeddings.")
+    em.add_argument("input_pos", nargs="?", metavar="INPUT", help="FASTA/YAML file, or '-' for stdin.")
+    em.add_argument("--sequence", help="A single protein sequence (convenience).")
+    em.add_argument("--input", help="Inline FASTA/YAML string.")
+    em.add_argument("--model", default="esmc-600m",
+                    help="Embedding model id (default esmc-600m). `japanfold models` lists them.")
+    em.add_argument("--pool", default="mean", choices=["mean", "max", "cls"])
+    em.add_argument("--format", default="npz", choices=["npz", "parquet"], dest="format")
+    em.add_argument("--name")
+    em.add_argument("--fast", action=argparse.BooleanOptionalAction, default=None)
+    em.add_argument("--param", action="append", help="Extra param key=value (repeatable).")
+    em.add_argument("--idempotency-key", dest="idempotency_key")
+    em.add_argument("--wait", action="store_true", help="Poll to completion and download results.")
+    em.add_argument("--out", help="Output directory for --wait (default: cwd).")
+
+    j = add(sub, "jobs", help="List / inspect / cancel jobs.")
+    jsub = j.add_subparsers(dest="jobs_cmd", required=True)
+    jl = add(jsub, "list")
+    jl.add_argument("--limit", type=int, default=20)
+    jl.add_argument("--cursor")
+    add(jsub, "get").add_argument("job_id")
+    add(jsub, "cancel").add_argument("job_id")
+
+    dl = add(sub, "download", aliases=["wait"],
+             help="Wait for a job to finish and download its results.")
+    dl.add_argument("job_id")
+    dl.add_argument("--out")
+    dl.add_argument("--name", help="Subdirectory name (default: job id).")
+
+    lg = add(sub, "logs", help="Print a job's run log.")
+    lg.add_argument("job_id")
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    # Materialize SUPPRESS-defaulted globals so handlers can read them freely.
+    args.json = getattr(args, "json", False)
+    args.base_url = getattr(args, "base_url", None)
+    args.api_key = getattr(args, "api_key", None)
+    if not hasattr(args, "name"):
+        args.name = None
+    handlers = {"auth": cmd_auth, "credits": cmd_credits, "models": cmd_models,
+                "predict": cmd_predict, "fold": cmd_predict, "design": cmd_design,
+                "embed": cmd_embed, "jobs": cmd_jobs, "download": cmd_download,
+                "wait": cmd_download, "logs": cmd_logs, "schema": cmd_schema}
+    try:
+        return handlers[args.cmd](args) or EXIT_OK
+    except Done as e:
+        return e.code
+    except ApiError as e:
+        _err(str(e))
+        return e.exit_code
+    except KeyboardInterrupt:
+        _err("interrupted")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

japanfold-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "japanfold"
+version = "1.0.0"
+description = "Command-line client for JapanFold: protein structure prediction, binder design and embeddings over an HTTP API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+# Intentionally dependency-free (stdlib only) so it installs anywhere an agent runs.
+dependencies = []
+keywords = ["protein", "structure-prediction", "boltz", "esmfold", "binder-design", "bioinformatics"]
+
+[project.urls]
+Homepage = "https://japanfold.aiand.com"
+Documentation = "https://japanfold.aiand.com/docs"
+
+[project.scripts]
+japanfold = "japanfold_cli:main"
+
+[tool.setuptools]
+py-modules = ["japanfold_cli"]

japanfold-1.0.0/setup.cfg

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