client.improve_runs

client.improve_runs — the improveRuns operations.

On AsyncKindgi every method is the same, awaited.

client.improve_runs.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    agent_id: str | UUID | None = None,
    project_id: str | UUID | None = None,
    status: Literal['running', 'completed', 'failed', 'cancelled'] | None = None,
    timeout: float | None = None,
) -> ImproveRunCollectionPage

Signature

List Improve runs. GET /v1/improve-runs

Newest first, only the Improve runs of agents the caller can read. ?agentId=, ?projectId= and ?status= narrow them.

client.improve_runs.start()

start(
    body: StartImproveRunBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ImproveRun

Signature

Start an Improve run. POST /v1/improve-runs

Starts an Improve run for an agent in a project. From the version the project runs (pinned there, else its Latest), it looks for better wording (the prompt tier) or settings values (the settings tier) on the project's test set, learning from the project's open corrections sorted to improve, within the budget. Its best change is proven on every case of the test set, at the reference's repetitions: when it passes more cases than that version and fails none that passed, it becomes a suggested change for a reviewer. It answers at once with the Improve run, running. Under kindgi dev, the run counts in its project (its corrections, its test set and its cost), and its suggested change is for the whole workspace (the tenant scope), which the pack's files serve: pinning it writes its block into the pack's files. The readiness check (POST /v1/improve-runs/check) runs first: when something the Improve run needs is missing, it's refused with 409 improve-not-ready, listing every missing item at once (details.items, each with its fix); while the agent has a running Improve run in the project, with 409 improve-run-running (details.improveRunId). An Improve run going when its project is suspended ends cancelled, with the reason in cancelReason. Needs publish on the agent; for an agent more than one project serves, write where its versions are made. Without Improve runs in this runtime, 501 improve-unsupported.

client.improve_runs.check()

check(
    body: StartImproveRunBody | Mapping[str, Any] | None = None,
    /,
    *,
    timeout: float | None = None,
    **fields: Any,
) -> ImproveRunCheck

Signature

Check an Improve run. POST /v1/improve-runs/check

Whether the Improve run this input would start is ready, and what it's estimated to cost, before you start it. The body is the start body of POST /v1/improve-runs. items lists everything an Improve run needs, in a fixed order, missing or not; each missing one says where it's fixed (repo: in the agent's code, then a deploy; kindgi: in Kindgi) and how. estimate.costUsd prices each replay at the version's mean cost over its recent completed runs: the search's replays at most budget.maxCostUsd, plus the proof's (estimate.basis.proofReplays), which the budget doesn't cap. It's absent when the version has no cost history; estimate.basis gives the inputs. The estimate prices every replay at that one mean, so a candidate whose prompt or settings cost more or less per run isn't captured, and it leaves out a prompt Improve run's one-off drafting of its templates: an Improve run can cost more than the estimate. The Improve run checks its cost before each comparison, so the one already running can take it a little over, and its search starts no more once the cost reaches budget.maxCostUsd. It proves its best change after that, uncapped. With an Improve schedule on the agent and project, month is this UTC month's spend on their Improve runs against the schedule's monthly cap; only the schedule stops at the cap. It changes nothing (no Improve run starts) and takes no Idempotency-Key. Needs publish on the agent; for an agent more than one project serves, write where its versions are made. Without Improve runs in this runtime, 501 improve-unsupported.

client.improve_runs.get()

get(improve_run_id: str | UUID, /, *, timeout: float | None = None) -> ImproveRun

Signature

Fetch an Improve run. GET /v1/improve-runs/{improveRunId}

Its status, the candidates it compared and what they cost, and once it ends, what it found. Needs read on its agent.

client.improve_runs.cancel()

cancel(
    improve_run_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ImproveRun

Signature

Cancel an Improve run. POST /v1/improve-runs/{improveRunId}/cancel

A running Improve run stops and ends cancelled, writing no suggested change. Needs publish on its agent.