runapprentice 0.2.1__tar.gz → 0.4.0__tar.gz

{runapprentice-0.2.1 → runapprentice-0.4.0}/.gitignore

@@ -34,5 +34,21 @@ optimized_program.json
 apprentice-ui/codex_working.md
 .codex/
 
-# Local dev databases
+# Local dev databases (and their manual backups)
 *.db
+*.db.bak*
+
+# Local machine config with secrets — never commit
+.mcp.json
+
+# Local working artifacts, not repo content
+# (.claude/skills holds symlinks into the ignored .agents/ dir — dangling on a fresh clone)
+.claude/skills/
+outputs/
+test-sdk/
+.agents/
+skills-lock.json
+docs/personal_learning.md
+.uv-cache/
+spike/Capture-*.png
+apprentice-ui/ClaudeDesign/screenshots/localhost-*.png

{runapprentice-0.2.1 → runapprentice-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runapprentice
-Version: 0.2.1
+Version: 0.4.0
 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
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 The Python SDK for [Apprentice](https://runapprentice.com), a tool that cuts frontier-LLM cost
 on repeatable tasks. You give it a dataset of inputs and correct outputs for one task (uploaded
-as a CSV, or captured live from a LangChain app with one callback). Apprentice runs prompt
+as a CSV, or captured live from an OpenAI or LangChain app). Apprentice runs prompt
 optimization (DSPy GEPA) against the verified rows (gold plus silver), or fine-tunes a small open model on
 your Mac, and reports the score change on a held-out slice, so the gain is measured, never
 claimed. Gated, eval-verified takeover of production traffic is still in development.
@@ -89,7 +89,54 @@ print(report.baseline_score, "->", report.optimized_score)
 
 # 4. Pull the optimized prompt back into your code (versioned)
 best = client.prompts.get("ticket-triage")
-print(best.version, best.text)
+resp = OpenAI().chat.completions.create(   # from openai import OpenAI
+    model="gpt-5-mini",
+    messages=best.messages(input=ticket_text),
+)
+```
+
+`datasets.upload()` replaces prior rows for this task where the source is an upload and
+the tier is silver or raw. Gold rows and SDK-captured traces stay intact. Omitting `prompt`
+or passing `None` clears the task's stored baseline prompt. Check
+`DatasetStatus.replaced_rows` to see how many rows were removed.
+
+`best.text` is instruction text, not a template. It holds no input placeholder and often
+contains literal JSON braces, so `best.text.format(input=...)` raises `KeyError` and
+`best.text.replace("{input}", ...)` drops the ticket with no error at all. `messages()`
+renders the message shape the backend recorded when it scored this version. Match the rest
+of the request too if you want the reported score to describe your call: JSON metrics were
+scored with `response_format={"type": "json_object"}` (on the Responses API, that is
+`text={"format": {"type": "json_object"}}`), on the model in
+`report.detail["student_model"]`. Versions optimized before 0.4.0 carry no recorded shape
+and fall back to the task's current baseline prompt. The keyword names are the artifact's `input_variables`:
+`input` for a plain task, `question` and `context` for RAG, your own names if you
+registered a template.
+
+## Live capture: OpenAI (one wrapper)
+
+```python
+from openai import OpenAI
+from runapprentice.openai import wrap
+
+openai = wrap(OpenAI(), client, task="ticket-triage")
+
+response = openai.responses.create(
+    model="gpt-5-mini",
+    input="Triage this ticket.",
+)
+# create() and parse() are captured, on chat.completions and responses alike
+# (parse posts on its own, so patching create alone would miss it).
+```
+
+Both sync `OpenAI` and async `AsyncOpenAI` clients work. Capture is fail-open and
+returns every OpenAI result unchanged. Calls with `stream=True` and calls through
+`responses.stream(...)` pass through uncaptured because reading them would consume
+the caller's stream.
+
+**PII redaction** runs in your process, before anything is transmitted:
+
+```python
+openai = wrap(OpenAI(), client, task="ticket-triage", redact=lambda s: my_scrubber(s))
 ```
 
 ## Live capture: LangChain (one line, zero code changes)
@@ -226,17 +273,33 @@ count and the minimum).
 |---|---|---|
 | `Apprentice(api_key=, base_url=, timeout=)` | client | `ApprenticeError` on bad config |
 | `client.tasks.create(name, metric="auto")` | dict (`created` bool) | `ApprenticeError` on HTTP failure |
-| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` | same; also if both/neither of path/rows |
+| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` including `replaced_rows` | same; also if both/neither of path/rows |
 | `client.datasets.status(task)` | `DatasetStatus(gold, silver, raw, ready_for_optimization)` | same |
 | `client.prompts.register(task, template)` | dict | `ImportError` if a LangChain template is passed without the `[langchain]` extra |
 | `client.prompts.to_langchain(task= or artifact=)` | LangChain prompt | `ImportError` without the `[langchain]` extra |
-| `client.optimize(task)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.optimize(task, baseline_prompt=None, budget=None, metric=None)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.preview_optimization(task, baseline_prompt=None, budget=None, metric=None)` | `OptimizationPreview` | `ApprenticeError` on API failure |
+| `client.train(task)` | `Job` | 400 if fewer gold rows than the backend's training minimum |
 | `client.job(job_id)` / `job.refresh()` / `job.wait(poll_seconds=, timeout_seconds=)` | `Job` | `ApprenticeError` on timeout |
-| `job.report()` | `OptimizationReport(baseline_score, optimized_score, optimized_prompt, ...)` | if job has no report |
-| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score)` | 404 if never optimized |
+| `client.cancel_job(job_id)` | dict (`cancel_requested`, `status`) | 409 if job is not cancellable |
+| `job.cancel()` | dict (`cancel_requested`, `status`) | 409 if job is not cancellable |
+| `client.jobs(task)` | `list[JobSummary]` | `ApprenticeError` on API failure |
+| `client.local_runs(task)` | `list[LocalRun]` | `ApprenticeError` on API failure |
+| `client.datasets.rows(task, tier, limit=200)` | `list[DatasetRow]` | `ApprenticeError` on API failure |
+| `client.optimize_local(task, data=None, **options)` | dict (local GEPA result) | `ApprenticeError` if no `data` and no API key |
+| `client.train_local(task, data=None, effort=None, **options)` | dict (local MLX result) | `ApprenticeError` if no `data` and no API key |
+| `client.register_local_run(task, base_model, dataset_row_count, seed, config=None)` | `LocalRun` | `ApprenticeError` on API failure |
+| `client.complete_local_run(run_id, payload)` | dict | `ApprenticeError` on API failure |
+| `client.capture(task, output, input= or inputs=, model=, latency_ms=, ...)` | trace_id or None | **never raises** |
+| `client.flush_captures(timeout=2.0)` | None (blocks until buffered traces deliver or timeout; no-op in sync mode) | nothing by design |
+| `client.close()` | None (flushes and closes transport) | nothing by design |
+| `job.report()` | typed optimize, train, or generate report; raw dict for future shapes | if job has no report |
+| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score, baseline_prompt)` | 404 if never optimized |
+| `PromptVersion.messages(user_prompt=None, **inputs)` | `list[dict]` reproducing the scored call | `ValueError` if a keyword is not one of the artifact's `input_variables` |
 | `client.prompts.history(task)` | `list[PromptVersion]` | `ApprenticeError` on API failure |
 | `client.feedback(trace_id, good=, score=, note=)` | None | 404 unknown trace; `ApprenticeError` if pending captures cannot drain in time, or on API failure |
 | `client.post_trace_failopen(record)` | trace_id or None | **never raises** |
+| `wrap(openai_client, client, task, redact=None)` | the same OpenAI client, with chat completions and responses captured | **never raises from capture; OpenAI call errors pass through unchanged** |
 | `ApprenticeCallback(task, client, redact=None)` | LangChain callback | **never raises into your chain** |
 
 ## Data tiers (how your rows are treated)

{runapprentice-0.2.1 → runapprentice-0.4.0}/README.md

@@ -2,7 +2,7 @@
 
 The Python SDK for [Apprentice](https://runapprentice.com), a tool that cuts frontier-LLM cost
 on repeatable tasks. You give it a dataset of inputs and correct outputs for one task (uploaded
-as a CSV, or captured live from a LangChain app with one callback). Apprentice runs prompt
+as a CSV, or captured live from an OpenAI or LangChain app). Apprentice runs prompt
 optimization (DSPy GEPA) against the verified rows (gold plus silver), or fine-tunes a small open model on
 your Mac, and reports the score change on a held-out slice, so the gain is measured, never
 claimed. Gated, eval-verified takeover of production traffic is still in development.
@@ -60,7 +60,54 @@ print(report.baseline_score, "->", report.optimized_score)
 
 # 4. Pull the optimized prompt back into your code (versioned)
 best = client.prompts.get("ticket-triage")
-print(best.version, best.text)
+resp = OpenAI().chat.completions.create(   # from openai import OpenAI
+    model="gpt-5-mini",
+    messages=best.messages(input=ticket_text),
+)
+```
+
+`datasets.upload()` replaces prior rows for this task where the source is an upload and
+the tier is silver or raw. Gold rows and SDK-captured traces stay intact. Omitting `prompt`
+or passing `None` clears the task's stored baseline prompt. Check
+`DatasetStatus.replaced_rows` to see how many rows were removed.
+
+`best.text` is instruction text, not a template. It holds no input placeholder and often
+contains literal JSON braces, so `best.text.format(input=...)` raises `KeyError` and
+`best.text.replace("{input}", ...)` drops the ticket with no error at all. `messages()`
+renders the message shape the backend recorded when it scored this version. Match the rest
+of the request too if you want the reported score to describe your call: JSON metrics were
+scored with `response_format={"type": "json_object"}` (on the Responses API, that is
+`text={"format": {"type": "json_object"}}`), on the model in
+`report.detail["student_model"]`. Versions optimized before 0.4.0 carry no recorded shape
+and fall back to the task's current baseline prompt. The keyword names are the artifact's `input_variables`:
+`input` for a plain task, `question` and `context` for RAG, your own names if you
+registered a template.
+
+## Live capture: OpenAI (one wrapper)
+
+```python
+from openai import OpenAI
+from runapprentice.openai import wrap
+
+openai = wrap(OpenAI(), client, task="ticket-triage")
+
+response = openai.responses.create(
+    model="gpt-5-mini",
+    input="Triage this ticket.",
+)
+# create() and parse() are captured, on chat.completions and responses alike
+# (parse posts on its own, so patching create alone would miss it).
+```
+
+Both sync `OpenAI` and async `AsyncOpenAI` clients work. Capture is fail-open and
+returns every OpenAI result unchanged. Calls with `stream=True` and calls through
+`responses.stream(...)` pass through uncaptured because reading them would consume
+the caller's stream.
+
+**PII redaction** runs in your process, before anything is transmitted:
+
+```python
+openai = wrap(OpenAI(), client, task="ticket-triage", redact=lambda s: my_scrubber(s))
 ```
 
 ## Live capture: LangChain (one line, zero code changes)
