pulse-ai-cli 0.1.0__tar.gz

pulse_ai_cli-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+*.egg-info/
+dist/

pulse_ai_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,23 @@
+# 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/docs.md

@@ -0,0 +1,201 @@
+# Pulse CLI
+
+Extract documents, apply schemas, split, and pull tables from your terminal.
+The CLI talks to the same Pulse API as the platform and MCP server — your API
+key is the only credential.
+
+```
+pulse extract invoice.pdf --schema schemas/invoice.json
+```
+
+## Install
+
+```
+uv tool install pulse-ai-cli
+```
+
+(or `pip install pulse-ai-cli`). Installs the `pulse` command. Requires
+Python 3.11+.
+
+## Authentication
+
+```
+pulse login
+```
+
+Opens the Pulse platform in your browser; you approve a short code (e.g.
+`ABCD-1234`) while signed in, and the CLI picks up your organization's API
+key automatically (OAuth 2.1 device flow, RFC 8628). The key is validated
+and stored in your OS keychain (or `~/.pulse/config.toml`, chmod 0600, if no
+keychain is available).
+
+No browser handy? `pulse login --api-key <key>` (or `pulse login --no-web`
+to be prompted) logs in with an API key directly — find yours in the Pulse
+platform under API Keys.
+
+Alternatives, in priority order:
+
+1. `--api-key <key>` on any command
+2. `PULSE_API_KEY` environment variable (recommended for CI)
+3. stored credential from `pulse login`
+
+Related commands:
+
+| command | what it does |
+|---|---|
+| `pulse whoami` | show the active (redacted) key, engine URL, and connectivity |
+| `pulse logout` | remove the stored key |
+
+`pulse login --base-url <url>` points the CLI at a different engine
+(e.g. a VPC deployment). `--platform-url <url>` overrides the platform
+(default `https://platform.runpulse.com`) used for browser login and
+`pulse usage`.
+
+## Commands
+
+### `pulse extract <file|dir|url>…`
+
+Convert documents to markdown + structured JSON. Accepts any mix of file
+paths, directories (recursed for supported types), and URLs.
+
+Writes `<name>.pulse.md` and `<name>.pulse.json` next to each input
+(`-o <dir>` redirects; URL inputs land in the current directory).
+
+| flag | description |
+|---|---|
+| `--schema <file or inline JSON>` | pipeline: extract, then apply this JSON Schema — structured output is written to `<name>.pulse.schema.json` |
+| `--pages "1-2,5"` | page range (1-indexed) |
+| `--model <name>` | model override (`default`, `pulse-ultra-2`) |
+| `--html` | also return an HTML rendition |
+| `--footnotes` | link footnote markers to their text |
+| `--figure-descriptions` | caption figures and visuals |
+| `--show-images` | return image URLs for visuals |
+| `--chunking semantic,page` | chunk types: `semantic`, `header`, `page`, `recursive` |
+| `--chunk-size <n>` | max characters per chunk |
+| `-o, --output <dir>` | directory for result files |
+| `--no-wait` | submit and print the `job_id` without polling |
+| `--json` | print the full JSON result to stdout, write no files |
+
+Examples:
+
+```
+pulse extract report.pdf
+pulse extract invoice.pdf --schema '{"type":"object","properties":{"total":{"type":"number"}}}'
+pulse extract ./contracts -o ./results --no-wait
+pulse extract https://example.com/10k.pdf --pages "1-15" --chunking semantic
+```
+
+Files up to 50 MB are uploaded directly; larger documents should be passed
+by URL.
+
+### `pulse schema`
+
+Structured extraction against a *previous* extraction (use `extract --schema` to do
+both in one command).
+
+`pulse schema generate` — AI-draft a JSON Schema:
+
+```
+pulse schema generate -p "vendor name, line items, total due" -o invoice.json
+pulse schema generate --from invoice.json -p "also capture the PO number"
+```
+
+`pulse schema apply` — run a schema against extracted content:
+
+```
+pulse schema apply <extraction_id> --schema invoice.json
+```
+
+| flag | description |
+|---|---|
+| `--schema <file>` | JSON Schema file |
+| `-p, --prompt <text>` | extra extraction guidance (works with or without `--schema`) |
+| `--extraction-ids a,b,c` | combine several extractions |
+| `--split-id <id>` | apply per-topic schemas to a split |
+| `--split-schema-config <file>` | per-topic schema mapping (with `--split-id`) |
+| `--schema-config-id <id>` | use a saved platform schema config |
+| `--effort` | higher-effort extraction |
+| `--pages "1-3"` | restrict to a page range |
+| `-o <file>` | write result JSON to a file (default: stdout) |
+
+### `pulse split <extraction_id>`
+
+Split a document into sections by topic:
+
+```
+pulse split <extraction_id> -t "introduction:opening section" -t "financials:tables and figures"
+```
+
+`-t "name:description"` is repeatable; `--topics-file <json>` and
+`--split-config-id <id>` are alternatives. Returns per-topic page ranges and
+content; the resulting `split_id` can feed `pulse schema apply --split-id`.
+
+### `pulse tables <extraction_id>`
+
+Extract tables from a prior extraction:
+
+```
+pulse tables <extraction_id> --format html
+```
+
+`--format html|json`, `--merge` (join tables spanning pages),
+`--charts-to-tables`, `-o <file>`.
+
+### `pulse jobs`
+
+Every long-running command runs async under the hood and polls for you.
+`--no-wait` (or Ctrl-C while polling — the job keeps running server-side)
+hands control back; resume any time:
+
+```
+pulse jobs get <job_id> --watch
+pulse jobs cancel <job_id>
+```
+
+### `pulse open`
+
+Jump from the terminal to the platform:
+
+```
+pulse open <extraction_id>
+pulse open
+```
+
+Opens the extraction (or the dashboard) at `platform.runpulse.com` in your
+browser.
+
+### `pulse usage`
+
+Plan and usage for the current billing period — pages used vs allowance, plus
+a breakdown (documents, pages, latency, by source):
+
+```
+pulse usage
+pulse usage --days 7
+pulse usage --json
+```
+
+Requires a platform URL (`pulse login --platform-url …` or
+`PULSE_PLATFORM_URL`).
+
+### `pulse dashboard`
+
+Full-screen status view (account, usage). Bare `pulse` in a terminal opens
+the interactive shell.
+
+## Output conventions
+
+- Human-readable progress goes to the terminal; `--json` switches any command
+  to raw, pipe-safe JSON on stdout.
+- File-writing commands echo every path they write, plus the `extraction_id`
+  you'll need for follow-up commands.
+- Exit codes: `0` success, `1` failure (any document in a batch failing),
+  `130` interrupted (job still running server-side).
+
+## Roadmap
+
+- `extract --split … --schema …` end-to-end pipeline (split a document, then apply
+  a schema per topic in one command).
+- Platform `/activate` approval page for `pulse login --web` (the API-side
+  device flow is live; approval UI is rolling out).
+- Full OAuth token auth for the MCP server (auth-code + PKCE, DCR).

pulse_ai_cli-0.1.0/pulse_cli/__init__.py

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

pulse_ai_cli-0.1.0/pulse_cli/__main__.py

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

pulse_ai_cli-0.1.0/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_ai_cli-0.1.0/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)