# kindgi proposals

> Improvement proposals: new content for a data block an agent pins, for one scope; evaluated on a test set, then promoted through the scope's gate (list / get / draft / evaluate / request / rollback / withdraw / improve / passes)

## `kindgi proposals`

**Synopsis**

```sh signature
kindgi proposals <command>
```

Improvement proposals: new content for a data block an agent pins, for one scope; evaluated on a test set, then promoted through the scope's gate (list / get / draft / evaluate / request / rollback / withdraw / improve / passes).

**Commands**

| Command                                                                                                            | Description                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| [`kindgi proposals list`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-list)         | List improvement proposals, newest first: only those of agents you can read.                                                       |
| [`kindgi proposals get`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-get)           | Show a proposal: its change, status, candidate versions, the comparison it was evaluated on and its promotion.                     |
| [`kindgi proposals draft`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-draft)       | Draft a proposal by hand: new content for one block the agent version pins (settings values, or a prompt template), for one scope. |
| [`kindgi proposals evaluate`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-evaluate) | Evaluate a proposal on a test set: a comparison of the candidate with the version it changes.                                      |
| [`kindgi proposals request`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-request)   | Request a proposal's promotion: its candidate version, for its scope, through the scope's gate with its evaluation.                |
| [`kindgi proposals rollback`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-rollback) | Roll back a promoted proposal: its scope goes back to the version that served it before.                                           |
| [`kindgi proposals withdraw`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-withdraw) | Withdraw a proposal before review, or after its promotion was refused, superseded or expired.                                      |
| [`kindgi proposals improve`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-improve)   | Ask the runtime to look for better values for an agent version's tunable settings for a scope, within a budget.                    |
| [`kindgi proposals passes`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes)     | Improvement passes: the runtime looking for better settings (list / get / cancel).                                                 |

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)

### `kindgi proposals list`

**Synopsis**

```sh signature
kindgi proposals list [--agent=<agent-id>] [(--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…)] [--tier=settings-block|prompt-block] [--status=<status>] [--limit=<n>] [--cursor=<cursor>] [--table]
```

List improvement proposals, newest first: only those of agents you can read. A scope flag keeps the proposals for exactly that scope. A status filter is applied after the page is read, so a page can hold fewer than --limit.

**Options**

| Option              | Default              | Description                                                                                                                                               |
| ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <value>`   | none                 | Only this agent's proposals.                                                                                                                              |
| `--cursor <value>`  | none                 | The next page, from `nextCursor`.                                                                                                                         |
| `--limit <value>`   | `25` (at most `100`) | Page size.                                                                                                                                                |
| `--org <value>`     | none                 | An org, by id.                                                                                                                                            |
| `--project <value>` | none                 | A project, by id; with `--segment`, a segment in it.                                                                                                      |
| `--segment <value>` | none                 | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable.                       |
| `--status <value>`  | none                 | One of: draft, evaluating, evaluated, not-better, evaluation-failed, in-review, promoted, refused, rejected, expired, superseded, rolled-back, withdrawn. |
| `--tenant`          | off                  | The whole tenant.                                                                                                                                         |
| `--tier <value>`    | none                 | `settings-block` or `prompt-block`.                                                                                                                       |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals list --agent=acme.rank.scorer --table
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals get`

**Synopsis**

```sh signature
kindgi proposals get <proposal-id>
```

Show a proposal: its change, status, candidate versions, the comparison it was evaluated on and its promotion.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals get <proposal-id>
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals draft`

**Synopsis**

```sh signature
kindgi proposals draft --agent=<agent-id> --from-version=<semver> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) --block=<block-id> (--values=<json>|@<file> | --template=<text>|@<file>) --hypothesis=<text> [--judgment=<judgment-id>]…
```

Draft a proposal by hand: new content for one block the agent version pins (settings values, or a prompt template), for one scope. The same change from the same version for the same scope returns the proposal drafted before. Needs `publish` on the agent.

**Options**

| Option                      | Default  | Description                                                                                                                         |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <value>`           | required | The agent.                                                                                                                          |
| `--block <value>`           | required | The data block to change; the version must pin it.                                                                                  |
| `--from-version <value>`    | required | The agent version the change applies to.                                                                                            |
| `--hypothesis <value>`      | required | What the change should improve, and why.                                                                                            |
| `--idempotency-key <value>` | none     | A retry with the same key returns the first call's result.                                                                          |
| `--judgment <value>`        | none     | A judgment behind the change (repeatable): kept as evidence. Repeatable.                                                            |
| `--org <value>`             | none     | An org, by id.                                                                                                                      |
| `--project <value>`         | none     | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--segment <value>`         | none     | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--template <value>`        | none     | A prompt block's new template: text, inline or `@<file>`.                                                                           |
| `--tenant`                  | off      | The whole tenant.                                                                                                                   |
| `--values <value>`          | none     | A settings block's new values: a JSON object, inline or `@<file>`.                                                                  |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals draft --agent=acme.rank.scorer --from-version=1.0.0 --tenant \
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals evaluate`

