qatlas-cli 0.22.0__py3-none-any.whl

qatlas/__init__.py

@@ -0,0 +1,48 @@
+"""
+QuantumAtlas - AI 驱动的量子算法开发辅助系统
+
+核心功能：从论文到可执行量子代码的完整转化链路
+"""
+
+from __future__ import annotations
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _version_from_pyproject() -> str:
+    """Read [project].version from the nearest repo-root pyproject.toml.
+
+    Supports both the legacy flat layout (``qatlas/`` at the repo root,
+    pyproject at ``parents[1]``) and the src layout (``src/qatlas/``,
+    pyproject at ``parents[2]``).
+    """
+    here = Path(__file__).resolve()
+    for parent in (here.parents[1], here.parents[2]):
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        try:
+            return str(data["project"]["version"])
+        except KeyError:
+            continue
+    raise FileNotFoundError("no pyproject.toml with [project].version found")
+
+
+def _resolve_version() -> str:
+    """Prefer repo pyproject when present, else installed distribution metadata."""
+    try:
+        return _version_from_pyproject()
+    except (FileNotFoundError, KeyError, OSError):
+        try:
+            return version("qatlas-cli")
+        except PackageNotFoundError:
+            return "0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

qatlas/cli.py

@@ -0,0 +1,218 @@
+"""Top-level command-line entry point for QuantumAtlas.
+
+This module backs the ``qatlas`` console script declared in
+``pyproject.toml``.  It intentionally delegates to the existing module CLIs so
+their behavior stays identical to ``python -m qatlas.<module>``.
+"""
+
+from __future__ import annotations
+
+import runpy
+import sys
+from dataclasses import dataclass
+from typing import Mapping, Sequence
+
+from qatlas import __version__
+
+
+@dataclass(frozen=True)
+class Command:
+    """A delegated QuantumAtlas CLI command."""
+
+    module: str
+    summary: str
+    client_friendly: bool = True
+
+
+COMMANDS: Mapping[str, Command] = {
+    "config": Command(
+        "qatlas.client.config",
+        "Manage the user-level config file (~/.config/qatlas/config.yaml)",
+    ),
+    "auth": Command(
+        "qatlas.client.auth",
+        "Manage saved PATs / session tokens per host (login, status, token, logout)",
+    ),
+    "paper": Command(
+        "qatlas.client.paper",
+        "Fetch paper PDF / markdown from the server (silent fetch + LRO polling for cache misses)",
+    ),
+    "contrib": Command(
+        "qatlas.client.contrib",
+        "Contributor workflows: upload PDFs (contrib pdf) or run local MinerU and push (contrib mineru)",
+    ),
+    "parser": Command("qatlas.parser.__main__", "Fetch and parse arXiv papers", False),
+}
+
+ALIASES: Mapping[str, str] = {
+    "papers": "paper",
+    "parse": "parser",
+}
+
+
+def _print_help() -> None:
+    """Print top-level CLI help."""
+
+    print(
+        """QuantumAtlas command line
+
+Usage:
+  qatlas <command> [args...]
+  qatlas --version
+  qatlas --help
+
+Commands:"""
+    )
+
+    print("  Client/operator commands:")
+    for name, command in COMMANDS.items():
+        if not command.client_friendly:
+            continue
+        print(f"    {name:<10} {command.summary}")
+
+    print("\n  Local workspace commands:")
+    for name, command in COMMANDS.items():
+        if command.client_friendly:
+            continue
+        print(f"    {name:<10} {command.summary}")
+
+    # Plugin-contributed top-level commands (only those available in the
+    # current environment). No first-party plugins ship today; third-party
+    # plugins register via the ``qatlas.plugins`` entry-point group.
+    try:
+        from qatlas.client.plugins import registry
+
+        plugin_cmds = registry.top_level_commands()
+    except Exception:
+        plugin_cmds = {}
+    if plugin_cmds:
+        print("\n  Plugin commands:")
+        for name in sorted(plugin_cmds):
+            print(f"    {name:<10} {plugin_cmds[name].summary}")
+
+    print(
+        """
+Aliases:
+  papers -> paper
+  parse -> parser
+
+Examples:
+  qatlas paper get markdown quant-ph/9508027 --output paper.md
+  qatlas paper get pdf 10.1103/PhysRevLett.103.150502 -o paper.pdf
+  qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+  qatlas contrib mineru 2501.00010v1
+  qatlas contrib mineru --watch
+
+Use "qatlas <command> --help" for command-specific options."""
+    )
+
+
+def _print_usage_error(message: str) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    print("Run 'qatlas --help' to see available commands.", file=sys.stderr)
+
+
+def _print_search_plugin_hint() -> None:
+    """Explain that ``search`` ships as the standalone qatlas-search plugin."""
+
+    print(
+        "The 'search' command is provided by the standalone plugin "
+        "qatlas-search, which is not installed.\n"
+        "Install it with pip/uv from the private repository "
+        "IAI-USTC-Quantum/qatlas-search, e.g.:\n"
+        "  uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-search.git qatlas-search\n"
+        "or, into the current environment:\n"
+        "  uv pip install git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-search.git",
+        file=sys.stderr,
+    )
+
+
+def _exit_code(code: object) -> int:
+    """Normalize a child ``SystemExit.code`` value to an integer exit code."""
+
+    if code is None:
+        return 0
+    if isinstance(code, int):
+        return code
+    print(code, file=sys.stderr)
+    return 1
+
+
+def _run_module(module: str, argv0: str, args: Sequence[str]) -> int:
+    """Run a child module as if it had been invoked with ``python -m``."""
+
+    original_argv = sys.argv[:]
+    sys.argv = [argv0, *args]
+    try:
+        try:
+            runpy.run_module(module, run_name="__main__")
+        except SystemExit as exc:
+            return _exit_code(exc.code)
+        return 0
+    finally:
+        sys.argv = original_argv
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the QuantumAtlas CLI."""
+
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if not args or args[0] in {"-h", "--help"}:
+        _print_help()
+        return 0
+
+    if args[0] in {"-V", "--version"}:
+        print(f"qatlas {__version__}")
+        return 0
+
+    requested_command = args[0].replace("_", "-")
+    command_name = ALIASES.get(requested_command, requested_command)
+    command = COMMANDS.get(command_name)
+
+    # Plugin-contributed top-level commands fill gaps the static table
+    # doesn't cover. Built-ins always take precedence.
+    plugin_spec = None
+    if command is None:
+        try:
+            from qatlas.client.plugins import registry
+
+            plugin_spec = registry.top_level_commands().get(command_name)
+        except Exception:
+            plugin_spec = None
+        if plugin_spec is None:
+            if command_name == "search":
+                _print_search_plugin_hint()
+                return 2
+            _print_usage_error(f"unknown command '{args[0]}'")
+            return 2
+
+    # v0.17.0+: client config lives exclusively in
+    # ~/.config/qatlas/config.yaml. Ensure it exists on first run so
+    # the user can immediately edit it; idempotent on subsequent runs.
+    #
+    # Exception: skip for `qatlas config` itself — its `path` / `show`
+    # subcommands intentionally tolerate a missing file and would
+    # display misleading "auto-created on first read" behaviour
+    # otherwise.
+    if command_name != "config":
+        try:
+            from qatlas.config import ensure_default_config_exists
+            ensure_default_config_exists()
+        except Exception:
+            # Defensive: never block a subcommand on config-file IO;
+            # the embedded defaults work for any read-only command.
+            pass
+
+    if plugin_spec is not None:
+        return plugin_spec.handler(args[1:])
+
+    return _run_module(
+        command.module,
+        argv0=f"qatlas {command_name}",
+        args=args[1:],
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qatlas/client/__init__.py

@@ -0,0 +1 @@
+"""HTTP client commands for QuantumAtlas."""

qatlas/client/_common.py

@@ -0,0 +1,231 @@
+"""Shared helpers for QuantumAtlas client-side CLIs.
+
+Configuration source (v0.17.0+): every value comes from
+``~/.config/qatlas/config.yaml`` via ``qatlas.config.ServerConfig``.
+No CLI flag, no OS env, no ``QATLAS_DOTENV``. ``qatlas auth login``
+still maintains a separate per-host token file
+(``~/.config/qatlas/hosts.yml``) used as the last-resort token
+fallback when ``config.yaml`` has no ``token:``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import Any
+
+import requests
+
+from qatlas import __version__ as _CLIENT_VERSION
+from qatlas.config import ServerConfig
+
+
+def _client_config() -> ServerConfig:
+    """Build a fresh ServerConfig view of the current YAML.
+
+    Cheap (~ms), and re-reading per call means a `qatlas config set`
+    in between two `qatlas papers ...` invocations is picked up
+    immediately without process state.
+    """
+    return ServerConfig.from_env()
+
+
+def default_base_url() -> str:
+    """Resolve the server base URL from ``config.yaml`` ``server_url``.
+
+    Falls back to ``http://127.0.0.1:8090`` (PocketBase default) when
+    unset so ``qatlas`` doesn't fatal on first run without a configured
+    server — useful for local dev.
+    """
+    cfg = _client_config()
+    server_url = cfg.get_server_url()
+    if server_url:
+        return server_url
+    return "http://127.0.0.1:8090"
+
+
+def base_url_from_args(args: argparse.Namespace) -> str:
+    """Return the config-file server_url.
+
+    ``args`` is accepted for back-compat with the v0.16 signature; no
+    field is read from it anymore. Subcommands that need a different
+    server should set up a separate ``XDG_CONFIG_HOME``-isolated
+    config.
+    """
+    return default_base_url()
+
+
+def request_verify(args: argparse.Namespace) -> bool:
+    """Honor ``insecure: true`` in config.yaml to disable TLS verification.
+
+    Same one-shot warning behaviour as before. ``args`` kept for
+    signature back-compat.
+    """
+    cfg = _client_config()
+    if not cfg.insecure:
+        return True
+    if not getattr(args, "_insecure_warning_shown", False):
+        requests.packages.urllib3.disable_warnings(  # type: ignore[attr-defined]
+            category=requests.packages.urllib3.exceptions.InsecureRequestWarning
+        )
+        print("Warning: TLS certificate verification is disabled.", file=sys.stderr)
+        args._insecure_warning_shown = True
+    return False
+
+
+def resolve_token(args: argparse.Namespace) -> str:
+    """Resolve the bearer credential from ``~/.config/qatlas/hosts.yml``.
+
+    The store is populated by ``qatlas auth login`` (browser OAuth /
+    ``--with-token`` from stdin). ``server_url:`` in config.yaml /
+    ``--server-url`` CLI flag picks WHICH host's token to use.
+
+    ``args`` kept for signature back-compat (used to honour
+    ``--token`` CLI flag, removed in v0.17.0; config.yaml ``token:``
+    field removed in v0.19.0 — it silently shadowed all per-host
+    tokens in hosts.yml).
+
+    An empty return value means no Authorization header will be set;
+    the server then either serves open reads or replies 401 for write
+    endpoints. The 401 body always points the user at ``/pat``
+    (top-level redirect to ``/<lang>/pat``, defined in
+    ``web/src/routes/pat.tsx``) regardless of language.
+    """
+    try:
+        from qatlas.client.auth import get_stored_token  # local import to avoid cycle
+
+        return get_stored_token(default_base_url())
+    except Exception:
+        # Defensive: never let a config-file glitch break unrelated commands.
+        return ""
+
+
+def auth_headers(args: argparse.Namespace) -> dict[str, str]:
+    """Build the Authorization header for a CLI request.
+
+    Returns an empty dict when no token is configured so callers can
+    safely splat ``{**auth_headers(args), ...other...}``.
+    """
+    token = resolve_token(args)
+    if not token:
+        return {}
+    return {"Authorization": f"Bearer {token}"}
+
+
+def print_json(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def add_common_http_args(parser: argparse.ArgumentParser) -> None:
+    """Register the shared ``--request-timeout`` flag.
+
+    v0.17.0 removed ``--base-url`` / ``--token`` / ``--insecure``
+    flags — those fields now live exclusively in
+    ``~/.config/qatlas/config.yaml``. ``--request-timeout`` is kept
+    because it's an in-call ergonomic knob (raise the timeout for a
+    slow MinerU poll), not a persistent config concern.
+    """
+    parser.add_argument(
+        "--request-timeout",
+        type=float,
+        default=120.0,
+        help="HTTP request timeout in seconds (per-call override).",
+    )
+
+
+def run_with_request_errors(func, *args, **kwargs) -> int:
+    """Convert ValueError / RequestException into standard CLI exit codes."""
+    try:
+        return func(*args, **kwargs)
+    except ValueError as exc:
+        print(f"Invalid input: {exc}", file=sys.stderr)
+        return 2
+    except requests.RequestException as exc:
+        print(f"Request failed: {exc}", file=sys.stderr)
+        return 1
+
+
+# ---------------------------------------------------------------------------
+# Client/server version negotiation (since v0.8.0)
+# ---------------------------------------------------------------------------
+#
+# Contract: the client version MUST be >= the server version (major+minor
+# semver). Rationale: when the server adds a new endpoint (e.g. the v0.8.0
+# `upload-mineru` replacing `upload-markdown`), an old client doesn't know
+# the new wire shape and will fail in confusing ways. Forcing client >=
+# server prevents the silent broken state.
+#
+# Mechanism:
+#   1. Every request adds  `X-Qatlas-Client-Version: <version>`  (Headers
+#      injected by client_version_headers()). The server logs / future
+#      rate-limit policies can use it.
+#   2. Every response (when from a v0.8.0+ server) includes
+#      `X-Qatlas-Server-Version: <version>`. The client compares major+
+#      minor against its own __version__.
+#   3. If server > client AND the call is a write op → raise SystemExit
+#      (hard fail). Read ops just emit a one-shot stderr warning.
+#   4. If the header is absent (older server) the client treats the
+#      server as "unknown version" and silently skips negotiation —
+#      forward-compatible with pre-v0.8.0 deployments.
+#
+# Patch-level differences are ignored on purpose: a patch bump is supposed
+# to be backwards-compatible bug-fix, so cross-patch usage is fine.
+
+_VERSION_TUPLE_RE = re.compile(r"^(\d+)\.(\d+)(?:\.(\d+))?(?:[.+-].*)?$")
+
+
+def _parse_semver(v: str) -> tuple[int, int] | None:
+    """Return (major, minor) for a semver string, or None if unparseable."""
+    if not v:
+        return None
+    m = _VERSION_TUPLE_RE.match(v.strip())
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)))
+
+
+def client_version_headers() -> dict[str, str]:
+    """Headers every outgoing request should include for version negotiation."""
+    return {"X-Qatlas-Client-Version": _CLIENT_VERSION}
+
+
+_WARNED_OLDER_CLIENT: set[str] = set()
+
+
+def check_response_version(response: requests.Response, *, write: bool) -> None:
+    """Compare X-Qatlas-Server-Version against this client's version.
+
+    * `write=True` callers (POST/PUT/PATCH/DELETE) hard-fail (SystemExit 4)
+      when the server is newer than the client at major+minor level — the
+      server's wire contract may have moved and silent breakage is the
+      worst failure mode.
+    * `write=False` callers (GET, status polls) only emit a one-shot
+      warning per unique server version, so read-mostly workflows still
+      function while signalling the upgrade is needed.
+
+    Older servers (pre-v0.8.0) don't send the header — we treat the
+    absence as "unknown" and do nothing, preserving the new client's
+    ability to talk to legacy deployments.
+    """
+    server_version = response.headers.get("X-Qatlas-Server-Version", "").strip()
+    if not server_version:
+        return  # pre-v0.8.0 server, skip negotiation
+    server = _parse_semver(server_version)
+    client = _parse_semver(_CLIENT_VERSION)
+    if server is None or client is None:
+        return  # unparseable on either side — fail open, don't block calls
+    if server <= client:
+        return  # client >= server, contract satisfied
+    msg = (
+        f"server version {server_version} is newer than client {_CLIENT_VERSION}.\n"
+        f"This client may not understand new endpoints/fields. Upgrade with:\n"
+        f"  pip install --upgrade quantum-atlas"
+    )
+    if write:
+        print(f"ERROR: {msg}", file=sys.stderr)
+        raise SystemExit(4)
+    if server_version not in _WARNED_OLDER_CLIENT:
+        print(f"WARNING: {msg}", file=sys.stderr)
+        _WARNED_OLDER_CLIENT.add(server_version)