cmpnd 0.64.0__tar.gz → 0.65.0__tar.gz

{cmpnd-0.64.0 → cmpnd-0.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.64.0
+Version: 0.65.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -497,14 +497,12 @@ sdk.optimize_deployment(
     reflection_lm=None,      # required: a dspy.LM, a bare model name or a cmpnd.HostedLM
     lms=None,                # optional: name -> dspy.LM, cmpnd.HostedLM or cmpnd.SystemOne
     credential=None,         # optional: the cmpnd.Credential every other binding spends
-    max_metric_calls=None,   # budget: the metric-call ceiling for one step
+    max_metric_calls=None,   # budget: the metric-call ceiling for the run
     auto=None,               # budget: "light", "medium" or "heavy"
     may_author_code=None,    # optional: False keeps each dspy.Flex at its deployed source
-    max_steps=10,            # optional: the most optimize steps
-    patience=2,              # optional: stop after this many steps without improvement
-    seed=0,                  # optional: the starting seed, advanced each step
+    seed=0,                  # optional: the search's random seed
     poll_interval=3.0,       # optional: seconds between status checks
-    timeout=600.0,           # optional: seconds to wait for each step
+    timeout=600.0,           # optional: seconds to wait for the run
 )
 ```
 
@@ -516,6 +514,21 @@ budget is missing.
 initiation with a 4xx, such as a 409 for missing data or a metric mismatch. It
 raises `cmpnd.OptimizeFailed` when a step reaches `failed`.
 
+The result's `optimization_run_id` names the run that produced it.
+`continue_optimization()` starts a new run from one of that run's candidates,
+reusing its data, with a budget of its own:
+
+```python
+better = sdk.continue_optimization(best, max_metric_calls=120)  # from the best candidate
+
+for candidate in sdk.list_candidates(best.optimization_run_id):  # read each one first
+    print(candidate["candidate_id"], candidate["aggregate_score"], candidate["instructions"])
+other = sdk.continue_optimization(best, candidate="ca_...", auto="light")
+```
+
+A refusal raises `cmpnd.OptimizeError`, whose `error_code` says why, such as
+`not_completed` or `unknown_candidate`.
+
 ## Command line
 
 The package installs the `cmpnd` command. `cmpnd login` saves your API key for
@@ -639,6 +652,11 @@ global config. Use it as a context manager or as a plain object.
 - `optimize_deployment(deployment, ...)` optimizes a deployment on the platform
   and returns the best `DeployedProgram`, whose `.score` is the best score
   found. It raises `cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
+- `list_candidates(run_id)` returns a run's candidates as dicts, each with its
+  `ca_` id, score, parent and instructions.
+- `continue_optimization(run, candidate=None, ...)` runs a new optimization
+  from one candidate of a completed run, with that run's data and a new budget,
+  and returns its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
 - `close()` flushes the client's traces and closes the client. A closed

{cmpnd-0.64.0 → cmpnd-0.65.0}/README.md

@@ -446,14 +446,12 @@ sdk.optimize_deployment(
     reflection_lm=None,      # required: a dspy.LM, a bare model name or a cmpnd.HostedLM
     lms=None,                # optional: name -> dspy.LM, cmpnd.HostedLM or cmpnd.SystemOne
     credential=None,         # optional: the cmpnd.Credential every other binding spends
-    max_metric_calls=None,   # budget: the metric-call ceiling for one step
+    max_metric_calls=None,   # budget: the metric-call ceiling for the run
     auto=None,               # budget: "light", "medium" or "heavy"
     may_author_code=None,    # optional: False keeps each dspy.Flex at its deployed source
-    max_steps=10,            # optional: the most optimize steps
-    patience=2,              # optional: stop after this many steps without improvement
-    seed=0,                  # optional: the starting seed, advanced each step
+    seed=0,                  # optional: the search's random seed
     poll_interval=3.0,       # optional: seconds between status checks
-    timeout=600.0,           # optional: seconds to wait for each step
+    timeout=600.0,           # optional: seconds to wait for the run
 )
 ```
 
@@ -465,6 +463,21 @@ budget is missing.
 initiation with a 4xx, such as a 409 for missing data or a metric mismatch. It
 raises `cmpnd.OptimizeFailed` when a step reaches `failed`.
 
+The result's `optimization_run_id` names the run that produced it.
+`continue_optimization()` starts a new run from one of that run's candidates,
+reusing its data, with a budget of its own:
+
+```python
+better = sdk.continue_optimization(best, max_metric_calls=120)  # from the best candidate
+
+for candidate in sdk.list_candidates(best.optimization_run_id):  # read each one first
+    print(candidate["candidate_id"], candidate["aggregate_score"], candidate["instructions"])
+other = sdk.continue_optimization(best, candidate="ca_...", auto="light")
+```
+
+A refusal raises `cmpnd.OptimizeError`, whose `error_code` says why, such as
+`not_completed` or `unknown_candidate`.
+
 ## Command line
 
 The package installs the `cmpnd` command. `cmpnd login` saves your API key for
@@ -588,6 +601,11 @@ global config. Use it as a context manager or as a plain object.
 - `optimize_deployment(deployment, ...)` optimizes a deployment on the platform
   and returns the best `DeployedProgram`, whose `.score` is the best score
   found. It raises `cmpnd.OptimizeError` or `cmpnd.OptimizeFailed` on failure.
+- `list_candidates(run_id)` returns a run's candidates as dicts, each with its
+  `ca_` id, score, parent and instructions.
+- `continue_optimization(run, candidate=None, ...)` runs a new optimization
+  from one candidate of a completed run, with that run's data and a new budget,
+  and returns its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
 - `close()` flushes the client's traces and closes the client. A closed

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/cli/commands/optimizations.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
 from .. import api_client, deprecation, pagination
+from . import top
 
 
 def _add_list_args(p: ArgumentParser) -> None:
@@ -88,6 +90,42 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     cancel.add_argument("id", help="Optimization run ID (op_...)")
     cancel.set_defaults(func=handle_cancel)
 
+    cont = sub.add_parser(
+        "continue",
+        help="Run a new optimization from one candidate of a completed run. It reuses that run's data, models "
+        "and credentials, and takes a new budget",
+    )
+    cont.add_argument("id", help="Completed optimization run ID (op_...)")
+    cont.add_argument(
+        "--candidate",
+        metavar="CANDIDATE_ID",
+        help="The ca_ id of the candidate to start from, as `cmpnd optimizations candidates ID` lists them "
+        "(default: the run's best)",
+    )
+    # The budget flags are `cmpnd optimize`'s, and the SDK refuses a run with none or two,
+    # so both commands answer a missing budget the same way.
+    cont.add_argument(
+        "--max-metric-calls",
+        dest="max_metric_calls",
+        type=int,
+        default=None,
+        help="Budget for the search, as metric calls (one per rollout). Required unless --auto is given",
+    )
+    cont.add_argument(
+        "--auto",
+        choices=["light", "medium", "heavy"],
+        default=None,
+        help="Budget as a t-shirt size, sized from the program and valset (alternative to --max-metric-calls)",
+    )
+    cont.add_argument(
+        "--async",
+        dest="asynchronous",
+        action="store_true",
+        help="Return the queued run at once instead of waiting for it to finish",
+    )
+    cont.add_argument("--json", action="store_true", help="Emit the result summary as JSON")
+    cont.set_defaults(func=handle_continue)
+
     delete = sub.add_parser("delete", help="Delete an optimization run and everything recorded under it")
     delete.add_argument("id", help="Optimization run ID (op_...)")
     delete.set_defaults(func=handle_delete)
@@ -124,8 +162,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     iters.add_argument("id", help="Optimization run ID (UUID)")
     iters.set_defaults(func=handle_iterations)
 
-    cands = sub.add_parser("candidates", help="List candidates for an optimization run")
-    cands.add_argument("id", help="Optimization run ID (UUID)")
+    cands = sub.add_parser(
+        "candidates",
+        help="List a run's candidates: each one's ca_ id, score and parent, to pick one to continue from",
+    )
+    cands.add_argument("id", help="Optimization run ID (op_...)")
     cands.add_argument(
         "--full",
         action="store_true",
@@ -213,6 +254,80 @@ def handle_cancel(client: api_client.ApiClient, args: Any) -> Any:
     return client.post(f"/api/v1/optimizations/{args.id}/cancel")
 
 
+def handle_continue(client: api_client.ApiClient, args: Any) -> Any:
+    """Run a new optimization from one candidate of a completed run, as `cmpnd optimize` runs one.
+
+    The new run reuses the completed run's data and configuration and takes a new budget.
+    The command names the candidate it starts from, waits for the run, and prints the
+    best program as `cmpnd optimize` does. `--async` returns the queued run instead.
+    """
+    from ... import optimization
+
+    cfg = top.sdk_config(client)
+    try:
+        started = optimization.start_continuation(
+            args.id,
+            cfg=cfg,
+            candidate=args.candidate,
+            max_metric_calls=args.max_metric_calls,
+            auto=args.auto,
+        )
+    except (optimization.OptimizeError, ValueError) as exc:
+        raise api_client.CliError(str(exc)) from exc
+    if args.asynchronous:
+        return started
+
+    texts = _instruction_texts(started.get("candidate_instructions"))
+    score = started.get("candidate_score")
+    print(
+        top._c(
+            f"continuing {args.id} from {started.get('continued_from_candidate_id')} "
+            f"(score {score:.3f}): {_first_line(texts)}"
+            if isinstance(score, (int, float))
+            else f"continuing {args.id} from {started.get('continued_from_candidate_id')}",
+            "dim",
+        ),
+        file=sys.stderr,
+    )
+    print(top._c(f"optimizing with {started.get('optimizer')}…", "dim"), file=sys.stderr)
+    try:
+        result = optimization.wait_for_continuation(started, cfg=cfg)
+    except (optimization.OptimizeError, optimization.OptimizeFailed) as exc:
+        raise api_client.CliError(str(exc)) from exc
+    top.print_optimize_result(
+        result,
+        as_json=args.json,
+        extra={
+            "optimization_id": started.get("optimization_id"),
+            "continued_from_run_id": started.get("continued_from_run_id"),
+            "continued_from_candidate_id": started.get("continued_from_candidate_id"),
+        },
+    )
+    return None
+
+
+def _instruction_texts(instructions: Any) -> list[tuple[str, str]]:
+    """A candidate's instructions as (component, text) pairs, in the order serve sent them."""
+    if not isinstance(instructions, dict):
+        return []
+    return [(str(name), text if isinstance(text, str) else str(text)) for name, text in instructions.items()]
+
+
+def _first_line(texts: list[tuple[str, str]], width: int = 72) -> str:
+    """The first line of the first component's text, naming the component when there are several."""
+    if not texts:
+        return "-"
+    name, text = texts[0]
+    line = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
+    if len(texts) > 1:
+        line = f"{name}: {line}"
+    if len(line) > width:
+        line = line[: width - 1] + "…"
+    if len(texts) > 1:
+        line += f" (+{len(texts) - 1} more)"
+    return line
+
+
 def handle_delete(client: api_client.ApiClient, args: Any) -> Any:
     # 204 No Content → delete() returns None; synthesize a confirmation.
     client.delete(f"/api/v1/optimizations/{args.id}")

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/cli/commands/top.py

@@ -1028,7 +1028,7 @@ def _optimize_credentials(
     ``cmpnd.HostedLM`` when ``--reflection-credential`` names its credential) and the
     credential per binding. :class:`_CredentialLookup` turns each name into a
     ``cmpnd.Credential``, so a mistyped one fails before the import and the deploy a run
-    makes ahead of its first step.
+    makes ahead of the optimization.
     """
     from ...lm_configuration import HostedLM
 
@@ -1133,29 +1133,30 @@ def cmd_optimize(client: api_client.ApiClient, args: Any) -> Any:
             lm_credentials=lm_credentials,
             max_metric_calls=getattr(args, "max_metric_calls", None),
             auto=getattr(args, "auto", None),
-            max_steps=getattr(args, "max_steps", 10),
-            patience=getattr(args, "patience", 2),
             seed=getattr(args, "seed", 0),
         )
     except (optimization.OptimizeError, optimization.OptimizeFailed, ValueError) as exc:
         raise api_client.CliError(str(exc))
 
-    if getattr(args, "json", False):
-        print(
-            json.dumps(
-                {
-                    "best_deployment_id": result.deployment_id,
-                    "best_score": result.score,
-                },
-                indent=2,
-                default=str,
-            )
-        )
+    print_optimize_result(result, as_json=getattr(args, "json", False))
+    return result
+
+
+def print_optimize_result(result: Any, *, as_json: bool, extra: dict[str, Any] | None = None) -> None:
+    """Print a finished optimization's best program, as every command that runs one does.
+
+    The best deployment's id goes to stdout and its score to stderr, so a script can
+    capture the id alone. ``--json`` prints both, and ``extra`` adds fields a command
+    knows about the run.
+    """
+    if as_json:
+        summary = {"best_deployment_id": result.deployment_id, "best_score": result.score}
+        summary.update(extra or {})
+        print(json.dumps(summary, indent=2, default=str))
     else:
         print(result.deployment_id)
         score = "n/a" if result.score is None else f"{result.score}"
         print(_c(f"best score: {score}", "dim"), file=sys.stderr)
-    return result
 
 
 def cmd_run(client: api_client.ApiClient, args: Any) -> None:
@@ -1563,7 +1564,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         dest="max_metric_calls",
         type=int,
         default=None,
-        help="Budget for each step's search, as metric calls (one per rollout). Required unless --auto is given",
+        help="Budget for the search, as metric calls (one per rollout). Required unless --auto is given",
     )
     opt.add_argument(
         "--auto",
@@ -1571,15 +1572,6 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
         default=None,
         help="Budget as a t-shirt size, sized from the program and valset (alternative to --max-metric-calls)",
     )
-    opt.add_argument(
-        "--max-steps",
-        dest="max_steps",
-        type=int,
-        default=10,
-        help="How many times to re-optimize the winner, each step a fresh search "
-        "with an advanced seed (default 10). Bounds the LOOP, not one search",
-    )
-    opt.add_argument("--patience", type=int, default=2, help="Stop after this many consecutive non-improving steps")
-    opt.add_argument("--seed", type=int, default=0, help="Starting seed; advanced each step")
+    opt.add_argument("--seed", type=int, default=0, help="The search's random seed (default 0)")
     opt.add_argument("--json", action="store_true", help="Emit the result summary as JSON")
     opt.set_defaults(func=_handler("optimize"))

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/cli/shell.py

@@ -537,8 +537,6 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
         reflection_model: str | None = None,
         source_root: str | None = None,
         include: list[str] | None = None,
-        max_steps: int = 10,
-        patience: int = 2,
         seed: int = 0,
         # Deprecated program id input: refused, and goes when the deprecated inputs are stripped out.
         program_id: str | None = None,
@@ -568,8 +566,6 @@ def _make_namespace(client: api_client.ApiClient, endpoint: str) -> dict[str, An
                 reflection_model=reflection_model,
                 source_root=source_root,
                 include=list(include or []),
-                max_steps=max_steps,
-                patience=patience,
                 seed=seed,
             ),
         )

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/cli/verbs.py

@@ -154,6 +154,7 @@ DOMAIN_VERBS: dict[str, str] = {
     "wait": "polls one accepted run until it settles or the local budget expires",
     "cancel": "settles an open run as cancelled and keeps its record; delete would read as removing the run",
     "follow": "tails a record until it settles — a list over time rather than a snapshot",
+    "continue": "starts a run from one candidate of a completed run; create would hide that it inherits its data",
     "select": "marks one candidate as the program's chosen version",
     "refresh": "re-reads a record from the system of record it mirrors; nothing the caller supplies is written",
     "allow": "grants permission to call a tool — a person's decision, never inferred from what code names",

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/client.py

@@ -507,17 +507,14 @@ class Client:
         max_metric_calls: int | None = None,
         auto: str | None = None,
         may_author_code: bool | None = None,
-        max_steps: int = 10,
-        patience: int = 2,
         seed: int = 0,
         poll_interval: float = 3.0,
         timeout: float = 600.0,
     ) -> Any:
         """Optimize a deployment on the platform, on this client's account, and return the best deployment.
 
-        Runs a client-driven loop over the per-step optimize API: upload the
-        optimization bundle once, then re-optimize the deployment with an advancing
-        seed until improvement plateaus. Deploy the program first with
+        Runs one optimization: upload the optimization bundle, wait for the run to
+        settle, and return its result deployment. Deploy the program first with
         ``deploy_program``. The optimization belongs to the deployment's program, and
         the program's model comes from the deployment.
 
@@ -676,28 +673,23 @@ class Client:
                 optimizes every ordinary predictor and leaves each ``dspy.Flex`` at
                 the source you deployed. A program with no ``dspy.Flex`` in it is
                 unaffected either way.
-            max_steps: How many times to re-optimize the winner, each step a fresh
-                ``optimize`` call with an advanced seed (default 10). Distinct from
-                the budget above, which bounds ONE step's search: total spend is
-                roughly the budget times the steps actually taken.
-            patience: Stop after this many consecutive non-improving steps (default 2).
-            seed: Starting seed; advanced by 1 each step (default 0).
+            seed: The search's random seed (default 0).
             poll_interval: Seconds between status polls (default 3.0).
-            timeout: Per-step polling timeout in seconds (default 600). Also the
-                outer bound on riding through transient answers: a step's backoff
-                waits are clipped by it rather than extending the step past it.
+            timeout: Polling timeout in seconds (default 600). Also the outer bound
+                on riding through transient answers: the run's backoff waits are
+                clipped by it rather than extending the wait past it.
 
         Returns:
-            The best ``cmpnd.DeployedProgram``. Run it with ``run_deployment``. Its
-            ``.score`` is the best score found (``None`` if the server returned no
+            The run's result ``cmpnd.DeployedProgram``. Run it with ``run_deployment``.
+            Its ``.score`` is the run's best score (``None`` if the server returned no
             scores).
 
         Raises:
             ValueError: A retired optimizer, an unknown one, a metric that is not a
                 5-arg feedback metric (or whose signature cannot be introspected), or a
                 proposer the sandbox could not call or whose source cannot be recovered.
-            OptimizeError: A 4xx initiating a step (e.g. 409 no-data / mismatch).
-            OptimizeFailed: A step transitioned to ``status="failed"``.
+            OptimizeError: A 4xx initiating the run (e.g. 409 mismatch).
+            OptimizeFailed: The run transitioned to ``status="failed"``.
             TypeError: A string for ``credential``. Look a credential up with
                 ``cmpnd.credentials.get``.
         """
@@ -719,13 +711,71 @@ class Client:
             max_metric_calls=max_metric_calls,
             auto=auto,
             may_author_code=may_author_code,
-            max_steps=max_steps,
-            patience=patience,
             seed=seed,
             poll_interval=poll_interval,
             timeout=timeout,
         )
 
+    def continue_optimization(
+        self,
+        run: Any,
+        *,
+        candidate: str | None = None,
+        max_metric_calls: int | None = None,
+        auto: str | None = None,
+        poll_interval: float = 3.0,
+        timeout: float = 600.0,
+    ) -> Any:
+        """Run a new optimization from one candidate of a completed one, and return its best program.
+
+        The new run is a fresh search that starts from the chosen candidate, with its own
+        budget. It reuses the completed run's training and validation data and its
+        configuration, so nothing is uploaded::
+
+            best = client.optimize_deployment(deployed, ..., max_metric_calls=120)
+            better = client.continue_optimization(best, max_metric_calls=120)
+
+        Args:
+            run: The completed run's ``op_`` id, or the ``DeployedProgram`` an
+                optimization returned.
+            candidate: The ``ca_`` id of the candidate to start from, as
+                ``list_candidates`` and ``cmpnd optimizations candidates`` list it. The
+                default is the run's best.
+            max_metric_calls: The budget as a ceiling on metric calls. Pass this or
+                ``auto``, exactly one.
+            auto: The budget as ``"light"``, ``"medium"`` or ``"heavy"``.
+            poll_interval: Seconds between status polls (default 3.0).
+            timeout: Polling timeout in seconds (default 600).
+
+        Returns:
+            The new run's best program, a ``cmpnd.DeployedProgram``, as
+            ``optimize_deployment`` returns.
+
+        Raises:
+            ValueError: No budget or two budgets, or a ``DeployedProgram`` that no
+                optimization produced.
+            OptimizeError: The platform refused the continuation. Its ``error_code``
+                says why, for example ``not_completed`` or ``unknown_candidate``.
+            OptimizeFailed: The new run transitioned to ``status="failed"``.
+        """
+        self._check_active()
+        from . import execution, optimization
+
+        run_id = run.optimization_run_id if isinstance(run, execution.DeployedProgram) else run
+        if not run_id:
+            raise ValueError(
+                f"deployment {run} is not the result of an optimization this client ran; pass the run's op_ id"
+            )
+        return optimization.continue_optimization(
+            run_id,
+            cfg=self._config,
+            candidate=candidate,
+            max_metric_calls=max_metric_calls,
+            auto=auto,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
     # -- data surface (flat verb-object over the client's credentials) -----
     #
     # Flat methods (create_valset_entry, list_assessments, get_trace, …), so the
@@ -747,6 +797,22 @@ class Client:
         _exporter_pool.flush(self._config)
         return programs.program_id_for(_http.ApiClient(self._config.api_key, self._config.endpoint), program)
 
+    def list_candidates(self, run_id: str) -> list[dict[str, Any]]:
+        """The candidates of an optimization run, to choose one to continue from.
+
+        Each carries its ``candidate_id`` (``ca_…``), ``aggregate_score``,
+        ``parent_candidate_id`` and ``instructions``, so a caller picks by what a
+        candidate is::
+
+            candidates = client.list_candidates("op_…")
+            chosen = max(candidates, key=lambda c: c["aggregate_score"])
+            client.continue_optimization("op_…", candidate=chosen["candidate_id"], max_metric_calls=120)
+        """
+        self._check_active()
+        from . import optimization
+
+        return optimization.list_candidates(run_id, cfg=self._config)
+
     def get_deployment_signature(self, deployment_id: str) -> DeploymentSignatureResponse:
         """Fetch one deployment's persisted artifact metadata."""
         self._check_active()

{cmpnd-0.64.0 → cmpnd-0.65.0}/cmpnd/execution.py

@@ -114,8 +114,12 @@ class DeployedProgram:
         endpoint: str | None = None,
         score: float | None = None,
         deployment_signature: DeploymentSignatureResponse | None = None,
+        optimization_run_id: str | None = None,
     ) -> None:
         self.deployment_id = deployment_id
+        #: The optimization run that produced this program, when it is a run's result.
+        #: ``cmpnd.Client.continue_optimization`` takes such a program in place of a run id.
+        self.optimization_run_id = optimization_run_id
         self.deployment_signature = deployment_signature
         self.artifact_metadata: DeploymentArtifactMetadata | None = None
         self.metadata_unavailable_reason: str | None = None