pulse-ai-cli 0.1.0__py3-none-any.whl

pulse_cli/config.py

@@ -0,0 +1,141 @@
+"""Credential + settings store for the Pulse CLI.
+
+Resolution order for the API key:
+  1. ``--api-key`` flag / ``PULSE_API_KEY`` env (CI-friendly, never persisted)
+  2. OS keychain via ``keyring`` (preferred persistent store)
+  3. ``~/.pulse/config.toml`` (0600) fallback when keyring is unavailable
+
+Non-secret settings (base URLs) always live in the TOML file.
+"""
+from __future__ import annotations
+
+import os
+import stat
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+CONFIG_DIR = Path(os.environ.get("PULSE_CONFIG_DIR", "~/.pulse")).expanduser()
+CONFIG_PATH = CONFIG_DIR / "config.toml"
+
+DEFAULT_API_URL = "https://api.runpulse.com"  # Flask extraction engine
+# User-facing platform. Also the default OAuth/platform-API base: the web
+# host proxies /api/v1/* straight to the FastAPI service.
+DEFAULT_PLATFORM_URL = "https://platform.runpulse.com"
+PLATFORM_WEB_URL = DEFAULT_PLATFORM_URL  # browser links
+KEYRING_SERVICE = "pulse-cli"
+KEYRING_USER = "api_key"
+
+try:  # optional dependency
+    import keyring  # type: ignore
+
+    try:  # a backendless keyring raises on use; probe once
+        keyring.get_password(KEYRING_SERVICE, "__probe__")
+        _KEYRING_OK = True
+    except Exception:
+        _KEYRING_OK = False
+except ImportError:
+    keyring = None  # type: ignore
+    _KEYRING_OK = False
+
+
+@dataclass
+class Config:
+    api_url: str = DEFAULT_API_URL
+    # Platform base for OAuth login + billing/analytics (override via
+    # `pulse login --platform-url` or PULSE_PLATFORM_URL).
+    platform_url: str = DEFAULT_PLATFORM_URL
+    # Only populated from file/env at load time; never written when keyring is available.
+    api_key: Optional[str] = field(default=None, repr=False)
+    key_source: str = "none"  # env | keyring | file | none
+
+
+def _read_file() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    try:
+        with open(CONFIG_PATH, "rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _write_file(values: dict) -> None:
+    """Write a flat TOML file with 0600 perms."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines = [f'{k} = "{v}"' for k, v in values.items() if v is not None]
+    tmp = CONFIG_PATH.with_suffix(".tmp")
+    tmp.write_text("\n".join(lines) + "\n")
+    tmp.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600 before it holds anything
+    tmp.replace(CONFIG_PATH)
+
+
+def load(api_key_override: Optional[str] = None, api_url_override: Optional[str] = None) -> Config:
+    data = _read_file()
+    cfg = Config(
+        api_url=api_url_override
+        or os.environ.get("PULSE_API_URL")
+        or data.get("api_url", DEFAULT_API_URL),
+        platform_url=os.environ.get("PULSE_PLATFORM_URL")
+        or data.get("platform_url", DEFAULT_PLATFORM_URL),
+    )
+
+    if api_key_override:
+        cfg.api_key, cfg.key_source = api_key_override, "flag"
+    elif os.environ.get("PULSE_API_KEY"):
+        cfg.api_key, cfg.key_source = os.environ["PULSE_API_KEY"], "env"
+    elif _KEYRING_OK and (k := keyring.get_password(KEYRING_SERVICE, KEYRING_USER)):
+        cfg.api_key, cfg.key_source = k, "keyring"
+    elif data.get("api_key"):
+        cfg.api_key, cfg.key_source = data["api_key"], "file"
+
+    return cfg
+
+
+def save_api_key(api_key: str) -> str:
+    """Persist the key; returns where it was stored ('keyring' or 'file')."""
+    data = _read_file()
+    if _KEYRING_OK:
+        keyring.set_password(KEYRING_SERVICE, KEYRING_USER, api_key)
+        data.pop("api_key", None)  # never leave a stale plaintext copy
+        _write_file(data)
+        return "keyring"
+    data["api_key"] = api_key
+    _write_file(data)
+    return "file"
+
+
+def save_settings(api_url: Optional[str] = None, platform_url: Optional[str] = None) -> None:
+    data = _read_file()
+    if api_url:
+        data["api_url"] = api_url
+    if platform_url:
+        data["platform_url"] = platform_url
+    _write_file(data)
+
+
+def clear_api_key() -> bool:
+    """Remove the stored key everywhere. Returns True if something was removed."""
+    removed = False
+    if _KEYRING_OK:
+        try:
+            if keyring.get_password(KEYRING_SERVICE, KEYRING_USER):
+                keyring.delete_password(KEYRING_SERVICE, KEYRING_USER)
+                removed = True
+        except Exception:
+            pass
+    data = _read_file()
+    if "api_key" in data:
+        del data["api_key"]
+        _write_file(data)
+        removed = True
+    return removed
+
+
+def redact(key: Optional[str]) -> str:
+    if not key:
+        return "<none>"
+    if len(key) <= 8:
+        return "****"
+    return f"{key[:4]}…{key[-4:]}"

pulse_cli/errors.py

@@ -0,0 +1,85 @@
+"""Engine error mapping — ported from mcp_server/errors.py so CLI and MCP
+surface identical, actionable messages for the same engine failures.
+
+Engine envelope: ``{"error": {"code", "message", "details"}}`` (or legacy
+``{"error": "<message>"}``).
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+_BILLING_URL = "https://runpulse.com/billing"
+
+
+class PulseCliError(Exception):
+    """Base CLI error; message is shown to the user, exit code 1."""
+
+
+class MissingApiKeyError(PulseCliError):
+    def __init__(self) -> None:
+        super().__init__(
+            "No Pulse API key found. Run `pulse login`, or set PULSE_API_KEY."
+        )
+
+
+class PulseEngineError(PulseCliError):
+    def __init__(
+        self,
+        status_code: int,
+        code: Optional[str] = None,
+        engine_message: Optional[str] = None,
+        details: Optional[Any] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.engine_message = engine_message
+        self.details = details
+        super().__init__(self.user_message())
+
+    @classmethod
+    def from_response(cls, status_code: int, body: Any) -> "PulseEngineError":
+        code: Optional[str] = None
+        message: Optional[str] = None
+        details: Optional[Any] = None
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, dict):
+                code, message, details = err.get("code"), err.get("message"), err.get("details")
+            elif isinstance(err, str):
+                message = err
+            elif "detail" in body:
+                d = body.get("detail")
+                message = d if isinstance(d, str) else None
+                details = None if isinstance(d, str) else d
+        elif isinstance(body, str):
+            message = body[:500] or None
+        return cls(status_code=status_code, code=code, engine_message=message, details=details)
+
+    def user_message(self) -> str:
+        sc = self.status_code
+        code = (self.code or "").upper()
+        msg = (self.engine_message or "").strip()
+        # The actionable reason often lives in details.error (e.g. GENERAL_001 is a
+        # generic "Internal server error" whose details carry the real cause).
+        if isinstance(self.details, dict) and isinstance(self.details.get("error"), str):
+            detail = self.details["error"].strip()
+            if detail and detail.lower() not in msg.lower():
+                msg = f"{msg}: {detail}" if msg else detail
+
+        if sc == 401 or code in ("AUTH_001", "AUTH_002", "AUTH_003"):
+            return "Authentication failed: missing or invalid API key. Run `pulse login`."
+        if sc == 402 or code == "BILLING_003":
+            return f"Payment required: plan limit reached. Upgrade at {_BILLING_URL}."
+        if code == "BILLING_002":
+            return "Insufficient Pulse credits for this operation."
+        if code == "BILLING_001":
+            return f"Your Pulse trial has expired. Upgrade at {_BILLING_URL}."
+        if code == "AUTH_004" or (sc == 403 and not code.startswith("BILLING")):
+            return "Insufficient permissions for this API key."
+        if sc == 429 or code in ("RATE_001", "GENERAL_004"):
+            return "Rate limit exceeded — please retry shortly."
+        if sc == 404:
+            return msg or "Not found."
+        if 400 <= sc < 500:
+            return msg or f"Pulse rejected the request (HTTP {sc})."
+        return msg or f"Pulse processing error (HTTP {sc})."

pulse_cli/oauth.py

@@ -0,0 +1,95 @@
+"""OAuth 2.1 device-flow login (RFC 8628) against the Pulse platform API.
+
+`pulse login` flow (endpoints are under /api/v1 so the platform web host
+— which proxies /api/v1/* to the FastAPI service — works as the base URL):
+  1. POST {platform}/api/v1/oauth/device/authorization -> user_code + URL
+  2. user approves in the browser (platform session cookie)
+  3. poll POST {platform}/api/v1/oauth/token until tokens are issued
+  4. exchange the Bearer access token for the org's API key
+     (GET /api/v1/keys) — the API key is what both the engine and the
+     platform accept everywhere, so the rest of the CLI is unchanged.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional
+
+import httpx
+
+from pulse_cli import __version__
+from pulse_cli.errors import PulseCliError
+
+DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+_HEADERS = {"user-agent": f"pulse-cli/{__version__}"}
+
+
+def _post(url: str, data: dict) -> httpx.Response:
+    try:
+        return httpx.post(url, data=data, headers=_HEADERS, timeout=30.0)
+    except httpx.RequestError as exc:
+        raise PulseCliError(f"could not reach {url}: {exc}") from exc
+
+
+def device_authorization(platform_url: str) -> dict:
+    """Start the flow; returns device_code, user_code, verification URIs, interval."""
+    resp = _post(f"{platform_url.rstrip('/')}/api/v1/oauth/device/authorization", {"client_id": "pulse-cli"})
+    if not resp.is_success:
+        raise PulseCliError(f"device authorization failed (HTTP {resp.status_code}): {resp.text[:200]}")
+    return resp.json()
+
+
+def poll_for_tokens(
+    platform_url: str,
+    device_code: str,
+    *,
+    interval: int = 5,
+    expires_in: int = 600,
+    on_tick: Optional[Callable[[], None]] = None,
+) -> dict:
+    """Poll the token endpoint until approval. Returns the token response."""
+    token_url = f"{platform_url.rstrip('/')}/api/v1/oauth/token"
+    deadline = time.monotonic() + expires_in
+    wait = max(interval, 1)
+    while time.monotonic() < deadline:
+        time.sleep(wait)
+        if on_tick is not None:
+            on_tick()
+        resp = _post(token_url, {"grant_type": DEVICE_GRANT_TYPE, "device_code": device_code})
+        body: Any = {}
+        try:
+            body = resp.json()
+        except Exception:
+            pass
+        if resp.is_success:
+            return body
+        error = body.get("error") if isinstance(body, dict) else None
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            wait += 5
+            continue
+        if error == "access_denied":
+            raise PulseCliError("login request was denied in the browser")
+        if error == "expired_token":
+            break
+        raise PulseCliError(f"token request failed (HTTP {resp.status_code}): {resp.text[:200]}")
+    raise PulseCliError("login code expired before it was approved — run `pulse login --web` again")
+
+
+def fetch_api_key(platform_url: str, access_token: str) -> str:
+    """Exchange the OAuth access token for the org's active API key."""
+    try:
+        resp = httpx.get(
+            f"{platform_url.rstrip('/')}/api/v1/keys",
+            headers={**_HEADERS, "authorization": f"Bearer {access_token}"},
+            timeout=30.0,
+        )
+    except httpx.RequestError as exc:
+        raise PulseCliError(f"could not fetch API keys: {exc}") from exc
+    if not resp.is_success:
+        raise PulseCliError(f"failed to list API keys (HTTP {resp.status_code}): {resp.text[:200]}")
+    keys = resp.json() or []
+    active = [k for k in keys if k.get("status", "active") == "active" and k.get("api_key")]
+    if not active:
+        raise PulseCliError("no active API key found for your organization — create one in the platform")
+    return active[0]["api_key"]

pulse_cli/output.py

@@ -0,0 +1,87 @@
+"""Console output: brand theme, JSON mode, result writers, polling spinner."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from rich.console import Console
+from rich.theme import Theme
+
+# Pulse brand palette
+NAVY_950 = "#02182E"
+NAVY_800 = "#022F56"
+PULSE_500 = "#0E7BC9"
+SKY_300 = "#85C4E4"
+SKY_200 = "#98E2FD"
+GRAY_200 = "#CCDEE4"
+GRAY_50 = "#E9F0F8"
+
+theme = Theme(
+    {
+        "brand": PULSE_500,
+        "accent": SKY_200,
+        "muted": SKY_300,
+        "body": GRAY_200,
+        "heading": f"bold {GRAY_50}",
+        "ok": "green",
+        "err": "bold red",
+    }
+)
+
+console = Console(theme=theme)
+err_console = Console(theme=theme, stderr=True)
+
+
+def is_tty() -> bool:
+    return sys.stdout.isatty()
+
+
+def print_json(data: Any) -> None:
+    """Machine-readable output to stdout (plain, pipe-safe)."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def fail(message: str, code: int = 1) -> "SystemExit":
+    err_console.print(f"[err]error:[/err] {message}")
+    return SystemExit(code)
+
+
+def spinner_status(label: str):
+    """Brand-colored spinner context (TTY only callers should guard)."""
+    return console.status(f"[muted]{label}[/muted]", spinner="dots", spinner_style="brand")
+
+
+def derive_output_stem(source: str, output_dir: Optional[Path]) -> Path:
+    """`report.pdf` -> `report.pulse` (in output_dir or alongside the input).
+
+    URL sources land in output_dir (or cwd) named from the URL path.
+    """
+    if source.startswith(("http://", "https://")):
+        name = Path(urlparse(source).path).name or "document"
+        base = output_dir or Path.cwd()
+    else:
+        p = Path(source)
+        name = p.name
+        base = output_dir or p.parent
+    stem = name.rsplit(".", 1)[0] if "." in name else name
+    return base / f"{stem}.pulse"
+
+
+def write_result_files(result: dict, stem: Path, *, write_md: bool = True) -> list[Path]:
+    """Write `<stem>.json` always, plus `<stem>.md` when markdown is present."""
+    stem.parent.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+
+    json_path = stem.parent / f"{stem.name}.json"
+    json_path.write_text(json.dumps(result, indent=2, default=str))
+    written.append(json_path)
+
+    md = result.get("markdown") if isinstance(result, dict) else None
+    if write_md and isinstance(md, str) and md.strip():
+        md_path = stem.parent / f"{stem.name}.md"
+        md_path.write_text(md)
+        written.append(md_path)
+    return written

pulse_cli/repl.py

@@ -0,0 +1,149 @@
+"""`pulse` (bare) — interactive shell, Claude Code style.
+
+A branded banner (one animated heartbeat sweep), then a persistent prompt.
+Every CLI command works inside it (`extract a.pdf`, `jobs get <id>`, ...);
+plain `input()` + readline keeps arrow keys/history working everywhere.
+"""
+from __future__ import annotations
+
+import shlex
+import time
+
+try:  # typer >= 0.16 vendors click; commands raise the *vendored* exceptions
+    from typer import _click as click  # type: ignore
+except ImportError:  # older typer depends on the real click package
+    import click  # type: ignore
+
+from pulse_cli import __version__
+from pulse_cli import config as cfg
+from pulse_cli.errors import PulseCliError
+from pulse_cli.output import console, err_console
+from pulse_cli.tui.logo import render_logo
+
+_EXIT_WORDS = {"exit", "quit", "q"}
+_HISTORY_PATH = cfg.CONFIG_DIR / "history"
+
+# \001/\002 mark zero-width sequences so readline computes the prompt width right.
+_PROMPT = "\001\x1b[1;38;2;14;123;201m\002pulse ›\001\x1b[0m\002 "
+
+
+def _banner_frame(frame: int, conf: cfg.Config):
+    from rich.table import Table
+    from rich.text import Text
+
+    if conf.api_key:
+        account = (
+            f"[#85C4E4]key[/]     [#E9F0F8]{cfg.redact(conf.api_key)}[/]  [#85C4E4]({conf.key_source})[/]\n"
+            f"[#85C4E4]engine[/]  [#E9F0F8]{conf.api_url}[/]"
+        )
+    else:
+        account = "[#85C4E4]not logged in — run:[/] [#E9F0F8]login --api-key <key>[/]"
+
+    info = Text.from_markup(
+        "\n\n\n"
+        "[bold #E9F0F8]P U L S E[/]\n"
+        f"[#85C4E4]document extraction · cli v{__version__}[/]\n"
+        "\n"
+        f"{account}\n"
+        "\n"
+        "[#0E7BC9]try[/]  [#CCDEE4]extract report.pdf --schema s.json · tables <id> · usage[/]\n"
+        "[#0E7BC9]    [/]  [#CCDEE4]'help' for commands · 'exit' to leave[/]"
+    )
+    grid = Table.grid(padding=(0, 5))
+    grid.add_column()
+    grid.add_column()
+    grid.add_row(render_logo(frame), info)
+    return grid
+
+
+def _print_banner(conf: cfg.Config) -> None:
+    from rich.live import Live
+
+    try:
+        with Live(_banner_frame(0, conf), console=console, refresh_per_second=12, transient=False) as live:
+            for frame in range(1, 27):  # one full heartbeat sweep, ~2s
+                time.sleep(1 / 12)
+                live.update(_banner_frame(frame, conf))
+    except KeyboardInterrupt:
+        pass
+    console.print()
+
+
+def _setup_history() -> None:
+    try:
+        import atexit
+        import readline
+
+        try:
+            readline.read_history_file(_HISTORY_PATH)
+        except (FileNotFoundError, OSError):
+            pass
+        readline.set_history_length(500)
+
+        def _save() -> None:
+            try:
+                cfg.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+                readline.write_history_file(_HISTORY_PATH)
+            except OSError:
+                pass
+
+        atexit.register(_save)
+    except ImportError:
+        pass
+
+
+def _dispatch(command, line: str) -> None:
+    try:
+        args = shlex.split(line)
+    except ValueError as exc:
+        err_console.print(f"[err]parse error:[/err] {exc}")
+        return
+    if args and args[0] == "pulse":  # tolerate pasting full commands
+        args = args[1:]
+    if not args:
+        return
+    if args[0].lower() in _EXIT_WORDS:
+        raise EOFError
+    if args[0].lower() in {"help", "?"}:
+        args = ["--help"]
+
+    try:
+        command.main(args, prog_name="pulse", standalone_mode=False)
+    except click.exceptions.Exit:
+        pass
+    except click.exceptions.UsageError as exc:
+        err_console.print(f"[err]error:[/err] {exc.format_message()}")
+        err_console.print("[muted]type 'help' to see available commands[/muted]")
+    except click.exceptions.ClickException as exc:
+        err_console.print(f"[err]error:[/err] {exc.format_message()}")
+    except (click.exceptions.Abort, KeyboardInterrupt):
+        console.print()
+    except PulseCliError as exc:
+        err_console.print(f"[err]error:[/err] {exc}")
+    except SystemExit:
+        pass  # e.g. Ctrl-C during polling prints its own resume hint
+
+
+def run_repl() -> None:
+    from typer.main import get_command
+
+    from pulse_cli.app import cli
+
+    command = get_command(cli)
+    _setup_history()
+    _print_banner(cfg.load())
+
+    while True:
+        try:
+            line = input(_PROMPT)
+        except KeyboardInterrupt:
+            console.print("[muted]  (ctrl-d or 'exit' to leave)[/muted]")
+            continue
+        except EOFError:
+            console.print()
+            break
+        try:
+            _dispatch(command, line)
+        except EOFError:
+            break
+    console.print("[muted]bye.[/muted]")

pulse_cli/runtime.py

@@ -0,0 +1,61 @@
+"""Shared command runtime: config resolution, client construction, submit+poll."""
+from __future__ import annotations
+
+from typing import Optional
+
+from pulse_cli import config as cfg
+from pulse_cli.client import PulseClient
+from pulse_cli.errors import MissingApiKeyError
+from pulse_cli.output import console, is_tty, spinner_status
+from pulse_cli.status import is_terminal
+
+
+def get_client(api_key: Optional[str] = None, base_url: Optional[str] = None) -> PulseClient:
+    conf = cfg.load(api_key_override=api_key, api_url_override=base_url)
+    if not conf.api_key:
+        raise MissingApiKeyError()
+    return PulseClient(conf.api_key, conf.api_url)
+
+
+def submit_and_poll(client: PulseClient, submit_result: dict, *, label: str, no_wait: bool = False) -> dict:
+    """CLI analogue of mcp_server.tools._common.submit_and_poll.
+
+    Engine-ran-sync results (no job_id) pass through. Otherwise poll to a
+    terminal state with a spinner — or return the submit stub when --no-wait.
+    """
+    # /tables names its pollable id tables_id ("Poll GET /job/{tables_id}").
+    job_id = submit_result.get("job_id") or submit_result.get("tables_id")
+    if not job_id or no_wait or is_terminal(submit_result.get("status")):
+        return submit_result
+
+    if is_tty():
+        with spinner_status(f"{label} · job {job_id} · submitted") as status:
+            def on_progress(s: str, _n: int, _job: dict) -> None:
+                status.update(f"[muted]{label} · job {job_id} · {s or 'processing'}[/muted]")
+
+            try:
+                return client.wait_for_job(job_id, on_progress=on_progress)
+            except KeyboardInterrupt:
+                console.print(
+                    f"\n[muted]Still running server-side. Resume with:[/muted] "
+                    f"[brand]pulse jobs get {job_id} --watch[/brand]"
+                )
+                raise SystemExit(130)
+    # non-TTY: quiet poll
+    try:
+        return client.wait_for_job(job_id)
+    except KeyboardInterrupt:
+        print(f"interrupted; job still running: {job_id}")
+        raise SystemExit(130)
+
+
+def resolve_offloaded_result(client: PulseClient, job: dict) -> dict:
+    """If the terminal result is an {is_url, url} stub, download and inline it."""
+    result = job.get("result")
+    if isinstance(result, dict) and result.get("is_url") and result.get("url"):
+        fetched = client.fetch_url(result["url"])
+        if isinstance(fetched, dict):
+            job = {**job, "result": fetched}
+        else:
+            job = {**job, "result": {"raw": fetched}}
+    return job

pulse_cli/status.py

@@ -0,0 +1,10 @@
+"""Job-status values, mirrored from the engine (and mcp_server/status.py)."""
+from __future__ import annotations
+
+TERMINAL_STATUSES: frozenset[str] = frozenset({"completed", "failed", "canceled", "expired"})
+
+
+def is_terminal(status: str | None) -> bool:
+    if not status:
+        return False
+    return status.strip().lower() in TERMINAL_STATUSES