**Synopsis**

```sh signature
kindgi proposals evaluate <proposal-id> --test-set=<suite-id> [--objective=weightedYesShare|weightedPrecisionAtK] [--reads=recorded|live] [--repetitions=<n>] [--k=<n>] [--class-weights=as-recorded|restricted-only] [--wait]
       kindgi proposals evaluate <proposal-id> --rescore [--wait]
```

Evaluate a proposal on a test set: a comparison of the candidate with the version it changes. The first evaluation publishes the block version and derives the agent version; they serve no scope until promoted, so the agent needs a live version for the whole tenant (`kindgi agents promote <agent-id> <version> --tenant`). The proposal is `evaluating`, then `evaluated` (better), `not-better` or `evaluation-failed`. With `--rescore`, after people judged the comparison's new answers on its replay runs: the latest evaluation scored again, counting those judgments, on the same replays (no other flag). Needs `publish` on the agent.

**Options**

| Option                      | Default            | Description                                                                                                                               |
| --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--class-weights <value>`   | `as-recorded`      | `as-recorded` (the default) or `restricted-only`: only judgments of restricted judge classes count.                                       |
| `--idempotency-key <value>` | none               | A retry with the same key returns the first call's result.                                                                                |
| `--k <value>`               | `10`               | How many ranked items weighted precision\@k looks at (1 to 100, default 10).                                                              |
| `--objective <value>`       | `weightedYesShare` | The metric that says whether the candidate is better: `weightedYesShare` (the default) or `weightedPrecisionAtK`.                         |
| `--reads <value>`           | `recorded`         | Whether replayed reads use the past run's results when it has them (`recorded`, the default) or run live.                                 |
| `--repetitions <value>`     | `1`                | Run each case this many times (1 to 10, default 1): a delta counts as better only above the spread.                                       |
| `--rescore`                 | off                | Score the latest evaluation's replays again, with what people judged on them since: same test set version and settings, nothing replayed. |
| `--test-set <value>`        | required           | The test set: a judged eval suite, by id.                                                                                                 |
| `--wait`                    | off                | Wait until the evaluation is done (at most 30 minutes), then print the proposal.                                                          |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals evaluate <proposal-id> --test-set=acme.rank-prompt-52080 --wait
pnpm exec kindgi proposals evaluate <proposal-id> --rescore --wait
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals request`

**Synopsis**

```sh signature
kindgi proposals request <proposal-id> [--reason=<text>]
```

Request a proposal's promotion: its candidate version, for its scope, through the scope's gate with its evaluation. The proposal is `promoted`, or `in-review` (a reviewer decides the promotion's approval: `kindgi approvals complete`); a gate refusal lists every check. Allowed once evaluated, also when `not-better`: the gate decides. Needs `promote` on the agent.

**Options**

| Option                      | Default | Description                                                |
| --------------------------- | ------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none    | A retry with the same key returns the first call's result. |
| `--reason <value>`          | none    | Why, kept on the promotion.                                |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals request <proposal-id> --reason="Live check: promote by hand."
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals rollback`

**Synopsis**

```sh signature
kindgi proposals rollback <proposal-id> [--reason=<text>]
```

Roll back a promoted proposal: its scope goes back to the version that served it before. The proposal and its versions stay, as history. Needs `promote` on the agent.

**Options**

| Option                      | Default | Description                                                |
| --------------------------- | ------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none    | A retry with the same key returns the first call's result. |
| `--reason <value>`          | none    | Why, kept on the record.                                   |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals rollback <proposal-id> --reason="Live check: put it back."
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals withdraw`

**Synopsis**

```sh signature
kindgi proposals withdraw <proposal-id> --reason=<text>
```

Withdraw a proposal before review, or after its promotion was refused, superseded or expired. Needs `publish` on the agent.

**Options**

| Option                      | Default  | Description                                                |
| --------------------------- | -------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none     | A retry with the same key returns the first call's result. |
| `--reason <value>`          | required | Why, kept on the record (required).                        |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md):

```sh
pnpm exec kindgi proposals withdraw <proposal-id> --reason="Superseded by a better draft"
```

