smartpipe-cli 1.3.0__py3-none-any.whl

smartpipe/__init__.py

@@ -0,0 +1,6 @@
+"""smartpipe — semantic pipes for your terminal."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "1.3.0"

smartpipe/__main__.py

@@ -0,0 +1,8 @@
+"""Support ``python -m smartpipe``."""
+
+from __future__ import annotations
+
+from smartpipe.cli.root import main
+
+if __name__ == "__main__":
+    main()

smartpipe/assets/probe.txt

@@ -0,0 +1 @@
+The quick brown fox jumps over the lazy dog.

smartpipe/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line surface: flag parsing, help screens, exit-code mapping."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

smartpipe/cli/auth_cmd.py

@@ -0,0 +1,78 @@
+"""``smartpipe auth`` — log in with ChatGPT, check the login, log out (D19)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+
+from smartpipe.core.errors import ExitCode
+
+__all__ = ["auth_command"]
+
+
+@click.group(name="auth")
+def auth_command() -> None:
+    """Log in with your ChatGPT Plus/Pro account (OpenAI models, no API key)."""
+
+
+@auth_command.command(name="login")
+@click.option("--headless", is_flag=True, help="Device-code flow for machines without a browser.")
+def login(headless: bool) -> None:
+    """Log in with ChatGPT. Opens your browser; --headless prints a code instead."""
+    asyncio.run(_login(headless=headless))
+
+
+@auth_command.command(name="status")
+def status() -> None:
+    """Show the login state (the status line is the result — it goes to stdout)."""
+    import os
+
+    from smartpipe.config.credentials import credentials_path, load_oauth
+
+    credential = load_oauth(credentials_path(os.environ), "openai")
+    if credential is None:
+        click.echo("openai: not logged in — run: smartpipe auth login")
+        raise SystemExit(int(ExitCode.OK))
+    account = credential.account_id or "unknown account"
+    click.echo(
+        f"openai: logged in with ChatGPT (account {account}) — token refreshes automatically"
+    )
+
+
+@auth_command.command(name="logout")
+def logout() -> None:
+    """Remove the stored ChatGPT login."""
+    import os
+
+    from smartpipe.config.credentials import credentials_path, remove_oauth
+    from smartpipe.io import diagnostics
+
+    if remove_oauth(credentials_path(os.environ), "openai"):
+        diagnostics.note("logged out — the stored ChatGPT tokens were removed")
+    else:
+        diagnostics.note("nothing to remove — you weren't logged in")
+
+
+async def _login(*, headless: bool) -> None:
+    import os
+
+    from smartpipe.config.credentials import credentials_path, save_oauth
+    from smartpipe.io import diagnostics
+    from smartpipe.models.http_support import make_client
+    from smartpipe.models.openai_oauth import login_via_browser, poll_device, start_device_flow
+
+    async with make_client() as client:
+        if headless:
+            start = await start_device_flow(client)
+            diagnostics.note(f"open {start.verify_url} and enter code: {start.user_code}")
+            credential = await poll_device(client, start)
+        else:
+
+            def announce(url: str) -> None:
+                diagnostics.note(f"complete the login in your browser (opening): {url}")
+
+            credential = await login_via_browser(client, announce=announce)
+    save_oauth(credentials_path(os.environ), "openai", credential)
+    account = credential.account_id or "unknown account"
+    diagnostics.note(f"logged in with ChatGPT (account {account})")

smartpipe/cli/cache_cmd.py