@@ -197,17 +244,33 @@ count and the minimum).
 |---|---|---|
 | `Apprentice(api_key=, base_url=, timeout=)` | client | `ApprenticeError` on bad config |
 | `client.tasks.create(name, metric="auto")` | dict (`created` bool) | `ApprenticeError` on HTTP failure |
-| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` | same; also if both/neither of path/rows |
+| `client.datasets.upload(task, path= or rows=, input_col=, output_col=, prompt=)` | `DatasetStatus` including `replaced_rows` | same; also if both/neither of path/rows |
 | `client.datasets.status(task)` | `DatasetStatus(gold, silver, raw, ready_for_optimization)` | same |
 | `client.prompts.register(task, template)` | dict | `ImportError` if a LangChain template is passed without the `[langchain]` extra |
 | `client.prompts.to_langchain(task= or artifact=)` | LangChain prompt | `ImportError` without the `[langchain]` extra |
-| `client.optimize(task)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.optimize(task, baseline_prompt=None, budget=None, metric=None)` | `Job` | 400 if fewer than the backend's configured verified-row minimum (20 by default) |
+| `client.preview_optimization(task, baseline_prompt=None, budget=None, metric=None)` | `OptimizationPreview` | `ApprenticeError` on API failure |
+| `client.train(task)` | `Job` | 400 if fewer gold rows than the backend's training minimum |
 | `client.job(job_id)` / `job.refresh()` / `job.wait(poll_seconds=, timeout_seconds=)` | `Job` | `ApprenticeError` on timeout |
-| `job.report()` | `OptimizationReport(baseline_score, optimized_score, optimized_prompt, ...)` | if job has no report |
-| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score)` | 404 if never optimized |
+| `client.cancel_job(job_id)` | dict (`cancel_requested`, `status`) | 409 if job is not cancellable |
+| `job.cancel()` | dict (`cancel_requested`, `status`) | 409 if job is not cancellable |
+| `client.jobs(task)` | `list[JobSummary]` | `ApprenticeError` on API failure |
+| `client.local_runs(task)` | `list[LocalRun]` | `ApprenticeError` on API failure |
+| `client.datasets.rows(task, tier, limit=200)` | `list[DatasetRow]` | `ApprenticeError` on API failure |
+| `client.optimize_local(task, data=None, **options)` | dict (local GEPA result) | `ApprenticeError` if no `data` and no API key |
+| `client.train_local(task, data=None, effort=None, **options)` | dict (local MLX result) | `ApprenticeError` if no `data` and no API key |
+| `client.register_local_run(task, base_model, dataset_row_count, seed, config=None)` | `LocalRun` | `ApprenticeError` on API failure |
+| `client.complete_local_run(run_id, payload)` | dict | `ApprenticeError` on API failure |
+| `client.capture(task, output, input= or inputs=, model=, latency_ms=, ...)` | trace_id or None | **never raises** |
+| `client.flush_captures(timeout=2.0)` | None (blocks until buffered traces deliver or timeout; no-op in sync mode) | nothing by design |
+| `client.close()` | None (flushes and closes transport) | nothing by design |
+| `job.report()` | typed optimize, train, or generate report; raw dict for future shapes | if job has no report |
+| `client.prompts.get(task, version=None)` | `PromptVersion(version, text, score, baseline_prompt)` | 404 if never optimized |
+| `PromptVersion.messages(user_prompt=None, **inputs)` | `list[dict]` reproducing the scored call | `ValueError` if a keyword is not one of the artifact's `input_variables` |
 | `client.prompts.history(task)` | `list[PromptVersion]` | `ApprenticeError` on API failure |
 | `client.feedback(trace_id, good=, score=, note=)` | None | 404 unknown trace; `ApprenticeError` if pending captures cannot drain in time, or on API failure |
 | `client.post_trace_failopen(record)` | trace_id or None | **never raises** |
