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

pulse_ai_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: pulse-ai-cli
+Version: 0.1.0
+Summary: Pulse CLI — document extraction from your terminal (runpulse.com)
+Project-URL: Homepage, https://runpulse.com
+Project-URL: Documentation, https://docs.runpulse.com
+License: Proprietary
+Keywords: cli,document-extraction,ocr,pdf,pulse
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click>=8
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=24; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# Pulse CLI
+
+Document extraction from your terminal — markdown, structured JSON schemas,
+splits, and tables, powered by the [Pulse](https://runpulse.com) API.
+
+```
+uv tool install pulse-ai-cli
+pulse login
+pulse extract invoice.pdf --schema schemas/invoice.json
+```
+
+- `pulse extract` — documents (PDF, Office, images, URLs) → markdown + JSON;
+  add `--schema` to pull structured fields in the same run
+- `pulse schema generate / apply` — AI-draft a JSON Schema, run it against
+  any extraction
+- `pulse split` / `pulse tables` — topic-based splitting, table extraction
+- `pulse jobs` — watch, resume, or cancel async jobs
+- `pulse usage` — plan and page/credit usage
+- bare `pulse` — interactive shell with the full command set
+
+Every command supports `--json` for pipe-safe output and `-h` for full
+options. See the [docs](https://docs.runpulse.com) for the complete
+reference.

pulse_ai_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+pulse_cli/__init__.py,sha256=rKvOFqvHdAA7qtswaBle803jzPxzQLbHcBgCq4-opBs,40
+pulse_cli/__main__.py,sha256=IGhIa-Q2mk1JcfJVNOJWh5nYpkKtz0hQzU1OWjnPsG0,68
+pulse_cli/app.py,sha256=jG3NDp-gJCeR-Ft261bE38IcI9X54xSf8lQsL_F67oM,3316
+pulse_cli/client.py,sha256=cmtiSxPrNzUVFuULnzg8mieA5d168PgAmYFauwbDSTc,7740
+pulse_cli/config.py,sha256=faeXOf5J-H1lbI13aEiCuPTcv1XYaow68O4qJazdwp0,4660
+pulse_cli/errors.py,sha256=qIpj8tBcQbzNAHR7wIXd8Ful25bqaGF2SV71YP-ZK0s,3518
+pulse_cli/oauth.py,sha256=eLc5GsPoVQLG5-TGanoW73wPLTI3CkHvrJtJczwDSQM,3812
+pulse_cli/output.py,sha256=Dk_HNpU0_tXMDM7BL0VPRDYtVDLStisIwilxko8skYg,2544
+pulse_cli/repl.py,sha256=wcjwy3MuKxTQz9PU3ZsvZmYsPwLhv0Qb_5MAyNBk_sA,4694
+pulse_cli/runtime.py,sha256=ZxBPJ40NjCE2nlW-qDVwMOodJ3A2JcZXxNQneU3YrLY,2558
+pulse_cli/status.py,sha256=yja6sIGhJV2TleHWjQd69t-y3Pbp3t0N_jz1qZwk_NQ,350
+pulse_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pulse_cli/commands/auth.py,sha256=YkDP7h7jYocJ2HVXnBeIT_HKSdpFMvIvJmoS8b_UMZQ,4393
+pulse_cli/commands/extract.py,sha256=SAJRL1kUMPlZLosEKkXgE0yPzc6Ug_6E_VfbRjSC3XI,8738
+pulse_cli/commands/jobs.py,sha256=J7LnUD7XK9DOnRtetHPkqyijxu2JXe-rRflZPBw-iT0,2147
+pulse_cli/commands/open_platform.py,sha256=FHn9KSnxrkhERkP81XY7VkR6jLe1wrilcLtgfv0JHA0,848
+pulse_cli/commands/schema.py,sha256=pRMCu1WLBc9WlGNk8sfnYy_blbt_f_exW_dk39rbm94,5701
+pulse_cli/commands/split.py,sha256=bDnNi6nRjub2v7n9LyhPLd3xwWgmo4s6jbFRPVGSXck,2654
+pulse_cli/commands/tables.py,sha256=YrWkcQyZe-YKi2_QRTsxgVQFqCfGlrIAy8ge9skSY0g,2241
+pulse_cli/commands/usage.py,sha256=p6GscHrLAp7z6-5b2TvTdsFLLx2dkjbm2B9KIqywdws,4440
+pulse_cli/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pulse_cli/tui/dashboard.py,sha256=hpV03wuyQUbdLdTbWrLN9me3yaiSCHxF2HWKt8yav_0,6312
+pulse_cli/tui/logo.py,sha256=E2h_tck3XuorGxAs2i4QMk42oq60V9-fJoTQy7ffVGA,2831
+pulse_ai_cli-0.1.0.dist-info/METADATA,sha256=bR0b2eLDyKx5wdX_MT9G8usBKiPA6znTUyRRITcqoM0,1800
+pulse_ai_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pulse_ai_cli-0.1.0.dist-info/entry_points.txt,sha256=2a29WIj6AS4LDvD9vHvmfQK-QSFBzGpjisDTJDP3sTw,44
+pulse_ai_cli-0.1.0.dist-info/RECORD,,

pulse_ai_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pulse_ai_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pulse = pulse_cli.app:app

pulse_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Pulse CLI."""
+
+__version__ = "0.1.0"

pulse_cli/__main__.py

@@ -0,0 +1,4 @@
+from pulse_cli.app import app
+
+if __name__ == "__main__":
+    app()

pulse_cli/app.py

@@ -0,0 +1,103 @@
+"""Pulse CLI root app."""
+from __future__ import annotations
+
+import typer
+
+from pulse_cli import __version__
+from pulse_cli.commands.auth import login, logout, whoami
+from pulse_cli.commands.extract import extract
+from pulse_cli.commands.jobs import jobs_app
+from pulse_cli.commands.open_platform import open_platform
+from pulse_cli.commands.schema import schema_app
+from pulse_cli.commands.split import split
+from pulse_cli.commands.tables import tables
+from pulse_cli.commands.usage import usage
+from pulse_cli.errors import PulseCliError
+from pulse_cli.output import err_console
+
+# typer joins epilog paragraphs (separated by blank lines) with single
+# newlines, so each example below renders on its own line.
+_EXAMPLES = [
+    ("pulse extract report.pdf", "document -> report.pulse.md / .json"),
+    ("pulse extract invoice.pdf --schema schema.json", "extract + structured fields in one go"),
+    ("pulse extract ./docs --no-wait", "submit a folder, fetch results later"),
+    ('pulse schema generate -p "vendor, total, date"', "AI-draft a JSON schema"),
+    ("pulse schema apply <extraction_id> --schema s.json", "structured fields from a past extract"),
+    ('pulse split <extraction_id> -t "intro:first part"', "split a document by topic"),
+    ("pulse tables <extraction_id>", "pull out tables"),
+    ("pulse jobs get <job_id> --watch", "watch or resume an async job"),
+    ("pulse open <extraction_id>", "view an extraction on the platform"),
+    ("pulse usage", "plan + credit/page usage"),
+]
+
+_EPILOG = "\n\n".join(
+    ["[bold]Examples[/bold]"]
+    + [f"[cyan]{cmd:<52}[/cyan] [dim]{desc}[/dim]" for cmd, desc in _EXAMPLES]
+    + [
+        "",
+        "Add [cyan]--json[/cyan] to any command for raw output, [cyan]-o[/cyan] to choose "
+        "where files go, and [cyan]-h[/cyan] after any command for its full options.",
+    ]
+)
+
+cli = typer.Typer(
+    name="pulse",
+    help="Pulse — document extraction from your terminal (runpulse.com).",
+    epilog=_EPILOG,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@cli.callback(invoke_without_command=True)
+def _root(ctx: typer.Context) -> None:
+    """Bare `pulse` in a terminal opens the interactive shell; otherwise show help."""
+    if ctx.invoked_subcommand is None:
+        import sys
+
+        if sys.stdin.isatty() and sys.stdout.isatty():
+            from pulse_cli.repl import run_repl
+
+            run_repl()
+        else:
+            print(ctx.get_help())
+        raise typer.Exit()
+
+
+@cli.command()
+def dashboard() -> None:
+    """Open the Pulse dashboard (account + usage)."""
+    from pulse_cli.tui.dashboard import run_dashboard
+
+    run_dashboard()
+
+
+cli.command()(login)
+cli.command()(logout)
+cli.command()(whoami)
+cli.command()(extract)
+cli.command()(split)
+cli.command()(tables)
+cli.command()(usage)
+cli.command("open")(open_platform)
+cli.add_typer(schema_app, name="schema")
+cli.add_typer(jobs_app, name="jobs")
+
+
+@cli.command()
+def version() -> None:
+    """Print the CLI version."""
+    print(f"pulse-cli {__version__}")
+
+
+def app() -> None:
+    """Console-script entry point with clean error rendering."""
+    try:
+        cli()
+    except PulseCliError as exc:
+        err_console.print(f"[err]error:[/err] {exc}")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    app()

pulse_cli/client.py

@@ -0,0 +1,197 @@
+"""Sync HTTP client for the Pulse engine — a CLI port of mcp_server/pulse_client.py.
+
+Same endpoints, same payload shapes, same submit -> poll semantics, so the CLI
+and MCP gateway behave identically against the engine. Auth is the caller's API
+key forwarded verbatim as ``x-api-key``; the engine enforces auth/credits/limits.
+"""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Callable, Optional
+
+import httpx
+
+from pulse_cli import __version__
+from pulse_cli.errors import PulseEngineError
+from pulse_cli.status import is_terminal
+
+MAX_UPLOAD_BYTES = 50 * 1024 * 1024  # engine upload cap
+
+DEFAULT_TIMEOUT = 120.0
+SCHEMA_HELPER_TIMEOUT = 240.0  # /ai-schema-helper is sync and can run long
+POLL_INTERVAL_SECONDS = 2.0
+
+# (status, poll_count, job_dict) -> None
+ProgressCallback = Callable[[str, int, dict], None]
+
+
+def _form_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (dict, list)):
+        return json.dumps(v)
+    return str(v)
+
+
+class PulseClient:
+    def __init__(self, api_key: str, base_url: str, *, transport: Optional[httpx.BaseTransport] = None) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=DEFAULT_TIMEOUT,
+            headers={"x-api-key": api_key, "user-agent": f"pulse-cli/{__version__}"},
+            transport=transport,
+        )
+
+    def __enter__(self) -> "PulseClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self._client.close()
+
+    # --- core -----------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            resp = self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise PulseEngineError(504, engine_message="The Pulse engine took too long to respond.") from exc
+        except httpx.RequestError as exc:
+            raise PulseEngineError(
+                502, engine_message=f"Could not reach the Pulse engine at {self._client.base_url}."
+            ) from exc
+
+        if resp.is_success:
+            if "application/json" in resp.headers.get("content-type", ""):
+                return resp.json()
+            return resp.text
+        try:
+            body: Any = resp.json()
+        except Exception:
+            body = resp.text
+        raise PulseEngineError.from_response(resp.status_code, body)
+
+    # --- endpoints (parity with mcp_server) ------------------------------------
+
+    def get_job(self, job_id: str) -> dict:
+        return self._request("GET", f"/job/{job_id}")
+
+    def cancel_job(self, job_id: str) -> dict:
+        return self._request("POST", f"/cancel/{job_id}")
+
+    def submit_extract(self, payload: dict) -> dict:
+        """POST /extract (JSON) — for file_url inputs; set async=True for a job_id."""
+        return self._request("POST", "/extract", json=payload)
+
+    def submit_extract_multipart(self, file: tuple, options: dict) -> dict:
+        """POST /extract (multipart) — local file bytes + form options."""
+        data = {k: _form_value(v) for k, v in options.items() if v is not None}
+        return self._request("POST", "/extract", data=data, files={"file": file})
+
+    def apply_schema(self, payload: dict) -> dict:
+        return self._request("POST", "/schema", json=payload)
+
+    def split(self, payload: dict) -> dict:
+        return self._request("POST", "/split", json=payload)
+
+    def tables(self, payload: dict) -> dict:
+        return self._request("POST", "/tables", json=payload)
+
+    def generate_schema(self, *, prompt: Optional[str] = None, current_schema: Optional[str] = None) -> dict:
+        data: dict[str, str] = {}
+        if prompt is not None:
+            data["prompt"] = prompt
+        if current_schema is not None:
+            data["current_schema"] = current_schema
+        return self._request("POST", "/ai-schema-helper", data=data, timeout=SCHEMA_HELPER_TIMEOUT)
+
+    def pages(self) -> dict:
+        """GET /pages — total pages processed (api-key safe; also used to validate keys)."""
+        return self._request("GET", "/pages")
+
+    # --- polling ----------------------------------------------------------------
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = POLL_INTERVAL_SECONDS,
+        on_progress: Optional[ProgressCallback] = None,
+    ) -> dict:
+        """Poll GET /job/{job_id} until terminal. The CLI polls indefinitely
+        (unlike MCP's inline budget) — Ctrl-C leaves the job running server-side."""
+        polls = 0
+        job = self.get_job(job_id)
+        while not is_terminal(job.get("status")):
+            polls += 1
+            if on_progress is not None:
+                on_progress(job.get("status", ""), polls, job)
+            time.sleep(interval_seconds)
+            job = self.get_job(job_id)
+        return job
+
+    def fetch_url(self, url: str) -> Any:
+        """Download an offloaded {is_url, url} result (pre-signed S3)."""
+        resp = httpx.get(url, timeout=DEFAULT_TIMEOUT, follow_redirects=True)
+        if not resp.is_success:
+            raise PulseEngineError(resp.status_code, engine_message="Failed to download result from URL.")
+        if "application/json" in resp.headers.get("content-type", ""):
+            return resp.json()
+        try:
+            return json.loads(resp.text)
+        except json.JSONDecodeError:
+            return resp.text
+
+
+class PlatformClient:
+    """Minimal client for the FastAPI service (api-key-safe, read-only endpoints)."""
+
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=30.0,
+            headers={"x-api-key": api_key, "user-agent": f"pulse-cli/{__version__}"},
+        )
+
+    def __enter__(self) -> "PlatformClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self._client.close()
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        try:
+            resp = self._client.get(path, params=params)
+        except httpx.TimeoutException as exc:
+            raise PulseEngineError(504, engine_message="The Pulse platform took too long to respond.") from exc
+        except httpx.RequestError as exc:
+            raise PulseEngineError(
+                502, engine_message=f"Could not reach the Pulse platform at {self._client.base_url}."
+            ) from exc
+        if resp.is_success:
+            return resp.json()
+        try:
+            body: Any = resp.json()
+        except Exception:
+            body = resp.text
+        raise PulseEngineError.from_response(resp.status_code, body)
+
+    def subscription(self) -> Optional[dict]:
+        """GET /api/v1/billing/subscription — plan/status; None if unreachable."""
+        try:
+            return self._get("/api/v1/billing/subscription")
+        except PulseEngineError:
+            return None
+
+    def current_period_usage(self) -> dict:
+        """GET /api/v1/analytics/usage/current-period — plan + pages for the billing cycle."""
+        return self._get("/api/v1/analytics/usage/current-period")
+
+    def usage_breakdown(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> dict:
+        """GET /api/v1/analytics/usage/breakdown — docs/pages/latency, by source.
+
+        Without dates the platform defaults to the current billing period
+        (or lifetime for lifetime plans).
+        """
+        params = {k: v for k, v in (("start_date", start_date), ("end_date", end_date)) if v}
+        return self._get("/api/v1/analytics/usage/breakdown", params=params or None)

pulse_cli/commands/auth.py

@@ -0,0 +1,114 @@
+"""`pulse login` / `pulse logout` / `pulse whoami`."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from pulse_cli import config as cfg
+from pulse_cli.client import PlatformClient, PulseClient
+from pulse_cli.errors import PulseCliError
+from pulse_cli.output import console, fail, print_json
+
+
+def login(
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="Skip the browser and log in with an API key directly."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="Engine URL override (default: api.runpulse.com)."),
+    platform_url: Optional[str] = typer.Option(None, "--platform-url", help="Platform API URL (enables `pulse usage`)."),
+    web: bool = typer.Option(True, "--web/--no-web", help="Browser login (default). --no-web prompts for an API key instead."),
+) -> None:
+    """Log in via the browser (default) or with an API key; the key is validated, then stored securely."""
+    if api_key:
+        key = api_key
+    elif web:
+        key = _device_flow_login(platform_url)
+    else:
+        key = typer.prompt("Pulse API key", hide_input=True)
+    key = key.strip()
+    if not key:
+        raise fail("empty API key")
+
+    conf = cfg.load(api_url_override=base_url)
+    console.print(f"[muted]Validating key against {conf.api_url} …[/muted]")
+    try:
+        with PulseClient(key, conf.api_url) as client:
+            pages = client.pages()
+    except PulseCliError as exc:
+        raise fail(str(exc))
+
+    store = cfg.save_api_key(key)
+    if base_url or platform_url:
+        cfg.save_settings(api_url=base_url, platform_url=platform_url)
+
+    where = "OS keychain" if store == "keyring" else f"{cfg.CONFIG_PATH} (0600)"
+    console.print(f"[ok]Logged in.[/ok] Key {cfg.redact(key)} stored in {where}.")
+    console.print(f"[muted]Pages processed so far:[/muted] {pages.get('total_pages_processed', 0)}")
+
+
+def _device_flow_login(platform_url_flag: Optional[str]) -> str:
+    """Browser-based device flow: approve in the platform, get the org API key back."""
+    import webbrowser
+
+    from pulse_cli import oauth
+
+    conf = cfg.load()
+    purl = platform_url_flag or conf.platform_url
+
+    try:
+        auth = oauth.device_authorization(purl)
+        console.print(f"\n  Your code: [bold]{auth['user_code']}[/bold]")
+        console.print(f"  Approve at: [link]{auth['verification_uri_complete']}[/link]\n")
+        webbrowser.open(auth["verification_uri_complete"])
+        with console.status("[muted]Waiting for approval in the browser …[/muted]"):
+            tokens = oauth.poll_for_tokens(
+                purl,
+                auth["device_code"],
+                interval=int(auth.get("interval", 5)),
+                expires_in=int(auth.get("expires_in", 600)),
+            )
+        return oauth.fetch_api_key(purl, tokens["access_token"])
+    except PulseCliError as exc:
+        raise fail(str(exc))
+
+
+def logout() -> None:
+    """Remove the stored API key."""
+    if cfg.clear_api_key():
+        console.print("[ok]Logged out.[/ok] Stored API key removed.")
+    else:
+        console.print("[muted]No stored API key found.[/muted]")
+
+
+def whoami(
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="Engine URL override."),
+) -> None:
+    """Show the active key (redacted), where it came from, and account status."""
+    conf = cfg.load(api_url_override=base_url)
+    if not conf.api_key:
+        raise fail("not logged in. Run `pulse login`.")
+
+    info: dict = {
+        "api_key": cfg.redact(conf.api_key),
+        "key_source": conf.key_source,
+        "api_url": conf.api_url,
+    }
+    try:
+        with PulseClient(conf.api_key, conf.api_url) as client:
+            info["total_pages_processed"] = client.pages().get("total_pages_processed")
+    except PulseCliError as exc:
+        info["status"] = f"key check failed: {exc}"
+
+    if conf.platform_url:
+        with PlatformClient(conf.api_key, conf.platform_url) as pc:
+            sub = pc.subscription()
+        if sub:
+            info["plan"] = sub.get("plan") or sub.get("plan_name")
+            info["subscription_status"] = sub.get("status")
+
+    if json_out:
+        print_json(info)
+        return
+    for k, v in info.items():
+        if v is not None:
+            console.print(f"[muted]{k:24}[/muted] [body]{v}[/body]")