@@ -0,0 +1,60 @@
+"""``smartpipe cache`` — maintenance for the result cache (D38/15)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+import click
+
+__all__ = ["cache_command"]
+
+
+def _cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME", "").strip()
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "smartpipe" / "results"
+
+
+@click.group(name="cache")
+def cache_command() -> None:
+    """Inspect or clear the result cache (enable with: smartpipe config cache on)."""
+
+
+@cache_command.command(name="clear")
+def cache_clear() -> None:
+    """Delete every cached reply and report the space freed."""
+    directory = _cache_dir()
+    if not directory.exists():
+        click.echo("cache is empty")
+        return
+    size = sum(entry.stat().st_size for entry in directory.rglob("*") if entry.is_file())
+    shutil.rmtree(directory)
+    click.echo(f"cache cleared: {size / 1_048_576:.1f} MB")
+
+
+@cache_command.command(name="stats")
+def cache_stats() -> None:
+    """Show the cache's size, entry count, and oldest entry."""
+    import time
+
+    directory = _cache_dir()
+    entries = list(directory.rglob("*.json")) if directory.exists() else []
+    if not entries:
+        click.echo("cache is empty")
+        return
+    total = sum(p.stat().st_size for p in entries)
+    oldest = min(p.stat().st_mtime for p in entries)
+    days = (time.time() - oldest) / 86_400
+    from smartpipe.cli.screens import tint
+
+    click.echo(f"{tint('entries', '2')}   {len(entries):,}")
+    click.echo(
+        f"{tint('size', '2')}      {total / 1_048_576:.1f} MB   "
+        f"{tint('(cap 500 MB default — cache-max-mb)', '2')}"
+    )
+    click.echo(
+        f"{tint('oldest', '2')}    {days:.0f} days   "
+        f"{tint('(ttl 30 days default — cache-days)', '2')}"
+    )

smartpipe/cli/chart_cmd.py