+| `wrap(openai_client, client, task, redact=None)` | the same OpenAI client, with chat completions and responses captured | **never raises from capture; OpenAI call errors pass through unchanged** |
 | `ApprenticeCallback(task, client, redact=None)` | LangChain callback | **never raises into your chain** |
 
 ## Data tiers (how your rows are treated)

{runapprentice-0.2.1 → runapprentice-0.4.0}/pyproject.toml

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

{runapprentice-0.2.1 → runapprentice-0.4.0}/src/runapprentice/__init__.py

@@ -4,12 +4,16 @@ from runapprentice.client import Apprentice, ApprenticeError, Job, enable_debug_
 from runapprentice.models import (
     DatasetRow,
     DatasetStatus,
+    GenerationReport,
     JobInfo,
+    JobReport,
     JobSummary,
     LocalRun,
     OptimizationReport,
+    OptimizationPreview,
     PromptVersion,
     TraceRecord,
+    TrainingReport,
 )
 
 __all__ = [
@@ -19,12 +23,16 @@ __all__ = [
     "Job",
     "DatasetRow",
     "DatasetStatus",
+    "GenerationReport",
     "JobInfo",
+    "JobReport",
     "JobSummary",
     "LocalRun",
     "OptimizationReport",
+    "OptimizationPreview",
     "PromptVersion",
     "TraceRecord",
+    "TrainingReport",
 ]
 
 # Single source of truth is pyproject.toml; read it from package metadata so

{runapprentice-0.2.1 → runapprentice-0.4.0}/src/runapprentice/cli.py

@@ -13,7 +13,13 @@ from typing import Any
 
 from runapprentice.client import Apprentice, ApprenticeError
 from runapprentice import local as _local
-from runapprentice.models import JobInfo, JobSummary, OptimizationReport
+from runapprentice.models import (
+    JobInfo,
+    JobReport,
+    JobSummary,
+    OptimizationPreview,
+    OptimizationReport,
+)
 
 CONFIG_DIR = Path("~/.apprentice").expanduser()
 CONFIG_PATH = CONFIG_DIR / "config.json"
@@ -107,6 +113,22 @@ def build_parser() -> argparse.ArgumentParser:
         type=Path,
         help="CSV with input,output columns; required for --local unless an API key is set",
     )
