runapprentice 0.4.1__tar.gz → 0.4.2__tar.gz

{runapprentice-0.4.1 → runapprentice-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runapprentice
-Version: 0.4.1
+Version: 0.4.2
 Summary: Cut LLM cost without losing quality: capture traffic, build golden datasets, and optimize prompts.
 Project-URL: Homepage, https://runapprentice.com
 Project-URL: Documentation, https://docs.runapprentice.com
@@ -50,10 +50,10 @@ apprentice optimize <task> --local --data golden.csv              # free, your O
 apprentice train <task> --local --data golden.csv --effort high   # free, fine-tunes on your Mac
 ```
 
-Both commands work on a CSV alone, no Apprentice account. No golden dataset yet? `apprentice
-login` also lets Apprentice generate a starter set and route rows to a subject-matter expert
-for review, and tracks every run in the console. `apprentice --help` (or any
-subcommand `--help`) documents every flag; `--json` gives clean machine-readable output.
+Both `--local --data` commands work end to end from a CSV. Hosted setup requires the console
+or Python SDK to create a task and upload its dataset; the CLI has no create or upload command.
+`apprentice --help` (or any subcommand `--help`) documents every flag; `--json` gives clean
+machine-readable output.
 
 ## Install
 

{runapprentice-0.4.1 → runapprentice-0.4.2}/README.md

@@ -21,10 +21,10 @@ apprentice optimize <task> --local --data golden.csv              # free, your O
 apprentice train <task> --local --data golden.csv --effort high   # free, fine-tunes on your Mac
 ```
 
-Both commands work on a CSV alone, no Apprentice account. No golden dataset yet? `apprentice
-login` also lets Apprentice generate a starter set and route rows to a subject-matter expert
-for review, and tracks every run in the console. `apprentice --help` (or any
-subcommand `--help`) documents every flag; `--json` gives clean machine-readable output.
+Both `--local --data` commands work end to end from a CSV. Hosted setup requires the console
+or Python SDK to create a task and upload its dataset; the CLI has no create or upload command.
+`apprentice --help` (or any subcommand `--help`) documents every flag; `--json` gives clean
+machine-readable output.
 
 ## Install
 

{runapprentice-0.4.1 → runapprentice-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runapprentice"
-version = "0.4.1"
+version = "0.4.2"
 description = "Cut LLM cost without losing quality: capture traffic, build golden datasets, and optimize prompts."
 readme = "README.md"
 requires-python = ">=3.11"

{runapprentice-0.4.1 → runapprentice-0.4.2}/src/runapprentice/cli.py

@@ -8,9 +8,12 @@ import json
 import os
 import stat
 import sys
+import tempfile
 from pathlib import Path
 from typing import Any
 
+import httpx
+
 from runapprentice.client import Apprentice, ApprenticeError
 from runapprentice import local as _local
 from runapprentice.models import (
@@ -51,7 +54,10 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     if args.command == "login":
         return _login(args)
-    api_key = _api_key()
+    try:
+        api_key = _api_key()
+    except ApprenticeError as exc:
+        return _fail(str(exc), bool(args.json))
     client = Apprentice(api_key=api_key)
     setattr(args, "_api_key_present", api_key is not None)
     keyless_local_optimize = args.command == "optimize" and args.local and api_key is None
@@ -168,7 +174,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     train.set_defaults(func=_train)
 
-    jobs = sub.add_parser("jobs", help="list hosted optimize/train jobs for a task, newest first")
+    jobs = sub.add_parser("jobs", help="list hosted jobs for a task, newest first")
     jobs.add_argument("task", help="task name")
     jobs.set_defaults(func=_jobs)
 
@@ -183,13 +189,70 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def _login(args: argparse.Namespace) -> int:
-    key = getpass.getpass("Apprentice API key: ").strip()
+    key = (
+        getpass.getpass("Apprentice API key: ") if sys.stdin.isatty() else sys.stdin.read()
+    ).strip()
     if not key:
         return _fail("API key required", bool(args.json))
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    CONFIG_PATH.write_text(json.dumps({"api_key": key}) + "\n", encoding="utf-8")
-    CONFIG_PATH.chmod(stat.S_IRUSR | stat.S_IWUSR)
-    return _emit({"config": str(CONFIG_PATH), "mode": "600"}, "Saved API key.", bool(args.json))
+    # The client rejects a key that cannot become an HTTP header (whitespace from a
+    # two-line paste, a smart quote). Letting it raise keeps one definition of what
+    # a usable key is, shared with the constructor and APPRENTICE_API_KEY.
+    # No captures happen during login, so skip the background dispatcher thread.
+    try:
+        client = Apprentice(api_key=key, capture_async=False)
+    except ApprenticeError as exc:
+        return _fail(f"{exc}, so it was not saved.", bool(args.json))
+    try:
+        response = client._http.get("/v1/tasks")
+    except httpx.HTTPError:
+        return _fail(
+            "Could not verify API key because Apprentice API is unavailable. "
+            "API key was not saved.",
+            bool(args.json),
+        )
+    if response.status_code in {401, 403}:
+        return _fail("API key was rejected and was not saved.", bool(args.json))
+    if not response.is_success:
+        return _fail(
+            "Could not verify API key because Apprentice API is unavailable. "
+            "API key was not saved.",
+            bool(args.json),
+        )
+    # The key is valid past this point, so a filesystem failure is the only thing
+    # left that can go wrong. Report it the same way as every other failure rather
+    # than as a traceback that emits no JSON in --json mode.
+    try:
+        return _save_api_key(key, bool(args.json))
+    except OSError as exc:
+        return _fail(f"Could not save the API key to {CONFIG_PATH}: {exc}", bool(args.json))
+
+
+def _save_api_key(key: str, as_json: bool) -> int:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    # mkdir's mode is masked by the process umask, so set it explicitly. A
+    # world-writable directory lets another local account replace the key file
+    # whatever the file's own mode is, because directory write governs entries.
+    CONFIG_PATH.parent.chmod(stat.S_IRWXU)
+    # Write private-then-rename rather than write-then-chmod. Writing first would
+    # leave the key world-readable (0644 under a normal umask, 0666 under a
+    # permissive one) until the chmod lands, and a process killed in that window
+    # leaves it that way for good. mkstemp creates at 0600, and os.replace is
+    # atomic, so a concurrent reader sees either the old file or the new one and
+    # never a half-written one. The rename also lands on the path itself, so a
+    # config.json symlink is replaced instead of its target being overwritten.
+    handle_fd, temporary_path = tempfile.mkstemp(dir=CONFIG_PATH.parent, prefix=".config-")
+    try:
+        with os.fdopen(handle_fd, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps({"api_key": key}) + "\n")
+        os.replace(temporary_path, CONFIG_PATH)
+    except BaseException:
+        os.unlink(temporary_path)
+        raise
+    return _emit(
+        {"config": str(CONFIG_PATH), "mode": "600", "validated": True},
+        f"API key verified and saved to {CONFIG_PATH}.",
+        as_json,
+    )
 
 
 def _status(args: argparse.Namespace, client: Apprentice) -> int:
@@ -474,9 +537,34 @@ def _api_key() -> str | None:
         return os.environ["APPRENTICE_API_KEY"]
     if not CONFIG_PATH.exists():
         return None
-    data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ApprenticeError(
+            f"Could not read {CONFIG_PATH}: invalid JSON. "
+            "Run `apprentice login` to replace it."
+        ) from exc
+    except (OSError, UnicodeError) as exc:
+        raise ApprenticeError(
+            f"Could not read {CONFIG_PATH}: {exc}. "
+            "Fix its permissions or set APPRENTICE_API_KEY."
+        ) from exc
+    if not isinstance(data, dict):
+        raise ApprenticeError(
+            f"Could not read {CONFIG_PATH}: expected a JSON object. "
+            "Run `apprentice login` to replace it."
+        )
     key = data.get("api_key")
-    return key if isinstance(key, str) else None
+    if key is None:
+        return None
+    # Present but not a string: the file is malformed, which is not the same as
+    # having no key. Saying so beats silently falling through to an auth error.
+    if not isinstance(key, str):
+        raise ApprenticeError(
+            f"Could not read {CONFIG_PATH}: api_key must be a string. "
+            "Run `apprentice login` to replace it."
+        )
+    return key
 
 
 def _job_summary(job: JobSummary) -> dict[str, Any]:

{runapprentice-0.4.1 → runapprentice-0.4.2}/src/runapprentice/client.py

@@ -35,6 +35,7 @@ from runapprentice.models import (
 )
 
 logger = logging.getLogger("runapprentice")
+logger.addHandler(logging.NullHandler())
 
 _DEFAULT_BASE_URL = "https://api.runapprentice.com"
 _DEFAULT_TIMEOUT = 10.0
@@ -64,6 +65,45 @@ class ApprenticeError(Exception):
     """Raised for control-plane API failures."""
 
 
+def _reject_unusable_api_key(api_key: str) -> None:
+    """Reject a key that cannot become an HTTP header.
+
+    httpx encodes header values as ASCII, so a key carrying a smart quote or an
+    accented character raises UnicodeEncodeError deep inside the transport on the
+    first request. Checked here so every path that supplies a key (constructor,
+    APPRENTICE_API_KEY, the CLI config file) fails with the same clear error.
+    """
+    if any(character.isspace() for character in api_key):
+        raise ApprenticeError("API key contains whitespace")
+    if not api_key.isascii() or not api_key.isprintable():
+        raise ApprenticeError("API key has characters that are not printable ASCII")
+
+
+def _printable(text: str) -> str:
+    """Drop control characters from server-controlled text.
+
+    The message goes to a terminal and to logs. Escape sequences in it can clear
+    the screen, move the cursor, or repaint earlier lines, so a hostile or
+    compromised backend could make its error read as something else entirely.
+    """
+    return "".join(character if character.isprintable() else " " for character in text)
+
+
+def _reason(resp: httpx.Response) -> str:
+    """The API's own explanation for a failed response, falling back to its body."""
+    try:
+        payload = resp.json()
+    except ValueError:
+        payload = None
+    # A body is not always a JSON object: a gateway can return a bare list or
+    # string, and FastAPI sends a list of dicts for 422. Only a string `detail`
+    # on an object is a written reason; everything else falls back to the body.
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    if isinstance(detail, str) and detail.strip():
+        return _printable(detail.strip())[:500]
+    return _printable(resp.text[:500]) or f"HTTP {resp.status_code}"
+
+
 class Apprentice:
     def __init__(
         self,
@@ -78,6 +118,8 @@ class Apprentice:
             base_url or os.environ.get("APPRENTICE_BASE_URL") or _DEFAULT_BASE_URL
         ).rstrip("/")
         api_key = api_key or os.environ.get("APPRENTICE_API_KEY")
+        if api_key is not None:
+            _reject_unusable_api_key(api_key)
         self._api_key_present = api_key is not None
         headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
         self._http = httpx.Client(base_url=self.base_url, headers=headers, timeout=timeout)
@@ -97,24 +139,48 @@ class Apprentice:
 
     def _request(self, method: str, path: str, json: Any | None = None) -> Any:
         t0 = time.monotonic()
+        # The path carries caller-supplied names, so an absurd one would otherwise
+        # put its whole length into every message and log line, defeating the cap
+        # on the response body. httpx.InvalidURL is not an HTTPError, so an
+        # over-long path would escape the handler below.
+        shown_path = path if len(path) <= 200 else f"{path[:200]}... ({len(path)} chars)"
         try:
             resp = self._http.request(method, path, json=json)
+        except httpx.InvalidURL as exc:
+            raise ApprenticeError(f"{method} {shown_path} is not a valid URL: {exc}") from exc
         except httpx.HTTPError as exc:
-            logger.error("%s %s failed after %.0fms: %s", method, path, _ms(t0), exc)
+            logger.error("%s %s failed after %.0fms: %s", method, shown_path, _ms(t0), exc)
             raise ApprenticeError(
-                f"{method} {path} failed: {exc}. "
+                f"{method} {shown_path} failed: {exc}. "
                 f"Is the Apprentice backend reachable at {self.base_url}?"
             ) from exc
-        logger.debug("%s %s -> %s (%.0fms)", method, path, resp.status_code, _ms(t0))
+        logger.debug("%s %s -> %s (%.0fms)", method, shown_path, resp.status_code, _ms(t0))
         if resp.status_code >= 400:
-            logger.error("%s %s -> %s: %s", method, path, resp.status_code, resp.text[:500])
+            logger.error("%s %s -> %s: %s", method, shown_path, resp.status_code, resp.text[:500])
+            # The API sends a written reason in `detail`; lead with it so the first
+            # thing a reader sees is why the call failed. The route cannot tell us
+            # that: a 404 on /v1/prompts/{task} means the task has no optimized
+            # prompt yet, not that the task is missing.
             suffix = (
-                ". Get a free Apprentice API key at https://runapprentice.com"
+                " Get a free Apprentice API key at https://runapprentice.com"
                 if resp.status_code in {401, 403}
                 else ""
             )
-            raise ApprenticeError(f"{method} {path} -> {resp.status_code}: {resp.text[:500]}{suffix}")
-        return resp.json()
+            raise ApprenticeError(
+                f"{_reason(resp)} ({method} {shown_path} -> {resp.status_code}){suffix}"
+            )
+        try:
+            return resp.json()
+        except ValueError as exc:
+            # A success with no body (204) or a non-JSON body from a proxy would
+            # otherwise raise JSONDecodeError, escaping every caller that catches
+            # ApprenticeError.
+            if not resp.content:
+                return {}
+            raise ApprenticeError(
+                f"{method} {shown_path} -> {resp.status_code} returned a body that is not JSON: "
+                f"{resp.text[:200]}"
+            ) from exc
 
     def optimize(
         self,
@@ -123,6 +189,7 @@ class Apprentice:
         budget: Literal["quick", "thorough"] | None = None,
         metric: str | None = None,
     ) -> Job:
+        """Queue hosted optimization over gold and silver rows, returning its Job immediately."""
         payload = {"task": task}
         payload.update(
             {
@@ -145,6 +212,7 @@ class Apprentice:
         budget: Literal["quick", "thorough"] | None = None,
         metric: str | None = None,
     ) -> OptimizationPreview:
+        """Return metric guidance and cost estimates without queueing optimization."""
         payload = {"task": task}
         payload.update(
             {
@@ -161,21 +229,26 @@ class Apprentice:
         return OptimizationPreview.model_validate(data)
 
     def job(self, job_id: str) -> Job:
+        """Fetch current job information and return its Job proxy."""
         data = self._request("GET", f"/v1/jobs/{job_id}")
         return Job(self, JobInfo.model_validate(data))
 
     def jobs(self, task: str) -> list[JobSummary]:
+        """Return every hosted job for a task, newest first, whatever its kind."""
         data = self._request("GET", f"/v1/tasks/{quote(task, safe='')}/jobs")
         return [JobSummary.model_validate(item) for item in data]
 
     def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Request job cancellation and return the API response."""
         return dict(self._request("POST", f"/v1/jobs/{job_id}/cancel"))
 
     def local_runs(self, task: str) -> list[LocalRun]:
+        """Return tracked local training runs for a task."""
         data = self._request("GET", f"/v1/tasks/{quote(task, safe='')}/local-runs")
         return [LocalRun.model_validate(item) for item in data]
 
     def train(self, task: str) -> Job:
+        """Queue hosted training over gold rows only, returning its Job immediately."""
         data = self._request("POST", f"/v1/tasks/{quote(task, safe='')}/train", json={})
         return Job(self, JobInfo.model_validate(data))
 
@@ -185,6 +258,7 @@ class Apprentice:
         data: str | Path | None = None,
         **options: Any,
     ) -> dict[str, Any]:
+        """Optimize locally using a CSV or the task's gold and silver rows, returning results."""
         from runapprentice.local import load_csv_rows, optimize_prompt_local
 
         if data is None:
@@ -203,6 +277,7 @@ class Apprentice:
         effort: str | None = None,
         **options: Any,
     ) -> dict[str, Any]:
+        """Train locally using a CSV or the task's gold rows, returning run results."""
         from runapprentice.local import load_csv_rows, train_mlx_local
 
         if data is None:
@@ -222,6 +297,7 @@ class Apprentice:
         seed: int,
         config: dict[str, Any] | None = None,
     ) -> LocalRun:
+        """Register a local training run and return its tracking record."""
         data = self._request(
             "POST",
             "/v1/local-runs",
@@ -236,6 +312,7 @@ class Apprentice:
         return LocalRun.model_validate(data)
 
     def complete_local_run(self, run_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Submit a local run result and return the API response."""
         return dict(self._request("POST", f"/v1/local-runs/{run_id}/complete", json=payload))
 
     def feedback(
@@ -245,6 +322,7 @@ class Apprentice:
         score: float | None = None,
         note: str | None = None,
     ) -> None:
+        """Flush pending captures, then submit feedback for a trace."""
         if self._dispatcher is not None and not self._dispatcher.flush():
             raise ApprenticeError(
                 "feedback not sent because pending captures did not finish before the flush timeout"
@@ -368,6 +446,7 @@ class Apprentice:
             logger.debug("runapprentice: %s", message)
 
     def close(self) -> None:
+        """Flush pending captures and close transport resources."""
         if self._dispatcher is not None:
             self._dispatcher.flush()
             self._dispatcher.close()
@@ -387,11 +466,18 @@ class Job:
     def status(self) -> str:
         return self.info.status
 
+    @property
+    def error(self) -> str | None:
+        """Return failure detail reported for the job, if any."""
+        return self.info.error
+
     def refresh(self) -> Job:
+        """Refresh this proxy in place and return it."""
         self.info = self._client.job(self.info.job_id).info
         return self
 
     def wait(self, poll_seconds: float = 5.0, timeout_seconds: float = 3600.0) -> Job:
+        """Poll until the job finishes; raise ApprenticeError on timeout and return this Job."""
         deadline = time.monotonic() + timeout_seconds
         while self.refresh().info.status in ("queued", "running"):
             if time.monotonic() > deadline:
@@ -400,9 +486,11 @@ class Job:
         return self
 
     def cancel(self) -> dict[str, Any]:
+        """Request cancellation and return the API response."""
         return self._client.cancel_job(self.info.job_id)
 
     def report(self) -> JobReport:
+        """Return the finished job report, or raise ApprenticeError when unavailable."""
         if self.info.report is None:
             raise ApprenticeError(
                 f"job {self.info.job_id} has no report (status={self.info.status})"

{runapprentice-0.4.1 → runapprentice-0.4.2}/tests/test_cli.py

@@ -1,17 +1,40 @@
 from __future__ import annotations
 
 import json
+import os
 import stat
+from io import StringIO
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
+import httpx
 import pytest
 
-from runapprentice import ApprenticeError, cli
+from runapprentice import Apprentice, ApprenticeError, cli
 import runapprentice.local as local
 from runapprentice.models import DatasetRow, JobInfo, JobSummary
 
 
+def _mock_login_api(
+    monkeypatch: pytest.MonkeyPatch,
+    handler: Callable[[httpx.Request], httpx.Response],
+) -> None:
+    def client(*, api_key: str, **_kwargs: Any) -> Apprentice:
+        result = Apprentice(
+            api_key=api_key,
+            base_url="http://mock",
+            capture_async=False,
+        )
+        result._http = httpx.Client(
+            base_url="http://mock",
+            headers={"Authorization": f"Bearer {api_key}"},
+            transport=httpx.MockTransport(handler),
+        )
+        return result
+
+    monkeypatch.setattr(cli, "Apprentice", client)
+
+
 def test_parser_supports_required_commands() -> None:
     parser = cli.build_parser()
 
@@ -48,6 +71,33 @@ def test_parser_supports_required_commands() -> None:
     assert parser.parse_args(["cancel", "j1"]).command == "cancel"
 
 
+def test_task_not_found_prints_once(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    client = Apprentice(api_key="test", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(
+            lambda _request: httpx.Response(404, json={"detail": "task not found"})
+        ),
+    )
+    monkeypatch.setattr(cli, "Apprentice", lambda **_kwargs: client)
+    monkeypatch.setattr(cli, "CONFIG_PATH", tmp_path / "config.json")
+    monkeypatch.setattr(cli, "PENDING_DIR", tmp_path / "pending")
+
+    assert cli.main(["status", "no-such-task"]) == 1
+
+    assert capsys.readouterr().err.splitlines() == [
+        "task not found (GET /v1/datasets/no-such-task/status -> 404)"
+    ]
+
+    assert cli.main(["--json", "status", "no-such-task"]) == 1
+    payload = json.loads(capsys.readouterr().err)
+    # --json keeps both halves: the reason to show a user, and the request that
+    # produced it so the failure can still be traced.
+    assert payload["error"] == "task not found (GET /v1/datasets/no-such-task/status -> 404)"
+
+
 def test_cli_renders_all_job_kinds() -> None:
     for kind, report in (
         ("optimize", {"task": "extract", "baseline_score": 50.0}),
@@ -283,13 +333,110 @@ def test_login_writes_config_0600(
     config_path = config_dir / "config.json"
     monkeypatch.setattr(cli, "CONFIG_DIR", config_dir)
     monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys.stdin, "isatty", lambda: True)
     monkeypatch.setattr("runapprentice.cli.getpass.getpass", lambda _: "secret-key")
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(200, json=[]))
 
     assert cli.main(["login"]) == 0
 
     assert json.loads(config_path.read_text(encoding="utf-8")) == {"api_key": "secret-key"}
     assert stat.S_IMODE(config_path.stat().st_mode) == 0o600
-    assert "secret-key" not in capsys.readouterr().out
+    out = capsys.readouterr().out
+    assert "secret-key" not in out
+    assert "API key verified" in out
+
+
+def test_login_rejects_invalid_key_without_writing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("invalid-key\n"))
+    _mock_login_api(
+        monkeypatch,
+        lambda _request: httpx.Response(401, json={"detail": "invalid API key"}),
+    )
+
+    assert cli.main(["login"]) == 1
+    assert not config_path.exists()
+    assert capsys.readouterr().err == "API key was rejected and was not saved.\n"
+
+
+def test_failed_login_does_not_clobber_existing_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_path = tmp_path / "config.json"
+    original = '{"api_key": "working-key"}\n'
+    config_path.write_text(original, encoding="utf-8")
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("invalid-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(403, json={"detail": "forbidden"}))
+
+    assert cli.main(["login"]) == 1
+    assert config_path.read_text(encoding="utf-8") == original
+
+
+def test_login_reports_unreachable_api_differently_from_rejected_key(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(cli, "CONFIG_PATH", tmp_path / "config.json")
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("candidate-key\n"))
+
+    def unreachable(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("connection refused", request=request)
+
+    _mock_login_api(monkeypatch, unreachable)
+
+    assert cli.main(["login"]) == 1
+    err = capsys.readouterr().err
+    assert "API is unavailable" in err
+    assert "rejected" not in err
+
+
+def test_login_reports_server_error_as_unavailable(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("candidate-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(503))
+
+    assert cli.main(["login"]) == 1
+    assert not config_path.exists()
+    assert "API is unavailable" in capsys.readouterr().err
+
+
+def test_corrupt_config_reports_clean_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_path = tmp_path / "config.json"
+    config_path.write_text("not json{", encoding="utf-8")
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+
+    assert cli.main(["status", "extract"]) == 1
+    err = capsys.readouterr().err
+    assert "invalid JSON" in err
+    assert "apprentice login" in err
+    assert "Traceback" not in err
+
+
+def test_login_reads_piped_stdin_and_validates_it(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("  piped-key  \n"))
+
+    def validate(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/tasks"
+        assert request.headers["Authorization"] == "Bearer piped-key"
+        return httpx.Response(200, json=[{"name": "extract"}])
+
+    _mock_login_api(monkeypatch, validate)
+
+    assert cli.main(["--json", "login"]) == 0
+    assert json.loads(config_path.read_text(encoding="utf-8")) == {"api_key": "piped-key"}
+    assert json.loads(capsys.readouterr().out)["validated"] is True
 
 
 def test_env_api_key_overrides_config(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -388,3 +535,158 @@ def test_local_optimize_missing_dspy_message(
 
     assert cli.main(["optimize", "extract", "--local", "--data", str(data)]) == 1
     assert "pip install 'runapprentice[optimize]'" in capsys.readouterr().err
+
+
+def test_login_rejects_a_key_containing_whitespace(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A two-line file piped in produces a key with a newline in it.
+
+    httpx raises LocalProtocolError on the header before sending, so without
+    this guard the user is told the API is unavailable when nothing was sent.
+    """
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("good-key\nJUNK-SECOND-LINE\n"))
+
+    def explode(_request: httpx.Request) -> httpx.Response:
+        raise AssertionError("a malformed key must never reach the network")
+
+    _mock_login_api(monkeypatch, explode)
+
+    assert cli.main(["login"]) == 1
+    assert not config_path.exists()
+    assert capsys.readouterr().err == "API key contains whitespace, so it was not saved.\n"
+
+
+def test_login_directory_is_not_world_writable_under_a_permissive_umask(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """mkdir's mode is masked by the umask, so it must be set explicitly.
+
+    A world-writable parent lets another local account replace the key file no
+    matter what the file's own mode is.
+    """
+    config_path = tmp_path / "nested" / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("good-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(200, json=[]))
+
+    previous = os.umask(0)
+    try:
+        assert cli.main(["login"]) == 0
+    finally:
+        os.umask(previous)
+
+    assert stat.S_IMODE(config_path.parent.stat().st_mode) == 0o700
+    assert stat.S_IMODE(config_path.stat().st_mode) == 0o600
+
+
+def test_config_with_a_non_string_api_key_reports_instead_of_silently_ignoring(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_path = tmp_path / "config.json"
+    config_path.write_text(json.dumps({"api_key": 12345}), encoding="utf-8")
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.delenv("APPRENTICE_API_KEY", raising=False)
+
+    assert cli.main(["status", "any-task"]) == 1
+    assert "api_key must be a string" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "key",
+    ["ap_live_café", "ap_live_\U0001f511", "ap_live_a\x01b"],
+    ids=["accented", "emoji", "control-char"],
+)
+def test_login_rejects_a_key_that_is_not_printable_ascii(
+    key: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """httpx encodes headers as ASCII and raises UnicodeEncodeError otherwise.
+
+    That is not an httpx.HTTPError, so without this guard it escapes _login's
+    handler and reaches the user as a traceback.
+    """
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO(key + "\n"))
+
+    def explode(_request: httpx.Request) -> httpx.Response:
+        raise AssertionError("a malformed key must never reach the network")
+
+    _mock_login_api(monkeypatch, explode)
+
+    assert cli.main(["login"]) == 1
+    assert not config_path.exists()
+    assert "printable ASCII" in capsys.readouterr().err
+
+
+def test_login_never_leaves_the_key_world_readable(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The key must never exist on disk at a readable mode, even briefly.
+
+    write-then-chmod leaves it at 0666 under a permissive umask until the chmod
+    lands; a process killed in that window leaves it that way permanently. This
+    asserts the mode observed at creation, not just the final mode.
+    """
+    config_path = tmp_path / "nested" / "config.json"
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("good-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(200, json=[]))
+
+    seen_modes: list[int] = []
+    real_replace = os.replace
+
+    def spy(src: Any, dst: Any) -> None:
+        # The moment before the file becomes visible at its final path.
+        seen_modes.append(stat.S_IMODE(os.stat(src).st_mode))
+        real_replace(src, dst)
+
+    monkeypatch.setattr(cli.os, "replace", spy)
+
+    previous = os.umask(0)
+    try:
+        assert cli.main(["login"]) == 0
+    finally:
+        os.umask(previous)
+
+    assert seen_modes == [0o600], f"key was written at {[oct(m) for m in seen_modes]}"
+    assert stat.S_IMODE(config_path.stat().st_mode) == 0o600
+
+
+def test_login_replaces_a_symlinked_config_instead_of_its_target(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    victim = tmp_path / "victim.txt"
+    victim.write_text("IMPORTANT DATA", encoding="utf-8")
+    config_path = tmp_path / "config.json"
+    config_path.symlink_to(victim)
+    monkeypatch.setattr(cli, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("good-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(200, json=[]))
+
+    assert cli.main(["login"]) == 0
+
+    assert victim.read_text(encoding="utf-8") == "IMPORTANT DATA"
+    assert not config_path.is_symlink()
+    assert json.loads(config_path.read_text(encoding="utf-8"))["api_key"] == "good-key"
+
+
+def test_login_reports_a_filesystem_failure_instead_of_a_traceback(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """The key validated, so only the write can still fail.
+
+    In --json mode a traceback also means no JSON is emitted at all, which breaks
+    the contract that --json always prints one object.
+    """
+    # A path whose parent cannot exist: /dev/null is a file, not a directory.
+    monkeypatch.setattr(cli, "CONFIG_PATH", Path("/dev/null/nope/config.json"))
+    monkeypatch.setattr(cli.sys, "stdin", StringIO("good-key\n"))
+    _mock_login_api(monkeypatch, lambda _request: httpx.Response(200, json=[]))
+
+    assert cli.main(["--json", "login"]) == 1
+
+    payload = json.loads(capsys.readouterr().err)
+    assert "Could not save the API key" in payload["error"]

{runapprentice-0.4.1 → runapprentice-0.4.2}/tests/test_client.py

@@ -1,6 +1,7 @@
 """Control-plane client: upload, status, optimize/job lifecycle, error clarity."""
 
 import json
+import logging
 from pathlib import Path
 import re
 import threading
@@ -10,7 +11,7 @@ from typing import Any
 import httpx
 import pytest
 
-from runapprentice import Apprentice, ApprenticeError, TraceRecord
+from runapprentice import Apprentice, ApprenticeError, Job, TraceRecord
 from runapprentice._capture import CaptureDispatcher
 import runapprentice.local as local
 from runapprentice.models import (
@@ -38,6 +39,14 @@ def make_client(routes: dict[str, Any]) -> tuple[Apprentice, list[dict[str, Any]
     return client, received
 
 
+def test_package_logging_is_silent_by_default(capsys: pytest.CaptureFixture[str]) -> None:
+    logger = logging.getLogger("runapprentice")
+
+    assert any(isinstance(handler, logging.NullHandler) for handler in logger.handlers)
+    logger.error("must stay silent")
+    assert capsys.readouterr().err == ""
+
+
 def test_dataset_upload_from_rows() -> None:
     client, received = make_client(
         {
@@ -234,6 +243,15 @@ def test_optimize_and_job_lifecycle() -> None:
     assert report.optimized_score == 88.0
 
 
+def test_job_error_is_reachable() -> None:
+    job = Job(
+        Apprentice(api_key="test", base_url="http://mock", capture_async=False),
+        JobInfo(job_id="j1", task="t1", kind="train", status="failed", error="training failed"),
+    )
+
+    assert job.error == "training failed"
+
+
 def test_optimization_report_round_trips_every_api_field() -> None:
     payload = {
         "task": "extract",
@@ -603,6 +621,79 @@ def test_http_4xx_raises_with_body() -> None:
         client.tasks.create("nope")
 
 
+def test_error_leads_with_the_reason_the_api_gave() -> None:
+    client, _ = make_client({})
+
+    with pytest.raises(ApprenticeError) as exc_info:
+        client.datasets.status("no-such-task")
+
+    assert str(exc_info.value) == (
+        "not found (GET /v1/datasets/no-such-task/status -> 404)"
+    )
+
+
+@pytest.mark.parametrize(
+    "body",
+    [["upstream failed"], "plain string", 42, None],
+    ids=["list", "string", "number", "null"],
+)
+def test_error_bodies_that_are_not_json_objects_still_raise_apprentice_error(body: object) -> None:
+    """A gateway can return any JSON shape, not the object FastAPI sends.
+
+    Reading `.get("detail")` off a list or string raises AttributeError, which
+    escapes past every caller that catches ApprenticeError.
+    """
+    client = Apprentice(api_key="k", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(lambda _request: httpx.Response(500, json=body)),
+    )
+
+    with pytest.raises(ApprenticeError):
+        client._request("GET", "/v1/jobs/x")
+
+
+def test_a_long_server_detail_is_capped() -> None:
+    client = Apprentice(api_key="k", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(
+            lambda _request: httpx.Response(500, json={"detail": "x" * 5000})
+        ),
+    )
+
+    with pytest.raises(ApprenticeError) as exc_info:
+        client._request("GET", "/v1/jobs/x")
+
+    assert len(str(exc_info.value)) < 700
+
+
+def test_a_404_does_not_claim_the_task_is_missing() -> None:
+    """A 404 on a task-scoped route often means something else is missing.
+
+    /v1/templates/{task} and /v1/prompts/{task} both 404 for a task that exists
+    and is healthy, so reading "task not found" off the route shape states
+    something false. Verified against production: a template fetch for a task
+    with 24 rows and a succeeded optimize job returns 404 "no template".
+    """
+    client = Apprentice(api_key="k", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(
+            lambda _request: httpx.Response(
+                404, json={"detail": "no optimized prompt for task 'live' yet. Run optimize first."}
+            )
+        ),
+    )
+
+    with pytest.raises(ApprenticeError) as exc_info:
+        client._request("GET", "/v1/prompts/live")
+
+    message = str(exc_info.value)
+    assert message.startswith("no optimized prompt for task 'live' yet.")
+    assert "was not found" not in message
+
+
 def test_auth_error_mentions_free_key() -> None:
     client = Apprentice(api_key=None, base_url="http://mock", capture_async=False)
     client._http = httpx.Client(
@@ -795,3 +886,82 @@ def test_task_names_with_url_delimiters_are_quoted() -> None:
     client.datasets.status("a/b?c")
 
     assert seen[0] == b"/v1/datasets/a%2Fb%3Fc/status"
+
+
+def test_a_success_with_no_body_does_not_leak_a_json_error() -> None:
+    """204 and non-JSON success bodies must not escape as JSONDecodeError.
+
+    A caller catching ApprenticeError would otherwise crash on a proxy response.
+    """
+    client = Apprentice(api_key="k", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(lambda _request: httpx.Response(204)),
+    )
+
+    assert client._request("DELETE", "/v1/keys/x") == {}
+
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(lambda _request: httpx.Response(200, text="<html>hi</html>")),
+    )
+    with pytest.raises(ApprenticeError, match="not JSON"):
+        client._request("GET", "/v1/jobs/x")
+
+
+@pytest.mark.parametrize(
+    "key", ["ap_live_café", "ap_live_a b", "ap_live_\x01"], ids=["non-ascii", "space", "control"]
+)
+def test_client_rejects_a_key_that_cannot_become_a_header(key: str) -> None:
+    """Every path that supplies a key must fail the same way.
+
+    httpx raises UnicodeEncodeError deep in the transport otherwise, which is not
+    an ApprenticeError and reaches a CLI user as a traceback.
+    """
+    with pytest.raises(ApprenticeError):
+        Apprentice(api_key=key, base_url="http://mock", capture_async=False)
+
+
+def test_api_key_from_the_environment_is_validated_too(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("APPRENTICE_API_KEY", "ap_live_café")
+    with pytest.raises(ApprenticeError):
+        Apprentice(base_url="http://mock", capture_async=False)
+
+
+def test_an_absurd_path_is_capped_and_never_leaks_invalid_url() -> None:
+    """A caller-supplied name lands in the path, so it must not size the message.
+
+    The 500-char body cap is defeated if the path itself is unbounded, and
+    httpx.InvalidURL is not an HTTPError so it would escape the handler.
+    """
+    client = Apprentice(api_key="safe", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(lambda _request: httpx.Response(400, json={"detail": "bad"})),
+    )
+
+    for size in (60_000, 66_000):
+        with pytest.raises(ApprenticeError) as exc_info:
+            client.datasets.status("x" * size)
+        assert len(str(exc_info.value)) < 400, f"message was {len(str(exc_info.value))} chars"
+
+
+def test_a_hostile_server_message_cannot_repaint_the_terminal() -> None:
+    """Error text is server-controlled and lands in terminals and CI logs.
+
+    Escape sequences there can clear the screen and rewrite earlier lines, so a
+    backend could make its own error read as a success.
+    """
+    hostile = "ok\x1b[2J\x1b[Hnothing to see\x07\rFAKE: login succeeded"
+    client = Apprentice(api_key="k", base_url="http://mock", capture_async=False)
+    client._http = httpx.Client(
+        base_url="http://mock",
+        transport=httpx.MockTransport(lambda _request: httpx.Response(400, json={"detail": hostile})),
+    )
+
+    with pytest.raises(ApprenticeError) as exc_info:
+        client._request("GET", "/v1/jobs/x")
+
+    message = str(exc_info.value)
+    assert "\x1b" not in message and "\x07" not in message and "\r" not in message
+    assert "FAKE: login succeeded" in message  # kept, but inert