Resume a Kapso campaign from its exact checkpoint state

Kapso can continue a previous evolution campaign from its exact search and orchestration state. Resume is intentionally strict: it never converts a missing, corrupt, incompatible, or completed checkpoint into a new campaign.

Basic usage

Run one iteration and keep the workspace:

solution = kapso.evolve(
    goal="Improve the support agent",
    output_path="./campaign",
    max_iterations=1,
)

Continue it with one additional iteration. The goal comes from the checkpoint and every other launch argument from the launch record, so nothing is retyped:

solution = kapso.evolve(
    output_path="./campaign",
    max_iterations=1,
    resume=True,
)

max_iterations is the number of iterations attempted by the current call. It is not a new lifetime limit. The result distinguishes the two counts:

solution.metadata["iterations"]             # this call
solution.metadata["cumulative_iterations"]  # entire campaign
solution.metadata["resumed"]

The same operation is available from the CLI:

kapso evolve --output ./campaign --iterations 1 --resume

Resume flow

Validation happens before Kapso initializes or changes the experiment workspace. A failed resume request therefore does not create a Git repository, rename a branch, or overwrite campaign state.

Strict requirements

With resume=True:

output_path is required and must already be a directory.
The path must be a non-bare Git repository.
.kapso/run_state.json must exist.
The checkpoint schema must be supported and structurally valid.
The goal, when passed, must match the checkpoint’s exactly; left out, it comes from the checkpoint.
Every other launch argument comes from .kapso/launch.json when left out. A passed mode, coding agent, eval_dir, config or knowledge index that differs from the record is refused, and the refusal names the setting.
The configured search strategy and configuration fingerprint must match.
A campaign marked completed cannot be resumed.

Starting without resume=True in a workspace that already has a run checkpoint also fails. This prevents accidental replacement of a campaign.

Checkpoint contents

Kapso owns the checkpoint rather than delegating persistence to each strategy. The current schema is:

{
  "schema_version": 2,
  "strategy_type": "generic",
  "goal": "Improve the support agent",
  "goal_hash": "sha256...",
  "config_fingerprint": "sha256...",
  "status": "running",
  "completed_iterations": 1,
  "cumulative_cost": 0.42,
  "elapsed_seconds": 812.4,
  "cost_by_component": {"implementation": 0.31, "feedback": 0.11},
  "last_stop": null,
  "current_feedback": "Address the failing edge case",
  "strategy_state": {
    "node_history": [],
    "iteration_count": 1,
    "previous_errors": []
  }
}

The configuration fingerprint includes the selected mode configuration, strategy type and parameters, any coding-agent override, and the external evaluator identity and failure policy when one is configured. It prevents a run from silently continuing under different search, model, or measurement settings. When eval_dir is provided, its content fingerprint is also part of strict compatibility. Pass the same unchanged suite to every resumed call.

Atomic saves and iteration boundaries

The checkpoint is written to a temporary file in .kapso/, flushed, and then installed with os.replace. If replacement is interrupted, the previous valid checkpoint remains readable. Kapso saves after every finalized iteration, including the iteration that achieves the goal. It records only nodes returned as completed by the strategy; a half-created iteration is not added to completed_iterations. Status has two values:

running: the call reached its iteration slice and can be resumed. A budget stop stays running too — it records why in last_stop and waits for the next slice. A campaign that paused for a reply in the inbox stays running with last_stop: "waiting_for_user"; resuming it with the request still open pauses again without running anything. See the inbox.
completed: the goal was achieved. Only goal achievement completes a campaign.

The checkpoint file and temporary files are ignored by the experiment Git repository. Candidate branches remain normal Git artifacts, while orchestration state remains local runtime state.

What is restored

Resume restores:

generic-search node history and next iteration number;
feedback injected into the next iteration;
the durable clock (elapsed_seconds) and cumulative campaign cost, broken down in cost_by_component;
cumulative completed-iteration count;
the status needed to reject completed campaigns.

Experiment history already stored in .kapso/experiment_history.json is loaded by the normal history store.

Failure handling

Resume errors are available from the top-level kapso package:

from kapso import (
    RunCheckpointCompletedError,
    RunCheckpointCorruptError,
    RunCheckpointIncompatibleError,
    RunCheckpointMissingError,
)

Error	Meaning
`RunCheckpointMissingError`	No JSON checkpoint is available
`RunCheckpointCorruptError`	JSON, fields, numeric values, or strategy state are invalid
`RunCheckpointIncompatibleError`	Goal, strategy, configuration, or schema does not match
`RunCheckpointCompletedError`	The campaign already reached a terminal status

Fix the mismatch or choose the correct workspace. Do not delete validation fields to force a resume; use a new output path for a new campaign.

Custom search strategies

A resumable custom strategy implements JSON-compatible state methods:

class MyStrategy(SearchStrategy):
    def dump_state(self) -> dict:
        return {
            "iteration_count": self.iteration_count,
            "nodes": [node.to_dict() for node in self.node_history],
        }

    def load_state(self, state: dict) -> None:
        self.iteration_count = state["iteration_count"]
        self.node_history = [
            SearchNode.from_dict(node) for node in state["nodes"]
        ]

State must contain only JSON-compatible values. Object graphs with references, such as tree search, should store IDs and rebuild references during load_state().

Execution flow

What a checkpoint captures

CLI reference

The —resume flag

Inbox

The pause a reply resumes

Related pages: Execution flow · CLI reference · Overview Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Resume a Kapso campaign from its exact checkpoint state

Basic usage

Resume flow

Strict requirements

Checkpoint contents

Atomic saves and iteration boundaries

What is restored

Failure handling

Custom search strategies

Execution flow

CLI reference

Inbox

​Basic usage

​Resume flow

​Strict requirements

​Checkpoint contents

​Atomic saves and iteration boundaries

​What is restored

​Failure handling

​Custom search strategies

​Related

Execution flow

CLI reference

Inbox

Basic usage

Resume flow

Strict requirements

Checkpoint contents

Atomic saves and iteration boundaries

What is restored

Failure handling

Custom search strategies

Related