+    optimize.add_argument(
+        "--budget",
+        choices=("quick", "thorough"),
+        help="hosted optimization budget; omit for balanced default",
+    )
+    optimize.add_argument("--metric", help="metric used to score this hosted run")
+    optimize.add_argument(
+        "--prompt-file",
+        type=Path,
+        help="read hosted run baseline prompt from this UTF-8 text file",
+    )
+    optimize.add_argument(
+        "--preview",
+        action="store_true",
+        help="show hosted metric and cost estimate without enqueueing a run",
+    )
     optimize.set_defaults(func=_optimize)
 
     train = sub.add_parser(
@@ -153,6 +175,10 @@ def build_parser() -> argparse.ArgumentParser:
     job = sub.add_parser("job", help="details for one hosted job")
     job.add_argument("job_id", help="job id from `apprentice jobs`")
     job.set_defaults(func=_job)
+
+    cancel = sub.add_parser("cancel", help="cancel a queued or running hosted job")
+    cancel.add_argument("job_id", help="job id from `apprentice jobs`")
+    cancel.set_defaults(func=_cancel)
     return parser
 
 
@@ -180,6 +206,11 @@ def _status(args: argparse.Namespace, client: Apprentice) -> int:
 
 def _optimize(args: argparse.Namespace, client: Apprentice) -> int:
     if args.local:
+        if args.budget or args.metric or args.prompt_file or args.preview:
+            return _fail(
+                "--budget, --metric, --prompt-file, and --preview apply to hosted optimization",
+                bool(args.json),
+            )
         return _optimize_local(
             args.task,
             args.data,
@@ -187,8 +218,39 @@ def _optimize(args: argparse.Namespace, client: Apprentice) -> int:
             bool(args.json),
             bool(args._api_key_present),
         )
-    job = client.optimize(args.task).wait()
+    baseline_prompt = None
+    if args.prompt_file is not None:
+        try:
+            baseline_prompt = args.prompt_file.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ApprenticeError(f"could not read prompt file {args.prompt_file}: {exc}") from exc
+    if args.preview:
+        preview = client.preview_optimization(
+            args.task,
+            baseline_prompt=baseline_prompt,
+            budget=args.budget,
+            metric=args.metric,
+        )
+        return _emit(
+            preview.model_dump(mode="json"),
+            _preview_line(preview),
+            bool(args.json),
+        )
+    job = client.optimize(
+        args.task,
+        baseline_prompt=baseline_prompt,
+        budget=args.budget,
+        metric=args.metric,
+    ).wait()
     payload = job.info.model_dump(mode="json")
+    if job.info.status != "succeeded":
+        # Exit nonzero, or a caller that checks the exit code (every script and
+        # every agent) reads a failed run as a shipped one.
+        return _fail(
+            f"optimize {job.info.status}: {job.info.error or 'no error reported'}",
+            bool(args.json),
+            payload=payload,
+        )
     return _emit(payload, _report_line(job.info.report), bool(args.json))
 
 
@@ -222,6 +284,11 @@ def _job(args: argparse.Namespace, client: Apprentice) -> int:
     return _emit(job.info.model_dump(mode="json"), _job_info_line(job.info), bool(args.json))
 
 
+def _cancel(args: argparse.Namespace, client: Apprentice) -> int:
+    result = client.cancel_job(args.job_id)
+    return _emit(result, f"cancel requested: {args.job_id} ({result['status']})", bool(args.json))
+
+
 def _train_local(
     task: str,
     client: Apprentice,
@@ -424,20 +491,33 @@ def _job_info_line(job: JobInfo) -> str:
     return f"{job.job_id} {job.kind} {job.status}"
 
 
-def _report_line(report: OptimizationReport | None) -> str:
+def _report_line(report: JobReport | None) -> str:
     if report is None:
         return "optimize finished with no report"
+    if not isinstance(report, OptimizationReport):
+        return "optimize finished with an unrecognized report"
     return f"optimize done: baseline={report.baseline_score} optimized={report.optimized_score}"
 
 
+def _preview_line(preview: OptimizationPreview) -> str:
+    estimate = preview.estimate
+    return (
+        f"optimize preview: metric={preview.eval_metric} budget={estimate.get('budget')} "
+        f"rows={estimate.get('rows')} cost_usd={estimate.get('cost_usd_low')}"
+        f"-{estimate.get('cost_usd_high')}"
+    )
+
+
 def _emit(payload: dict[str, Any], text: str, as_json: bool) -> int:
     print(json.dumps(payload, sort_keys=True) if as_json else text)
     return 0
 
 
-def _fail(message: str, as_json: bool) -> int:
+def _fail(message: str, as_json: bool, payload: dict[str, Any] | None = None) -> int:
     if as_json:
-        print(json.dumps({"error": message}, sort_keys=True), file=sys.stderr)
+        # Keep the job fields alongside the error so a caller parsing --json still
+        # gets the job id and status it needs to investigate.
+        print(json.dumps({**(payload or {}), "error": message}, sort_keys=True), file=sys.stderr)
     else:
         print(message, file=sys.stderr)
     return 1

{runapprentice-0.2.1 → runapprentice-0.4.0}/src/runapprentice/client.py

@@ -16,7 +16,7 @@ import os
 import time
 import uuid
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import httpx
 
@@ -25,9 +25,10 @@ from runapprentice.models import (
     DatasetRow,
     DatasetStatus,
     JobInfo,
+    JobReport,
     JobSummary,
     LocalRun,
-    OptimizationReport,
+    OptimizationPreview,
     PromptVersion,
     TraceRecord,
 )
@@ -114,10 +115,50 @@ class Apprentice:
             raise ApprenticeError(f"{method} {path} -> {resp.status_code}: {resp.text[:500]}{suffix}")
         return resp.json()
 
-    def optimize(self, task: str) -> Job:
-        data = self._request("POST", "/v1/optimize", json={"task": task})
+    def optimize(
+        self,
+        task: str,
+        baseline_prompt: str | None = None,
+        budget: Literal["quick", "thorough"] | None = None,
+        metric: str | None = None,
+    ) -> Job:
+        payload = {"task": task}
+        payload.update(
+            {
+                key: value
+                for key, value in {
+                    "baseline_prompt": baseline_prompt,
+                    "budget": budget,
+                    "metric": metric,
+                }.items()
+                if value is not None
+            }
+        )
+        data = self._request("POST", "/v1/optimize", json=payload)
         return Job(self, JobInfo.model_validate(data))
 
+    def preview_optimization(
+        self,
+        task: str,
+        baseline_prompt: str | None = None,
+        budget: Literal["quick", "thorough"] | None = None,
+        metric: str | None = None,
+    ) -> OptimizationPreview:
+        payload = {"task": task}
+        payload.update(
+            {
+                key: value
+                for key, value in {
+                    "baseline_prompt": baseline_prompt,
+                    "budget": budget,
+                    "metric": metric,
+                }.items()
+                if value is not None
+            }
+        )
+        data = self._request("POST", "/v1/optimize/preview", json=payload)
+        return OptimizationPreview.model_validate(data)
+
     def job(self, job_id: str) -> Job:
         data = self._request("GET", f"/v1/jobs/{job_id}")
         return Job(self, JobInfo.model_validate(data))
@@ -126,6 +167,13 @@ class Apprentice:
         data = self._request("GET", f"/v1/tasks/{task}/jobs")
         return [JobSummary.model_validate(item) for item in data]
 
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return dict(self._request("POST", f"/v1/jobs/{job_id}/cancel"))
+
+    def local_runs(self, task: str) -> list[LocalRun]:
+        data = self._request("GET", f"/v1/tasks/{task}/local-runs")
+        return [LocalRun.model_validate(item) for item in data]
+
     def train(self, task: str) -> Job:
         data = self._request("POST", f"/v1/tasks/{task}/train", json={})
         return Job(self, JobInfo.model_validate(data))
@@ -350,7 +398,10 @@ class Job:
             time.sleep(poll_seconds)
         return self
 
-    def report(self) -> OptimizationReport:
+    def cancel(self) -> dict[str, Any]:
+        return self._client.cancel_job(self.info.job_id)
+
+    def report(self) -> JobReport:
         if self.info.report is None:
             raise ApprenticeError(
                 f"job {self.info.job_id} has no report (status={self.info.status})"
@@ -371,10 +422,15 @@ class _DatasetsAPI:
         output_col: str = "output",
         prompt: str | None = None,
     ) -> DatasetStatus:
-        """Upload rows.
+        """Replace uploaded, unverified rows for a task.
 
         Rows may use legacy `input`/`output` or structured `inputs`/`output`.
         LCEL auto-capture of prompt variables is future work; v1 stays explicit.
+
+        This is a replace, not an append: existing uploaded silver and raw rows are
+        removed first, and `replaced_rows` in the response reports how many. Gold
+        rows and captured traces survive. Omitting `prompt` (or passing `None`)
+        clears the task's stored baseline prompt.
         """
         if (path is None) == (rows is None):
             raise ApprenticeError("provide exactly one of path= or rows=")