refactor: improve windows error handling and add connection error messages in CLI

Author: ai-singhal

profine/cli/errors.py

@@ -12,7 +12,6 @@
 from __future__ import annotations
 
 import os
-from pathlib import Path
 
 
 def format_user_error(exc: BaseException) -> tuple[str, int] | None:
@@ -49,11 +48,13 @@ def format_user_error(exc: BaseException) -> tuple[str, int] | None:
             2,
         )
 
-    # File not found — script path that doesn't exist
+    # File not found — script path that doesn't exist.
+    # Render exc.filename directly (no Path round-trip) so the displayed path
+    # keeps the separators the user passed; this also keeps the cross-platform
+    # test assertion (which uses forward slashes) stable on Windows.
     if isinstance(exc, FileNotFoundError):
-        target = Path(exc.filename) if exc.filename else None
-        if target:
-            return (f"File not found: {target}", 2)
+        if exc.filename:
+            return (f"File not found: {exc.filename}", 2)
         return (f"File not found: {msg}", 2)
 
     # Permission denied — output dir that's not writable
@@ -73,6 +74,20 @@ def format_user_error(exc: BaseException) -> tuple[str, int] | None:
             2,
         )
 
+    # OpenAI/httpx connection failure — typically `--provider local` with no
+    # server listening. Surfaces as openai.APIConnectionError (which wraps
+    # httpx.ConnectError) or a bare httpx.ConnectError.
+    if name in ("APIConnectionError", "ConnectError", "ConnectionRefusedError") or (
+        "connection error" in low or "connection refused" in low or "all connection attempts failed" in low
+    ):
+        return (
+            "Could not connect to the LLM endpoint. If you're using --provider local, "
+            "make sure your OpenAI-compatible server (Ollama, vLLM, LM Studio, ...) is "
+            "running and reachable. Default base URL is http://localhost:11434/v1 "
+            "(Ollama); override with --base-url or PROFINE_LOCAL_BASE_URL.",
+            2,
+        )
+
     # Malformed JSON from the LLM after retries — wraps LlmJsonParseError
     if name == "LlmJsonParseError":
         # Surface the saved debug-dump path if call_and_parse wrote one

profine/cli/main.py

@@ -35,33 +35,62 @@
 _LLM_COMMANDS = {"read", "profile", "interpret", "suggest", "edit", "benchmark", "run-all"}
 
 
+def _ensure_utf8_stdout() -> None:
+    """Reconfigure stdout/stderr to UTF-8 so non-ASCII help text (arrows,
+    em-dashes) doesn't crash on Windows consoles defaulting to CP1252.
+    """
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if stream and hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+
+def _add_shared(p: argparse.ArgumentParser, *, suppress: bool) -> None:
+    """Attach the shared flags to `p`.
+
+    `suppress=True` makes the argparse defaults SUPPRESS, so the action does
+    not write to the namespace when the user didn't pass the flag. We use
+    that for subparsers so that a flag set at the top level (e.g.
+    `profine --provider local read x`) isn't clobbered when the subparser
+    parses into its fresh namespace and copies attrs back. The top-level
+    parser keeps real defaults so the value is always present after parse.
+    """
+    NONE = argparse.SUPPRESS if suppress else None
+    OUT = argparse.SUPPRESS if suppress else "profine_output"
+    PROV = argparse.SUPPRESS if suppress else "openai"
+    p.add_argument("--provider", default=PROV,
+                   choices=["openai", "anthropic", "local"],
+                   help="LLM provider: 'openai', 'anthropic', or 'local' (OpenAI-compatible local server)")
+    p.add_argument("--api-key", default=NONE, help="API key override")
+    p.add_argument("--model", default=NONE, help="Model name override (required for --provider local)")
+    p.add_argument("--base-url", default=NONE,
+                   help="OpenAI-compatible endpoint URL (for --provider local; defaults to "
+                        "http://localhost:11434/v1 for Ollama). Env: PROFINE_LOCAL_BASE_URL")
+    p.add_argument("--seed", type=int, default=NONE,
+                   help="Seed for the LLM provider (best-effort; OpenAI honors it, Anthropic "
+                        "ignores it and relies on temperature=0). Use to make optimization "
+                        "rankings reproducible across runs.")
+    p.add_argument("--output", "-o", default=OUT, help="Output directory")
+    p.add_argument("--prefs", default=NONE, help="Path to user preferences markdown")
+
+
 def build_parser() -> argparse.ArgumentParser:
