vecshift 0.2.0__tar.gz → 0.3.0__tar.gz

{vecshift-0.2.0 → vecshift-0.3.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-10
+
+### Changed
+
+- A new look at the terminal, across every command: a gradient block wordmark, numbered
+  steps and arrow-key menus in `vecshift init` (with hidden input for secrets), a panel
+  with the migration's progress in `vecshift status`, a live progress bar in `apply`,
+  highlighted SQL in `plan`, tables in `eval` and `bench`, and consistent headers,
+  findings, verdicts, and next steps everywhere. Off a terminal, output stays plain and
+  prompts fall back to typed answers, as before.
+- New dependency: `questionary`, for the arrow-key menus.
+
 ## [0.2.0] - 2026-10-10
 
 ### Added
@@ -149,6 +161,7 @@ The first release.
 - `Capability` flags and plugin contracts for sources, targets, and embedding providers.
 - `vecshift fingerprint` and `vecshift --version` commands.
 
-[Unreleased]: https://github.com/Osamamu64/vecshift/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Osamamu64/vecshift/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Osamamu64/vecshift/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Osamamu64/vecshift/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Osamamu64/vecshift/releases/tag/v0.1.0

{vecshift-0.2.0 → vecshift-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vecshift
-Version: 0.2.0
+Version: 0.3.0
 Summary: Zero-downtime embedding model migrations for pgvector and Supabase: plan, re-embed, evaluate, and cut over safely.
 Project-URL: Homepage, https://github.com/Osamamu64/vecshift
 Project-URL: Repository, https://github.com/Osamamu64/vecshift
@@ -31,6 +31,8 @@ Requires-Dist: numpy>=1.26
 Requires-Dist: psycopg[binary]>=3.2
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyyaml>=6
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{vecshift-0.2.0 → vecshift-0.3.0}/pyproject.toml

@@ -32,6 +32,8 @@ dependencies = [
     "psycopg[binary]>=3.2",
     "pydantic>=2.6",
     "pyyaml>=6",
+    "questionary>=2.0",
+    "rich>=13",
     "typer>=0.12",
 ]
 

{vecshift-0.2.0 → vecshift-0.3.0}/src/vecshift/__init__.py

@@ -4,7 +4,7 @@ from vecshift.core.capabilities import Capability
 from vecshift.core.fingerprint import EmbeddingFingerprint
 from vecshift.core.record import Record, SparseVector
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Capability",

{vecshift-0.2.0 → vecshift-0.3.0}/src/vecshift/cli.py

@@ -11,7 +11,7 @@ import typer
 
 from vecshift import __version__
 from vecshift.cli_style import STYLE as _STYLE
-from vecshift.cli_style import banner, warn_if_password_on_command_line
+from vecshift.cli_style import warn_if_password_on_command_line
 from vecshift.cli_style import wrap as _wrap
 from vecshift.core.fingerprint import EmbeddingFingerprint
 from vecshift.doctor import Report, Severity, run_checks
@@ -80,7 +80,9 @@ def main(
     """Safe, observable embedding migrations for any vector store."""
     _load_env_file(None if no_env_file else env_file)
     if ctx.invoked_subcommand is None:
-        banner(__version__, TAGLINE)
+        from vecshift import ui
+
+        ui.banner(__version__, TAGLINE)
         typer.echo(ctx.get_help())
 
 
@@ -119,7 +121,39 @@ class FailOn(StrEnum):
     ERROR = "error"
 
 
+def _render_fancy(report: Report, connection: str) -> None:
+    from rich.text import Text
+
+    from vecshift import ui
+
+    dims = f"({report.declared_dimensions})" if report.declared_dimensions else ""
+    rows = f"~{report.estimated_rows:,}" if report.estimated_rows is not None else "unknown"
+    ui.title("doctor", f"{report.store} via {connection}")
+    ui.kv(
+        [
+            ("Target", Text.assemble(report.target, (f"  {report.vector_type}{dims}", "dim")), ""),
+            ("Rows", rows, f"inspected {report.sample_rows:,}, {report.sample_method}"),
+        ]
+    )
+    ui.section("Findings")
+    ui.findings(report.sorted_findings())
+    summary = Text("  ")
+    for severity, (_, _, name) in _STYLE.items():
+        n = report.count(severity)
+        icon, colour, _ = ui.SEVERITY_STYLE[severity.value]
+        plural = "s" if n != 1 and name in ("error", "warning") else ""
+        summary.append(f"{icon} {n} {name}{plural}   ", style=colour if n else "dim")
+    ui.console.print()
+    ui.console.print(summary)
+    ui.console.print()
+
+
 def _render(report: Report, connection: str) -> None:
+    from vecshift import ui
+
+    if ui.fancy():
+        _render_fancy(report, connection)
+        return
     dims = f"({report.declared_dimensions})" if report.declared_dimensions else ""
     rows = f"~{report.estimated_rows:,}" if report.estimated_rows is not None else "unknown"
     typer.secho(f"vecshift doctor · {report.store} via {connection}", bold=True)

{vecshift-0.2.0 → vecshift-0.3.0}/src/vecshift/cli_apply.py

@@ -83,6 +83,82 @@ class _Progress:
             self.last_print = time.monotonic()
 
 
+class _FancyProgress:
+    """A live progress bar and spinners, for a person at a colour terminal."""
+
+    def __init__(self) -> None:
+        from rich.progress import (
+            BarColumn,
+            MofNCompleteColumn,
+            Progress,
+            SpinnerColumn,
+            TextColumn,
+            TimeRemainingColumn,
+        )
+
+        from vecshift import ui
+
+        self.ui = ui
+        self.started = time.monotonic()
+        self.progress = Progress(
+            SpinnerColumn(style=ui.ACCENT),
+            TextColumn("{task.description}"),
+            BarColumn(complete_style=ui.ACCENT, finished_style="green", bar_width=32),
+            MofNCompleteColumn(),
+            TextColumn("[dim]{task.fields[rate]}"),
+            TextColumn("[dim]{task.fields[cost]}"),
+            TimeRemainingColumn(compact=True),
+            console=ui.console,
+            transient=False,
+        )
+        self.task: Any = None
+        self.status: Any = None
+        self.done = 0
+
+    def __call__(self, event: Event) -> None:
+        ui, d = self.ui, event.data
+        if event.kind == "column" and d["added"]:
+            ui.success("Added the new column")
+        elif event.kind == "trigger" and d["added"]:
+            ui.success("Added the sync trigger")
+        elif event.kind == "start":
+            ui.note(f"  {d['pending']:,} rows need a new vector")
+            self.progress.start()
+            self.task = self.progress.add_task("Embedding", total=d["pending"], rate="", cost="")
+        elif event.kind == "batch" and self.task is not None:
+            self.done = d["rows_written"]
+            rate = self.done / max(time.monotonic() - self.started, 1e-6)
+            cost = _money(d["spent_usd"]) if d["spent_usd"] is not None else ""
+            self.progress.update(
+                self.task, completed=self.done, rate=f"{rate:,.0f} rows/s", cost=cost
+            )
+        elif event.kind == "pass" and d["number"] > 1 and self.task is not None:
+            self.progress.update(
+                self.task, description="Catching up", total=self.done + d["remaining"]
+            )
+        elif event.kind == "index":
+            self.close()
+            if d["state"] == "building":
+                self.status = ui.console.status(
+                    f"Building the {d['method']} index concurrently. Writes continue…",
+                    spinner="dots",
+                    spinner_style=ui.ACCENT,
+                )
+                self.status.start()
+            else:
+                ui.success(f"Index {d['state']}")
+        elif event.kind == "done":
+            self.close()
+
+    def close(self) -> None:
+        if self.task is not None:
+            self.progress.stop()
+            self.task = None
+        if self.status is not None:
+            self.status.stop()
+            self.status = None
+
+
 def _eta(seconds: float) -> str:
     if seconds < 90:
         return f"{max(1, round(seconds))} s"
@@ -91,7 +167,44 @@ def _eta(seconds: float) -> str:
     return f"{seconds / 3600:.1f} h"
 
 
+def _summary_fancy(result: ApplyResult) -> None:
+    from vecshift import ui
+
+    kind = {"complete": "ok", "failed": "error"}.get(result.status, "warn")
+    ui.verdict(f"Apply {result.status}.", kind)
+    if result.message:
+        ui.detail(result.message)
+    spent = _money(result.spent_usd) if result.spent_usd is not None else "unknown"
+    total = _money(result.total_spent_usd) if result.total_spent_usd is not None else ""
+    ui.console.print()
+    ui.kv(
+        [
+            ("Rows written", f"{result.rows_written:,}", ""),
+            ("Tokens", f"{result.tokens:,}", ""),
+            ("Spent", spent, f"{total} across runs" if total else ""),
+            ("Time", f"{result.seconds:,.0f} s", ""),
+        ]
+        + (
+            [("Rejected", f"{result.rows_failed:,} rows", "retried on the next run")]
+            if result.rows_failed
+            else []
+        )
+    )
+    if result.status == "complete":
+        ui.next_step(
+            "check it's safe to switch with vecshift cutover --check, then run vecshift "
+            "cutover. It embeds rows added or edited since this run first."
+        )
+    elif result.status in {"stopped", "budget"}:
+        ui.next_step("run vecshift apply again to continue where it stopped.")
+
+
 def _summary(result: ApplyResult) -> None:
+    from vecshift import ui
+
+    if ui.fancy():
+        _summary_fancy(result)
+        return
     color = {"complete": typer.colors.GREEN, "failed": typer.colors.RED}.get(
         result.status, typer.colors.YELLOW
     )
@@ -169,7 +282,39 @@ def apply(
     state = JobState.for_job(job_file, job.name)
     est = plan.estimates
     warnings = [f for f in plan.findings if f.severity.rank == 2]
-    if not output_json:
+    from vecshift import ui
+
+    fancy = ui.fancy() and not output_json
+    if fancy:
+        from rich.text import Text
+
+        from vecshift.cli_plan import CHANGE_MARKS
+
+        ui.title("apply", job.name)
+        for change in plan.changes:
+            if change.kind != "cutover":
+                mark, colour = CHANGE_MARKS.get(change.kind, ("·", "dim"))
+                ui.console.print(Text.assemble((f"  {mark} ", f"bold {colour}"), change.summary))
+        ui.console.print()
+        rows: list[tuple[str, str, str]] = [
+            ("Estimated cost", _money(est.cost_usd), ""),
+            ("New column", _size(est.new_bytes), ""),
+        ]
+        if job.limits.budget_usd:
+            rows.append(("Budget", f"${job.limits.budget_usd:,.2f}", "apply stops there"))
+        if state.runs:
+            rows.append(
+                (
+                    "Resuming",
+                    f"{state.rows_written:,} rows",
+                    f"written in earlier runs, {_money(state.spent_usd)} spent",
+                )
+            )
+        ui.kv(rows)
+        if warnings:
+            ui.console.print()
+            ui.findings(warnings)
+    elif not output_json:
         typer.secho(f"vecshift apply · {job.name}", bold=True)
         for change in plan.changes:
             if change.kind != "cutover":
@@ -184,7 +329,14 @@ def apply(
             )
         if warnings:
             finding_lines(warnings)
-    if not yes:
+    if not yes and fancy:
+        where = "your machine" if spec.is_local else spec.url
+        ui.console.print()
+        ui.note(f"  This changes {plan.source.split()[0]} and sends row text to {where}.")
+        if not ui.confirm("Apply?", default=False):
+            raise typer.Exit(1)
+        ui.console.print()
+    elif not yes:
         where = "your machine" if spec.is_local else spec.url
         typer.echo(
             f"\nThis changes {plan.source.split()[0]} and sends row text to {where}.",
@@ -221,6 +373,8 @@ def apply(
         def on_event(event: Event) -> None:
             typer.echo(json.dumps({"event": event.kind, **event.data}))
 
+    elif fancy:
+        on_event = _FancyProgress()
     else:
         on_event = _Progress(live=sys.stdout.isatty())
     try:
@@ -255,6 +409,8 @@ def apply(
             )
         raise _fail(f"The database reported an error: {detail}", hint) from exc
     finally:
+        if isinstance(on_event, _FancyProgress):
+            on_event.close()
         signal.signal(signal.SIGINT, previous)
         conn.close()
 

{vecshift-0.2.0 → vecshift-0.3.0}/src/vecshift/cli_bench.py

@@ -6,7 +6,7 @@ import asyncio
 import json
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated
+from typing import TYPE_CHECKING, Annotated, Any
 
 import typer
 
@@ -28,7 +28,12 @@ def _fail(message: str, hint: str | None = None) -> typer.Exit:
 
 
 def _note(message: str) -> None:
-    typer.secho(message, err=True, dim=True)
+    from vecshift import ui
+
+    if ui.fancy():
+        ui.note(f"  · {message}")
+    else:
+        typer.secho(message, err=True, dim=True)
 
 
 def money(value: float | None) -> str:
@@ -48,8 +53,30 @@ def _ms(value: float | None) -> str:
 
 
 def _confirm(items: list[PlanItem], generator: ModelSpec | None, n_docs: int, yes: bool) -> None:
+    from vecshift import ui
+
     remote = [i for i in items if not i.spec.is_local]
     remote_gen = generator is not None and not generator.is_local
+    if ui.fancy():
+        ui.title("bench")
+        rows: list[list[str | Any]] = [
+            [
+                item.spec.name,
+                f"~{item.est_tokens:,}",
+                money(item.est_cost) if item.est_cost is not None else "unknown price",
+                "local" if item.spec.is_local else (item.spec.url or ""),
+            ]
+            for item in items
+        ]
+        if generator is not None:
+            rows.append([generator.name, "generates queries", "", generator.url or ""])
+        ui.table(["Model", "Tokens", "Cost", "Where"], rows, right=frozenset({1, 2}))
+        if not remote and not remote_gen:
+            return
+        ui.warn(f"  This sends the text of {n_docs:,} sampled documents to the services above.")
+        if not yes and not ui.confirm("Continue?", default=False):
+            raise typer.Exit(1)
+        return
     typer.echo("Plan", err=True)
     for item in items:
         where = "local" if item.spec.is_local else (item.spec.url or "")
@@ -74,13 +101,17 @@ def _confirm(items: list[PlanItem], generator: ModelSpec | None, n_docs: int, ye
 
 
 def _render(result: BenchResult) -> None:
+    from vecshift import ui
     from vecshift.bench.runner import ModelResult
 
-    typer.secho(
-        f"vecshift bench · {result.documents:,} documents, {result.queries:,} queries "
-        f"({result.query_source}) from {result.source}",
-        bold=True,
-    )
+    fancy = ui.fancy()
+
+    if not fancy:
+        typer.secho(
+            f"vecshift bench · {result.documents:,} documents, {result.queries:,} queries "
+            f"({result.query_source}) from {result.source}",
+            bold=True,
+        )
     rows: list[tuple[str, ...]] = []
     ranked = result.ranked()
     for rank, m in enumerate(ranked, 1):
@@ -115,7 +146,23 @@ def _render(result: BenchResult) -> None:
         "Per 1M docs",
         "Per 1M vecs",
     )
-    if rows:
+    if rows and fancy:
+        from rich.text import Text
+
+        ui.section(
+            f"Results · {result.documents:,} documents, {result.queries:,} queries "
+            f"({result.query_source}) from {result.source}"
+        )
+        styled: list[list[str | Text]] = [
+            [
+                Text(r[0], style="bold green" if r[0] == "1" else "dim"),
+                Text(r[1], style="bold"),
+                *r[2:],
+            ]
+            for r in rows
+        ]
+        ui.table(header, styled, right=frozenset({0, 2, 3, 4, 5, 6, 7, 8}))
+    elif rows:
         widths = [max(len(r[i]) for r in [header, *rows]) for i in range(len(header))]
         right = {0, 2, 3, 4, 5, 6, 7, 8}
 
@@ -132,9 +179,17 @@ def _render(result: BenchResult) -> None:
 
     failed: list[ModelResult] = [m for m in ranked if m.error]
     for m in failed:
-        typer.secho(f"\n✖ {m.name} failed: {m.error}", fg=typer.colors.RED)
+        if fancy:
+            ui.error(f"{m.name} failed: {m.error}")
+        else:
+            typer.secho(f"\n✖ {m.name} failed: {m.error}", fg=typer.colors.RED)
     for note in result.notes:
-        typer.secho(f"\n{note}", dim=True)
+        if fancy:
+            ui.note(f"  {note}")
+        else:
+            typer.secho(f"\n{note}", dim=True)
+    if fancy:
+        ui.console.print()
 
 
 def bench(

{vecshift-0.2.0 → vecshift-0.3.0}/src/vecshift/cli_cutover.py

@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Annotated, Any
 
 import typer
 
+from vecshift import ui
 from vecshift.cli_plan import DEFAULT_JOB, _fail, load
 from vecshift.cli_style import finding_lines
 
@@ -85,8 +86,16 @@ def _locate(job_file: Path) -> _Located:
 
 
 def _confirm(message: str, yes: bool) -> None:
+    from vecshift import ui
+
     if yes:
         return
+    if ui.fancy():
+        ui.console.print()
+        ui.note("  " + " ".join(message.split()))
+        if not ui.confirm("Continue?", default=False):
+            raise typer.Exit(1)
+        return
     typer.echo(message, err=True)
     if not sys.stdin.isatty():
         raise _fail("Not changing the database without confirmation.", "Pass --yes to proceed.")
@@ -219,7 +228,7 @@ def cutover(
             if check or blocked:
                 return {"status": "ready" if ready.ok else "blocked", "readiness": ready}
             if not output_json:
-                typer.secho(f"vecshift cutover · {found.job.name}", bold=True)
+                ui.title("cutover", found.job.name)
             _show([f for f in ready.findings if f.severity.rank >= 1], output_json)
             where = "your machine" if found.spec.is_local else found.spec.url
             sends = (
@@ -284,24 +293,24 @@ def cutover(
             )
         )
     elif outcome["status"] in {"ready", "blocked"}:
-        typer.secho(f"vecshift cutover · {found.job.name}", bold=True)
+        ui.title("cutover", found.job.name)
         finding_lines(ready.findings)
-        verdict = (
-            ("Ready to cut over.", typer.colors.GREEN)
-            if ready.ok
-            else ("Not ready to cut over.", typer.colors.RED)
-        )
-        typer.secho(f"\n{verdict[0]}", fg=verdict[1], bold=True)
+        if ready.ok:
+            ui.verdict("Ready to cut over.")
+            if ui.fancy():
+                ui.next_step("vecshift cutover")
+        else:
+            ui.verdict("Not ready to cut over.", "error")
     else:
-        typer.secho("\nCut over.", fg=typer.colors.GREEN, bold=True)
-        typer.echo(
-            f"  {lay.table}.{lay.live} now holds {found.spec.name} vectors; the old ones are "
+        ui.verdict("Cut over.")
+        ui.detail(
+            f"{lay.table}.{lay.live} now holds {found.spec.name} vectors; the old ones are "
             f"kept in {lay.previous}."
         )
         if outcome.get("caught_up"):
-            typer.echo(f"  Embedded {outcome['caught_up']:,} late rows first.")
-        typer.echo(
-            f"\nNext: make sure your application embeds queries and new rows with "
+            ui.detail(f"Embedded {outcome['caught_up']:,} late rows first.")
+        ui.next_step(
+            f"make sure your application embeds queries and new rows with "
             f"{found.spec.name}.\nUndo with: vecshift rollback. When you're sure, drop "
             f"{lay.previous} to free its space."
         )
@@ -363,16 +372,20 @@ def rollback(
             )
         )
         return
-    typer.secho("\nRolled back.", fg=typer.colors.GREEN, bold=True)
-    typer.echo(
-        f"  {lay.table}.{lay.live} holds the old vectors again; the new ones are back in "
+    if ui.fancy():
+        ui.title("rollback", found.job.name)
+    ui.verdict("Rolled back.")
+    ui.detail(
+        f"{lay.table}.{lay.live} holds the old vectors again; the new ones are back in "
         f"{lay.target}, kept in sync for another cutover."
     )
     if missing:
-        typer.echo(
-            f"  {missing:,} rows were added or edited after cutover and have no old-model "
+        ui.detail(
+            f"{missing:,} rows were added or edited after cutover and have no old-model "
             "vector. Your application needs to embed them with the old model."
         )
+    if ui.fancy():
+        ui.console.print()
 
 
 def cleanup(
@@ -406,14 +419,18 @@ def cleanup(
                     "Drop or change them first.",
                 )
             if not yes:
-                typer.echo(
+                warning = (
                     f"Cleanup drops {lay.schema}.{lay.table}.{lay.previous} and its index. The "
-                    "old vectors are gone for good, and rollback is no longer possible.",
-                    err=True,
+                    "old vectors are gone for good, and rollback is no longer possible."
                 )
-                if not sys.stdin.isatty():
-                    raise _fail("Not dropping anything without confirmation.", "Pass --yes.")
-                typed = typer.prompt(f"Type {lay.previous} to confirm", err=True, default="")
+                if ui.fancy():
+                    ui.warn(warning)
+                    typed = ui.text(f"Type {lay.previous} to confirm")
+                else:
+                    typer.echo(warning, err=True)
+                    if not sys.stdin.isatty():
+                        raise _fail("Not dropping anything without confirmation.", "Pass --yes.")
+                    typed = typer.prompt(f"Type {lay.previous} to confirm", err=True, default="")
                 if typed != lay.previous:
                     raise _fail("That didn't match, so nothing was dropped.")
             switch.cleanup()
@@ -428,4 +445,8 @@ def cleanup(
     if output_json:
         typer.echo(json.dumps({"status": "cleaned_up", "dropped": lay.previous}))
     else:
-        typer.secho(f"\nDropped {lay.previous}. The migration is complete.", fg=typer.colors.GREEN)
+        if ui.fancy():
+            ui.title("cleanup", found.job.name)
+        ui.verdict(f"Dropped {lay.previous}. The migration is complete.")
+        if ui.fancy():
+            ui.console.print()