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

pulse_cli/commands/extract.py

@@ -0,0 +1,199 @@
+"""`pulse extract <file|url|dir> …` — document -> markdown (+ JSON result)."""
+from __future__ import annotations
+
+import json
+import mimetypes
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from pulse_cli.client import MAX_UPLOAD_BYTES
+from pulse_cli.errors import PulseCliError
+from pulse_cli.output import console, derive_output_stem, fail, print_json, write_result_files
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+
+SUPPORTED_EXTS = {
+    ".pdf", ".png", ".jpg", ".jpeg", ".tiff", ".webp",
+    ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".csv",
+    ".html", ".txt", ".md",
+}
+
+
+def _collect_sources(inputs: list[str]) -> list[str]:
+    """Expand directories (recursive) into supported files; keep URLs/files as-is."""
+    sources: list[str] = []
+    for item in inputs:
+        if item.startswith(("http://", "https://")):
+            sources.append(item)
+            continue
+        p = Path(item).expanduser()
+        if p.is_dir():
+            found = sorted(
+                str(f) for f in p.rglob("*")
+                if f.is_file() and f.suffix.lower() in SUPPORTED_EXTS
+            )
+            if not found:
+                console.print(f"[muted]no supported documents in {p}[/muted]")
+            sources.extend(found)
+        elif p.is_file():
+            sources.append(str(p))
+        else:
+            raise fail(f"not found: {item}")
+    return sources
+
+
+def _parse_schema_arg(value: str) -> dict:
+    """`--schema` accepts a JSON Schema file path or inline JSON."""
+    text = value.strip()
+    if text.startswith("{"):
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise fail(f"--schema inline JSON is invalid ({exc})")
+    p = Path(text).expanduser()
+    if not p.is_file():
+        raise fail(f"--schema file not found: {p}")
+    try:
+        return json.loads(p.read_text())
+    except json.JSONDecodeError as exc:
+        raise fail(f"--schema {p} is not valid JSON ({exc})")
+
+
+def _build_options(
+    pages: Optional[str],
+    model: Optional[str],
+    html: bool,
+    footnotes: bool,
+    figures: bool,
+    show_images: bool,
+    chunk_types: Optional[str],
+    chunk_size: Optional[int],
+) -> dict:
+    """Same payload shaping as the MCP extract tool (grouped extensions)."""
+    options: dict = {"async": True}
+    if pages:
+        options["pages"] = pages
+    if model:
+        options["model"] = model
+
+    extensions: dict = {}
+    if html:
+        extensions["alt_outputs"] = {"return_html": True}
+    if footnotes:
+        extensions["footnote_references"] = True
+    chunking: dict = {}
+    if chunk_types:
+        chunking["chunk_types"] = [c.strip() for c in chunk_types.split(",") if c.strip()]
+    if chunk_size:
+        chunking["chunk_size"] = chunk_size
+    if chunking:
+        extensions["chunking"] = chunking
+    if extensions:
+        options["extensions"] = extensions
+
+    figure_processing: dict = {}
+    if figures:
+        figure_processing["description"] = True
+    if show_images:
+        figure_processing["show_images"] = True
+    if figure_processing:
+        options["figure_processing"] = figure_processing
+    return options
+
+
+def extract(
+    inputs: list[str] = typer.Argument(..., help="File path(s), directory, or URL(s)."),
+    pages: Optional[str] = typer.Option(None, help='Page range, 1-indexed, e.g. "1-2,5".'),
+    model: Optional[str] = typer.Option(None, help='Model override: "default" or "pulse-ultra-2".'),
+    html: bool = typer.Option(False, "--html", help="Also return an HTML representation."),
+    footnotes: bool = typer.Option(False, "--footnotes", help="Link footnote markers to text."),
+    figures: bool = typer.Option(False, "--figure-descriptions", help="Caption figures/visuals."),
+    show_images: bool = typer.Option(False, "--show-images", help="Return image URLs for visuals."),
+    chunk_types: Optional[str] = typer.Option(None, "--chunking", help="Comma list: semantic,header,page,recursive."),
+    chunk_size: Optional[int] = typer.Option(None, help="Max characters per chunk."),
+    schema_arg: Optional[str] = typer.Option(
+        None, "--schema",
+        help="JSON Schema (file path or inline JSON). Pipelines: extract, then apply the schema for structured output.",
+    ),
+    output_dir: Optional[Path] = typer.Option(None, "--output", "-o", help="Directory for result files."),
+    no_wait: bool = typer.Option(False, "--no-wait", help="Submit and print job_id without polling."),
+    json_out: bool = typer.Option(False, "--json", help="Print full JSON to stdout; skip file writing."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY", help="Override stored key."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="Engine URL override."),
+) -> None:
+    """Extract markdown (and more) from documents. Writes <name>.pulse.md / .pulse.json."""
+    sources = _collect_sources(inputs)
+    if not sources:
+        raise fail("nothing to extract")
+
+    schema_obj = _parse_schema_arg(schema_arg) if schema_arg else None
+    if schema_obj and no_wait:
+        raise fail("--schema needs the extraction result; remove --no-wait")
+
+    options = _build_options(pages, model, html, footnotes, figures, show_images, chunk_types, chunk_size)
+    failures = 0
+
+    with get_client(api_key, base_url) as client:
+        for source in sources:
+            label = Path(source).name if not source.startswith("http") else source
+            try:
+                if source.startswith(("http://", "https://")):
+                    submit = client.submit_extract({"file_url": source, **options})
+                else:
+                    p = Path(source)
+                    size = p.stat().st_size
+                    if size > MAX_UPLOAD_BYTES:
+                        raise PulseCliError(f"{p.name} is {size / 1e6:.0f} MB — exceeds the 50 MB upload limit.")
+                    ctype = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
+                    submit = client.submit_extract_multipart((p.name, p.read_bytes(), ctype), options)
+
+                job = submit_and_poll(client, submit, label=f"extracting {label}", no_wait=no_wait)
+
+                if no_wait and job.get("job_id"):
+                    console.print(f"[body]{label}[/body] [muted]submitted →[/muted] [brand]{job['job_id']}[/brand]")
+                    continue
+                if job.get("status") == "failed":
+                    raise PulseCliError(job.get("error") or "extraction failed")
+
+                job = resolve_offloaded_result(client, job)
+                result = job.get("result") if isinstance(job.get("result"), dict) else job
+                eid = result.get("extraction_id") or job.get("extraction_id")
+
+                # Optional second pipeline stage: structured extraction (-s).
+                structured = None
+                if schema_obj is not None:
+                    if not eid:
+                        raise PulseCliError("engine returned no extraction_id; cannot apply schema")
+                    s_submit = client.apply_schema({
+                        "async": True,
+                        "extraction_id": eid,
+                        "schema_config": {"input_schema": schema_obj},
+                    })
+                    s_job = submit_and_poll(client, s_submit, label=f"applying schema {label}")
+                    if s_job.get("status") == "failed":
+                        raise PulseCliError(s_job.get("error") or "schema extraction failed")
+                    structured = resolve_offloaded_result(client, s_job)
+
+                if json_out:
+                    print_json({"extract": job, "schema": structured} if structured is not None else job)
+                else:
+                    stem = derive_output_stem(source, output_dir)
+                    written = write_result_files(result, stem)
+                    if structured is not None:
+                        s_path = stem.parent / f"{stem.name}.schema.json"
+                        s_path.write_text(json.dumps(
+                            structured.get("result") or structured, indent=2, default=str
+                        ))
+                        written.append(s_path)
+                    console.print(
+                        f"[ok]✓[/ok] [body]{label}[/body] [muted]→[/muted] "
+                        + ", ".join(str(w) for w in written)
+                        + (f"  [muted]extraction_id=[/muted][brand]{eid}[/brand]" if eid else "")
+                    )
+            except PulseCliError as exc:
+                failures += 1
+                console.print(f"[err]✗ {label}:[/err] {exc}")
+
+    if failures:
+        raise SystemExit(1)

pulse_cli/commands/jobs.py

@@ -0,0 +1,53 @@
+"""`pulse jobs <job_id>` — inspect / watch / cancel async jobs."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from pulse_cli.output import console, print_json
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+from pulse_cli.status import is_terminal
+
+jobs_app = typer.Typer(help="Inspect, watch, and cancel async jobs.")
+
+
+@jobs_app.command("get")
+def get(
+    job_id: str = typer.Argument(..., help="Job id returned by extract/schema/split/tables."),
+    watch: bool = typer.Option(False, "--watch", "-w", help="Poll until the job is terminal."),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """Show a job's status (and result when complete)."""
+    with get_client(api_key, base_url) as client:
+        job = client.get_job(job_id)
+        if watch and not is_terminal(job.get("status")):
+            job = submit_and_poll(client, {**job, "job_id": job_id}, label="job")
+        if is_terminal(job.get("status")):
+            job = resolve_offloaded_result(client, job)
+
+    if json_out:
+        print_json(job)
+        return
+    status = job.get("status", "unknown")
+    style = {"completed": "ok", "failed": "err", "canceled": "err", "expired": "err"}.get(status, "muted")
+    console.print(f"[muted]job[/muted] [brand]{job_id}[/brand] [muted]status =[/muted] [{style}]{status}[/{style}]")
+    print_json(job)
+
+
+@jobs_app.command("cancel")
+def cancel(
+    job_id: str = typer.Argument(...),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """Cancel a pending/processing job (POST /cancel/{job_id})."""
+    with get_client(api_key, base_url) as client:
+        resp = client.cancel_job(job_id)
+    if json_out:
+        print_json(resp)
+    else:
+        console.print(f"[ok]✓[/ok] cancel requested for [brand]{job_id}[/brand]")

pulse_cli/commands/open_platform.py

@@ -0,0 +1,25 @@
+"""`pulse open [extraction_id]` — jump to the Pulse platform in the browser."""
+from __future__ import annotations
+
+import webbrowser
+from typing import Optional
+
+import typer
+
+from pulse_cli.config import PLATFORM_WEB_URL
+from pulse_cli.output import console
+
+
+def open_platform(
+    extraction_id: Optional[str] = typer.Argument(
+        None, help="Extraction/job id to view (omit for the dashboard)."
+    ),
+) -> None:
+    """Open an extraction (or the dashboard) on platform.runpulse.com."""
+    if extraction_id:
+        url = f"{PLATFORM_WEB_URL}/dashboard/extractions/{extraction_id}"
+    else:
+        url = f"{PLATFORM_WEB_URL}/dashboard"
+    console.print(f"[muted]opening[/muted] [brand]{url}[/brand]")
+    if not webbrowser.open(url):
+        console.print("[muted]couldn't launch a browser — open the URL above manually[/muted]")

pulse_cli/commands/schema.py

@@ -0,0 +1,124 @@
+"""`pulse schema apply` / `pulse schema generate` — structured extraction tooling."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from pulse_cli.output import console, fail, print_json
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+
+schema_app = typer.Typer(help="JSON-schema structured extraction (apply / generate).")
+
+
+def _load_json_file(path: Path, what: str) -> dict:
+    try:
+        return json.loads(path.read_text())
+    except FileNotFoundError:
+        raise fail(f"{what} file not found: {path}")
+    except json.JSONDecodeError as exc:
+        raise fail(f"{what} is not valid JSON ({exc})")
+
+
+@schema_app.command("apply")
+def apply(
+    extraction_id: Optional[str] = typer.Argument(None, help="Extraction to apply the schema to."),
+    extraction_ids: Optional[str] = typer.Option(None, "--extraction-ids", help="Comma list to combine several extractions."),
+    split_id: Optional[str] = typer.Option(None, "--split-id", help="Apply per-topic schemas to a split."),
+    schema_file: Optional[Path] = typer.Option(None, "--schema", help="JSON Schema file."),
+    schema_prompt: Optional[str] = typer.Option(None, "--prompt", "-p", help="Extra extraction guidance."),
+    schema_config_id: Optional[str] = typer.Option(None, "--schema-config-id", help="Saved schema config id."),
+    split_schema_config_file: Optional[Path] = typer.Option(None, "--split-schema-config", help="JSON file: per-topic schema config (with --split-id)."),
+    effort: bool = typer.Option(False, "--effort", help="Higher-effort extraction."),
+    pages: Optional[str] = typer.Option(None, help='Page range, e.g. "1-3".'),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write result JSON to file."),
+    no_wait: bool = typer.Option(False, "--no-wait"),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """Apply a JSON schema to a prior extraction (or split) for structured output."""
+    # Mirrors mcp_server/tools/schema.py payload shaping exactly.
+    payload: dict = {"async": True}
+    if split_id:
+        payload["split_id"] = split_id
+        if split_schema_config_file:
+            payload["split_schema_config"] = _load_json_file(split_schema_config_file, "--split-schema-config")
+    else:
+        if extraction_ids:
+            payload["extraction_ids"] = [e.strip() for e in extraction_ids.split(",") if e.strip()]
+        elif extraction_id:
+            payload["extraction_id"] = extraction_id
+        else:
+            raise fail("provide an extraction_id, --extraction-ids, or --split-id")
+        if schema_config_id:
+            payload["schema_config_id"] = schema_config_id
+        else:
+            schema_config: dict = {}
+            if schema_file:
+                schema_config["input_schema"] = _load_json_file(schema_file, "--schema")
+            if schema_prompt:
+                schema_config["schema_prompt"] = schema_prompt
+            if effort:
+                schema_config["effort"] = True
+            if not schema_config:
+                raise fail("provide --schema, --prompt, or --schema-config-id")
+            payload["schema_config"] = schema_config
+        if pages:
+            payload["page_range"] = pages
+
+    with get_client(api_key, base_url) as client:
+        submit = client.apply_schema(payload)
+        job = submit_and_poll(client, submit, label="applying schema", no_wait=no_wait)
+        if no_wait and job.get("job_id"):
+            console.print(f"[muted]submitted →[/muted] [brand]{job['job_id']}[/brand]")
+            return
+        job = resolve_offloaded_result(client, job)
+
+    if output:
+        output.write_text(json.dumps(job, indent=2, default=str))
+        console.print(f"[ok]✓[/ok] wrote {output}")
+    elif json_out:
+        print_json(job)
+    else:
+        print_json(job.get("result") or job)
+
+
+@schema_app.command("generate")
+def generate(
+    prompt: Optional[str] = typer.Option(None, "--prompt", "-p", help="Describe the fields you want."),
+    from_schema: Optional[Path] = typer.Option(None, "--from", help="Existing schema JSON file to refine."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write schema to file."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """AI-generate or refine a JSON extraction schema (POST /ai-schema-helper)."""
+    if not prompt and not from_schema:
+        raise fail("provide --prompt and/or --from")
+
+    current = json.dumps(_load_json_file(from_schema, "--from")) if from_schema else None
+    with get_client(api_key, base_url) as client:
+        from pulse_cli.output import is_tty, spinner_status
+
+        if is_tty():
+            with spinner_status("generating schema"):
+                resp = client.generate_schema(prompt=prompt, current_schema=current)
+        else:
+            resp = client.generate_schema(prompt=prompt, current_schema=current)
+
+    # Engine returns the schema as a JSON string; parse for clean output.
+    raw = resp.get("schema") if isinstance(resp, dict) else None
+    if isinstance(raw, str):
+        try:
+            raw = json.loads(raw)
+        except json.JSONDecodeError:
+            pass
+    schema = raw if raw is not None else resp
+
+    if output:
+        output.write_text(json.dumps(schema, indent=2))
+        console.print(f"[ok]✓[/ok] wrote {output}")
+    else:
+        print_json(schema)

pulse_cli/commands/split.py

@@ -0,0 +1,63 @@
+"""`pulse split <extraction_id>` — partition an extraction into topic page-ranges."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from pulse_cli.output import console, fail, print_json
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+
+
+def split(
+    extraction_id: str = typer.Argument(..., help="ID of a completed extraction."),
+    topic: list[str] = typer.Option(
+        [], "--topic", "-t",
+        help='Repeatable. "name" or "name:description", e.g. -t "invoice:billing pages".',
+    ),
+    topics_file: Optional[Path] = typer.Option(None, "--topics-file", help="JSON file: [{name, description}, …]."),
+    split_config_id: Optional[str] = typer.Option(None, "--split-config-id", help="Saved split config id."),
+    no_wait: bool = typer.Option(False, "--no-wait"),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """Split a prior extraction into topics (run `pulse extract` first)."""
+    payload: dict = {"extraction_id": extraction_id, "async": True}
+    if split_config_id:
+        payload["split_config_id"] = split_config_id
+    elif topics_file:
+        try:
+            payload["split_config"] = {"split_input": json.loads(topics_file.read_text())}
+        except (OSError, json.JSONDecodeError) as exc:
+            raise fail(f"--topics-file: {exc}")
+    elif topic:
+        topics = []
+        for t in topic:
+            name, _, desc = t.partition(":")
+            entry: dict = {"name": name.strip()}
+            if desc.strip():
+                entry["description"] = desc.strip()
+            topics.append(entry)
+        payload["split_config"] = {"split_input": topics}
+    else:
+        raise fail("provide --topic (repeatable), --topics-file, or --split-config-id")
+
+    with get_client(api_key, base_url) as client:
+        submit = client.split(payload)
+        job = submit_and_poll(client, submit, label="splitting", no_wait=no_wait)
+        if no_wait and job.get("job_id"):
+            console.print(f"[muted]submitted →[/muted] [brand]{job['job_id']}[/brand]")
+            return
+        job = resolve_offloaded_result(client, job)
+
+    if json_out:
+        print_json(job)
+        return
+    result = job.get("result") if isinstance(job.get("result"), dict) else job
+    sid = result.get("split_id")
+    if sid:
+        console.print(f"[muted]split_id =[/muted] [brand]{sid}[/brand]")
+    print_json(result.get("split_output") or result)

pulse_cli/commands/tables.py

@@ -0,0 +1,52 @@
+"""`pulse tables <extraction_id>` — extract tables from a completed extraction."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from pulse_cli.output import console, print_json
+from pulse_cli.runtime import get_client, resolve_offloaded_result, submit_and_poll
+
+
+def tables(
+    extraction_id: str = typer.Argument(..., help="ID of a completed extraction."),
+    table_format: str = typer.Option("html", "--format", "-f", help='Table output format (e.g. "html", "json").'),
+    merge: bool = typer.Option(False, "--merge", help="Merge tables that span pages."),
+    charts: bool = typer.Option(False, "--charts-to-tables", help="Convert charts into tables too."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write result JSON to file."),
+    no_wait: bool = typer.Option(False, "--no-wait"),
+    json_out: bool = typer.Option(False, "--json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    base_url: Optional[str] = typer.Option(None, "--base-url"),
+) -> None:
+    """Extract tables (run `pulse extract` first to get an extraction_id)."""
+    # Format validation is left to the engine (valid set varies by deployment).
+    payload = {
+        "extraction_id": extraction_id,
+        "async": True,
+        "tables_config": {
+            "merge": merge,
+            "table_format": table_format,
+            "charts_to_tables": charts,
+        },
+    }
+    with get_client(api_key, base_url) as client:
+        submit = client.tables(payload)
+        job = submit_and_poll(client, submit, label="extracting tables", no_wait=no_wait)
+        jid = job.get("job_id") or job.get("tables_id")
+        if no_wait and jid:
+            console.print(f"[muted]submitted →[/muted] [brand]{jid}[/brand]")
+            return
+        job = resolve_offloaded_result(client, job)
+
+    result = job.get("result") if isinstance(job.get("result"), dict) else job
+    if output:
+        output.write_text(json.dumps(result, indent=2, default=str))
+        console.print(f"[ok]✓[/ok] wrote {output}")
+    elif json_out:
+        print_json(job)
+    else:
+        print_json(result.get("tables_output") or result)

pulse_cli/commands/usage.py

@@ -0,0 +1,109 @@
+"""`pulse usage` — credit/page usage for the current billing period."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import typer
+
+from pulse_cli import config as cfg
+from pulse_cli.client import PlatformClient
+from pulse_cli.errors import MissingApiKeyError
+from pulse_cli.output import console, fail, is_tty, print_json, spinner_status
+
+
+def _fmt_int(v: object) -> str:
+    return f"{v:,}" if isinstance(v, (int, float)) else "—"
+
+
+# Bookkeeping rows in by_source that aren't actual document work.
+_NOISE_SOURCES = {"get_job", "delete_job", "large_result_download"}
+
+
+def usage(
+    days: Optional[int] = typer.Option(
+        None, "--days", help="Breakdown window in days (default: current billing period)."
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="PULSE_API_KEY"),
+    platform_url: Optional[str] = typer.Option(
+        None, "--platform-url", envvar="PULSE_PLATFORM_URL", help="Platform API URL override."
+    ),
+) -> None:
+    """Show plan, pages used vs allowance, and a usage breakdown by source."""
+    conf = cfg.load(api_key_override=api_key)
+    if not conf.api_key:
+        raise MissingApiKeyError()
+    url = platform_url or conf.platform_url
+    if not url:
+        raise fail(
+            "No platform URL configured. Re-run login with it, e.g.\n"
+            "  pulse login --platform-url https://platform.runpulse.com"
+        )
+
+    start = end = None
+    if days:
+        now = datetime.now(timezone.utc)
+        start, end = (now - timedelta(days=days)).strftime("%Y-%m-%d"), now.strftime("%Y-%m-%d")
+
+    with PlatformClient(conf.api_key, url) as pc:
+        if is_tty() and not json_out:
+            with spinner_status("fetching usage"):
+                period = pc.current_period_usage()
+                breakdown = pc.usage_breakdown(start, end)
+        else:
+            period = pc.current_period_usage()
+            breakdown = pc.usage_breakdown(start, end)
+
+    if json_out:
+        print_json({"current_period": period, "breakdown": breakdown})
+        return
+
+    plan = period.get("plan_name") or "—"
+    label = period.get("period_label") or period.get("period_type") or ""
+    used = period.get("pages_used")
+    allowance = period.get("page_allowance")
+    pct = period.get("usage_percentage")
+
+    console.print(f"\n[heading]plan[/heading]      [body]{plan}[/body]  [muted]{label}[/muted]")
+    if period.get("is_metered"):
+        rate = period.get("metered_rate")
+        console.print(
+            f"[heading]pages[/heading]     [body]{_fmt_int(used)}[/body] "
+            f"[muted]metered{f' @ ${rate}/page' if rate else ''}[/muted]"
+        )
+    elif period.get("is_unlimited") or allowance is None:
+        console.print(f"[heading]pages[/heading]     [body]{_fmt_int(used)}[/body] [muted]/ unlimited[/muted]")
+    else:
+        remaining = period.get("pages_remaining")
+        console.print(
+            f"[heading]pages[/heading]     [body]{_fmt_int(used)}[/body] [muted]/[/muted] "
+            f"[body]{_fmt_int(allowance)}[/body]"
+            + (f"  [muted]({pct:.1f}% used, {_fmt_int(remaining)} left)[/muted]" if pct is not None else "")
+        )
+
+    by_source = {
+        k: v for k, v in (breakdown.get("by_source") or {}).items() if k not in _NOISE_SOURCES
+    }
+    # Recompute totals from real work only (server totals include polling noise).
+    if by_source:
+        docs = sum(v.get("documents") or 0 for v in by_source.values())
+        pgs = sum(v.get("pages") or 0 for v in by_source.values())
+    else:
+        docs, pgs = breakdown.get("total_documents"), breakdown.get("total_pages")
+
+    window = f"last {days} days" if days else "this period"
+    console.print(
+        f"\n[heading]activity[/heading]  [muted]{window}[/muted]  "
+        f"[body]{_fmt_int(docs)}[/body] [muted]requests ·[/muted] "
+        f"[body]{_fmt_int(pgs)}[/body] [muted]pages[/muted]"
+    )
+
+    if by_source:
+        console.print("\n[heading]by source[/heading]")
+        for src, row in sorted(by_source.items(), key=lambda kv: -(kv[1].get("pages") or 0)):
+            console.print(
+                f"  [body]{src:<14}[/body] [muted]{_fmt_int(row.get('documents'))} docs ·[/muted] "
+                f"[body]{_fmt_int(row.get('pages'))}[/body] [muted]pages[/muted]"
+            )
+    console.print()