-    # Shared flags live in a parent parser so they work before OR after the
-    # subcommand (e.g. `profine read train.py -o out` and
-    # `profine -o out read train.py` both work).
-    shared = argparse.ArgumentParser(add_help=False)
-    shared.add_argument("--provider", default="openai",
-                        choices=["openai", "anthropic", "local"],
-                        help="LLM provider: 'openai', 'anthropic', or 'local' (OpenAI-compatible local server)")
-    shared.add_argument("--api-key", default=None, help="API key override")
-    shared.add_argument("--model", default=None, help="Model name override (required for --provider local)")
-    shared.add_argument("--base-url", default=None,
-                        help="OpenAI-compatible endpoint URL (for --provider local; defaults to "
-                             "http://localhost:11434/v1 for Ollama). Env: PROFINE_LOCAL_BASE_URL")
-    shared.add_argument("--seed", type=int, default=None,
-                        help="Seed for the LLM provider (best-effort; OpenAI honors it, Anthropic "
-                             "ignores it and relies on temperature=0). Use to make optimization "
-                             "rankings reproducible across runs.")
-    shared.add_argument("--output", "-o", default="profine_output", help="Output directory")
-    shared.add_argument("--prefs", default=None, help="Path to user preferences markdown")
+    # Shared flags work before OR after the subcommand. Subparsers use
+    # SUPPRESS defaults so they don't clobber values set at the top level.
+    shared_suppress = argparse.ArgumentParser(add_help=False)
+    _add_shared(shared_suppress, suppress=True)
 
     parser = argparse.ArgumentParser(
         prog="profine",
         description="Agentic ML Training Optimizer",
-        parents=[shared],
     )
+    _add_shared(parser, suppress=False)
 
     sub = parser.add_subparsers(dest="command", help="Tool to run")
+    shared = shared_suppress
 
     p_read = sub.add_parser("read", help="Read and analyze a training script", parents=[shared], conflict_handler="resolve")
     p_read.add_argument("script", help="Path to the training script")
@@ -128,6 +157,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
+    _ensure_utf8_stdout()
     try:
         # When profine is installed as a console script, find_dotenv()'s default
         # (usecwd=False) walks up from the entry-script's directory — e.g.

tests/test_cli_dispatch.py

@@ -99,6 +99,77 @@ def test_format_user_error_llm_json_parse():
     assert "malformed JSON" in msg
 
 
+def test_format_user_error_connection_refused_builtin():
+    # Bare ConnectionRefusedError (raised by httpx when local server is down)
+    exc = ConnectionRefusedError(61, "Connection refused")
+    formatted = format_user_error(exc)
+    assert formatted is not None
+    msg, code = formatted
+    assert "--provider local" in msg
+    assert "--base-url" in msg
+    assert "localhost:11434" in msg
+    assert code == 2
+
+
+def test_format_user_error_openai_api_connection_error():
+    # Simulates openai.APIConnectionError without depending on the openai SDK
+    class APIConnectionError(Exception):
+        pass
+
+    exc = APIConnectionError("Connection error.")
+    formatted = format_user_error(exc)
+    assert formatted is not None
+    msg, code = formatted
+    assert "--base-url" in msg
+    assert code == 2
+
+
+def test_format_user_error_httpx_connect_error():
+    class ConnectError(Exception):
+        pass
+
+    exc = ConnectError("All connection attempts failed")
+    formatted = format_user_error(exc)
+    assert formatted is not None
+    msg, _ = formatted
+    assert "OpenAI-compatible server" in msg
+
+
+def test_parser_provider_flag_before_subcommand_is_preserved():
+    # Regression: subparsers used to clobber the top-level --provider value
+    # back to the default 'openai' because parents=[shared] copied the
+    # argparse defaults into subparser actions.
+    parser = build_parser()
+    args = parser.parse_args(
+        ["--provider", "local", "--model", "llama3.1:8b", "read", "train.py"]
+    )
+    assert args.provider == "local"
+    assert args.model == "llama3.1:8b"
+
+
+def test_parser_provider_flag_after_subcommand_still_works():
+    parser = build_parser()
+    args = parser.parse_args(
+        ["read", "--provider", "local", "--model", "llama3.1:8b", "train.py"]
+    )
+    assert args.provider == "local"
+    assert args.model == "llama3.1:8b"
+
+
+def test_parser_provider_defaults_when_unset():
+    parser = build_parser()
+    args = parser.parse_args(["read", "train.py"])
+    assert args.provider == "openai"
+    assert args.model is None
+    assert args.output == "profine_output"
+
+
+def test_parser_output_flag_before_subcommand_is_preserved():
+    parser = build_parser()
+    args = parser.parse_args(["-o", "custom_out", "read", "train.py"])
+    assert args.output == "custom_out"
+
+
 def test_format_user_error_unknown_returns_none():
     # Unrecognised exception types must signal "unknown" so the caller re-raises
     assert format_user_error(KeyError("random")) is None