**See also**

- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals improve`

**Synopsis**

```sh signature
kindgi proposals improve --agent=<agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) --test-set=<suite-id> [--from-version=<semver>] [--objective=weightedYesShare|weightedPrecisionAtK] [--max-cost=<usd>] [--max-candidates=<n>] [--wait]
```

Ask the runtime to look for better values for an agent version's tunable settings for a scope, within a budget. It searches on part of the test set and proves its best candidate on the rest; if that candidate is better, it writes a proposal, which a reviewer decides (`kindgi proposals request`). Answers at once with the pass; `--wait` waits for its outcome. Needs `publish` on the agent.

**Options**

| Option                      | Default                       | Description                                                                                                                         |
| --------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <value>`           | required                      | The agent.                                                                                                                          |
| `--from-version <value>`    | the version serving the scope | The version whose settings it tunes (default: the one serving the scope).                                                           |
| `--idempotency-key <value>` | none                          | A retry with the same key returns the first call's result.                                                                          |
| `--max-candidates <value>`  | `30`                          | The most candidates it compares (default 30).                                                                                       |
| `--max-cost <value>`        | `5` (US dollars)              | The most its comparisons may cost, in US dollars (default 5).                                                                       |
| `--objective <value>`       | `weightedYesShare`            | What better means: `weightedYesShare` (the default) or `weightedPrecisionAtK`.                                                      |
| `--org <value>`             | none                          | An org, by id.                                                                                                                      |
| `--project <value>`         | none                          | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--segment <value>`         | none                          | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`                  | off                           | The whole tenant.                                                                                                                   |
| `--test-set <value>`        | required                      | The judged test set to search and prove on, by id.                                                                                  |
| `--wait`                    | off                           | Wait until the pass is done (at most 30 minutes), then print it.                                                                    |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md):

```sh
pnpm exec kindgi proposals improve --agent=acme.rank.scorer --tenant --test-set=acme.rank-prompt-52080 --max-candidates=4 --wait
```

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

### `kindgi proposals passes`

**Synopsis**

```sh signature
kindgi proposals passes <command>
```

Improvement passes: the runtime looking for better settings (list / get / cancel).

**Commands**

| Command                                                                                                                      | Description                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [`kindgi proposals passes list`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes-list)     | List improvement passes, newest first: only those of agents you can read.                                                             |
| [`kindgi proposals passes get`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes-get)       | Show an improvement pass: how many candidates it compared, what that cost, and what it found (the proposal it wrote, or why nothing). |
| [`kindgi proposals passes cancel`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes-cancel) | Stop a running improvement pass: it ends `cancelled` and writes no proposal.                                                          |

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [Propose a change, and test it](https://docs.kindgi.com/v0.1.8/guides/evals/propose-a-change.md)
- [`kindgi proposals`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals)

#### `kindgi proposals passes list`

**Synopsis**

```sh signature
kindgi proposals passes list [--agent=<agent-id>] [--limit=<n>] [--cursor=<cursor>] [--table]
```

List improvement passes, newest first: only those of agents you can read.

**Options**

| Option             | Default              | Description                       |
| ------------------ | -------------------- | --------------------------------- |
| `--agent <value>`  | none                 | Only this agent's passes.         |
| `--cursor <value>` | none                 | The next page, from `nextCursor`. |
| `--limit <value>`  | `25` (at most `100`) | Page size.                        |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md):

```sh
pnpm exec kindgi proposals passes list --table
```

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [`kindgi proposals passes`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes)

#### `kindgi proposals passes get`

**Synopsis**

```sh signature
kindgi proposals passes get <pass-id>
```

Show an improvement pass: how many candidates it compared, what that cost, and what it found (the proposal it wrote, or why nothing).

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md):

```sh
pnpm exec kindgi proposals passes get <pass-id>
```

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [`kindgi proposals passes`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes)

#### `kindgi proposals passes cancel`

**Synopsis**

```sh signature
kindgi proposals passes cancel <pass-id>
```

Stop a running improvement pass: it ends `cancelled` and writes no proposal.

**Options**

| Option                      | Default | Description                                                |
| --------------------------- | ------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none    | A retry with the same key returns the first call's result. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md):

```sh
pnpm exec kindgi proposals passes cancel <pass-id>
```

**See also**

- [Let a pass look for something better](https://docs.kindgi.com/v0.1.8/guides/evals/improve-an-agent.md)
- [`kindgi proposals passes`](https://docs.kindgi.com/v0.1.8/reference/cli/proposals.md#kindgi-proposals-passes)