@@ -0,0 +1,60 @@
+"""``smartpipe chart`` — bars in the terminal, SVG on disk. No model calls."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from smartpipe.core.errors import ExitCode
+from smartpipe.verbs.chart import ChartRequest, run_chart
+
+__all__ = ["chart_command"]
+
+
+@click.command(name="chart")
+@click.argument("field", required=False)
+@click.option("--top", type=int, help="How many bars (default 20).")
+@click.option(
+    "--save",
+    type=click.Path(path_type=Path),
+    help="Also write the chart as an SVG file (no extra dependencies).",
+)
+@click.option("--title", help="Title for the saved SVG.")
+@click.option("--facet", "facet", help="Several distributions in one pass: --facet label,severity.")
+@click.option(
+    "--by-time",
+    "by_time",
+    metavar="FIELD:BUCKET",
+    help="Chronological buckets: --by-time ts:1h (ISO-8601 or epoch).",
+)
+def chart_command(
+    field: str | None,
+    top: int | None,
+    save: Path | None,
+    title: str | None,
+    facet: str | None,
+    by_time: str | None,
+) -> None:
+    """Draw a bar chart of a field's values (or of whole lines). Free.
+
+    \b
+    Examples:
+      cat tickets.txt | smartpipe map "Extract {label}" | smartpipe chart label
+      jq -r .status data.jsonl | smartpipe chart
+      … | smartpipe chart label --save labels.svg --title "Ticket labels"
+      cat tickets.jsonl | smartpipe chart --facet label,severity,region
+      cat app.jsonl | smartpipe where 'level == "error"' | smartpipe chart --by-time ts:1h
+
+    Reads NDJSON records (counts FIELD) or plain lines (counts each line).
+    The chart is the result — it goes to stdout; --save adds an SVG.
+    """
+    facets = tuple(name.strip() for name in facet.split(",") if name.strip()) if facet else ()
+    code = run_chart(
+        ChartRequest(field=field, top=top, save=save, title=title, facets=facets, by_time=by_time),
+        stdin=sys.stdin,
+        stdout=sys.stdout,
+    )
+    if code is not ExitCode.OK:
+        raise SystemExit(int(code))

smartpipe/cli/cite_cmd.py

@@ -0,0 +1,26 @@
+"""``smartpipe cite`` — print the BibTeX entry (the output IS the result, like --version)."""
+
+from __future__ import annotations
+
+import click
+
+from smartpipe import __version__
+
+__all__ = ["cite_command"]
+
+_BIBTEX = """\
+@software{{gupta_smartpipe_2026,
+  author = {{Gupta, Prabal}},
+  title = {{smartpipe: semantic pipes for your terminal}},
+  year = {{2026}},
+  version = {{{version}}},
+  license = {{Apache-2.0}},
+  url = {{https://github.com/prabal-rje/smartpipe}}
+}}
+"""
+
+
+@click.command(name="cite")
+def cite_command() -> None:
+    """Print a BibTeX entry for citing smartpipe."""
+    click.echo(_BIBTEX.format(version=__version__), nl=False)

smartpipe/cli/cluster_cmd.py

@@ -0,0 +1,102 @@
+"""``smartpipe cluster`` — themes with sizes and quotes."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+import click
+
+from smartpipe.cli.completions import complete_chat_models, complete_embed_models
+from smartpipe.cli.input_options import input_options, input_spec
+from smartpipe.cli.interrupts import graceful_interrupts, settle_budget
+from smartpipe.core.errors import ExitCode
+from smartpipe.verbs.cluster import ClusterRequest, run_cluster
+
+__all__ = ["cluster_command"]
+
+
+@click.command(name="cluster")
+@click.option("--k", type=int, help="Force exactly K clusters (merge smallest).")
+@click.option("--top", type=int, help="Show N clusters; fold the rest into (other).")
+@click.option(
+    "--explode",
+    metavar="members",
+    help="One row per input item, labeled with its cluster.",
+)
+@click.option(
+    "--model",
+    "model_flag",
+    shell_complete=complete_chat_models,
+    help="Chat model for cluster labels.",
+)
+@click.option(
+    "--embed-model",
+    "embed_flag",
+    shell_complete=complete_embed_models,
+    help="Embedding model for grouping.",
+)
+@click.option("--concurrency", "concurrency_flag", type=int, help="Max parallel model calls.")
+@click.option("--max-calls", "max_calls", type=int, help="Stop after N model calls (cost cap).")
+@click.option(
+    "--allow-captions",
+    "allow_captions",
+    is_flag=True,
+    help="Let a CLOUD model convert images/audio to text (paid; local models do it free).",
+)
+@input_options
+def cluster_command(
+    k: int | None,
+    top: int | None,
+    explode: str | None,
+    model_flag: str | None,
+    embed_flag: str | None,
+    concurrency_flag: int | None,
+    max_calls: int | None,
+    allow_captions: bool,
+    in_patterns: tuple[str, ...],
+    from_files: bool,
+) -> None:
+    """Group items by meaning and label each group — themes, sized, with quotes.
+
+    \b
+    Examples:
+      cat feedback.txt | smartpipe cluster
+      cat tickets.jsonl | smartpipe cluster --top 8 | smartpipe chart cluster
+      cat snippets.txt | smartpipe cluster --explode members > coded.jsonl
+
+    One row per cluster, largest first: {"cluster", "size", "share",
+    "examples"} — the examples are the most representative quotes. The cost
+    shape is the point: N embeddings + one label call per cluster, never N
+    chat calls. Labels are deterministic (temperature 0): re-runs don't
+    change your slide.
+    """
+    request = ClusterRequest(
+        k=k,
+        top=top,
+        explode=explode,
+        model_flag=model_flag,
+        embed_flag=embed_flag,
+        concurrency_flag=concurrency_flag,
+        allow_captions=allow_captions,
+        input=input_spec(in_patterns, from_files=from_files),
+    )
+    code = asyncio.run(_run(request, max_calls))
+    if code is not ExitCode.OK:
+        raise SystemExit(int(code))
+
+
+async def _run(request: ClusterRequest, max_calls: int | None) -> ExitCode:
+    from dataclasses import replace
+
+    from smartpipe.container import build_container
+
+    async with (
+        graceful_interrupts() as stop,
+        build_container(os.environ, max_calls=max_calls, stop=stop) as container,
+    ):
+        if not request.allow_captions and container.config.allow_captions:
+            request = replace(request, allow_captions=True)  # profile consent (D35)
+        code = await run_cluster(request, container, stdin=sys.stdin, stdout=sys.stdout, stop=stop)
+        return settle_budget(container.budget, code)

smartpipe/cli/completions.py

@@ -0,0 +1,91 @@
+"""Shell-completion callbacks — instant model-name suggestions, never a hang.
+
+Completion runs on every ``<TAB>``, so the budget is hard: the configured model
+comes from the config file, the installed ones from a single Ollama probe capped
+at 150 ms — and *any* failure (no daemon, slow daemon, broken config) collapses
+to "no suggestions", never an error and never a wait. httpx stays a
+function-local import: this module loads with the CLI, the probe runs only
+inside a completion request.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    import click
+    from click.shell_completion import CompletionItem
+
+__all__ = ["complete_chat_models", "complete_embed_models", "suggest_models"]
+
+_PROBE_TIMEOUT_SECONDS = 0.15  # a <TAB> must feel instant; a slow probe is a missing probe
+
+
+def suggest_models(incomplete: str, env: Mapping[str, str], *, embed: bool) -> tuple[str, ...]:
+    """Configured model first, then ``ollama/<name>`` per installed model.
+
+    Every failure path degrades to fewer suggestions — completion must never
+    crash, hang, or print (the shell would splice the noise into the command line).
+    """
+    try:
+        configured = _configured(env, embed=embed)
+    except Exception:  # a broken config file must not break <TAB>
+        configured = ()
+    try:
+        local = tuple(f"ollama/{name}" for name in _ollama_names(env))
+    except Exception:  # no daemon / slow daemon / bad payload — suggest nothing extra
+        local = ()
+    merged = dict.fromkeys(configured + local)  # dedupe, configured first
+    return tuple(name for name in merged if name.startswith(incomplete))
+
+
+def _configured(env: Mapping[str, str], *, embed: bool) -> tuple[str, ...]:
+    from smartpipe.config.paths import config_path
+    from smartpipe.config.store import load_config
+
+    config = load_config(config_path(env))
+    env_value = env.get("SMARTPIPE_EMBED_MODEL" if embed else "SMARTPIPE_MODEL", "").strip()
+    stored = config.embed_model if embed else config.model
+    return tuple(name for name in (env_value, stored) if name)
+
+
+def _ollama_names(env: Mapping[str, str]) -> tuple[str, ...]:
+    import httpx
+
+    from smartpipe.core.jsontools import as_items, as_record
+    from smartpipe.models.ollama import resolve_host
+
+    with httpx.Client(timeout=_PROBE_TIMEOUT_SECONDS) as client:
+        response = client.get(f"{resolve_host(env)}/api/tags")
+        response.raise_for_status()
+        payload = as_record(response.json())
+    entries = as_items(payload.get("models")) if payload is not None else None
+    if entries is None:
+        return ()
+    records = (as_record(entry) for entry in entries)
+    names = (record.get("name") for record in records if record is not None)
+    return tuple(name for name in names if isinstance(name, str))
+
+
+def complete_chat_models(
+    ctx: click.Context, param: click.Parameter, incomplete: str
+) -> list[CompletionItem]:
+    del ctx, param  # click's callback shape; the suggestions need neither
+    return _items(incomplete, embed=False)
+
+
+def complete_embed_models(
+    ctx: click.Context, param: click.Parameter, incomplete: str
+) -> list[CompletionItem]:
+    del ctx, param
+    return _items(incomplete, embed=True)
+
+
+def _items(incomplete: str, *, embed: bool) -> list[CompletionItem]:
+    import os
+
+    from click.shell_completion import CompletionItem
+
+    return [CompletionItem(name) for name in suggest_models(incomplete, os.environ, embed=embed)]

smartpipe/cli/config_cmd.py

@@ -0,0 +1,234 @@
+"""The ``config`` verb: show settings, set a model, or run interactive setup.
+
+The interactive flow (``run_interactive_setup``) takes its I/O as injected
+callables (ask/confirm/say/save) so it is unit-testable without a real terminal
+— the click wiring supplies the real prompts. This is the first-class-function
+DI the design template favors.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+import click
+
+from smartpipe.cli.completions import complete_chat_models, complete_embed_models
+from smartpipe.config.display import render_show, settings_with_origin
+from smartpipe.config.paths import config_path, human_path
+from smartpipe.config.store import Config, load_config, save_config
+from smartpipe.core.errors import SetupFault
+from smartpipe.io import diagnostics
+from smartpipe.models.base import parse_model_ref
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+__all__ = ["config_command", "run_interactive_setup"]
+
+_TRY_IT = 'echo "hello world" | smartpipe map "translate to Spanish"'
+_NON_TTY = (
+    "error: 'smartpipe config' is interactive and needs a terminal\n"
+    "  Set a model without prompts:\n"
+    "    smartpipe config model ollama/qwen3:8b        (local, free)\n"
+    "    smartpipe config model gpt-5.4-mini            (cloud)"
+)
+
+
+@click.group(name="config", invoke_without_command=True)
+@click.pass_context
+def config_command(ctx: click.Context) -> None:
+    """Configure models and settings."""
+    if ctx.invoked_subcommand is not None:
+        return
+    import sys
+
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        raise SetupFault(_NON_TTY)
+    asyncio.run(_interactive_entry())
+
+
+@config_command.command(name="profile")
+@click.argument("name", required=False)
+@click.option("--unset", is_flag=True, help="Clear the active profile.")
+def config_profile(name: str | None, unset: bool) -> None:
+    """Show, switch, or clear the active profile.
+
+    \b
+      smartpipe config profile           list profiles (the active one marked)
+      smartpipe config profile local     switch — local runs ollama/gemma-4-e2b
+      SMARTPIPE_PROFILE=gemini smartpipe … one-off, no file change
+    """
+    from smartpipe.config.store import profile_names, set_active_profile
+
+    path = config_path(os.environ)
+    if unset:
+        set_active_profile(path, None)
+        diagnostics.note("profile cleared — flat config keys stand alone")
+        return
+    if name is None:
+        config = load_config(path, os.environ)
+        for known in profile_names(path):
+            marker = "* " if known == config.profile else "  "
+            click.echo(f"{marker}{known}")
+        return
+    known = profile_names(path)
+    if name not in known:
+        raise SetupFault(
+            f"error: profile {name!r} doesn't exist\n  Known profiles: {', '.join(known)}\n"
+            f"  Define [profiles.{name}] in {human_path(path)} to create it."
+        )
+    set_active_profile(path, name)
+    effective = load_config(path)
+    summary = ", ".join(
+        f"{label} {value}"
+        for label, value in (("model:", effective.model), ("embed:", effective.embed_model))
+        if value is not None
+    )
+    diagnostics.note(f"profile '{name}' active — {summary}")
+
+
+@config_command.command(name="show")
+def config_show() -> None:
+    """Show the effective settings and where each comes from."""
+    env = os.environ
+    path = config_path(env)
+    config = load_config(path, env)
+    if config.profile is not None:
+        origin = "SMARTPIPE_PROFILE" if env.get("SMARTPIPE_PROFILE", "").strip() else "config file"
+        click.echo(f"profile      {config.profile}  ({origin})")
+    click.echo(render_show(settings_with_origin(env, config), human_path(path)))
+
+
+@config_command.command(name="model")
+@click.argument("model_string", shell_complete=complete_chat_models)
+def config_set_model(model_string: str) -> None:
+    """Set the default chat model (e.g. ollama/qwen3:8b, gpt-5.4-mini)."""
+    ref = parse_model_ref(model_string)
+    _update(lambda c: replace(c, model=str(ref)))
+    click.echo(f"model set to {ref}")
+
+
+@config_command.command(name="embed-model")
+@click.argument("model_string", shell_complete=complete_embed_models)
+def config_set_embed_model(model_string: str) -> None:
+    """Set the embedding model used by embed and top_k."""
+    ref = parse_model_ref(model_string)
+    _update(lambda c: replace(c, embed_model=str(ref)))
+    click.echo(f"embed-model set to {ref}")
+
+
+@config_command.command(name="stt-model")
+@click.argument("model_string")
+def config_set_stt(model_string: str) -> None:
+    """Set the remote transcription model (e.g. openai/whisper-1) — verbatim STT."""
+    ref = parse_model_ref(model_string)
+    _update(lambda c: replace(c, stt_model=str(ref)))
+    click.echo(f"stt-model set to {ref} (runs first in the audio ladder; consent rules apply)")
+
+
+@config_command.command(name="cache")
+@click.argument("state", type=click.Choice(["on", "off"]))
+def config_set_cache(state: str) -> None:
+    """Turn result caching on or off (identical calls reuse stored replies)."""
+    _update(lambda c: replace(c, cache=state == "on"))
+    click.echo(f"cache {state} — stored replies live in ~/.cache/smartpipe (smartpipe cache clear)")
+
+
+def _update(change: Callable[[Config], Config]) -> None:
+    path = config_path(os.environ)
+    save_config(path, change(load_config(path)))
+
+
+async def _interactive_entry() -> None:
+    from smartpipe.container import build_container
+
+    async with build_container(os.environ) as container:
+        path = config_path(os.environ)
+        await run_interactive_setup(
+            current=container.config,
+            probe=container.probe_ollama,
+            ask=lambda question, default: click.prompt(question, default=default),
+            confirm=lambda question: click.confirm(question, default=True),
+            say=click.echo,
+            save=lambda config: save_config(path, config),
+        )
+
+
+async def run_interactive_setup(
+    *,
+    current: Config,
+    probe: Callable[[], Awaitable[tuple[str, ...] | None]],
+    ask: Callable[[str, str], str],
+    confirm: Callable[[str], bool],
+    say: Callable[[str], None],
+    save: Callable[[Config], None],
+) -> Config:
+    say("smartpipe setup — one minute, three questions\n")
+    if current.profile is None and current.model is None:
+        say("Pick a starting profile (a named bundle you can switch any time):")
+        say(
+            "  1. openai — gpt-5.4-mini + text-embedding-3-small "
+            "(key or ChatGPT login; no audio input)"
+        )
+        say("  2. gemini — gemini-3.1-flash-lite, the most multimodal wire (needs GEMINI_API_KEY)")
+        say("  3. local  — ollama/gemma-4-e2b, multimodal, nothing leaves this machine")
+        say("  4. custom — answer the questions instead")
+        choice = ask("Profile [1-4]?", "4").strip()
+        picked = {"1": "openai", "2": "gemini", "3": "local"}.get(choice)
+        if picked is not None:
+            from smartpipe.config.store import BUILTIN_PROFILES
+
+            chosen = replace(current, profile=picked)
+            save(chosen)  # a fresh setup has no flat keys to materialize
+            bundle = ", ".join(f"{k} = {v}" for k, v in BUILTIN_PROFILES[picked].items())
+            say(f"\n  ✓ profile '{picked}' active ({bundle})")
+            if BUILTIN_PROFILES[picked].get("allow-captions"):
+                say(
+                    "  note: this profile converts images/audio to text through its"
+                    " model when needed (fractions of a cent each, disclosed per row)"
+                )
+            say("  Check the setup end to end:  smartpipe doctor\n")
+            return chosen
+    names = await probe() or ()
+    chat = _first_chat(names)
+    say("  Tip: pick a model that can SEE images (gpt-5.4-mini, gemini-3.1-flash-lite,")
+    say("  ollama/llava) — smartpipe is multimodal; text-only models refuse image rows.")
+    if chat is not None:
+        say(f"  ✓ found Ollama ({len(names)} models)\n")
+        model_answer = ask("Default model?", f"ollama/{chat}")
+    else:
+        # No Ollama, or Ollama has only embedding models — offer a cloud chat model.
+        say(
+            "  no local chat model found — install one at https://ollama.com, "
+            "or use a cloud model.\n"
+        )
+        model_answer = ask(
+            "Default model (e.g. gpt-5.4-mini, needs OPENAI_API_KEY)", "gpt-5.4-mini"
+        )
+    embed_answer = ask("Embedding model?", f"ollama/{_first_embed(names)}")
+
+    updated = replace(
+        current,
+        model=str(parse_model_ref(model_answer)),
+        embed_model=str(parse_model_ref(embed_answer)),
+    )
+    if confirm("Save to config?"):
+        save(updated)
+        say("\n  Saved. Try it:")
+        say(f"    {_TRY_IT}")
+    else:
+        say("\n  Not saved. Set a model any time with: smartpipe config model <name>")
+    return updated
+
+
+def _first_chat(names: tuple[str, ...]) -> str | None:
+    """The first non-embedding model, or None — never propose an embedding
+    model as the chat default just because it's the only thing installed."""
+    return next((name for name in names if "embed" not in name.lower()), None)
+
+
+def _first_embed(names: tuple[str, ...]) -> str:
+    return next((name for name in names if "embed" in name.lower()), "nomic-embed-text")