# Kitaru Reference



This site is the auto-generated reference for Kitaru's public **Python SDK** and
**command-line interface**. It is generated directly from the Kitaru source on
every release.

Looking for guides, concepts, and tutorials? Those live in the main
[Kitaru documentation](https://docs.zenml.io/kitaru).

<Cards>
  <Card title="Python SDK Reference" description="Every public function, class, and decorator in the kitaru package" href="/reference/python" />

  <Card title="CLI Reference" description="Every kitaru command, subcommand, flag, and argument" href="/cli" />
</Cards>


# kitaru doctor



## Usage [#usage]

```bash
kitaru doctor [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# CLI Reference



Reference pages for every `kitaru` command, generated from the CLI's own schema output.

## Global options [#global-options]

Every command accepts these options in addition to its own.

| Name                     | Type                      | Required | Description                 |
| ------------------------ | ------------------------- | -------- | --------------------------- |
| `--output/-o`            | `auto\|text\|json\|jsonl` | No       | Serialization mode.         |
| `--machine/--no-machine` | `boolean`                 | No       | Terminal rendering mode.    |
| `--server`               | `URL`                     | No       | Server URL override.        |
| `--non-interactive`      | `boolean`                 | No       | Disable interaction.        |
| `--no-browser`           | `boolean`                 | No       | Disable browser launch.     |
| `--request-timeout`      | `positive float`          | No       | HTTP timeout.               |
| `--debug`                | `boolean`                 | No       | Redacted debug diagnostics. |
| `--traceback`            | `boolean`                 | No       | Redacted traceback.         |

The `--output` type above is the union across all commands; each command page lists the modes that command supports.

## Commands [#commands]

| Command                                | Description                                                                                                                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`agent`](/cli/agent/)                 | Register and inspect agents.                                                                                                                                                           |
| [`analyzer`](/cli/analyzer/)           | Register and inspect analyzers.                                                                                                                                                        |
| [`annotation`](/cli/annotation/)       | Create and manage session annotations.                                                                                                                                                 |
| [`cohort`](/cli/cohort/)               | Manage cohort namespaces and immutable membership versions.                                                                                                                            |
| [`config`](/cli/config/)               | Manage allowlisted CLI preferences.                                                                                                                                                    |
| [`connection`](/cli/connection/)       | Create and manage provider connections.                                                                                                                                                |
| [`doctor`](/cli/doctor/)               | Run independent local, server, authentication, and tooling checks.                                                                                                                     |
| [`evaluation`](/cli/evaluation/)       | Inspect stored evaluations.                                                                                                                                                            |
| [`evaluator`](/cli/evaluator/)         | Develop, register, and inspect evaluators.                                                                                                                                             |
| [`experiment`](/cli/experiment/)       | Configure experiments and manage asynchronous runs.                                                                                                                                    |
| [`import`](/cli/import/)               | Inspect imports and rerun analyzers over them.                                                                                                                                         |
| [`importer`](/cli/importer/)           | Develop, register, and inspect importers.                                                                                                                                              |
| [`info`](/cli/info/)                   | Show local runtime details and resolved server information.                                                                                                                            |
| [`insight`](/cli/insight/)             | Create and inspect agent insights.                                                                                                                                                     |
| [`investigation`](/cli/investigation/) | Create investigations and review their linked sessions.                                                                                                                                |
| [`job`](/cli/job/)                     | Inspect, watch, and cancel jobs.                                                                                                                                                       |
| [`local`](/cli/local/)                 | Inspect the CLI-owned local Kitaru deployment.                                                                                                                                         |
| [`login`](/cli/login/)                 | Authenticate with managed cloud (14-day trial, no credit card required) or a Kitaru server.                                                                                            |
| [`logout`](/cli/logout/)               | Disconnect from a server and stop an owned local deployment.                                                                                                                           |
| [`replay`](/cli/replay/)               | Create and inspect standalone replays.                                                                                                                                                 |
| [`schema`](/cli/schema/)               | Describe the CLI command tree from offline registration metadata.                                                                                                                      |
| [`session`](/cli/session/)             | Import and inspect sessions and their nodes.                                                                                                                                           |
| [`setup`](/cli/setup/)                 | Install the agent skills and register the MCP server with every detected coding agent. Re-run after installing a new one. The global --server picks the server the MCP server targets. |
| [`status`](/cli/status/)               | Show connection, authentication, compatibility, and live-worker status.                                                                                                                |
| [`version`](/cli/version/)             | Show the installed Kitaru version.                                                                                                                                                     |
| [`worker`](/cli/worker/)               | Run and inspect generic local workers.                                                                                                                                                 |


# kitaru info



## Usage [#usage]

```bash
kitaru info [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru login



## Usage [#usage]

```bash
kitaru login [SERVER] [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type  | Required | Description                                                  |
| -------- | ----- | -------- | ------------------------------------------------------------ |
| `SERVER` | `URL` | No       | Managed or self-hosted instance URL; omit for managed cloud. |

## Options [#options]

| Name               | Type      | Required | Description                                           |
| ------------------ | --------- | -------- | ----------------------------------------------------- |
| `--local`          | `boolean` | No       | Provision and use a local Docker deployment.          |
| `--port`           | `integer` | No       | Host port for --local; overrides KITARU\_LOCAL\_PORT. |
| `--upgrade`        | `boolean` | No       | Upgrade the CLI-owned local deployment.               |
| `--username`       | `string`  | No       | Local account name.                                   |
| `--password-stdin` | `boolean` | No       | Read password from stdin.                             |
| `--api-key-stdin`  | `boolean` | No       | Read API key from stdin.                              |
| `--refresh`        | `boolean` | No       | Skip stored credentials and force a new device login. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru logout



## Usage [#usage]

```bash
kitaru logout [SERVER] [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type  | Required | Description             |
| -------- | ----- | -------- | ----------------------- |
| `SERVER` | `URL` | No       | Server to log out from. |

## Options [#options]

| Name           | Type      | Required | Description                                     |
| -------------- | --------- | -------- | ----------------------------------------------- |
| `--all`        | `boolean` | No       | Remove every stored credential.                 |
| `--volumes/-v` | `boolean` | No       | Delete data for the CLI-owned local deployment. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru schema



## Usage [#usage]

```bash
kitaru schema [COMMAND...] [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type       | Required | Description            |
| --------- | ---------- | -------- | ---------------------- |
| `COMMAND` | `string[]` | No       | Command or group path. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru setup



## Usage [#usage]

```bash
kitaru setup [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name          | Type      | Required | Description                                                         |
| ------------- | --------- | -------- | ------------------------------------------------------------------- |
| `--mode`      | `string`  | No       | MCP capability mode: read-only, standard (default), or destructive. |
| `--no-skills` | `boolean` | No       | Skip installing the skills.                                         |
| `--no-mcp`    | `boolean` | No       | Skip registering the MCP server.                                    |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru status



## Usage [#usage]

```bash
kitaru status [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru version



## Usage [#usage]

```bash
kitaru version [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent delete



## Usage [#usage]

```bash
kitaru agent delete AGENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name    | Type        | Required | Description         |
| ------- | ----------- | -------- | ------------------- |
| `AGENT` | `reference` | Yes      | Agent UUID or name. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent get



## Usage [#usage]

```bash
kitaru agent get AGENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name    | Type        | Required | Description         |
| ------- | ----------- | -------- | ------------------- |
| `AGENT` | `reference` | Yes      | Agent UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent



## Usage [#usage]

```bash
kitaru agent COMMAND
```

## Commands [#commands]

| Command                            | Description                                        |
| ---------------------------------- | -------------------------------------------------- |
| [`delete`](/cli/agent/delete/)     | Soft delete an agent.                              |
| [`get`](/cli/agent/get/)           | Get an agent by exact UUID or case-sensitive name. |
| [`list`](/cli/agent/list/)         | List agents.                                       |
| [`register`](/cli/agent/register/) | Create an agent and its first mutable version.     |
| [`version`](/cli/agent/version/)   | Subcommands of `kitaru agent version`.             |


# kitaru agent list



## Usage [#usage]

```bash
kitaru agent list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent register



## Usage [#usage]

```bash
kitaru agent register NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description     |
| ------ | -------- | -------- | --------------- |
| `NAME` | `string` | Yes      | New agent name. |

## Options [#options]

| Name                    | Type               | Required | Description                       |
| ----------------------- | ------------------ | -------- | --------------------------------- |
| `--description`         | `string`           | No       | Parent description.               |
| `--version-description` | `string`           | No       | Version description.              |
| `--spec`                | `path`             | No       | YAML or JSON spec document.       |
| `--command`             | `string`           | No       | Shell command stored as supplied. |
| `--display-version`     | `string`           | No       | Human-readable version.           |
| `--working-dir`         | `path`             | No       | Worker process directory.         |
| `--env`                 | `KEY=VALUE[]`      | No       | Non-secret process environment.   |
| `--secret-id`           | `UUID[]`           | No       | Server secret IDs.                |
| `--timeout-seconds`     | `positive integer` | No       | Process timeout.                  |
| `--tool`                | `string[]`         | No       | Declared tools.                   |
| `--mcp-server`          | `string[]`         | No       | Declared MCP servers.             |
| `--skill`               | `string[]`         | No       | Declared skills.                  |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer get



## Usage [#usage]

```bash
kitaru analyzer get ANALYZER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `ANALYZER` | `reference` | Yes      | Analyzer UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer



## Usage [#usage]

```bash
kitaru analyzer COMMAND
```

## Commands [#commands]

| Command                               | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| [`get`](/cli/analyzer/get/)           | Get an analyzer by exact UUID or case-sensitive name. |
| [`list`](/cli/analyzer/list/)         | List analyzers.                                       |
| [`register`](/cli/analyzer/register/) | Create an analyzer and its first version.             |
| [`version`](/cli/analyzer/version/)   | Subcommands of `kitaru analyzer version`.             |


# kitaru analyzer list



## Usage [#usage]

```bash
kitaru analyzer list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer register



## Usage [#usage]

```bash
kitaru analyzer register NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description        |
| ------ | -------- | -------- | ------------------ |
| `NAME` | `string` | Yes      | New analyzer name. |

## Options [#options]

| Name                  | Type          | Required | Description                                        |
| --------------------- | ------------- | -------- | -------------------------------------------------- |
| `--description`       | `string`      | No       | Parent description.                                |
| `--metadata`          | `JSON object` | No       | Parent metadata.                                   |
| `--provider`          | `string`      | No       | Source provider.                                   |
| `--connection-schema` | `path`        | No       | JSON Schema file describing the connection values. |
| `--script`            | `path`        | No       | Python script to upload.                           |
| `--package`           | `requirement` | No       | Pinned package requirement.                        |
| `--entrypoint`        | `string`      | Yes      | Script attribute or module reference.              |
| `--display-version`   | `string`      | No       | Human-readable version.                            |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru annotation create



## Usage [#usage]

```bash
kitaru annotation create [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name                      | Type          | Required | Description                                                                                           |
| ------------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--session`               | `UUID`        | No       | Session ID for a manual annotation.                                                                   |
| `--investigation-session` | `UUID`        | No       | Investigation-session ID for an answer.                                                               |
| `--question-key`          | `string`      | No       | Key of the question being answered.                                                                   |
| `--selector`              | `JSON object` | No       | Optional node, JSON Pointer, or span selector.                                                        |
| `--value`                 | `JSON value`  | Yes      | Annotation value.                                                                                     |
| `--idempotency-key`       | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru annotation delete



## Usage [#usage]

```bash
kitaru annotation delete ANNOTATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `ANNOTATION` | `UUID` | Yes      | Annotation ID. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru annotation get



## Usage [#usage]

```bash
kitaru annotation get ANNOTATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `ANNOTATION` | `UUID` | Yes      | Annotation ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru annotation



## Usage [#usage]

```bash
kitaru annotation COMMAND
```

## Commands [#commands]

| Command                             | Description                                                     |
| ----------------------------------- | --------------------------------------------------------------- |
| [`create`](/cli/annotation/create/) | Create a manual annotation or answer an investigation question. |
| [`delete`](/cli/annotation/delete/) | Delete an annotation.                                           |
| [`get`](/cli/annotation/get/)       | Get an annotation by exact UUID.                                |
| [`list`](/cli/annotation/list/)     | List annotations.                                               |
| [`update`](/cli/annotation/update/) | Replace an annotation's JSON value.                             |


# kitaru annotation list



## Usage [#usage]

```bash
kitaru annotation list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru annotation update



## Usage [#usage]

```bash
kitaru annotation update ANNOTATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `ANNOTATION` | `UUID` | Yes      | Annotation ID. |

## Options [#options]

| Name      | Type         | Required | Description        |
| --------- | ------------ | -------- | ------------------ |
| `--value` | `JSON value` | Yes      | Replacement value. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort create



## Usage [#usage]

```bash
kitaru cohort create NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description      |
| ------ | -------- | -------- | ---------------- |
| `NAME` | `string` | Yes      | New cohort name. |

## Options [#options]

| Name                | Type          | Required | Description                                                                                           |
| ------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--agent`           | `reference`   | Yes      | Exact agent UUID or case-sensitive name.                                                              |
| `--description`     | `string`      | No       | Cohort description.                                                                                   |
| `--metadata`        | `JSON object` | No       | Cohort metadata.                                                                                      |
| `--session`         | `UUID[]`      | No       | Explicit session IDs.                                                                                 |
| `--sessions-file`   | `path`        | No       | UTF-8 file with one session UUID per nonblank line.                                                   |
| `--tag`             | `text`        | No       | Sessions with this tag.                                                                               |
| `--cohort`          | `reference`   | No       | Sessions in this cohort version.                                                                      |
| `--filter`          | `JSON filter` | No       | Session filter expression.                                                                            |
| `--all`             | `boolean`     | No       | All sessions.                                                                                         |
| `--display-version` | `string`      | No       | Display version for the membership snapshot.                                                          |
| `--idempotency-key` | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort delete



## Usage [#usage]

```bash
kitaru cohort delete COHORT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type        | Required | Description          |
| -------- | ----------- | -------- | -------------------- |
| `COHORT` | `reference` | Yes      | Cohort UUID or name. |

## Options [#options]

| Name      | Type      | Required | Description                        |
| --------- | --------- | -------- | ---------------------------------- |
| `--force` | `boolean` | No       | Confirm cascading remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort get



## Usage [#usage]

```bash
kitaru cohort get COHORT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type        | Required | Description          |
| -------- | ----------- | -------- | -------------------- |
| `COHORT` | `reference` | Yes      | Cohort UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort



## Usage [#usage]

```bash
kitaru cohort COMMAND
```

## Commands [#commands]

| Command                           | Description                                                |
| --------------------------------- | ---------------------------------------------------------- |
| [`create`](/cli/cohort/create/)   | Create a cohort and optionally snapshot selected sessions. |
| [`delete`](/cli/cohort/delete/)   | Delete a cohort and all of its versions.                   |
| [`get`](/cli/cohort/get/)         | Get a cohort by exact UUID or case-sensitive name.         |
| [`list`](/cli/cohort/list/)       | List cohorts.                                              |
| [`update`](/cli/cohort/update/)   | Update selected fields on an exact cohort.                 |
| [`version`](/cli/cohort/version/) | Subcommands of `kitaru cohort version`.                    |


# kitaru cohort list



## Usage [#usage]

```bash
kitaru cohort list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort update



## Usage [#usage]

```bash
kitaru cohort update COHORT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type        | Required | Description          |
| -------- | ----------- | -------- | -------------------- |
| `COHORT` | `reference` | Yes      | Cohort UUID or name. |

## Options [#options]

| Name                  | Type          | Required | Description                          |
| --------------------- | ------------- | -------- | ------------------------------------ |
| `--name`              | `string`      | No       | New cohort name.                     |
| `--description`       | `string`      | No       | New description.                     |
| `--clear-description` | `boolean`     | No       | Clear the description.               |
| `--metadata`          | `JSON object` | No       | Replacement metadata; \{} clears it. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru config get



## Usage [#usage]

```bash
kitaru config get KEY [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type     | Required | Description                 |
| ----- | -------- | -------- | --------------------------- |
| `KEY` | `string` | Yes      | Allowlisted preference key. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru config



## Usage [#usage]

```bash
kitaru config COMMAND
```

## Commands [#commands]

| Command                     | Description                                                         |
| --------------------------- | ------------------------------------------------------------------- |
| [`get`](/cli/config/get/)   | Get one allowlisted CLI preference.                                 |
| [`list`](/cli/config/list/) | List allowlisted CLI preferences with effective values and sources. |
| [`path`](/cli/config/path/) | Show the global CLI config path without reading its contents.       |
| [`set`](/cli/config/set/)   | Set one allowlisted CLI preference.                                 |


# kitaru config list



## Usage [#usage]

```bash
kitaru config list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru config path



## Usage [#usage]

```bash
kitaru config path [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru config set



## Usage [#usage]

```bash
kitaru config set KEY VALUE [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name    | Type      | Required | Description                 |
| ------- | --------- | -------- | --------------------------- |
| `KEY`   | `string`  | Yes      | Allowlisted preference key. |
| `VALUE` | `boolean` | Yes      | Boolean preference value.   |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluation get



## Usage [#usage]

```bash
kitaru evaluation get EVALUATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `EVALUATION` | `UUID` | Yes      | Evaluation ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluation



## Usage [#usage]

```bash
kitaru evaluation COMMAND
```

## Commands [#commands]

| Command                         | Description                            |
| ------------------------------- | -------------------------------------- |
| [`get`](/cli/evaluation/get/)   | Get a stored evaluation by exact UUID. |
| [`list`](/cli/evaluation/list/) | List stored evaluations.               |


# kitaru evaluation list



## Usage [#usage]

```bash
kitaru evaluation list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator get



## Usage [#usage]

```bash
kitaru evaluator get EVALUATOR [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name        | Type        | Required | Description             |
| ----------- | ----------- | -------- | ----------------------- |
| `EVALUATOR` | `reference` | Yes      | Evaluator UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator



## Usage [#usage]

```bash
kitaru evaluator COMMAND
```

## Commands [#commands]

| Command                                | Description                                                              |
| -------------------------------------- | ------------------------------------------------------------------------ |
| [`get`](/cli/evaluator/get/)           | Get an evaluator by exact UUID or case-sensitive name.                   |
| [`list`](/cli/evaluator/list/)         | List evaluators.                                                         |
| [`register`](/cli/evaluator/register/) | Create an evaluator and its first version.                               |
| [`scaffold`](/cli/evaluator/scaffold/) | Create a minimal evaluator script.                                       |
| [`test`](/cli/evaluator/test/)         | Load an evaluator and validate its signature in a bounded child process. |
| [`version`](/cli/evaluator/version/)   | Subcommands of `kitaru evaluator version`.                               |


# kitaru evaluator list



## Usage [#usage]

```bash
kitaru evaluator list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator register



## Usage [#usage]

```bash
kitaru evaluator register NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description         |
| ------ | -------- | -------- | ------------------- |
| `NAME` | `string` | Yes      | New evaluator name. |

## Options [#options]

| Name                | Type          | Required | Description                           |
| ------------------- | ------------- | -------- | ------------------------------------- |
| `--description`     | `string`      | No       | Parent description.                   |
| `--metadata`        | `JSON object` | No       | Parent metadata.                      |
| `--agent-id`        | `UUID`        | No       | Scoping agent.                        |
| `--script`          | `path`        | No       | Python script to upload.              |
| `--package`         | `requirement` | No       | Pinned package requirement.           |
| `--entrypoint`      | `string`      | Yes      | Script attribute or module reference. |
| `--display-version` | `string`      | No       | Human-readable version.               |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator scaffold



## Usage [#usage]

```bash
kitaru evaluator scaffold NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description    |
| ------ | -------- | -------- | -------------- |
| `NAME` | `string` | Yes      | Scaffold name. |

## Options [#options]

| Name      | Type      | Required | Description                |
| --------- | --------- | -------- | -------------------------- |
| `--path`  | `path`    | No       | Exact target .py file.     |
| `--force` | `boolean` | No       | Overwrite the target file. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator test



## Usage [#usage]

```bash
kitaru evaluator test PATH [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type   | Required | Description       |
| ------ | ------ | -------- | ----------------- |
| `PATH` | `path` | Yes      | Evaluator script. |

## Options [#options]

| Name           | Type             | Required | Description          |
| -------------- | ---------------- | -------- | -------------------- |
| `--entrypoint` | `attribute`      | Yes      | Evaluator attribute. |
| `--timeout`    | `positive float` | No       | Child timeout.       |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection create



## Usage [#usage]

```bash
kitaru connection create NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description          |
| ------ | -------- | -------- | -------------------- |
| `NAME` | `string` | Yes      | New connection name. |

## Options [#options]

| Name                | Type          | Required | Description                                                                                           |
| ------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--importer`        | `reference`   | No       | Importer whose connection schema drives the prompts.                                                  |
| `--analyzer`        | `reference`   | No       | Analyzer whose connection schema drives the prompts.                                                  |
| `--provider`        | `string`      | No       | Provider addressed directly.                                                                          |
| `--set`             | `KEY=VALUE[]` | No       | Non-secret environment value.                                                                         |
| `--set-secret`      | `KEY=VALUE[]` | No       | Sensitive environment value.                                                                          |
| `--default`         | `boolean`     | No       | Make this the provider's default connection.                                                          |
| `--idempotency-key` | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection delete



## Usage [#usage]

```bash
kitaru connection delete CONNECTION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `CONNECTION` | `reference` | Yes      | Connection UUID or name. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection get



## Usage [#usage]

```bash
kitaru connection get CONNECTION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `CONNECTION` | `reference` | Yes      | Connection UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection



## Usage [#usage]

```bash
kitaru connection COMMAND
```

## Commands [#commands]

| Command                                       | Description                                                     |
| --------------------------------------------- | --------------------------------------------------------------- |
| [`create`](/cli/connection/create/)           | Create a connection from a plugin schema or from direct values. |
| [`delete`](/cli/connection/delete/)           | Delete a connection and the secret holding its values.          |
| [`get`](/cli/connection/get/)                 | Get a connection by exact UUID or case-sensitive name.          |
| [`list`](/cli/connection/list/)               | List connections.                                               |
| [`set-default`](/cli/connection/set-default/) | Make a connection the default for its provider.                 |
| [`update`](/cli/connection/update/)           | Update values on an exact connection.                           |


# kitaru connection list



## Usage [#usage]

```bash
kitaru connection list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection set-default



## Usage [#usage]

```bash
kitaru connection set-default CONNECTION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `CONNECTION` | `reference` | Yes      | Connection UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru connection update



## Usage [#usage]

```bash
kitaru connection update CONNECTION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `CONNECTION` | `reference` | Yes      | Connection UUID or name. |

## Options [#options]

| Name                     | Type          | Required | Description                                                     |
| ------------------------ | ------------- | -------- | --------------------------------------------------------------- |
| `--set`                  | `KEY=VALUE[]` | No       | Non-secret environment value. Keeps the other stored values.    |
| `--set-secret`           | `KEY=VALUE[]` | No       | Sensitive environment value. Replaces all stored secret values. |
| `--default/--no-default` | `boolean`     | No       | Set or clear the provider's default connection.                 |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment create



## Usage [#usage]

```bash
kitaru experiment create NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description          |
| ------ | -------- | -------- | -------------------- |
| `NAME` | `string` | Yes      | New experiment name. |

## Options [#options]

| Name                 | Type                              | Required | Description                                                                                           |
| -------------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--agent`            | `reference`                       | Yes      | Exact agent UUID or case-sensitive name.                                                              |
| `--description`      | `string`                          | No       | Experiment description.                                                                               |
| `--override`         | `JSON object`                     | No       | Replay override applied to every run.                                                                 |
| `--tool-policy`      | `JSON object`                     | No       | Tool policy applied to every run; omitted uses the server default.                                    |
| `--evaluator`        | `reference[]`                     | Yes      | Exact EVALUATOR\@VERSION references.                                                                  |
| `--evaluator-params` | `EVALUATOR@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected evaluator token.                                                            |
| `--idempotency-key`  | `string`                          | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment delete



## Usage [#usage]

```bash
kitaru experiment delete EXPERIMENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `EXPERIMENT` | `reference` | Yes      | Experiment UUID or name. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment get



## Usage [#usage]

```bash
kitaru experiment get EXPERIMENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `EXPERIMENT` | `reference` | Yes      | Experiment UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment



## Usage [#usage]

```bash
kitaru experiment COMMAND
```

## Commands [#commands]

| Command                             | Description                                                 |
| ----------------------------------- | ----------------------------------------------------------- |
| [`create`](/cli/experiment/create/) | Create an experiment with exact evaluator versions.         |
| [`delete`](/cli/experiment/delete/) | Delete an experiment and preserve server conflict behavior. |
| [`get`](/cli/experiment/get/)       | Get an experiment by exact UUID or case-sensitive name.     |
| [`list`](/cli/experiment/list/)     | List experiments.                                           |
| [`run`](/cli/experiment/run/)       | Subcommands of `kitaru experiment run`.                     |
| [`update`](/cli/experiment/update/) | Update selected fields on an exact experiment.              |


# kitaru experiment list



## Usage [#usage]

```bash
kitaru experiment list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment update



## Usage [#usage]

```bash
kitaru experiment update EXPERIMENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `EXPERIMENT` | `reference` | Yes      | Experiment UUID or name. |

## Options [#options]

| Name                  | Type                              | Required | Description                                           |
| --------------------- | --------------------------------- | -------- | ----------------------------------------------------- |
| `--name`              | `string`                          | No       | New experiment name.                                  |
| `--description`       | `string`                          | No       | New description.                                      |
| `--clear-description` | `boolean`                         | No       | Clear the description.                                |
| `--override`          | `JSON object`                     | No       | Replacement replay override.                          |
| `--clear-override`    | `boolean`                         | No       | Clear the replay override.                            |
| `--tool-policy`       | `JSON object`                     | No       | Replacement tool policy; cannot be cleared.           |
| `--evaluator`         | `reference[]`                     | No       | Exact evaluator versions replacing the complete list. |
| `--evaluator-params`  | `EVALUATOR@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected evaluator token.            |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru import analyze



## Usage [#usage]

```bash
kitaru import analyze IMPORT_ID [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name        | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `IMPORT_ID` | `UUID` | Yes      | Import ID.  |

## Options [#options]

| Name                    | Type                             | Required | Description                                                                                           |
| ----------------------- | -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--analyzer`            | `ANALYZER@VERSION[]`             | Yes      | Exact analyzer version run once over the import's sessions.                                           |
| `--analyzer-params`     | `ANALYZER@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected analyzer token.                                                             |
| `--analyzer-connection` | `ANALYZER@VERSION=CONNECTION[]`  | No       | Connection for a selected analyzer token.                                                             |
| `--wait`                | `boolean`                        | No       | Wait for remote work settlement.                                                                      |
| `--interval`            | `positive float`                 | No       | Polling interval; requires --wait.                                                                    |
| `--timeout`             | `positive float`                 | No       | Local wait timeout; requires --wait.                                                                  |
| `--idempotency-key`     | `string`                         | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru import get



## Usage [#usage]

```bash
kitaru import get IMPORT_ID [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name        | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `IMPORT_ID` | `UUID` | Yes      | Import ID.  |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru import



## Usage [#usage]

```bash
kitaru import COMMAND
```

## Commands [#commands]

| Command                           | Description                                                       |
| --------------------------------- | ----------------------------------------------------------------- |
| [`analyze`](/cli/import/analyze/) | Run analyzers over the sessions of an existing import as one job. |
| [`get`](/cli/import/get/)         | Get one import by exact UUID.                                     |
| [`list`](/cli/import/list/)       | List imports.                                                     |


# kitaru import list



## Usage [#usage]

```bash
kitaru import list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer get



## Usage [#usage]

```bash
kitaru importer get IMPORTER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `IMPORTER` | `reference` | Yes      | Importer UUID or name. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer



## Usage [#usage]

```bash
kitaru importer COMMAND
```

## Commands [#commands]

| Command                               | Description                                                               |
| ------------------------------------- | ------------------------------------------------------------------------- |
| [`get`](/cli/importer/get/)           | Get an importer by exact UUID or case-sensitive name.                     |
| [`list`](/cli/importer/list/)         | List importers.                                                           |
| [`register`](/cli/importer/register/) | Create an importer and its first version.                                 |
| [`scaffold`](/cli/importer/scaffold/) | Create a minimal importer Parser script.                                  |
| [`test`](/cli/importer/test/)         | Load and optionally invoke an importer Parser in a bounded child process. |
| [`version`](/cli/importer/version/)   | Subcommands of `kitaru importer version`.                                 |


# kitaru importer list



## Usage [#usage]

```bash
kitaru importer list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer register



## Usage [#usage]

```bash
kitaru importer register NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description        |
| ------ | -------- | -------- | ------------------ |
| `NAME` | `string` | Yes      | New importer name. |

## Options [#options]

| Name                  | Type          | Required | Description                                        |
| --------------------- | ------------- | -------- | -------------------------------------------------- |
| `--description`       | `string`      | No       | Parent description.                                |
| `--metadata`          | `JSON object` | No       | Parent metadata.                                   |
| `--provider`          | `string`      | No       | Source provider.                                   |
| `--connection-schema` | `path`        | No       | JSON Schema file describing the connection values. |
| `--script`            | `path`        | No       | Python script to upload.                           |
| `--package`           | `requirement` | No       | Pinned package requirement.                        |
| `--entrypoint`        | `string`      | Yes      | Script attribute or module reference.              |
| `--display-version`   | `string`      | No       | Human-readable version.                            |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer scaffold



## Usage [#usage]

```bash
kitaru importer scaffold NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description    |
| ------ | -------- | -------- | -------------- |
| `NAME` | `string` | Yes      | Scaffold name. |

## Options [#options]

| Name      | Type      | Required | Description                |
| --------- | --------- | -------- | -------------------------- |
| `--path`  | `path`    | No       | Exact target .py file.     |
| `--force` | `boolean` | No       | Overwrite the target file. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer test



## Usage [#usage]

```bash
kitaru importer test PATH [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type   | Required | Description      |
| ------ | ------ | -------- | ---------------- |
| `PATH` | `path` | Yes      | Importer script. |

## Options [#options]

| Name           | Type             | Required | Description        |
| -------------- | ---------------- | -------- | ------------------ |
| `--entrypoint` | `attribute`      | Yes      | Parser attribute.  |
| `--payload`    | `path`           | No       | Payload to parse.  |
| `--params`     | `JSON object`    | No       | Parser parameters. |
| `--timeout`    | `positive float` | No       | Child timeout.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru insight create



## Usage [#usage]

```bash
kitaru insight create [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name                | Type        | Required | Description                                                                                           |
| ------------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--agent`           | `reference` | Yes      | Agent UUID or case-sensitive name.                                                                    |
| `--insight`         | `JSON[]`    | Yes      | Insight JSON object; repeat for each created insight.                                                 |
| `--idempotency-key` | `string`    | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru insight delete



## Usage [#usage]

```bash
kitaru insight delete INSIGHT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `INSIGHT` | `UUID` | Yes      | Insight ID. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru insight get



## Usage [#usage]

```bash
kitaru insight get INSIGHT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `INSIGHT` | `UUID` | Yes      | Insight ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru insight



## Usage [#usage]

```bash
kitaru insight COMMAND
```

## Commands [#commands]

| Command                          | Description                               |
| -------------------------------- | ----------------------------------------- |
| [`create`](/cli/insight/create/) | Create a batch of insights for one agent. |
| [`delete`](/cli/insight/delete/) | Delete an insight.                        |
| [`get`](/cli/insight/get/)       | Get an insight by exact UUID.             |
| [`list`](/cli/insight/list/)     | List insights.                            |
| [`update`](/cli/insight/update/) | Update selected insight fields.           |


# kitaru insight list



## Usage [#usage]

```bash
kitaru insight list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type                        | Required | Description                                      |
| ---------- | --------------------------- | -------- | ------------------------------------------------ |
| `--size`   | `integer`                   | No       | Items per page (1-1000).                         |
| `--cursor` | `string`                    | No       | Cursor from the previous page.                   |
| `--sort`   | `field:direction`           | No       | Sort by created:asc or created:desc.             |
| `--filter` | `JSON`                      | No       | Advanced JSON filter expression.                 |
| `--agent`  | `reference`                 | No       | Only insights for this exact agent UUID or name. |
| `--name`   | `string`                    | No       | Only insights with this exact name.              |
| `--type`   | `text\|categorical\|binned` | No       | Only insights with this data type.               |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru insight update



## Usage [#usage]

```bash
kitaru insight update INSIGHT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `INSIGHT` | `UUID` | Yes      | Insight ID. |

## Options [#options]

| Name                  | Type      | Required | Description            |
| --------------------- | --------- | -------- | ---------------------- |
| `--title`             | `string`  | No       | New title.             |
| `--description`       | `string`  | No       | New description.       |
| `--clear-description` | `boolean` | No       | Clear the description. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation create



## Usage [#usage]

```bash
kitaru investigation create NAME [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name   | Type     | Required | Description             |
| ------ | -------- | -------- | ----------------------- |
| `NAME` | `string` | Yes      | New investigation name. |

## Options [#options]

| Name                   | Type                       | Required | Description                                                                                           |
| ---------------------- | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--agent`              | `reference`                | Yes      | Agent UUID or case-sensitive name.                                                                    |
| `--description`        | `string`                   | No       | Curator rationale.                                                                                    |
| `--session`            | `UUID[]`                   | No       | Ordered session UUID; repeat for each linked session.                                                 |
| `--session-question`   | `SESSION:KEY=QUESTION[]`   | No       | Keyed question for a session selected with --session.                                                 |
| `--session-highlights` | `SESSION:KEY=JSON_ARRAY[]` | No       | Curated highlights for a question added with --session-question.                                      |
| `--idempotency-key`    | `string`                   | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation delete



## Usage [#usage]

```bash
kitaru investigation delete INVESTIGATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `INVESTIGATION` | `UUID` | Yes      | Investigation ID. |

## Options [#options]

| Name      | Type      | Required | Description                        |
| --------- | --------- | -------- | ---------------------------------- |
| `--force` | `boolean` | No       | Confirm cascading remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation get



## Usage [#usage]

```bash
kitaru investigation get INVESTIGATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `INVESTIGATION` | `UUID` | Yes      | Investigation ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation



## Usage [#usage]

```bash
kitaru investigation COMMAND
```

## Commands [#commands]

| Command                                  | Description                                                    |
| ---------------------------------------- | -------------------------------------------------------------- |
| [`create`](/cli/investigation/create/)   | Create an investigation with linked sessions.                  |
| [`delete`](/cli/investigation/delete/)   | Delete an investigation, its linked sessions, and its answers. |
| [`get`](/cli/investigation/get/)         | Get an investigation by exact UUID.                            |
| [`list`](/cli/investigation/list/)       | List investigations.                                           |
| [`session`](/cli/investigation/session/) | Subcommands of `kitaru investigation session`.                 |
| [`update`](/cli/investigation/update/)   | Update selected investigation fields.                          |


# kitaru investigation list



## Usage [#usage]

```bash
kitaru investigation list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation update



## Usage [#usage]

```bash
kitaru investigation update INVESTIGATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `INVESTIGATION` | `UUID` | Yes      | Investigation ID. |

## Options [#options]

| Name                  | Type                     | Required | Description                  |
| --------------------- | ------------------------ | -------- | ---------------------------- |
| `--name`              | `string`                 | No       | New name.                    |
| `--description`       | `string`                 | No       | New curator rationale.       |
| `--clear-description` | `boolean`                | No       | Clear the curator rationale. |
| `--status`            | `in_progress\|completed` | No       | New investigation status.    |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru job cancel



## Usage [#usage]

```bash
kitaru job cancel JOB [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `JOB` | `UUID` | Yes      | Job ID.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru job get



## Usage [#usage]

```bash
kitaru job get JOB [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `JOB` | `UUID` | Yes      | Job ID.     |

## Options [#options]

| Name      | Type      | Required | Description            |
| --------- | --------- | -------- | ---------------------- |
| `--tasks` | `boolean` | No       | Include all job tasks. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru job



## Usage [#usage]

```bash
kitaru job COMMAND
```

## Commands [#commands]

| Command                      | Description                                                               |
| ---------------------------- | ------------------------------------------------------------------------- |
| [`cancel`](/cli/job/cancel/) | Request job cancellation once without waiting for settlement.             |
| [`get`](/cli/job/get/)       | Get a job and optionally include a complete task snapshot.                |
| [`watch`](/cli/job/watch/)   | Poll a job until it completes, fails, or is canceled without changing it. |


# kitaru job watch



## Usage [#usage]

```bash
kitaru job watch JOB [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name  | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `JOB` | `UUID` | Yes      | Job ID.     |

## Options [#options]

| Name         | Type             | Required | Description         |
| ------------ | ---------------- | -------- | ------------------- |
| `--interval` | `positive float` | No       | Polling interval.   |
| `--timeout`  | `positive float` | No       | Local wait timeout. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru local



## Usage [#usage]

```bash
kitaru local COMMAND
```

## Commands [#commands]

| Command                    | Description                                    |
| -------------------------- | ---------------------------------------------- |
| [`logs`](/cli/local/logs/) | Read logs from the CLI-owned local deployment. |


# kitaru local logs



## Usage [#usage]

```bash
kitaru local logs [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Options [#options]

| Name        | Type         | Required | Description                          |
| ----------- | ------------ | -------- | ------------------------------------ |
| `--service` | `server\|db` | No       | Limit output to one Compose service. |
| `--tail`    | `integer`    | No       | Number of recent lines.              |
| `--follow`  | `boolean`    | No       | Follow new log lines.                |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru replay create



## Usage [#usage]

```bash
kitaru replay create BASELINE [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type   | Required | Description          |
| ---------- | ------ | -------- | -------------------- |
| `BASELINE` | `UUID` | Yes      | Baseline session ID. |

## Options [#options]

| Name                         | Type                              | Required | Description                                                                                           |
| ---------------------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--evaluator`                | `EVALUATOR@VERSION[]`             | Yes      | Exact evaluator version; repeat for additional evaluators.                                            |
| `--evaluator-params`         | `EVALUATOR@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected evaluator token.                                                            |
| `--agent`                    | `AGENT@VERSION`                   | No       | Exact agent version; omit to use the baseline's recorded version.                                     |
| `--override`                 | `JSON object`                     | No       | Replay model, prompt, or model-parameter override.                                                    |
| `--tool-policy`              | `JSON object`                     | No       | Tool policy; omitting it uses the server default and may execute live tools.                          |
| `--baseline-evaluation-mode` | `none\|if_missing\|force`         | No       | How to score the baseline session.                                                                    |
| `--idempotency-key`          | `string`                          | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru replay get



## Usage [#usage]

```bash
kitaru replay get REPLAY [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `REPLAY` | `UUID` | Yes      | Replay ID.  |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru replay



## Usage [#usage]

```bash
kitaru replay COMMAND
```

## Commands [#commands]

| Command                         | Description                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| [`create`](/cli/replay/create/) | Create one standalone replay from an exact baseline session. |
| [`get`](/cli/replay/get/)       | Get one replay by exact UUID.                                |
| [`list`](/cli/replay/list/)     | List standalone and experiment-created replays.              |


# kitaru replay list



## Usage [#usage]

```bash
kitaru replay list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru session evaluate



## Usage [#usage]

```bash
kitaru session evaluate [SESSION...] [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name      | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `SESSION` | `UUID[]` | No       | Explicit session IDs. |

## Options [#options]

| Name                 | Type                              | Required | Description                                                                                           |
| -------------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--sessions-file`    | `path`                            | No       | UTF-8 file with one session UUID per nonblank line.                                                   |
| `--tag`              | `text`                            | No       | Evaluate sessions with this tag.                                                                      |
| `--agent`            | `reference`                       | No       | Evaluate an agent's sessions.                                                                         |
| `--cohort`           | `reference`                       | No       | Evaluate sessions in this cohort version.                                                             |
| `--filter`           | `JSON filter`                     | No       | Evaluate matching sessions.                                                                           |
| `--all`              | `boolean`                         | No       | Evaluate all sessions.                                                                                |
| `--evaluator`        | `reference[]`                     | Yes      | Exact EVALUATOR\@VERSION references.                                                                  |
| `--evaluator-params` | `EVALUATOR@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected evaluator token.                                                            |
| `--wait`             | `boolean`                         | No       | Wait for remote work settlement.                                                                      |
| `--interval`         | `positive float`                  | No       | Polling interval; requires --wait.                                                                    |
| `--timeout`          | `positive float`                  | No       | Local wait timeout; requires --wait.                                                                  |
| `--idempotency-key`  | `string`                          | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru session get



## Usage [#usage]

```bash
kitaru session get SESSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `SESSION` | `UUID` | Yes      | Session ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru session import



## Usage [#usage]

```bash
kitaru session import [FILE] [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name   | Type   | Required | Description                                 |
| ------ | ------ | -------- | ------------------------------------------- |
| `FILE` | `path` | No       | Local payload file. Omit for an API import. |

## Options [#options]

| Name                    | Type                              | Required | Description                                                                                                       |
| ----------------------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `--importer`            | `reference`                       | Yes      | Exact IMPORTER\@VERSION reference.                                                                                |
| `--agent`               | `reference`                       | Yes      | Exact AGENT\@VERSION reference.                                                                                   |
| `--params`              | `JSON object`                     | No       | Importer parameters.                                                                                              |
| `--join-on`             | `JSON Pointer`                    | No       | Group source traces by the value at this RFC 6901 JSON Pointer.                                                   |
| `--since`               | `timestamp or duration`           | No       | For an API import, fetch traces at or after this ISO 8601 timestamp or relative duration such as 7d, 12h, or 30m. |
| `--until`               | `timestamp or duration`           | No       | For an API import, fetch traces before this ISO 8601 timestamp or relative duration such as 7d, 12h, or 30m.      |
| `--trace-id`            | `text[]`                          | No       | For an API import, fetch exactly these provider trace ids.                                                        |
| `--query`               | `JSON object`                     | No       | Additional importer-defined API selection fields, merged with --since, --until, and --trace-id.                   |
| `--connection`          | `reference`                       | No       | For an API import, the connection UUID or name supplying provider credentials.                                    |
| `--tag`                 | `text[]`                          | No       | Tag every session created by this import; requires --wait.                                                        |
| `--evaluator`           | `EVALUATOR@VERSION[]`             | No       | Exact evaluator version scored against every imported session.                                                    |
| `--evaluator-params`    | `EVALUATOR@VERSION=JSON_OBJECT[]` | No       | Parameters for a selected evaluator token.                                                                        |
| `--analyzer`            | `ANALYZER@VERSION[]`              | No       | Exact analyzer version run once over every imported session.                                                      |
| `--analyzer-params`     | `ANALYZER@VERSION=JSON_OBJECT[]`  | No       | Parameters for a selected analyzer token.                                                                         |
| `--analyzer-connection` | `ANALYZER@VERSION=CONNECTION[]`   | No       | Connection for a selected analyzer token.                                                                         |
| `--media-type`          | `string`                          | No       | Payload media type.                                                                                               |
| `--max-sessions`        | `integer`                         | No       | Stop the import after creating this many sessions.                                                                |
| `--wait`                | `boolean`                         | No       | Wait for remote work settlement.                                                                                  |
| `--interval`            | `positive float`                  | No       | Polling interval; requires --wait.                                                                                |
| `--timeout`             | `positive float`                  | No       | Local wait timeout; requires --wait.                                                                              |
| `--idempotency-key`     | `string`                          | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice.             |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru session



## Usage [#usage]

```bash
kitaru session COMMAND
```

## Commands [#commands]

| Command                              | Description                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------ |
| [`evaluate`](/cli/session/evaluate/) | Evaluate sessions selected by ID, tag, or all sessions.                        |
| [`get`](/cli/session/get/)           | Get a session by exact UUID.                                                   |
| [`import`](/cli/session/import/)     | Upload a local payload or fetch from a provider API, and create an import job. |
| [`list`](/cli/session/list/)         | List sessions.                                                                 |
| [`nodes`](/cli/session/nodes/)       | List a session's nodes in index order.                                         |


# kitaru session list



## Usage [#usage]

```bash
kitaru session list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name                 | Type                             | Required | Description                                                |
| -------------------- | -------------------------------- | -------- | ---------------------------------------------------------- |
| `--size`             | `integer`                        | No       | Items per page (1-1000).                                   |
| `--cursor`           | `string`                         | No       | Cursor from the previous page.                             |
| `--sort`             | `field:direction`                | No       | Sort by created:asc or created:desc.                       |
| `--filter`           | `JSON`                           | No       | Advanced JSON filter expression.                           |
| `--status`           | `in_progress\|completed\|failed` | No       | Only sessions with this status.                            |
| `--agent`            | `reference`                      | No       | Only sessions for this exact agent UUID or name.           |
| `--origin`           | `imported\|recorded\|replay`     | No       | Only sessions with this origin.                            |
| `--imported-from`    | `string`                         | No       | Only sessions imported from this exact source system.      |
| `--tag`              | `text`                           | No       | Only sessions with this tag.                               |
| `--cohort`           | `reference`                      | No       | Only sessions in this cohort version.                      |
| `--started-after`    | `timestamp`                      | No       | Only sessions started at or after this ISO 8601 timestamp. |
| `--started-before`   | `timestamp`                      | No       | Only sessions started before this ISO 8601 timestamp.      |
| `--include-payloads` | `boolean`                        | No       | Include session inputs and outputs.                        |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru session nodes



## Usage [#usage]

```bash
kitaru session nodes SESSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `SESSION` | `UUID` | Yes      | Session ID. |

## Options [#options]

| Name                 | Type      | Required | Description                                   |
| -------------------- | --------- | -------- | --------------------------------------------- |
| `--size`             | `integer` | No       | Items per page.                               |
| `--cursor`           | `string`  | No       | Page cursor.                                  |
| `--filter`           | `JSON`    | No       | Filter expression as a JSON object.           |
| `--include-payloads` | `boolean` | No       | Include node inputs, outputs, and attributes. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru worker get



## Usage [#usage]

```bash
kitaru worker get WORKER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `WORKER` | `UUID` | Yes      | Worker ID.  |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru worker



## Usage [#usage]

```bash
kitaru worker COMMAND
```

## Commands [#commands]

| Command                       | Description                                                                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [`get`](/cli/worker/get/)     | Get a worker by exact UUID.                                                                                                                     |
| [`list`](/cli/worker/list/)   | List live workers, or every server record with --include-stale.                                                                                 |
| [`start`](/cli/worker/start/) | Run a generic local worker in the foreground without durable provider binding. The first SIGINT or SIGTERM requests a safe drain of held tasks. |


# kitaru worker list



## Usage [#usage]

```bash
kitaru worker list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name              | Type              | Required | Description                               |
| ----------------- | ----------------- | -------- | ----------------------------------------- |
| `--size`          | `integer`         | No       | Items per page (1-1000).                  |
| `--cursor`        | `string`          | No       | Cursor from the previous page.            |
| `--sort`          | `field:direction` | No       | Sort by created:asc or created:desc.      |
| `--filter`        | `JSON`            | No       | Advanced JSON filter expression.          |
| `--include-stale` | `boolean`         | No       | Include workers past the liveness window. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru worker start



## Usage [#usage]

```bash
kitaru worker start [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Options [#options]

| Name                   | Type                                       | Required | Description                                                                                                   |
| ---------------------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `--name`               | `string`                                   | No       | Ephemeral worker name.                                                                                        |
| `--claim`              | `agent\|evaluator\|importer\|agent=UUID[]` | No       | Claim the worker serves: agent, evaluator, importer, or agent=AGENT\_VERSION\_ID. Repeat for multiple claims. |
| `--selector`           | `KEY=[VALUE[,VALUE]][]\|JSON[]`            | No       | Task label selectors, combined by conjunction.                                                                |
| `--job-id`             | `UUID`                                     | No       | Restrict claims to one job.                                                                                   |
| `--concurrency`        | `positive integer`                         | No       | Maximum held tasks.                                                                                           |
| `--claim-batch-size`   | `positive integer`                         | No       | Maximum tasks per claim.                                                                                      |
| `--poll-interval`      | `positive float`                           | No       | Idle polling interval.                                                                                        |
| `--heartbeat-interval` | `positive float`                           | No       | Heartbeat interval.                                                                                           |
| `--timeout`            | `positive float`                           | No       | Worker lifetime in seconds.                                                                                   |
| `--drain-timeout`      | `positive float`                           | No       | Seconds to wait for held tasks before canceling them.                                                         |
| `--blob-cache-root`    | `path`                                     | No       | Blob cache directory.                                                                                         |
| `--payload-cache-root` | `path`                                     | No       | Payload cache directory.                                                                                      |
| `--metadata`           | `KEY=VALUE[]`                              | No       | Worker registration metadata.                                                                                 |
| `--log-level`          | `string`                                   | No       | Log level for worker runtime logs: debug, info, warning, or error.                                            |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru



Kitaru.

<Tabs items="[&#x22;Modules&#x22;]">
  <Tab value="&#x22;Modules&#x22;">
    <Cards>
      <Card href="&#x22;/reference/python/api_models&#x22;" title="&#x22;api_models&#x22;" />

      <Card href="&#x22;/reference/python/client&#x22;" title="&#x22;client&#x22;" />

      <Card href="&#x22;/reference/python/task&#x22;" title="&#x22;task&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# kitaru agent version get



## Usage [#usage]

```bash
kitaru agent version get AGENT@VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type        | Required | Description              |
| --------------- | ----------- | -------- | ------------------------ |
| `AGENT@VERSION` | `reference` | Yes      | Exact version reference. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent version



## Usage [#usage]

```bash
kitaru agent version COMMAND
```

## Commands [#commands]

| Command                                    | Description                                              |
| ------------------------------------------ | -------------------------------------------------------- |
| [`get`](/cli/agent/version/get/)           | Get an agent version by exact PARENT\@VERSION reference. |
| [`list`](/cli/agent/version/list/)         | List versions of an exact agent.                         |
| [`register`](/cli/agent/version/register/) | Create the next mutable version of an existing agent.    |


# kitaru agent version list



## Usage [#usage]

```bash
kitaru agent version list AGENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name    | Type        | Required | Description         |
| ------- | ----------- | -------- | ------------------- |
| `AGENT` | `reference` | Yes      | Agent UUID or name. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru agent version register



## Usage [#usage]

```bash
kitaru agent version register AGENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name    | Type        | Required | Description         |
| ------- | ----------- | -------- | ------------------- |
| `AGENT` | `reference` | Yes      | Agent UUID or name. |

## Options [#options]

| Name                | Type               | Required | Description                                                                                           |
| ------------------- | ------------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `--description`     | `string`           | No       | Version description.                                                                                  |
| `--spec`            | `path`             | No       | YAML or JSON spec document.                                                                           |
| `--command`         | `string`           | No       | Shell command stored as supplied.                                                                     |
| `--display-version` | `string`           | No       | Human-readable version.                                                                               |
| `--working-dir`     | `path`             | No       | Worker process directory.                                                                             |
| `--env`             | `KEY=VALUE[]`      | No       | Non-secret process environment.                                                                       |
| `--secret-id`       | `UUID[]`           | No       | Server secret IDs.                                                                                    |
| `--timeout-seconds` | `positive integer` | No       | Process timeout.                                                                                      |
| `--tool`            | `string[]`         | No       | Declared tools.                                                                                       |
| `--mcp-server`      | `string[]`         | No       | Declared MCP servers.                                                                                 |
| `--skill`           | `string[]`         | No       | Declared skills.                                                                                      |
| `--idempotency-key` | `string`           | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer version get



## Usage [#usage]

```bash
kitaru analyzer version get ANALYZER@VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name               | Type        | Required | Description              |
| ------------------ | ----------- | -------- | ------------------------ |
| `ANALYZER@VERSION` | `reference` | Yes      | Exact version reference. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer version



## Usage [#usage]

```bash
kitaru analyzer version COMMAND
```

## Commands [#commands]

| Command                                       | Description                                                 |
| --------------------------------------------- | ----------------------------------------------------------- |
| [`get`](/cli/analyzer/version/get/)           | Get an analyzer version by exact PARENT\@VERSION reference. |
| [`list`](/cli/analyzer/version/list/)         | List versions of an exact analyzer.                         |
| [`register`](/cli/analyzer/version/register/) | Create the next version of an existing analyzer.            |


# kitaru analyzer version list



## Usage [#usage]

```bash
kitaru analyzer version list ANALYZER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `ANALYZER` | `reference` | Yes      | Analyzer UUID or name. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru analyzer version register



## Usage [#usage]

```bash
kitaru analyzer version register ANALYZER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `ANALYZER` | `reference` | Yes      | Analyzer UUID or name. |

## Options [#options]

| Name                | Type          | Required | Description                                                                                           |
| ------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--script`          | `path`        | No       | Python script to upload.                                                                              |
| `--package`         | `requirement` | No       | Pinned package requirement.                                                                           |
| `--entrypoint`      | `string`      | Yes      | Script attribute or module reference.                                                                 |
| `--display-version` | `string`      | No       | Human-readable version.                                                                               |
| `--idempotency-key` | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort version create



## Usage [#usage]

```bash
kitaru cohort version create COHORT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type        | Required | Description          |
| -------- | ----------- | -------- | -------------------- |
| `COHORT` | `reference` | Yes      | Cohort UUID or name. |

## Options [#options]

| Name                | Type     | Required | Description                                                                                           |
| ------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--add-session`     | `UUID[]` | No       | Ordered session IDs to add.                                                                           |
| `--remove-session`  | `UUID[]` | No       | Ordered session IDs to remove.                                                                        |
| `--baseline`        | `UUID`   | No       | Exact cohort version the membership delta applies to.                                                 |
| `--display-version` | `string` | No       | Human-readable version.                                                                               |
| `--idempotency-key` | `string` | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort version delete



## Usage [#usage]

```bash
kitaru cohort version delete VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type                   | Required | Description                                           |
| --------- | ---------------------- | -------- | ----------------------------------------------------- |
| `VERSION` | `UUID\|COHORT@VERSION` | Yes      | Cohort-version UUID or exact server-assigned version. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort version get



## Usage [#usage]

```bash
kitaru cohort version get VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type                   | Required | Description                                           |
| --------- | ---------------------- | -------- | ----------------------------------------------------- |
| `VERSION` | `UUID\|COHORT@VERSION` | Yes      | Cohort-version UUID or exact server-assigned version. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort version



## Usage [#usage]

```bash
kitaru cohort version COMMAND
```

## Commands [#commands]

| Command                                 | Description                                                     |
| --------------------------------------- | --------------------------------------------------------------- |
| [`create`](/cli/cohort/version/create/) | Create the next immutable version from a membership delta.      |
| [`delete`](/cli/cohort/version/delete/) | Delete one immutable cohort version without reusing its number. |
| [`get`](/cli/cohort/version/get/)       | Get a version by UUID or exact COHORT\@VERSION reference.       |
| [`list`](/cli/cohort/version/list/)     | List immutable versions of an exact cohort.                     |
| [`update`](/cli/cohort/version/update/) | Update a cohort version's display version.                      |


# kitaru cohort version list



## Usage [#usage]

```bash
kitaru cohort version list COHORT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name     | Type        | Required | Description          |
| -------- | ----------- | -------- | -------------------- |
| `COHORT` | `reference` | Yes      | Cohort UUID or name. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru cohort version update



## Usage [#usage]

```bash
kitaru cohort version update VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name      | Type                   | Required | Description                                           |
| --------- | ---------------------- | -------- | ----------------------------------------------------- |
| `VERSION` | `UUID\|COHORT@VERSION` | Yes      | Cohort-version UUID or exact server-assigned version. |

## Options [#options]

| Name                      | Type      | Required | Description                       |
| ------------------------- | --------- | -------- | --------------------------------- |
| `--display-version`       | `string`  | No       | New human-readable version.       |
| `--clear-display-version` | `boolean` | No       | Clear the human-readable version. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator version get



## Usage [#usage]

```bash
kitaru evaluator version get EVALUATOR@VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name                | Type        | Required | Description              |
| ------------------- | ----------- | -------- | ------------------------ |
| `EVALUATOR@VERSION` | `reference` | Yes      | Exact version reference. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator version



## Usage [#usage]

```bash
kitaru evaluator version COMMAND
```

## Commands [#commands]

| Command                                        | Description                                                  |
| ---------------------------------------------- | ------------------------------------------------------------ |
| [`get`](/cli/evaluator/version/get/)           | Get an evaluator version by exact PARENT\@VERSION reference. |
| [`list`](/cli/evaluator/version/list/)         | List versions of an exact evaluator.                         |
| [`register`](/cli/evaluator/version/register/) | Create the next version of an existing evaluator.            |


# kitaru evaluator version list



## Usage [#usage]

```bash
kitaru evaluator version list EVALUATOR [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name        | Type        | Required | Description             |
| ----------- | ----------- | -------- | ----------------------- |
| `EVALUATOR` | `reference` | Yes      | Evaluator UUID or name. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru evaluator version register



## Usage [#usage]

```bash
kitaru evaluator version register EVALUATOR [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name        | Type        | Required | Description             |
| ----------- | ----------- | -------- | ----------------------- |
| `EVALUATOR` | `reference` | Yes      | Evaluator UUID or name. |

## Options [#options]

| Name                | Type          | Required | Description                                                                                           |
| ------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--script`          | `path`        | No       | Python script to upload.                                                                              |
| `--package`         | `requirement` | No       | Pinned package requirement.                                                                           |
| `--entrypoint`      | `string`      | Yes      | Script attribute or module reference.                                                                 |
| `--display-version` | `string`      | No       | Human-readable version.                                                                               |
| `--idempotency-key` | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run cancel



## Usage [#usage]

```bash
kitaru experiment run cancel RUN [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `RUN` | `UUID` | Yes      | Experiment-run ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run delete



## Usage [#usage]

```bash
kitaru experiment run delete RUN [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `RUN` | `UUID` | Yes      | Experiment-run ID. |

## Options [#options]

| Name      | Type      | Required | Description              |
| --------- | --------- | -------- | ------------------------ |
| `--force` | `boolean` | No       | Confirm remote deletion. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run get



## Usage [#usage]

```bash
kitaru experiment run get RUN [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `RUN` | `UUID` | Yes      | Experiment-run ID. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run



## Usage [#usage]

```bash
kitaru experiment run COMMAND
```

## Commands [#commands]

| Command                                 | Description                                                               |
| --------------------------------------- | ------------------------------------------------------------------------- |
| [`cancel`](/cli/experiment/run/cancel/) | Request run cancellation once without waiting for settlement.             |
| [`delete`](/cli/experiment/run/delete/) | Delete a run and immediately delete all of its replay jobs and tasks.     |
| [`get`](/cli/experiment/run/get/)       | Get an experiment run and its aggregate progress by exact UUID.           |
| [`jobs`](/cli/experiment/run/jobs/)     | List one page of replay jobs backing an experiment run.                   |
| [`list`](/cli/experiment/run/list/)     | List experiment runs without deriving state from their jobs.              |
| [`start`](/cli/experiment/run/start/)   | Start an experiment run and optionally wait for terminal settlement.      |
| [`watch`](/cli/experiment/run/watch/)   | Poll a run until it completes, fails, or is canceled without changing it. |


# kitaru experiment run jobs



## Usage [#usage]

```bash
kitaru experiment run jobs RUN [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `RUN` | `UUID` | Yes      | Experiment-run ID. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run list



## Usage [#usage]

```bash
kitaru experiment run list [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |
| `--filter` | `JSON`            | No       | Advanced JSON filter expression.     |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run start



## Usage [#usage]

```bash
kitaru experiment run start EXPERIMENT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name         | Type        | Required | Description              |
| ------------ | ----------- | -------- | ------------------------ |
| `EXPERIMENT` | `reference` | Yes      | Experiment UUID or name. |

## Options [#options]

| Name                         | Type                      | Required | Description                                                                                           |
| ---------------------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--cohort-version`           | `UUID`                    | Yes      | Exact cohort-version ID.                                                                              |
| `--agent`                    | `AGENT@VERSION`           | Yes      | Exact agent version reference.                                                                        |
| `--baseline-evaluation-mode` | `none\|if_missing\|force` | No       | How to score each baseline session.                                                                   |
| `--wait`                     | `boolean`                 | No       | Wait for remote work settlement.                                                                      |
| `--interval`                 | `positive float`          | No       | Polling interval; requires --wait.                                                                    |
| `--timeout`                  | `positive float`          | No       | Local wait timeout; requires --wait.                                                                  |
| `--idempotency-key`          | `string`                  | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru experiment run watch



## Usage [#usage]

```bash
kitaru experiment run watch RUN [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`, `jsonl`.

## Arguments [#arguments]

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `RUN` | `UUID` | Yes      | Experiment-run ID. |

## Options [#options]

| Name         | Type             | Required | Description           |
| ------------ | ---------------- | -------- | --------------------- |
| `--interval` | `positive float` | No       | Run polling interval. |
| `--timeout`  | `positive float` | No       | Local wait timeout.   |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer version get



## Usage [#usage]

```bash
kitaru importer version get IMPORTER@VERSION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name               | Type        | Required | Description              |
| ------------------ | ----------- | -------- | ------------------------ |
| `IMPORTER@VERSION` | `reference` | Yes      | Exact version reference. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer version



## Usage [#usage]

```bash
kitaru importer version COMMAND
```

## Commands [#commands]

| Command                                       | Description                                                 |
| --------------------------------------------- | ----------------------------------------------------------- |
| [`get`](/cli/importer/version/get/)           | Get an importer version by exact PARENT\@VERSION reference. |
| [`list`](/cli/importer/version/list/)         | List versions of an exact importer.                         |
| [`register`](/cli/importer/version/register/) | Create the next version of an existing importer.            |


# kitaru importer version list



## Usage [#usage]

```bash
kitaru importer version list IMPORTER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `IMPORTER` | `reference` | Yes      | Importer UUID or name. |

## Options [#options]

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `--size`   | `integer`         | No       | Items per page (1-1000).             |
| `--cursor` | `string`          | No       | Cursor from the previous page.       |
| `--sort`   | `field:direction` | No       | Sort by created:asc or created:desc. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru importer version register



## Usage [#usage]

```bash
kitaru importer version register IMPORTER [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name       | Type        | Required | Description            |
| ---------- | ----------- | -------- | ---------------------- |
| `IMPORTER` | `reference` | Yes      | Importer UUID or name. |

## Options [#options]

| Name                | Type          | Required | Description                                                                                           |
| ------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `--script`          | `path`        | No       | Python script to upload.                                                                              |
| `--package`         | `requirement` | No       | Pinned package requirement.                                                                           |
| `--entrypoint`      | `string`      | Yes      | Script attribute or module reference.                                                                 |
| `--display-version` | `string`      | No       | Human-readable version.                                                                               |
| `--idempotency-key` | `string`      | No       | Retrying this exact invocation with the same key returns the original result instead of acting twice. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation session



## Usage [#usage]

```bash
kitaru investigation session COMMAND
```

## Commands [#commands]

| Command                                          | Description                                                     |
| ------------------------------------------------ | --------------------------------------------------------------- |
| [`list`](/cli/investigation/session/list/)       | List sessions linked to an investigation in presentation order. |
| [`verdict`](/cli/investigation/session/verdict/) | Set an investigation session verdict.                           |


# kitaru investigation session list



## Usage [#usage]

```bash
kitaru investigation session list INVESTIGATION [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| `INVESTIGATION` | `UUID` | Yes      | Investigation ID. |

## Options [#options]

| Name       | Type      | Required | Description                    |
| ---------- | --------- | -------- | ------------------------------ |
| `--size`   | `integer` | No       | Items per page (1-1000).       |
| `--cursor` | `string`  | No       | Cursor from the previous page. |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# kitaru investigation session verdict



## Usage [#usage]

```bash
kitaru investigation session verdict INVESTIGATION SESSION VERDICT [OPTIONS]
```

Supported `--output` modes: `auto`, `text`, `json`.

## Arguments [#arguments]

| Name            | Type                                 | Required | Description                             |
| --------------- | ------------------------------------ | -------- | --------------------------------------- |
| `INVESTIGATION` | `UUID`                               | Yes      | Investigation ID.                       |
| `SESSION`       | `UUID`                               | Yes      | Session ID linked to the investigation. |
| `VERDICT`       | `acceptable\|problematic\|uncertain` | Yes      | Verdict for the investigation session.  |

Every command also accepts the [global options](/cli/) listed on the CLI overview page.


# api_models



API wire contract models.

<Tabs items="[&#x22;Modules&#x22;]">
  <Tab value="&#x22;Modules&#x22;">
    <Cards>
      <Card href="&#x22;/reference/python/api_models/v1&#x22;" title="&#x22;v1&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# task



Agent-facing accessors for code running inside a task process.

<Tabs items="[&#x22;Functions&#x22;,&#x22;Modules&#x22;]">
  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;get_task_id&#x22;" type="&#x22;() -> str | None&#x22;">
      Get the id of the running task.

      <PySourceCode>
        ```python
        def get_task_id() -> str | None:
            """Get the id of the running task.

            Returns:
                Task id, None outside task mode.
            """
            return os.environ.get("KITARU_TASK_ID")
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;str | None&#x22;">
        Task id, None outside task mode.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;get_task_inputs&#x22;" type="&#x22;() -> Any&#x22;">
      Get the inputs of the running agent task.

      Reads KITARU\_TASK\_INPUTS when set. Otherwise fetches the task spec with a
      single synchronous request, since this accessor must stay callable from
      inside a running event loop.

      <PySourceCode>
        ```python
        def get_task_inputs() -> Any:
            """Get the inputs of the running agent task.

            Reads KITARU_TASK_INPUTS when set. Otherwise fetches the task spec with a
            single synchronous request, since this accessor must stay callable from
            inside a running event loop.

            Raises:
                RuntimeError: KITARU_API_URL is not set and the spec fetch fallback
                    is needed, or the task is not an agent task.

            Returns:
                Task inputs, None outside task mode.
            """
            task_id = os.environ.get("KITARU_TASK_ID")
            if task_id is None:
                return None
            inputs_env = os.environ.get("KITARU_TASK_INPUTS")
            if inputs_env is not None:
                return json.loads(inputs_env)

            base_url = get_required_env("KITARU_API_URL")
            headers = {}
            token = os.environ.get("KITARU_API_TOKEN")
            if token:
                headers["Authorization"] = f"Bearer {token}"
            response = httpx.get(f"{base_url}/api/v1/tasks/{task_id}/spec", headers=headers)
            response.raise_for_status()
            spec = TaskSpecResponse.model_validate(response.json())
            if not isinstance(spec.details, AgentTaskDetails):
                raise RuntimeError(f"Task {task_id} is not an agent task")
            return spec.details.inputs
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;typing.Any&#x22;">
        Task inputs, None outside task mode.
      </PyFunctionReturn>
    </PyFunction>
  </Tab>

  <Tab value="&#x22;Modules&#x22;">
    <Cards>
      <Card href="&#x22;/reference/python/task/analyzer&#x22;" title="&#x22;analyzer&#x22;" />

      <Card href="&#x22;/reference/python/task/evaluator&#x22;" title="&#x22;evaluator&#x22;" />

      <Card href="&#x22;/reference/python/task/importer&#x22;" title="&#x22;importer&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# APIError



API error.

## Attributes [#attributes]

<PyAttribute name="&#x22;status_code&#x22;" type="null" value="&#x22;status_code&#x22;" />

<PyAttribute name="&#x22;detail&#x22;" type="null" value="&#x22;detail&#x22;" />

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, status_code, detail) -> None&#x22;">
  Initialize the error.

  <PySourceCode>
    ```python
    def __init__(self, status_code: int, detail: str) -> None:
        """Initialize the error.

        Args:
            status_code: HTTP status code.
            detail: Error detail.
        """
        super().__init__(f"{status_code}: {detail}")
        self.status_code = status_code
        self.detail = detail
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;status_code&#x22;" type="&#x22;int&#x22;" value="undefined">
      HTTP status code.
    </PyParameter>

    <PyParameter name="&#x22;detail&#x22;" type="&#x22;str&#x22;" value="undefined">
      Error detail.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# ApiToken



Cached bearer token.

## Attributes [#attributes]

<PyAttribute name="&#x22;access_token&#x22;" type="&#x22;str&#x22;" value="null" />

<PyAttribute name="&#x22;expires_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;leeway_seconds&#x22;" type="&#x22;int&#x22;" value="&#x22;0&#x22;" />

<PyAttribute name="&#x22;expired&#x22;" type="&#x22;bool&#x22;" value="null">
  Report whether the token is expired or about to be.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;from_response&#x22;" type="&#x22;(cls, response) -> Self&#x22;">
  Build a cached token from a login response.

  <PySourceCode>
    ```python
    @classmethod
    def from_response(cls, response: TokenResponse) -> Self:
        """Build a cached token from a login response.

        Args:
            response: Token response returned by the server.

        Returns:
            Token with its absolute expiry and leeway resolved.
        """
        return cls.issued(response.access_token, response.expires_in)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;cls&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;response&#x22;" type="&#x22;TokenResponse&#x22;" value="undefined">
      Token response returned by the server.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;typing.Self&#x22;">
    Token with its absolute expiry and leeway resolved.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;issued&#x22;" type="&#x22;(cls, access_token, expires_in) -> Self&#x22;">
  Build a cached token from a bearer token and its lifetime.

  <PySourceCode>
    ```python
    @classmethod
    def issued(cls, access_token: str, expires_in: int) -> Self:
        """Build a cached token from a bearer token and its lifetime.

        Args:
            access_token: Bearer token.
            expires_in: Token lifetime in seconds.

        Returns:
            Token with its absolute expiry and leeway resolved.
        """
        return cls(
            access_token=access_token,
            expires_at=datetime.now(UTC) + timedelta(seconds=expires_in),
            leeway_seconds=_leeway_seconds(expires_in),
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;cls&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;access_token&#x22;" type="&#x22;str&#x22;" value="undefined">
      Bearer token.
    </PyParameter>

    <PyParameter name="&#x22;expires_in&#x22;" type="&#x22;int&#x22;" value="undefined">
      Token lifetime in seconds.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;typing.Self&#x22;">
    Token with its absolute expiry and leeway resolved.
  </PyFunctionReturn>
</PyFunction>


# ApiType



API type.

## Attributes [#attributes]

<PyAttribute name="&#x22;SERVER&#x22;" type="null" value="&#x22;'server'&#x22;" />

<PyAttribute name="&#x22;CONTROL_PLANE&#x22;" type="null" value="&#x22;'control_plane'&#x22;" />


# AuthenticationError



Authentication error.


# AuthorizationError



Authorization error.


# ClientConfig



Client configuration.

## Attributes [#attributes]

<PyAttribute name="&#x22;server_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;client_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;analytics_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;cli&#x22;" type="&#x22;CLISettings&#x22;" value="&#x22;Field(default_factory=CLISettings)&#x22;" />


# ControlPlaneLoginError



Raised when a control plane login cannot be started.


# ControlPlaneSession



Control plane tokens for one control plane, refreshed as they expire.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, api_url, store, timeout=30.0, retries=3, pool_size=20) -> None&#x22;">
  Initialize the session.

  <PySourceCode>
    ```python
    def __init__(
        self,
        api_url: str,
        store: CredentialStore,
        timeout: float = 30.0,
        retries: int = 3,
        pool_size: int = 20,
    ) -> None:
        """Initialize the session.

        Args:
            api_url: Control plane API base URL.
            store: Credential store holding the token and the API key that
                renews it.
            timeout: Request timeout in seconds.
            retries: Retry count for failed requests.
            pool_size: Connection pool size.
        """
        self._url = normalize_server_url(api_url)
        self._store = store
        self._http = build_async_client(
            self._url,
            {"Accept": "application/json"},
            timeout=timeout,
            retries=retries,
            pool_size=pool_size,
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;api_url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Control plane API base URL.
    </PyParameter>

    <PyParameter name="&#x22;store&#x22;" type="&#x22;CredentialStore&#x22;" value="undefined">
      Credential store holding the token and the API key that
      renews it.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float&#x22;" value="&#x22;30.0&#x22;">
      Request timeout in seconds.
    </PyParameter>

    <PyParameter name="&#x22;retries&#x22;" type="&#x22;int&#x22;" value="&#x22;3&#x22;">
      Retry count for failed requests.
    </PyParameter>

    <PyParameter name="&#x22;pool_size&#x22;" type="&#x22;int&#x22;" value="&#x22;20&#x22;">
      Connection pool size.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get_token&#x22;" type="&#x22;(self) -> str | None&#x22;">
  Return a usable control plane token, renewing an expiring one first.

  <PySourceCode>
    ```python
    async def get_token(self) -> str | None:
        """Return a usable control plane token, renewing an expiring one first.

        Returns:
            Bearer token, or None when nothing stored can produce one.
        """
        token = self._store.get_token(self._url)
        if token is not None:
            return token.access_token
        credentials = self._store.get_control_plane(self._url)
        if credentials is None or credentials.api_key is None:
            return None
        return (await self.login_with_api_key(credentials.api_key)).access_token
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;str | None&#x22;">
    Bearer token, or None when nothing stored can produce one.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;login_with_api_key&#x22;" type="&#x22;(self, api_key) -> ApiToken&#x22;">
  Exchange a control plane API key for a control plane token.

  <PySourceCode>
    ```python
    async def login_with_api_key(self, api_key: str) -> ApiToken:
        """Exchange a control plane API key for a control plane token.

        Args:
            api_key: Control plane API key.

        Raises:
            APIError: The request failed, including 401 for an invalid key.

        Returns:
            Token issued by the control plane.
        """
        response = await self._post(
            LOGIN_PATH,
            data={"grant_type": API_KEY_GRANT_TYPE, "password": api_key},
            headers={"Authorization": f"Bearer {api_key}"},
        )
        credentials = self._store.get_control_plane(self._url)
        # Stored only once the control plane has accepted it, so a rejected key
        # never displaces a working one.
        if credentials is None or credentials.api_key != api_key:
            self._store.set_api_key(self._url, api_key, type=ApiType.CONTROL_PLANE)
        return self._store_token(response)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;api_key&#x22;" type="&#x22;str&#x22;" value="undefined">
      Control plane API key.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.ApiToken&#x22;">
    Token issued by the control plane.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;device_login&#x22;" type="&#x22;(self, open_browser=True, prompt=None, workspace_id=None) -> ApiToken&#x22;">
  Authorize this machine and return its cached control plane token.

  <PySourceCode>
    ```python
    async def device_login(
        self,
        open_browser: bool = True,
        prompt: Callable[[ControlPlaneDeviceAuthorization], None] | None = None,
        workspace_id: str | None = None,
    ) -> ApiToken:
        """Authorize this machine and return its cached control plane token."""
        result = await self.device_login_with_metadata(
            open_browser=open_browser,
            prompt=prompt,
            workspace_id=workspace_id,
        )
        return ApiToken.issued(result.access_token, result.expires_in)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;open_browser&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;" />

    <PyParameter name="&#x22;prompt&#x22;" type="&#x22;Callable[[ControlPlaneDeviceAuthorization], None] | None&#x22;" value="&#x22;None&#x22;" />

    <PyParameter name="&#x22;workspace_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.ApiToken&#x22;" />
</PyFunction>

<PyFunction name="&#x22;device_login_with_metadata&#x22;" type="&#x22;(self, open_browser=True, prompt=None, workspace_id=None) -> ControlPlaneToken&#x22;">
  Authorize this machine against the control plane.

  The call blocks until a signed-in account completes authorization in a
  browser, or until the authorization expires.

  <PySourceCode>
    ```python
    async def device_login_with_metadata(
        self,
        open_browser: bool = True,
        prompt: Callable[[ControlPlaneDeviceAuthorization], None] | None = None,
        workspace_id: str | None = None,
    ) -> ControlPlaneToken:
        """Authorize this machine against the control plane.

        The call blocks until a signed-in account completes authorization in a
        browser, or until the authorization expires.

        Args:
            open_browser: Whether to open the verification page.
            prompt: Called with the authorization so the caller can show the
                verification URL. Defaults to logging it.
            workspace_id: Workspace ID preselected on the verification page.

        Raises:
            DeviceLoginError: The authorization expired or was refused.

        Returns:
            Control plane token and workspace selection issued for the device.
        """
        client_id = get_client_id()
        device = describe_this_device()
        response = await self._post(
            DEVICE_AUTHORIZATION_PATH,
            data={"client_id": str(client_id)},
            headers={"User-Agent": f"Host/{device.hostname} OS/{device.os}"},
        )
        authorization = ControlPlaneDeviceAuthorization.model_validate(response.json())
        uri = authorization.verification_uri_complete or authorization.verification_uri
        verification_uri = self._url + uri if uri.startswith("/") else uri
        parsed = urlparse(verification_uri)
        query_params = dict(parse_qsl(parsed.query))
        query_params["product"] = PRODUCT
        if workspace_id is not None:
            query_params["workspace"] = workspace_id
        verification_uri = urlunparse(parsed._replace(query=urlencode(query_params)))
        # Written back so the prompt shows the same URL the browser opens.
        authorization.verification_uri_complete = verification_uri
        if prompt is not None:
            prompt(authorization)
        else:
            logger.info(
                "Open %s to continue.",
                verification_uri,
            )
        if open_browser:
            webbrowser.open(verification_uri)

        async def exchange() -> httpx.Response:
            return await self._post(
                LOGIN_PATH,
                data={
                    "grant_type": DEVICE_CODE_GRANT_TYPE,
                    "client_id": str(client_id),
                    "device_code": authorization.device_code,
                },
            )

        confirmed = await poll_for_token(
            exchange, authorization.expires_in, authorization.interval
        )
        issued = ControlPlaneToken.model_validate(confirmed.json())
        self._store_issued_token(issued)
        return issued
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;open_browser&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to open the verification page.
    </PyParameter>

    <PyParameter name="&#x22;prompt&#x22;" type="&#x22;Callable[[ControlPlaneDeviceAuthorization], None] | None&#x22;" value="&#x22;None&#x22;">
      Called with the authorization so the caller can show the
      verification URL. Defaults to logging it.
    </PyParameter>

    <PyParameter name="&#x22;workspace_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Workspace ID preselected on the verification page.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.control_plane.ControlPlaneToken&#x22;">
    Control plane token and workspace selection issued for the device.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_workspace&#x22;" type="&#x22;(self, workspace_id, access_token) -> ControlPlaneWorkspace&#x22;">
  Get the managed workspace selected during device authorization.

  <PySourceCode>
    ```python
    async def get_workspace(
        self, workspace_id: uuid.UUID, access_token: str
    ) -> ControlPlaneWorkspace:
        """Get the managed workspace selected during device authorization.

        Args:
            workspace_id: Selected workspace ID.
            access_token: Control plane bearer token.

        Returns:
            Managed workspace connection details.
        """
        response = await self._http.get(
            WORKSPACE_PATH.format(workspace_id=workspace_id),
            headers={"Authorization": f"Bearer {access_token}"},
        )
        raise_for_response(response)
        return ControlPlaneWorkspace.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;workspace_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Selected workspace ID.
    </PyParameter>

    <PyParameter name="&#x22;access_token&#x22;" type="&#x22;str&#x22;" value="undefined">
      Control plane bearer token.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.control_plane.ControlPlaneWorkspace&#x22;">
    Managed workspace connection details.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the underlying HTTP client.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close the underlying HTTP client."""
        await self._http.aclose()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# CredentialStore



Server credentials persisted as JSON in the user's config directory.

## Attributes [#attributes]

<PyAttribute name="&#x22;path&#x22;" type="&#x22;Path&#x22;" value="null">
  Return the location of the credentials file.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, path=None, persist=None) -> None&#x22;">
  Initialize the store and load any credentials already on disk.

  <PySourceCode>
    ```python
    def __init__(self, path: Path | None = None, persist: bool | None = None) -> None:
        """Initialize the store and load any credentials already on disk.

        Args:
            path: Location of the credentials file.
            persist: Whether to read and write the file. Defaults to reading
                ``KITARU_DISABLE_CREDENTIALS_CACHE``.
        """
        self._path = path or get_config_directory() / CREDENTIALS_FILE_NAME
        if persist is None:
            persist = os.environ.get(ENV_DISABLE_CREDENTIALS_CACHE, "").lower() not in (
                "1",
                "true",
                "yes",
            )
        self._persist = persist
        self._credentials: dict[str, ServerCredentials] = {}
        self._loaded_at: float | None = None
        self._load()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;path&#x22;" type="&#x22;Path | None&#x22;" value="&#x22;None&#x22;">
      Location of the credentials file.
    </PyParameter>

    <PyParameter name="&#x22;persist&#x22;" type="&#x22;bool | None&#x22;" value="&#x22;None&#x22;">
      Whether to read and write the file. Defaults to reading
      `KITARU_DISABLE_CREDENTIALS_CACHE`.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, url) -> ServerCredentials | None&#x22;">
  Return the credentials stored for a server.

  <PySourceCode>
    ```python
    def get(self, url: str) -> ServerCredentials | None:
        """Return the credentials stored for a server.

        Args:
            url: Server base URL.

        Returns:
            Stored credentials, or None when the server is unknown.
        """
        self._reload_if_stale()
        return self._credentials.get(normalize_server_url(url))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;ServerCredentials | None&#x22;">
    Stored credentials, or None when the server is unknown.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self) -> list[ServerCredentials]&#x22;">
  Return the credentials of every known server.

  <PySourceCode>
    ```python
    def list(self) -> list[ServerCredentials]:
        """Return the credentials of every known server.

        Returns:
            Stored credentials, ordered by server URL.
        """
        self._reload_if_stale()
        return [self._credentials[key] for key in sorted(self._credentials)]
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;list&#x22;">
    Stored credentials, ordered by server URL.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_token&#x22;" type="&#x22;(self, url, allow_expired=False) -> ApiToken | None&#x22;">
  Return the cached token of a server.

  <PySourceCode>
    ```python
    def get_token(self, url: str, allow_expired: bool = False) -> ApiToken | None:
        """Return the cached token of a server.

        Args:
            url: Server base URL.
            allow_expired: Whether to return a token inside its leeway window.

        Returns:
            Cached token, or None when there is none to return.
        """
        credentials = self.get(url)
        if credentials is None or credentials.api_token is None:
            return None
        if credentials.api_token.expired and not allow_expired:
            return None
        return credentials.api_token
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>

    <PyParameter name="&#x22;allow_expired&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;">
      Whether to return a token inside its leeway window.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;ApiToken | None&#x22;">
    Cached token, or None when there is none to return.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;set_token&#x22;" type="&#x22;(self, url, token, type=None, control_plane_api_url=None) -> None&#x22;">
  Cache a token for a server.

  The control plane is recorded with the token it issued rather than on
  its own, because an entry that holds neither a token nor a credential
  is dropped when the store is written.

  <PySourceCode>
    ```python
    def set_token(
        self,
        url: str,
        token: ApiToken,
        type: ApiType | None = None,
        control_plane_api_url: str | None = None,
    ) -> None:
        """Cache a token for a server.

        The control plane is recorded with the token it issued rather than on
        its own, because an entry that holds neither a token nor a credential
        is dropped when the store is written.

        Args:
            url: Server base URL.
            token: Token to cache.
            type: API type, left as stored when omitted.
            control_plane_api_url: Control plane that issued the credential
                behind this token, left as stored when omitted.
        """
        values: dict[str, object] = {"api_token": token}
        if type is not None:
            values["type"] = type
        if control_plane_api_url is not None:
            values["control_plane_api_url"] = normalize_server_url(
                control_plane_api_url
            )
        self._mutate(url, values)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>

    <PyParameter name="&#x22;token&#x22;" type="&#x22;ApiToken&#x22;" value="undefined">
      Token to cache.
    </PyParameter>

    <PyParameter name="&#x22;type&#x22;" type="&#x22;ApiType | None&#x22;" value="&#x22;None&#x22;">
      API type, left as stored when omitted.
    </PyParameter>

    <PyParameter name="&#x22;control_plane_api_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Control plane that issued the credential
      behind this token, left as stored when omitted.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;set_api_key&#x22;" type="&#x22;(self, url, api_key, type=ApiType.SERVER) -> None&#x22;">
  Store an API key for a server and drop the token it replaces.

  <PySourceCode>
    ```python
    def set_api_key(
        self,
        url: str,
        api_key: str,
        type: ApiType = ApiType.SERVER,
    ) -> None:
        """Store an API key for a server and drop the token it replaces.

        Args:
            url: Server base URL.
            api_key: API key to store.
            type: API type.
        """
        self._mutate(url, {"api_key": api_key, "type": type, "api_token": None})
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>

    <PyParameter name="&#x22;api_key&#x22;" type="&#x22;str&#x22;" value="undefined">
      API key to store.
    </PyParameter>

    <PyParameter name="&#x22;type&#x22;" type="&#x22;ApiType&#x22;" value="&#x22;ApiType.SERVER&#x22;">
      API type.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;set_device&#x22;" type="&#x22;(self, url, device_id, device_code) -> None&#x22;">
  Store a device authorization for a server.

  <PySourceCode>
    ```python
    def set_device(self, url: str, device_id: uuid.UUID, device_code: str) -> None:
        """Store a device authorization for a server.

        Args:
            url: Server base URL.
            device_id: Id of the authorized device.
            device_code: Device code the client polls with.
        """
        self._mutate(url, {"device_id": device_id, "device_code": device_code})
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>

    <PyParameter name="&#x22;device_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the authorized device.
    </PyParameter>

    <PyParameter name="&#x22;device_code&#x22;" type="&#x22;str&#x22;" value="undefined">
      Device code the client polls with.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get_control_plane&#x22;" type="&#x22;(self, control_plane_api_url) -> ServerCredentials | None&#x22;">
  Return the credentials stored for a control plane.

  <PySourceCode>
    ```python
    def get_control_plane(self, control_plane_api_url: str) -> ServerCredentials | None:
        """Return the credentials stored for a control plane.

        Args:
            control_plane_api_url: Control plane API base URL.

        Returns:
            Stored credentials, or None when the entry is missing or is not a
            control plane entry.
        """
        credentials = self.get(control_plane_api_url)
        if credentials is None or credentials.type is not ApiType.CONTROL_PLANE:
            return None
        return credentials
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;control_plane_api_url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Control plane API base URL.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;ServerCredentials | None&#x22;">
    Stored credentials, or None when the entry is missing or is not a
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;clear_token&#x22;" type="&#x22;(self, url) -> None&#x22;">
  Drop the cached token of a server, keeping the way to get a new one.

  <PySourceCode>
    ```python
    def clear_token(self, url: str) -> None:
        """Drop the cached token of a server, keeping the way to get a new one.

        Args:
            url: Server base URL.
        """
        if self.get(url) is None:
            return
        self._mutate(url, {"api_token": None})
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;clear&#x22;" type="&#x22;(self, url) -> None&#x22;">
  Drop every credential stored for a server.

  <PySourceCode>
    ```python
    def clear(self, url: str) -> None:
        """Drop every credential stored for a server.

        Args:
            url: Server base URL.
        """
        self._reload_if_stale()
        if self._credentials.pop(normalize_server_url(url), None) is not None:
            self._save()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;clear_all&#x22;" type="&#x22;(self) -> None&#x22;">
  Drop every stored credential and remove the credentials file.

  <PySourceCode>
    ```python
    def clear_all(self) -> None:
        """Drop every stored credential and remove the credentials file."""
        self._credentials = {}
        if not self._persist:
            return
        self._path.unlink(missing_ok=True)
        self._loaded_at = None
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# CredentialStoreTokenSource



Token source backed by the credentials stored for one server.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, base_url, store, exchange) -> None&#x22;">
  Initialize the source.

  <PySourceCode>
    ```python
    def __init__(
        self,
        base_url: str,
        store: CredentialStore,
        exchange: TokenExchange,
    ) -> None:
        """Initialize the source.

        Args:
            base_url: Server base URL credentials are stored under.
            store: Credential store holding the token and the way to renew it.
            exchange: Login endpoint calls used to renew the token.
        """
        self._url = normalize_server_url(base_url)
        self._store = store
        self._exchange = exchange
        self._control_plane: ControlPlaneSession | None = None
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;base_url&#x22;" type="&#x22;str&#x22;" value="undefined">
      Server base URL credentials are stored under.
    </PyParameter>

    <PyParameter name="&#x22;store&#x22;" type="&#x22;CredentialStore&#x22;" value="undefined">
      Credential store holding the token and the way to renew it.
    </PyParameter>

    <PyParameter name="&#x22;exchange&#x22;" type="&#x22;TokenExchange&#x22;" value="undefined">
      Login endpoint calls used to renew the token.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get_cached_token&#x22;" type="&#x22;(self) -> str | None&#x22;">
  Return the stored bearer token.

  <PySourceCode>
    ```python
    def get_cached_token(self) -> str | None:
        """Return the stored bearer token.

        Returns:
            Bearer token, or None when nothing usable is stored.
        """
        credentials = self._store.get(self._url)
        if credentials is not None and credentials.server_api_key is not None:
            # A server API key is used directly as a bearer credential and we
            # don't need to exchange it for a server token.
            return credentials.server_api_key
        token = self._store.get_token(self._url)
        if token is not None:
            return token.access_token
        return None
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;str | None&#x22;">
    Bearer token, or None when nothing usable is stored.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;fetch_token&#x22;" type="&#x22;(self) -> str | None&#x22;">
  Fetch a fresh bearer token and write it back to the store.

  <PySourceCode>
    ```python
    async def fetch_token(self) -> str | None:
        """Fetch a fresh bearer token and write it back to the store.

        Returns:
            Bearer token, or None when nothing stored can produce one.
        """
        credentials = self._store.get(self._url)
        if credentials is None:
            return None
        token = await self._fetch(credentials)
        if token is None:
            return None
        self._store.set_token(self._url, token)
        return token.access_token
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;str | None&#x22;">
    Bearer token, or None when nothing stored can produce one.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the control plane session the source opened.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close the control plane session the source opened."""
        if self._control_plane is not None:
            await self._control_plane.close()
            self._control_plane = None
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# DeviceLoginError



Raised when a device authorization cannot be completed.


# KitaruAPIClient



Kitaru API client.

## Attributes [#attributes]

<PyAttribute name="&#x22;base_url&#x22;" type="&#x22;str&#x22;" value="null">
  Return the server base URL this client resolved.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, base_url=None, api_key=None, credential_store=None, timeout=30.0, retries=3, pool_size=20, analytics_source=AnalyticsSource.PYTHON) -> None&#x22;">
  Initialize the client.

  <PySourceCode>
    ```python
    def __init__(
        self,
        base_url: str | None = None,
        api_key: str | None = None,
        credential_store: CredentialStore | None = None,
        timeout: float = 30.0,
        retries: int = 3,
        pool_size: int = 20,
        analytics_source: AnalyticsSource = AnalyticsSource.PYTHON,
    ) -> None:
        """Initialize the client.

        Args:
            base_url: Server base URL, read from KITARU_API_URL and then the
                stored server URL when omitted.
            api_key: API key authenticating this client. A server key is sent
                as a bearer token, a control plane key is exchanged for a
                session token held in memory. Read from KITARU_API_TOKEN and
                then KITARU_API_KEY when omitted.
            credential_store: Store holding the credentials this client
                authenticates with, renewing its token as it expires. Defaults
                to the on-disk store when no API key is given.
            timeout: Request timeout in seconds.
            retries: Retry count for failed requests.
            pool_size: Connection pool size.
            analytics_source: Client sending the requests.

        Raises:
            RuntimeError: No server URL is configured.
            ValueError: Both an API key and a credential store were supplied.
        """
        if api_key is not None and credential_store is not None:
            raise ValueError("api_key and credential_store are mutually exclusive")
        if base_url is None:
            base_url = os.environ.get("KITARU_API_URL") or get_server_url()
            if not base_url:
                raise RuntimeError("No server URL is configured")

        self._base_url = base_url
        self._owns_transport = True
        self._owns_auth = True
        self._request_headers: dict[str, str] = {}
        identification = format_client_header(analytics_source)
        client_identification = format_client_header(
            analytics_source, get_analytics_id()
        )
        headers = {"User-Agent": identification, CLIENT_HEADER: client_identification}
        if skill := os.environ.get("KITARU_ACTIVE_SKILL"):
            headers[SKILL_HEADER] = skill
        self._http = build_async_client(
            base_url, headers, timeout=timeout, retries=retries, pool_size=pool_size
        )
        self._auth: TokenAuth | None = None

        if api_key is None and credential_store is None:
            if api_token := os.environ.get("KITARU_API_TOKEN"):
                self._auth = StaticTokenAuth(api_token)
            elif api_key := os.environ.get("KITARU_API_KEY"):
                # Used later
                pass
            else:
                # Nothing configured, fall back to the on-disk credential store.
                credential_store = CredentialStore()

        if api_key:
            if api_key.startswith(CONTROL_PLANE_API_KEY_PREFIX):
                # Control plane API keys are exchanged for a session token, so
                # we need an in-memory credential store to hold it.
                credential_store = CredentialStore(persist=False)
                credential_store.set_api_key(base_url, api_key)
            else:
                self._auth = StaticTokenAuth(api_key)

        self._bind_resources()
        if credential_store is not None:
            self._auth = RenewingTokenAuth(
                CredentialStoreTokenSource(base_url, credential_store, self.auth)
            )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;base_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Server base URL, read from KITARU\_API\_URL and then the
      stored server URL when omitted.
    </PyParameter>

    <PyParameter name="&#x22;api_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      API key authenticating this client. A server key is sent
      as a bearer token, a control plane key is exchanged for a
      session token held in memory. Read from KITARU\_API\_TOKEN and
      then KITARU\_API\_KEY when omitted.
    </PyParameter>

    <PyParameter name="&#x22;credential_store&#x22;" type="&#x22;CredentialStore | None&#x22;" value="&#x22;None&#x22;">
      Store holding the credentials this client
      authenticates with, renewing its token as it expires. Defaults
      to the on-disk store when no API key is given.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float&#x22;" value="&#x22;30.0&#x22;">
      Request timeout in seconds.
    </PyParameter>

    <PyParameter name="&#x22;retries&#x22;" type="&#x22;int&#x22;" value="&#x22;3&#x22;">
      Retry count for failed requests.
    </PyParameter>

    <PyParameter name="&#x22;pool_size&#x22;" type="&#x22;int&#x22;" value="&#x22;20&#x22;">
      Connection pool size.
    </PyParameter>

    <PyParameter name="&#x22;analytics_source&#x22;" type="&#x22;AnalyticsSource&#x22;" value="&#x22;AnalyticsSource.PYTHON&#x22;">
      Client sending the requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;with_token&#x22;" type="&#x22;(self, token) -> KitaruAPIClient&#x22;">
  Return a view of this client authenticating with a fixed bearer token.

  <PySourceCode>
    ```python
    def with_token(self, token: str) -> "KitaruAPIClient":
        """Return a view of this client authenticating with a fixed bearer token.

        Args:
            token: Bearer token attached to every request sent through the
                view.

        Returns:
            Client view authenticating with the given token.
        """
        return self.with_auth(StaticTokenAuth(token))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;token&#x22;" type="&#x22;str&#x22;" value="undefined">
      Bearer token attached to every request sent through the
      view.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.KitaruAPIClient&#x22;">
    Client view authenticating with the given token.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;with_auth&#x22;" type="&#x22;(self, auth) -> KitaruAPIClient&#x22;">
  Return a view of this client authenticating with the given auth flow.

  The view shares this client's HTTP transport instead of opening a new
  connection pool. Closing the view closes only its auth flow, and
  closing this client also invalidates the view.

  <PySourceCode>
    ```python
    def with_auth(self, auth: TokenAuth) -> "KitaruAPIClient":
        """Return a view of this client authenticating with the given auth flow.

        The view shares this client's HTTP transport instead of opening a new
        connection pool. Closing the view closes only its auth flow, and
        closing this client also invalidates the view.

        Args:
            auth: Auth flow attached to every request sent through the view.

        Returns:
            Client view authenticating with the given auth flow.
        """
        view = copy.copy(self)
        view._auth = auth
        view._owns_transport = False
        view._owns_auth = True
        view._bind_resources()
        return view
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;auth&#x22;" type="&#x22;TokenAuth&#x22;" value="undefined">
      Auth flow attached to every request sent through the view.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.KitaruAPIClient&#x22;">
    Client view authenticating with the given auth flow.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;with_options&#x22;" type="&#x22;(self, consistency=None) -> KitaruAPIClient&#x22;">
  Return a view of this client with request options applied.

  The view shares this client's HTTP transport and auth flow, and
  closing it leaves both open.

  <PySourceCode>
    ```python
    def with_options(
        self, consistency: Literal["strong"] | None = None
    ) -> "KitaruAPIClient":
        """Return a view of this client with request options applied.

        The view shares this client's HTTP transport and auth flow, and
        closing it leaves both open.

        Args:
            consistency: ``strong`` sends ``Prefer: consistency=strong`` on
                every request, so endpoints that serve reads from a replica
                serve the view from the primary database.

        Returns:
            Client view with the options applied.
        """
        view = copy.copy(self)
        if consistency == "strong":
            view._request_headers = {
                **self._request_headers,
                "Prefer": "consistency=strong",
            }
        view._owns_transport = False
        view._owns_auth = False
        view._bind_resources()
        return view
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;consistency&#x22;" type="&#x22;Literal['strong'] | None&#x22;" value="&#x22;None&#x22;">
      `strong` sends `Prefer: consistency=strong` on
      every request, so endpoints that serve reads from a replica
      serve the view from the primary database.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.client.KitaruAPIClient&#x22;">
    Client view with the options applied.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;request&#x22;" type="&#x22;(self, method, path, params=None, json=None, data=None, files=None, content=None, headers=None, idempotency_key=None, authenticate=True) -> httpx.Response&#x22;">
  Send a request and raise a typed error on failure.

  <PySourceCode>
    ```python
    async def request(
        self,
        method: str,
        path: str,
        params: dict[str, Any] | None = None,
        json: Any = None,
        data: dict[str, str] | None = None,
        files: dict[str, tuple[str | None, bytes, str]] | None = None,
        content: bytes | AsyncIterable[bytes] | None = None,
        headers: dict[str, str] | None = None,
        idempotency_key: str | None = None,
        authenticate: bool = True,
    ) -> httpx.Response:
        """Send a request and raise a typed error on failure.

        Args:
            method: HTTP method.
            path: Request path relative to the base URL.
            params: Query parameters.
            json: JSON request body.
            data: Form request body.
            files: Multipart file fields, filename/content/content-type per
                field.
            content: Raw or streaming request body.
            headers: Additional request headers.
            idempotency_key: Idempotency key overriding the transport's
                random default.
            authenticate: Whether to send the request through this client's
                auth flow. The login endpoints send their own credential.

        Raises:
            APIError: The response has an error status code.
            InvalidServerResponseError: The response is not an API response.

        Returns:
            HTTP response.
        """
        if params is not None:
            # httpx renders None query values as empty strings, which the
            # server rejects for typed filters.
            params = {key: value for key, value in params.items() if value is not None}
        if idempotency_key is not None:
            headers = {**(headers or {}), IDEMPOTENCY_KEY_HEADER: idempotency_key}
        if self._request_headers:
            headers = {**self._request_headers, **(headers or {})}
        response = await self._http.request(
            method,
            path,
            params=params,
            json=json,
            data=data,
            files=files,
            content=content,
            headers=headers,
            auth=self._auth if authenticate else None,
        )
        raise_for_response(response)
        # A UI catch-all or proxy answers an unknown path with an HTML page
        # and a success status, usually on a client/server version mismatch.
        if response.headers.get("Content-Type", "").startswith("text/html"):
            raise InvalidServerResponseError(
                f"The server answered {method} {path} with an HTML page "
                "instead of an API response"
            )
        return response
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;method&#x22;" type="&#x22;str&#x22;" value="undefined">
      HTTP method.
    </PyParameter>

    <PyParameter name="&#x22;path&#x22;" type="&#x22;str&#x22;" value="undefined">
      Request path relative to the base URL.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;dict[str, Any] | None&#x22;" value="&#x22;None&#x22;">
      Query parameters.
    </PyParameter>

    <PyParameter name="&#x22;json&#x22;" type="&#x22;Any&#x22;" value="&#x22;None&#x22;">
      JSON request body.
    </PyParameter>

    <PyParameter name="&#x22;data&#x22;" type="&#x22;dict[str, str] | None&#x22;" value="&#x22;None&#x22;">
      Form request body.
    </PyParameter>

    <PyParameter name="&#x22;files&#x22;" type="&#x22;dict[str, tuple[str | None, bytes, str]] | None&#x22;" value="&#x22;None&#x22;">
      Multipart file fields, filename/content/content-type per
      field.
    </PyParameter>

    <PyParameter name="&#x22;content&#x22;" type="&#x22;bytes | AsyncIterable[bytes] | None&#x22;" value="&#x22;None&#x22;">
      Raw or streaming request body.
    </PyParameter>

    <PyParameter name="&#x22;headers&#x22;" type="&#x22;dict[str, str] | None&#x22;" value="&#x22;None&#x22;">
      Additional request headers.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>

    <PyParameter name="&#x22;authenticate&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to send the request through this client's
      auth flow. The login endpoints send their own credential.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;httpx.Response&#x22;">
    HTTP response.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the auth flow and HTTP transport this client owns.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close the auth flow and HTTP transport this client owns."""
        if self._auth is not None and self._owns_auth:
            await self._auth.close()
        if self._owns_transport:
            await self._http.aclose()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# KitaruClient



Kitaru client.

## Attributes [#attributes]

<PyAttribute name="&#x22;api&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="null">
  API client with one method per endpoint.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, api_client=None) -> None&#x22;">
  Initialize the client.

  <PySourceCode>
    ```python
    def __init__(self, api_client: KitaruAPIClient | None = None) -> None:
        """Initialize the client.

        Args:
            api_client: API client used to send requests.
        """
        self._api_client = api_client or KitaruAPIClient()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;api_client&#x22;" type="&#x22;KitaruAPIClient | None&#x22;" value="&#x22;None&#x22;">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the underlying API client.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close the underlying API client."""
        await self._api_client.close()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get_agent&#x22;" type="&#x22;(self, agent) -> AgentResponse&#x22;">
  Get an agent by id or name.

  <PySourceCode>
    ```python
    async def get_agent(self, agent: uuid.UUID | str) -> AgentResponse:
        """Get an agent by id or name.

        Args:
            agent: Id or name of the agent.

        Raises:
            APIError: The request failed, including 404 for a missing agent.

        Returns:
            Stored agent.
        """
        if isinstance(agent, uuid.UUID):
            return await self._api_client.agents.get(agent)
        return await self._get_by_name(
            "agent", agent, AgentListParams, self._api_client.agents.list
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the agent.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent.AgentResponse&#x22;">
    Stored agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_agents&#x22;" type="&#x22;(self) -> AsyncIterator[AgentResponse]&#x22;">
  Iterate over all agents.

  <PySourceCode>
    ```python
    def list_agents(self) -> AsyncIterator[AgentResponse]:
        """Iterate over all agents.

        Returns:
            Async iterator over every agent.
        """
        return self._api_client.agents.iter()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_session&#x22;" type="&#x22;(self, session_id) -> SessionDetailResponse&#x22;">
  Get a session by id.

  <PySourceCode>
    ```python
    async def get_session(self, session_id: uuid.UUID) -> SessionDetailResponse:
        """Get a session by id.

        Args:
            session_id: Id of the session.

        Raises:
            APIError: The request failed, including 404 for a missing session.

        Returns:
            Stored session.
        """
        return await self._api_client.sessions.get(session_id)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionDetailResponse&#x22;">
    Stored session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_sessions&#x22;" type="&#x22;(self, agent=None) -> AsyncIterator[SessionResponse]&#x22;">
  Iterate over sessions, optionally scoped to one agent.

  <PySourceCode>
    ```python
    async def list_sessions(
        self, agent: uuid.UUID | str | None = None
    ) -> AsyncIterator[SessionResponse]:
        """Iterate over sessions, optionally scoped to one agent.

        Args:
            agent: Id or name of the agent to scope to.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every matching session.
        """
        params = SessionListParams()
        if agent is not None:
            agent_id = (await self.get_agent(agent)).id
            params = SessionListParams(
                filter=FilterCondition(
                    field="agent_id", op=FilterOp.EQ, value=str(agent_id)
                )
            )
        async for session in self._api_client.sessions.iter(params):
            yield session
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent&#x22;" type="&#x22;uuid.UUID | str | None&#x22;" value="&#x22;None&#x22;">
      Id or name of the agent to scope to.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every matching session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_session_nodes&#x22;" type="&#x22;(self, session_id) -> AsyncIterator[SessionNodeResponse]&#x22;">
  Iterate over the nodes of a session in index order.

  <PySourceCode>
    ```python
    def list_session_nodes(
        self, session_id: uuid.UUID
    ) -> AsyncIterator[SessionNodeResponse]:
        """Iterate over the nodes of a session in index order.

        Args:
            session_id: Id of the session.

        Returns:
            Async iterator over every node.
        """
        return self._api_client.sessions.iter_nodes(session_id)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every node.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;replay&#x22;" type="&#x22;(self, session_id, evaluators, agent_version_id=None, override=None, tool_policy=None, baseline_evaluation_mode=BaselineEvaluationMode.IF_MISSING, wait=True, timeout=None) -> ReplayResponse&#x22;">
  Replay a session and optionally wait for it to finish.

  <PySourceCode>
    ```python
    async def replay(
        self,
        session_id: uuid.UUID,
        evaluators: list[EvaluatorConfig],
        agent_version_id: uuid.UUID | None = None,
        override: ReplayOverride | None = None,
        tool_policy: ToolPolicy | None = None,
        baseline_evaluation_mode: BaselineEvaluationMode = (
            BaselineEvaluationMode.IF_MISSING
        ),
        wait: bool = True,
        timeout: float | None = None,
    ) -> ReplayResponse:
        """Replay a session and optionally wait for it to finish.

        Args:
            session_id: Id of the session to replay.
            evaluators: Evaluators run against the result session.
            agent_version_id: Agent version to replay with, the session's
                recorded version when unset.
            override: Override to apply.
            tool_policy: Tool policy to apply.
            baseline_evaluation_mode: How to score the baseline session.
            wait: Whether to wait for the replay to reach a terminal status.
            timeout: Seconds to wait before giving up.

        Raises:
            APIError: The request failed, including 404 for a missing session
                or agent version.
            TimeoutError: The replay did not finish within the timeout.

        Returns:
            Replay, in a terminal status when waited for.
        """
        request = ReplayCreateRequest(
            baseline_session_id=session_id,
            agent_version_id=agent_version_id,
            override=override,
            tool_policy=tool_policy,
            evaluators=evaluators,
            baseline_evaluation_mode=baseline_evaluation_mode,
        )
        replay = await self._api_client.replays.create(request)
        if wait:
            replay = await self.wait_for_replay(replay.id, timeout=timeout)
        return replay
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session to replay.
    </PyParameter>

    <PyParameter name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="undefined">
      Evaluators run against the result session.
    </PyParameter>

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;None&#x22;">
      Agent version to replay with, the session's
      recorded version when unset.
    </PyParameter>

    <PyParameter name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;None&#x22;">
      Override to apply.
    </PyParameter>

    <PyParameter name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy | None&#x22;" value="&#x22;None&#x22;">
      Tool policy to apply.
    </PyParameter>

    <PyParameter name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;BaselineEvaluationMode.IF_MISSING&#x22;">
      How to score the baseline session.
    </PyParameter>

    <PyParameter name="&#x22;wait&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to wait for the replay to reach a terminal status.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Replay, in a terminal status when waited for.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_replay&#x22;" type="&#x22;(self, replay_id) -> ReplayResponse&#x22;">
  Get a replay by id.

  <PySourceCode>
    ```python
    async def get_replay(self, replay_id: uuid.UUID) -> ReplayResponse:
        """Get a replay by id.

        Args:
            replay_id: Id of the replay.

        Raises:
            APIError: The request failed, including 404 for a missing replay.

        Returns:
            Stored replay.
        """
        return await self._api_client.replays.get(replay_id)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Stored replay.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;wait_for_replay&#x22;" type="&#x22;(self, replay_id, timeout=None, poll_interval=2.0) -> ReplayResponse&#x22;">
  Wait for a replay to reach a terminal status.

  <PySourceCode>
    ```python
    async def wait_for_replay(
        self,
        replay_id: uuid.UUID,
        timeout: float | None = None,
        poll_interval: float = 2.0,
    ) -> ReplayResponse:
        """Wait for a replay to reach a terminal status.

        Args:
            replay_id: Id of the replay.
            timeout: Seconds to wait before giving up.
            poll_interval: Seconds between status checks.

        Raises:
            APIError: The request failed.
            TimeoutError: The replay did not finish within the timeout.

        Returns:
            Replay in a terminal status.
        """
        return await self._wait_for_status(
            lambda: self._api_client.replays.get(replay_id),
            lambda replay: replay.status in TERMINAL_REPLAY_STATUSES,
            timeout=timeout,
            poll_interval=poll_interval,
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>

    <PyParameter name="&#x22;poll_interval&#x22;" type="&#x22;float&#x22;" value="&#x22;2.0&#x22;">
      Seconds between status checks.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Replay in a terminal status.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_experiment&#x22;" type="&#x22;(self, experiment) -> ExperimentResponse&#x22;">
  Get an experiment by id or name.

  <PySourceCode>
    ```python
    async def get_experiment(self, experiment: uuid.UUID | str) -> ExperimentResponse:
        """Get an experiment by id or name.

        Args:
            experiment: Id or name of the experiment.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment.

        Returns:
            Stored experiment.
        """
        if isinstance(experiment, uuid.UUID):
            return await self._api_client.experiments.get(experiment)
        return await self._get_by_name(
            "experiment",
            experiment,
            ExperimentListParams,
            self._api_client.experiments.list,
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the experiment.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment.ExperimentResponse&#x22;">
    Stored experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_experiments&#x22;" type="&#x22;(self) -> AsyncIterator[ExperimentResponse]&#x22;">
  Iterate over all experiments.

  <PySourceCode>
    ```python
    def list_experiments(self) -> AsyncIterator[ExperimentResponse]:
        """Iterate over all experiments.

        Returns:
            Async iterator over every experiment.
        """
        return self._api_client.experiments.iter()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;run_experiment&#x22;" type="&#x22;(self, experiment, cohort_version_id, agent_version_id, baseline_evaluation_mode=BaselineEvaluationMode.IF_MISSING, wait=True, timeout=None) -> ExperimentRunResponse&#x22;">
  Start an experiment run and optionally wait for it to finish.

  <PySourceCode>
    ```python
    async def run_experiment(
        self,
        experiment: uuid.UUID | str,
        cohort_version_id: uuid.UUID,
        agent_version_id: uuid.UUID,
        baseline_evaluation_mode: BaselineEvaluationMode = (
            BaselineEvaluationMode.IF_MISSING
        ),
        wait: bool = True,
        timeout: float | None = None,
    ) -> ExperimentRunResponse:
        """Start an experiment run and optionally wait for it to finish.

        Args:
            experiment: Id or name of the experiment.
            cohort_version_id: Cohort version whose sessions are replayed.
            agent_version_id: Agent version to replay with.
            baseline_evaluation_mode: How to score each baseline session.
            wait: Whether to wait for the run to reach a terminal status.
            timeout: Seconds to wait before giving up.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment, cohort version, or agent version.
            TimeoutError: The run did not finish within the timeout.

        Returns:
            Experiment run, in a terminal status when waited for.
        """
        experiment_id = (await self.get_experiment(experiment)).id
        request = ExperimentRunCreateRequest(
            cohort_version_id=cohort_version_id,
            agent_version_id=agent_version_id,
            baseline_evaluation_mode=baseline_evaluation_mode,
        )
        run = await self._api_client.experiments.start_run(experiment_id, request)
        if wait:
            run = await self.wait_for_experiment_run(run.id, timeout=timeout)
        return run
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the experiment.
    </PyParameter>

    <PyParameter name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Cohort version whose sessions are replayed.
    </PyParameter>

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Agent version to replay with.
    </PyParameter>

    <PyParameter name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;BaselineEvaluationMode.IF_MISSING&#x22;">
      How to score each baseline session.
    </PyParameter>

    <PyParameter name="&#x22;wait&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to wait for the run to reach a terminal status.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Experiment run, in a terminal status when waited for.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_experiment_run&#x22;" type="&#x22;(self, run_id) -> ExperimentRunResponse&#x22;">
  Get an experiment run by id.

  <PySourceCode>
    ```python
    async def get_experiment_run(self, run_id: uuid.UUID) -> ExperimentRunResponse:
        """Get an experiment run by id.

        Args:
            run_id: Id of the experiment run.

        Raises:
            APIError: The request failed, including 404 for a missing run.

        Returns:
            Stored experiment run.
        """
        return await self._api_client.experiment_runs.get(run_id)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment run.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Stored experiment run.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;wait_for_experiment_run&#x22;" type="&#x22;(self, run_id, timeout=None, poll_interval=2.0) -> ExperimentRunResponse&#x22;">
  Wait for an experiment run to reach a terminal status.

  <PySourceCode>
    ```python
    async def wait_for_experiment_run(
        self,
        run_id: uuid.UUID,
        timeout: float | None = None,
        poll_interval: float = 2.0,
    ) -> ExperimentRunResponse:
        """Wait for an experiment run to reach a terminal status.

        Args:
            run_id: Id of the experiment run.
            timeout: Seconds to wait before giving up.
            poll_interval: Seconds between status checks.

        Raises:
            APIError: The request failed.
            TimeoutError: The run did not finish within the timeout.

        Returns:
            Experiment run in a terminal status.
        """
        return await self._wait_for_status(
            lambda: self._api_client.experiment_runs.get(run_id),
            lambda run: run.status in TERMINAL_EXPERIMENT_RUN_STATUSES,
            timeout=timeout,
            poll_interval=poll_interval,
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment run.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>

    <PyParameter name="&#x22;poll_interval&#x22;" type="&#x22;float&#x22;" value="&#x22;2.0&#x22;">
      Seconds between status checks.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Experiment run in a terminal status.
  </PyFunctionReturn>
</PyFunction>


# KitaruClientError



Kitaru client error.


# KitaruSyncClient



Synchronous Kitaru client.

## Attributes [#attributes]

<PyAttribute name="&#x22;api&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="null">
  API client with one method per endpoint.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, api_client=None) -> None&#x22;">
  Initialize the client.

  <PySourceCode>
    ```python
    def __init__(self, api_client: KitaruAPIClient | None = None) -> None:
        """Initialize the client.

        Args:
            api_client: API client used to send requests.
        """
        self._loop = asyncio.new_event_loop()
        self._thread = threading.Thread(target=self._loop.run_forever, daemon=True)
        self._thread.start()
        self._client = KitaruClient(api_client=api_client)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;api_client&#x22;" type="&#x22;KitaruAPIClient | None&#x22;" value="&#x22;None&#x22;">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the underlying client and stop the event loop thread.

  <PySourceCode>
    ```python
    def close(self) -> None:
        """Close the underlying client and stop the event loop thread."""
        self._run(self._client.close())
        self._loop.call_soon_threadsafe(self._loop.stop)
        self._thread.join()
        self._loop.close()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get_agent&#x22;" type="&#x22;(self, agent) -> AgentResponse&#x22;">
  Get an agent by id or name.

  <PySourceCode>
    ```python
    def get_agent(self, agent: uuid.UUID | str) -> AgentResponse:
        """Get an agent by id or name.

        Args:
            agent: Id or name of the agent.

        Raises:
            APIError: The request failed, including 404 for a missing agent.

        Returns:
            Stored agent.
        """
        return self._run(self._client.get_agent(agent))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the agent.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent.AgentResponse&#x22;">
    Stored agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_agents&#x22;" type="&#x22;(self) -> Iterator[AgentResponse]&#x22;">
  Iterate over all agents.

  <PySourceCode>
    ```python
    def list_agents(self) -> Iterator[AgentResponse]:
        """Iterate over all agents.

        Returns:
            Iterator over every agent.
        """
        return self._iterate(self._client.list_agents())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator&#x22;">
    Iterator over every agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_session&#x22;" type="&#x22;(self, session_id) -> SessionDetailResponse&#x22;">
  Get a session by id.

  <PySourceCode>
    ```python
    def get_session(self, session_id: uuid.UUID) -> SessionDetailResponse:
        """Get a session by id.

        Args:
            session_id: Id of the session.

        Raises:
            APIError: The request failed, including 404 for a missing session.

        Returns:
            Stored session.
        """
        return self._run(self._client.get_session(session_id))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionDetailResponse&#x22;">
    Stored session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_sessions&#x22;" type="&#x22;(self, agent=None) -> Iterator[SessionResponse]&#x22;">
  Iterate over sessions, optionally scoped to one agent.

  <PySourceCode>
    ```python
    def list_sessions(
        self, agent: uuid.UUID | str | None = None
    ) -> Iterator[SessionResponse]:
        """Iterate over sessions, optionally scoped to one agent.

        Args:
            agent: Id or name of the agent to scope to.

        Raises:
            APIError: The request failed.

        Returns:
            Iterator over every matching session.
        """
        return self._iterate(self._client.list_sessions(agent))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent&#x22;" type="&#x22;uuid.UUID | str | None&#x22;" value="&#x22;None&#x22;">
      Id or name of the agent to scope to.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator&#x22;">
    Iterator over every matching session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_session_nodes&#x22;" type="&#x22;(self, session_id) -> Iterator[SessionNodeResponse]&#x22;">
  Iterate over the nodes of a session in index order.

  <PySourceCode>
    ```python
    def list_session_nodes(
        self, session_id: uuid.UUID
    ) -> Iterator[SessionNodeResponse]:
        """Iterate over the nodes of a session in index order.

        Args:
            session_id: Id of the session.

        Returns:
            Iterator over every node.
        """
        return self._iterate(self._client.list_session_nodes(session_id))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator&#x22;">
    Iterator over every node.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;replay&#x22;" type="&#x22;(self, session_id, evaluators, agent_version_id=None, override=None, tool_policy=None, baseline_evaluation_mode=BaselineEvaluationMode.IF_MISSING, wait=True, timeout=None) -> ReplayResponse&#x22;">
  Replay a session and optionally wait for it to finish.

  <PySourceCode>
    ```python
    def replay(
        self,
        session_id: uuid.UUID,
        evaluators: list[EvaluatorConfig],
        agent_version_id: uuid.UUID | None = None,
        override: ReplayOverride | None = None,
        tool_policy: ToolPolicy | None = None,
        baseline_evaluation_mode: BaselineEvaluationMode = (
            BaselineEvaluationMode.IF_MISSING
        ),
        wait: bool = True,
        timeout: float | None = None,
    ) -> ReplayResponse:
        """Replay a session and optionally wait for it to finish.

        Args:
            session_id: Id of the session to replay.
            evaluators: Evaluators run against the result session.
            agent_version_id: Agent version to replay with, the session's
                recorded version when unset.
            override: Override to apply.
            tool_policy: Tool policy to apply.
            baseline_evaluation_mode: How to score the baseline session.
            wait: Whether to wait for the replay to reach a terminal status.
            timeout: Seconds to wait before giving up.

        Raises:
            APIError: The request failed, including 404 for a missing session
                or agent version.
            TimeoutError: The replay did not finish within the timeout.

        Returns:
            Replay, in a terminal status when waited for.
        """
        return self._run(
            self._client.replay(
                session_id,
                evaluators,
                agent_version_id=agent_version_id,
                override=override,
                tool_policy=tool_policy,
                baseline_evaluation_mode=baseline_evaluation_mode,
                wait=wait,
                timeout=timeout,
            )
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session to replay.
    </PyParameter>

    <PyParameter name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="undefined">
      Evaluators run against the result session.
    </PyParameter>

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;None&#x22;">
      Agent version to replay with, the session's
      recorded version when unset.
    </PyParameter>

    <PyParameter name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;None&#x22;">
      Override to apply.
    </PyParameter>

    <PyParameter name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy | None&#x22;" value="&#x22;None&#x22;">
      Tool policy to apply.
    </PyParameter>

    <PyParameter name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;BaselineEvaluationMode.IF_MISSING&#x22;">
      How to score the baseline session.
    </PyParameter>

    <PyParameter name="&#x22;wait&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to wait for the replay to reach a terminal status.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Replay, in a terminal status when waited for.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_replay&#x22;" type="&#x22;(self, replay_id) -> ReplayResponse&#x22;">
  Get a replay by id.

  <PySourceCode>
    ```python
    def get_replay(self, replay_id: uuid.UUID) -> ReplayResponse:
        """Get a replay by id.

        Args:
            replay_id: Id of the replay.

        Raises:
            APIError: The request failed, including 404 for a missing replay.

        Returns:
            Stored replay.
        """
        return self._run(self._client.get_replay(replay_id))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Stored replay.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;wait_for_replay&#x22;" type="&#x22;(self, replay_id, timeout=None, poll_interval=2.0) -> ReplayResponse&#x22;">
  Wait for a replay to reach a terminal status.

  <PySourceCode>
    ```python
    def wait_for_replay(
        self,
        replay_id: uuid.UUID,
        timeout: float | None = None,
        poll_interval: float = 2.0,
    ) -> ReplayResponse:
        """Wait for a replay to reach a terminal status.

        Args:
            replay_id: Id of the replay.
            timeout: Seconds to wait before giving up.
            poll_interval: Seconds between status checks.

        Raises:
            APIError: The request failed.
            TimeoutError: The replay did not finish within the timeout.

        Returns:
            Replay in a terminal status.
        """
        return self._run(
            self._client.wait_for_replay(
                replay_id, timeout=timeout, poll_interval=poll_interval
            )
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>

    <PyParameter name="&#x22;poll_interval&#x22;" type="&#x22;float&#x22;" value="&#x22;2.0&#x22;">
      Seconds between status checks.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Replay in a terminal status.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_experiment&#x22;" type="&#x22;(self, experiment) -> ExperimentResponse&#x22;">
  Get an experiment by id or name.

  <PySourceCode>
    ```python
    def get_experiment(self, experiment: uuid.UUID | str) -> ExperimentResponse:
        """Get an experiment by id or name.

        Args:
            experiment: Id or name of the experiment.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment.

        Returns:
            Stored experiment.
        """
        return self._run(self._client.get_experiment(experiment))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the experiment.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment.ExperimentResponse&#x22;">
    Stored experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_experiments&#x22;" type="&#x22;(self) -> Iterator[ExperimentResponse]&#x22;">
  Iterate over all experiments.

  <PySourceCode>
    ```python
    def list_experiments(self) -> Iterator[ExperimentResponse]:
        """Iterate over all experiments.

        Returns:
            Iterator over every experiment.
        """
        return self._iterate(self._client.list_experiments())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator&#x22;">
    Iterator over every experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;run_experiment&#x22;" type="&#x22;(self, experiment, cohort_version_id, agent_version_id, baseline_evaluation_mode=BaselineEvaluationMode.IF_MISSING, wait=True, timeout=None) -> ExperimentRunResponse&#x22;">
  Start an experiment run and optionally wait for it to finish.

  <PySourceCode>
    ```python
    def run_experiment(
        self,
        experiment: uuid.UUID | str,
        cohort_version_id: uuid.UUID,
        agent_version_id: uuid.UUID,
        baseline_evaluation_mode: BaselineEvaluationMode = (
            BaselineEvaluationMode.IF_MISSING
        ),
        wait: bool = True,
        timeout: float | None = None,
    ) -> ExperimentRunResponse:
        """Start an experiment run and optionally wait for it to finish.

        Args:
            experiment: Id or name of the experiment.
            cohort_version_id: Cohort version whose sessions are replayed.
            agent_version_id: Agent version to replay with.
            baseline_evaluation_mode: How to score each baseline session.
            wait: Whether to wait for the run to reach a terminal status.
            timeout: Seconds to wait before giving up.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment, cohort version, or agent version.
            TimeoutError: The run did not finish within the timeout.

        Returns:
            Experiment run, in a terminal status when waited for.
        """
        return self._run(
            self._client.run_experiment(
                experiment,
                cohort_version_id,
                agent_version_id,
                baseline_evaluation_mode=baseline_evaluation_mode,
                wait=wait,
                timeout=timeout,
            )
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment&#x22;" type="&#x22;uuid.UUID | str&#x22;" value="undefined">
      Id or name of the experiment.
    </PyParameter>

    <PyParameter name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Cohort version whose sessions are replayed.
    </PyParameter>

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Agent version to replay with.
    </PyParameter>

    <PyParameter name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;BaselineEvaluationMode.IF_MISSING&#x22;">
      How to score each baseline session.
    </PyParameter>

    <PyParameter name="&#x22;wait&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
      Whether to wait for the run to reach a terminal status.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Experiment run, in a terminal status when waited for.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_experiment_run&#x22;" type="&#x22;(self, run_id) -> ExperimentRunResponse&#x22;">
  Get an experiment run by id.

  <PySourceCode>
    ```python
    def get_experiment_run(self, run_id: uuid.UUID) -> ExperimentRunResponse:
        """Get an experiment run by id.

        Args:
            run_id: Id of the experiment run.

        Raises:
            APIError: The request failed, including 404 for a missing run.

        Returns:
            Stored experiment run.
        """
        return self._run(self._client.get_experiment_run(run_id))
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment run.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Stored experiment run.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;wait_for_experiment_run&#x22;" type="&#x22;(self, run_id, timeout=None, poll_interval=2.0) -> ExperimentRunResponse&#x22;">
  Wait for an experiment run to reach a terminal status.

  <PySourceCode>
    ```python
    def wait_for_experiment_run(
        self,
        run_id: uuid.UUID,
        timeout: float | None = None,
        poll_interval: float = 2.0,
    ) -> ExperimentRunResponse:
        """Wait for an experiment run to reach a terminal status.

        Args:
            run_id: Id of the experiment run.
            timeout: Seconds to wait before giving up.
            poll_interval: Seconds between status checks.

        Raises:
            APIError: The request failed.
            TimeoutError: The run did not finish within the timeout.

        Returns:
            Experiment run in a terminal status.
        """
        return self._run(
            self._client.wait_for_experiment_run(
                run_id, timeout=timeout, poll_interval=poll_interval
            )
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment run.
    </PyParameter>

    <PyParameter name="&#x22;timeout&#x22;" type="&#x22;float | None&#x22;" value="&#x22;None&#x22;">
      Seconds to wait before giving up.
    </PyParameter>

    <PyParameter name="&#x22;poll_interval&#x22;" type="&#x22;float&#x22;" value="&#x22;2.0&#x22;">
      Seconds between status checks.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Experiment run in a terminal status.
  </PyFunctionReturn>
</PyFunction>


# NotFoundError



Not found error.


# RenewingTokenAuth



Bearer token auth flow renewing its token through a source on HTTP 401.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, source) -> None&#x22;">
  Initialize the auth flow.

  <PySourceCode>
    ```python
    def __init__(self, source: TokenSource) -> None:
        """Initialize the auth flow.

        Args:
            source: Source producing and renewing the bearer token.
        """
        self._source = source
        self._lock = asyncio.Lock()
        self._generation = 0
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;source&#x22;" type="&#x22;TokenSource&#x22;" value="undefined">
      Source producing and renewing the bearer token.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;async_auth_flow&#x22;" type="&#x22;(self, request) -> AsyncGenerator[httpx.Request, httpx.Response]&#x22;">
  Attach a bearer token and retry once with a renewed one on HTTP 401.

  A request rejected with HTTP 401 is retried once with a renewed token,
  unless another caller renewed it first, in which case the retry uses
  theirs.

  <PySourceCode>
    ```python
    async def async_auth_flow(
        self, request: httpx.Request
    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
        """Attach a bearer token and retry once with a renewed one on HTTP 401.

        A request rejected with HTTP 401 is retried once with a renewed token,
        unless another caller renewed it first, in which case the retry uses
        theirs.

        Args:
            request: Outgoing HTTP request.

        Yields:
            The request with a bearer token attached, and once more after a
            renewal following an HTTP 401 response.
        """
        generation = self._generation
        token = await self._get_token()
        if token is not None:
            request.headers["Authorization"] = f"Bearer {token}"
        response = yield request
        if response.status_code != httpx.codes.UNAUTHORIZED:
            return
        token = await self._renew(generation)
        if token is None:
            return
        request.headers["Authorization"] = f"Bearer {token}"
        yield request
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;httpx.Request&#x22;" value="undefined">
      Outgoing HTTP request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncGenerator[httpx.httpx.Request, httpx.httpx.Response]&#x22;" />
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close the token source.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close the token source."""
        await self._source.close()
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# ServerCredentials



Credentials stored for one server.

## Attributes [#attributes]

<PyAttribute name="&#x22;url&#x22;" type="&#x22;str&#x22;" value="null" />

<PyAttribute name="&#x22;type&#x22;" type="&#x22;ApiType&#x22;" value="&#x22;ApiType.SERVER&#x22;" />

<PyAttribute name="&#x22;api_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;api_token&#x22;" type="&#x22;ApiToken | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;device_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;device_code&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;control_plane_api_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;control_plane_api_key&#x22;" type="&#x22;str | None&#x22;" value="null">
  Return the stored API key when it is a control plane key.
</PyAttribute>

<PyAttribute name="&#x22;server_api_key&#x22;" type="&#x22;str | None&#x22;" value="null">
  Return the stored API key when it is a server key.
</PyAttribute>

<PyAttribute name="&#x22;can_refresh&#x22;" type="&#x22;bool&#x22;" value="null">
  Report whether a new token can be obtained without a fresh login.
</PyAttribute>


# ServerError



Server error.


# StaticTokenAuth



Fixed bearer token that never renews.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, token) -> None&#x22;">
  Initialize the auth flow.

  <PySourceCode>
    ```python
    def __init__(self, token: str) -> None:
        """Initialize the auth flow.

        Args:
            token: Bearer token attached to every request.
        """
        self._header = f"Bearer {token}"
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;token&#x22;" type="&#x22;str&#x22;" value="undefined">
      Bearer token attached to every request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;async_auth_flow&#x22;" type="&#x22;(self, request) -> AsyncGenerator[httpx.Request, httpx.Response]&#x22;">
  Attach the fixed bearer token to the request.

  <PySourceCode>
    ```python
    async def async_auth_flow(
        self, request: httpx.Request
    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
        """Attach the fixed bearer token to the request.

        Args:
            request: Outgoing HTTP request.

        Yields:
            The request with the bearer token attached.
        """
        request.headers["Authorization"] = self._header
        yield request
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;httpx.Request&#x22;" value="undefined">
      Outgoing HTTP request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncGenerator[httpx.httpx.Request, httpx.httpx.Response]&#x22;" />
</PyFunction>


# TokenAuth



Bearer token auth flow.

## Functions [#functions]

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close any resources this auth flow opened.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close any resources this auth flow opened."""
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# TokenGrantError



Token grant error.

## Attributes [#attributes]

<PyAttribute name="&#x22;error&#x22;" type="null" value="&#x22;error&#x22;" />

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, status_code, detail, error) -> None&#x22;">
  Initialize the error.

  <PySourceCode>
    ```python
    def __init__(self, status_code: int, detail: str, error: str) -> None:
        """Initialize the error.

        Args:
            status_code: HTTP status code.
            detail: Error detail.
            error: OAuth 2.0 error code.
        """
        super().__init__(status_code, detail)
        self.error = error
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;status_code&#x22;" type="&#x22;int&#x22;" value="undefined">
      HTTP status code.
    </PyParameter>

    <PyParameter name="&#x22;detail&#x22;" type="&#x22;str&#x22;" value="undefined">
      Error detail.
    </PyParameter>

    <PyParameter name="&#x22;error&#x22;" type="&#x22;str&#x22;" value="undefined">
      OAuth 2.0 error code.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# TokenSource



Source of bearer tokens for a renewing auth flow.

## Functions [#functions]

<PyFunction name="&#x22;get_cached_token&#x22;" type="&#x22;(self) -> str | None&#x22;">
  Return the cached bearer token.

  <PySourceCode>
    ```python
    def get_cached_token(self) -> str | None:
        """Return the cached bearer token.

        Returns:
            Bearer token, or None when nothing usable is cached.
        """
        ...
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;str | None&#x22;">
    Bearer token, or None when nothing usable is cached.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;fetch_token&#x22;" type="&#x22;(self) -> str | None&#x22;">
  Fetch a fresh bearer token.

  <PySourceCode>
    ```python
    async def fetch_token(self) -> str | None:
        """Fetch a fresh bearer token.

        Returns:
            Bearer token, or None when the source cannot produce one.
        """
        ...
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;str | None&#x22;">
    Bearer token, or None when the source cannot produce one.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;close&#x22;" type="&#x22;(self) -> None&#x22;">
  Close any resources this source opened.

  <PySourceCode>
    ```python
    async def close(self) -> None:
        """Close any resources this source opened."""
        ...
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# ValidationError



Validation error.


# client



Public SDK surface.

<Tabs items="[&#x22;Class&#x22;,&#x22;Functions&#x22;,&#x22;Modules&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;APIError&#x22;" href="&#x22;/reference/python/client/APIError&#x22;" />

      <Card title="&#x22;ApiToken&#x22;" href="&#x22;/reference/python/client/ApiToken&#x22;" />

      <Card title="&#x22;ApiType&#x22;" href="&#x22;/reference/python/client/ApiType&#x22;" />

      <Card title="&#x22;AuthenticationError&#x22;" href="&#x22;/reference/python/client/AuthenticationError&#x22;" />

      <Card title="&#x22;AuthorizationError&#x22;" href="&#x22;/reference/python/client/AuthorizationError&#x22;" />

      <Card title="&#x22;ClientConfig&#x22;" href="&#x22;/reference/python/client/ClientConfig&#x22;" />

      <Card title="&#x22;ControlPlaneLoginError&#x22;" href="&#x22;/reference/python/client/ControlPlaneLoginError&#x22;" />

      <Card title="&#x22;ControlPlaneSession&#x22;" href="&#x22;/reference/python/client/ControlPlaneSession&#x22;" />

      <Card title="&#x22;CredentialStore&#x22;" href="&#x22;/reference/python/client/CredentialStore&#x22;" />

      <Card title="&#x22;CredentialStoreTokenSource&#x22;" href="&#x22;/reference/python/client/CredentialStoreTokenSource&#x22;" />

      <Card title="&#x22;DeviceLoginError&#x22;" href="&#x22;/reference/python/client/DeviceLoginError&#x22;" />

      <Card title="&#x22;KitaruAPIClient&#x22;" href="&#x22;/reference/python/client/KitaruAPIClient&#x22;" />

      <Card title="&#x22;KitaruClient&#x22;" href="&#x22;/reference/python/client/KitaruClient&#x22;" />

      <Card title="&#x22;KitaruClientError&#x22;" href="&#x22;/reference/python/client/KitaruClientError&#x22;" />

      <Card title="&#x22;KitaruSyncClient&#x22;" href="&#x22;/reference/python/client/KitaruSyncClient&#x22;" />

      <Card title="&#x22;NotFoundError&#x22;" href="&#x22;/reference/python/client/NotFoundError&#x22;" />

      <Card title="&#x22;RenewingTokenAuth&#x22;" href="&#x22;/reference/python/client/RenewingTokenAuth&#x22;" />

      <Card title="&#x22;ServerCredentials&#x22;" href="&#x22;/reference/python/client/ServerCredentials&#x22;" />

      <Card title="&#x22;ServerError&#x22;" href="&#x22;/reference/python/client/ServerError&#x22;" />

      <Card title="&#x22;StaticTokenAuth&#x22;" href="&#x22;/reference/python/client/StaticTokenAuth&#x22;" />

      <Card title="&#x22;TokenAuth&#x22;" href="&#x22;/reference/python/client/TokenAuth&#x22;" />

      <Card title="&#x22;TokenGrantError&#x22;" href="&#x22;/reference/python/client/TokenGrantError&#x22;" />

      <Card title="&#x22;TokenSource&#x22;" href="&#x22;/reference/python/client/TokenSource&#x22;" />

      <Card title="&#x22;ValidationError&#x22;" href="&#x22;/reference/python/client/ValidationError&#x22;" />
    </Cards>
  </Tab>

  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;control_plane_login&#x22;" type="&#x22;(api_client, base_url, store, api_key=None, open_browser=True, prompt=None, refresh=False) -> tuple[ApiToken, ControlPlaneLoginMethod]&#x22;">
      Log in to a server that delegates identity to a control plane.

      Without an API key, a stored control plane credential that still produces
      an accepted token is reused. Otherwise the call blocks until a signed-in
      account confirms the user code in a browser, or until the authorization
      expires.

      <PySourceCode>
        ```python
        async def control_plane_login(
            api_client: KitaruAPIClient,
            base_url: str,
            store: CredentialStore,
            api_key: str | None = None,
            open_browser: bool = True,
            prompt: Callable[[ControlPlaneDeviceAuthorization], None] | None = None,
            refresh: bool = False,
        ) -> tuple[ApiToken, ControlPlaneLoginMethod]:
            """Log in to a server that delegates identity to a control plane.

            Without an API key, a stored control plane credential that still produces
            an accepted token is reused. Otherwise the call blocks until a signed-in
            account confirms the user code in a browser, or until the authorization
            expires.

            Args:
                api_client: API client pointed at the server.
                base_url: Server base URL credentials are stored under.
                store: Credential store the credentials are written to.
                api_key: Control plane API key. Reuses a stored credential or runs
                    the device authorization flow when omitted.
                open_browser: Whether to open the verification page.
                prompt: Called with the authorization so the caller can show the user
                    code.
                refresh: Whether to skip stored credentials and force a new device
                    authorization flow.

            Raises:
                ControlPlaneLoginError: The server does not delegate to a control
                    plane.
                DeviceLoginError: The authorization expired or was refused.

            Returns:
                Session token issued by the server and the method that produced it.
            """
            info = await api_client.info.get()
            if not info.control_plane_api_url:
                raise ControlPlaneLoginError(
                    f"Server {base_url} does not authenticate against a control plane"
                )
            control_plane_api_url = info.control_plane_api_url
            session = ControlPlaneSession(control_plane_api_url, store)
            try:
                if api_key is not None:
                    credential = (await session.login_with_api_key(api_key)).access_token
                    token = await exchange_control_plane_credential(
                        api_client, base_url, store, control_plane_api_url, credential
                    )
                    return token, "api_key"
                if not refresh:
                    # A stored credential the control plane or the server no longer
                    # accepts falls through to the device flow.
                    try:
                        credential = await session.get_token()
                    except AuthenticationError:
                        credential = None
                    if credential is not None:
                        try:
                            token = await exchange_control_plane_credential(
                                api_client, base_url, store, control_plane_api_url, credential
                            )
                            return token, "stored"
                        except AuthenticationError:
                            pass
                credential = (
                    await session.device_login(
                        open_browser=open_browser,
                        prompt=prompt,
                        workspace_id=str(info.id) if info.id else None,
                    )
                ).access_token
                token = await exchange_control_plane_credential(
                    api_client, base_url, store, control_plane_api_url, credential
                )
                return token, "device"
            finally:
                await session.close()
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;api_client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
          API client pointed at the server.
        </PyParameter>

        <PyParameter name="&#x22;base_url&#x22;" type="&#x22;str&#x22;" value="undefined">
          Server base URL credentials are stored under.
        </PyParameter>

        <PyParameter name="&#x22;store&#x22;" type="&#x22;CredentialStore&#x22;" value="undefined">
          Credential store the credentials are written to.
        </PyParameter>

        <PyParameter name="&#x22;api_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
          Control plane API key. Reuses a stored credential or runs
          the device authorization flow when omitted.
        </PyParameter>

        <PyParameter name="&#x22;open_browser&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
          Whether to open the verification page.
        </PyParameter>

        <PyParameter name="&#x22;prompt&#x22;" type="&#x22;Callable[[ControlPlaneDeviceAuthorization], None] | None&#x22;" value="&#x22;None&#x22;">
          Called with the authorization so the caller can show the user
          code.
        </PyParameter>

        <PyParameter name="&#x22;refresh&#x22;" type="&#x22;bool&#x22;" value="&#x22;False&#x22;">
          Whether to skip stored credentials and force a new device
          authorization flow.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;tuple&#x22;">
        Session token issued by the server and the method that produced it.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;device_login&#x22;" type="&#x22;(api_client, base_url, store, open_browser=True, prompt=None) -> ApiToken&#x22;">
      Authorize this machine against a server and store the token it gets.

      The call blocks until a signed-in account completes authorization in a
      browser, or until the authorization expires.

      <PySourceCode>
        ```python
        async def device_login(
            api_client: KitaruAPIClient,
            base_url: str,
            store: CredentialStore,
            open_browser: bool = True,
            prompt: Callable[[DeviceAuthorizationResponse], None] | None = None,
        ) -> ApiToken:
            """Authorize this machine against a server and store the token it gets.

            The call blocks until a signed-in account completes authorization in a
            browser, or until the authorization expires.

            Args:
                api_client: API client pointed at the server.
                base_url: Server base URL credentials are stored under.
                store: Credential store the device authorization is written to.
                open_browser: Whether to open the verification page.
                prompt: Called with the authorization so the caller can show the
                    verification URL. Defaults to logging it.

            Raises:
                DeviceLoginError: The authorization expired or was refused.

            Returns:
                Token issued for the authorized device.
            """
            fingerprint = describe_this_device()
            authorization = await api_client.auth.device_authorization(
                hostname=fingerprint.hostname,
                os=fingerprint.os,
                python_version=fingerprint.python_version,
                client_version=fingerprint.client_version,
            )
            if prompt is not None:
                prompt(authorization)
            else:
                logger.info(
                    "Open %s to continue.",
                    authorization.verification_uri_complete,
                )
            if open_browser:
                webbrowser.open(authorization.verification_uri_complete)
            response = await _poll_for_token(api_client, authorization)
            token = ApiToken.from_response(response)
            store.set_device(base_url, authorization.device_id, authorization.device_code)
            store.set_token(base_url, token)
            return token
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;api_client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
          API client pointed at the server.
        </PyParameter>

        <PyParameter name="&#x22;base_url&#x22;" type="&#x22;str&#x22;" value="undefined">
          Server base URL credentials are stored under.
        </PyParameter>

        <PyParameter name="&#x22;store&#x22;" type="&#x22;CredentialStore&#x22;" value="undefined">
          Credential store the device authorization is written to.
        </PyParameter>

        <PyParameter name="&#x22;open_browser&#x22;" type="&#x22;bool&#x22;" value="&#x22;True&#x22;">
          Whether to open the verification page.
        </PyParameter>

        <PyParameter name="&#x22;prompt&#x22;" type="&#x22;Callable[[DeviceAuthorizationResponse], None] | None&#x22;" value="&#x22;None&#x22;">
          Called with the authorization so the caller can show the
          verification URL. Defaults to logging it.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;kitaru.client.ApiToken&#x22;">
        Token issued for the authorized device.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;get_server_url&#x22;" type="&#x22;() -> str | None&#x22;">
      Return the stored server URL.

      <PySourceCode>
        ```python
        def get_server_url() -> str | None:
            """Return the stored server URL.

            Returns:
                Server URL, or None when none is stored.
            """
            return load_config().server_url
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;str | None&#x22;">
        Server URL, or None when none is stored.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;load_config&#x22;" type="&#x22;() -> ClientConfig&#x22;">
      Read the configuration file, ignoring one that cannot be parsed.

      <PySourceCode>
        ```python
        def load_config() -> ClientConfig:
            """Read the configuration file, ignoring one that cannot be parsed.

            Returns:
                Stored configuration, or an empty one when the file is missing or
                malformed.
            """
            path = get_config_path()
            try:
                raw = path.read_text(encoding="utf-8")
            except OSError:
                return ClientConfig()
            try:
                return ClientConfig.model_validate_json(raw)
            except ValidationError:
                logger.warning("Ignoring malformed configuration file %s.", path)
                return ClientConfig()
        ```
      </PySourceCode>

      <PyFunctionReturn type="&#x22;kitaru.client.ClientConfig&#x22;">
        Stored configuration, or an empty one when the file is missing or
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;save_config&#x22;" type="&#x22;(config) -> None&#x22;">
      Write the configuration file, replacing it in one step.

      <PySourceCode>
        ```python
        def save_config(config: ClientConfig) -> None:
            """Write the configuration file, replacing it in one step.

            Args:
                config: Configuration to write.
            """
            write_json_file(
                get_config_path(),
                config.model_dump(mode="json", exclude_none=True),
            )
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;config&#x22;" type="&#x22;ClientConfig&#x22;" value="undefined">
          Configuration to write.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;None&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;set_server_url&#x22;" type="&#x22;(url) -> None&#x22;">
      Store the server URL.

      <PySourceCode>
        ```python
        def set_server_url(url: str | None) -> None:
            """Store the server URL.

            Args:
                url: Server base URL, None clears the stored URL.
            """
            config = load_config()
            config.server_url = normalize_server_url(url) if url else None
            save_config(config)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;url&#x22;" type="&#x22;str | None&#x22;" value="undefined">
          Server base URL, None clears the stored URL.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;None&#x22;" />
    </PyFunction>
  </Tab>

  <Tab value="&#x22;Modules&#x22;">
    <Cards>
      <Card href="&#x22;/reference/python/client/resources&#x22;" title="&#x22;resources&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# v1



Version 1 API models.

<Tabs items="[&#x22;Modules&#x22;]">
  <Tab value="&#x22;Modules&#x22;">
    <Cards>
      <Card href="&#x22;/reference/python/api_models/v1/agent&#x22;" title="&#x22;agent&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/agent_version&#x22;" title="&#x22;agent_version&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/analyzer&#x22;" title="&#x22;analyzer&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/annotation&#x22;" title="&#x22;annotation&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/base&#x22;" title="&#x22;base&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/cohort&#x22;" title="&#x22;cohort&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/cohort_version&#x22;" title="&#x22;cohort_version&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/evaluation&#x22;" title="&#x22;evaluation&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/evaluator&#x22;" title="&#x22;evaluator&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/experiment&#x22;" title="&#x22;experiment&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/experiment_run&#x22;" title="&#x22;experiment_run&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/filter&#x22;" title="&#x22;filter&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/imports&#x22;" title="&#x22;imports&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/insight&#x22;" title="&#x22;insight&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/investigation&#x22;" title="&#x22;investigation&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/job&#x22;" title="&#x22;job&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/replay&#x22;" title="&#x22;replay&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/replay_config&#x22;" title="&#x22;replay_config&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/session&#x22;" title="&#x22;session&#x22;" />

      <Card href="&#x22;/reference/python/api_models/v1/session_node&#x22;" title="&#x22;session_node&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AnalysisError



Raised when loading or invoking an analyzer plugin fails.


# InsightInput



Insight input.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Insight name.')&#x22;" />

<PyAttribute name="&#x22;title&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Insight title.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Insight description.')&#x22;" />

<PyAttribute name="&#x22;data&#x22;" type="&#x22;InsightData&#x22;" value="&#x22;Field(description='Insight data.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />


# analyzer



Analyzer plugin contract and the analysis flow.

<PyAttribute name="&#x22;AnalyzerReturn&#x22;" type="null" value="&#x22;InsightInput | list[InsightInput]&#x22;" />

<Tabs items="[&#x22;Class&#x22;,&#x22;Functions&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AnalysisError&#x22;" href="&#x22;/reference/python/task/analyzer/AnalysisError&#x22;" />

      <Card title="&#x22;InsightInput&#x22;" href="&#x22;/reference/python/task/analyzer/InsightInput&#x22;" />
    </Cards>
  </Tab>

  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;call_analyzer&#x22;" type="&#x22;(name, analyzer, session_ids, params) -> list[InsightInput]&#x22;">
      Invoke an analyzer and validate its results.

      <PySourceCode>
        ```python
        async def call_analyzer(
            name: str,
            analyzer: Callable[..., AnalyzerReturn | Awaitable[AnalyzerReturn]],
            session_ids: list[uuid.UUID],
            params: dict[str, Any],
        ) -> list[InsightInput]:
            """Invoke an analyzer and validate its results.

            Args:
                name: Analyzer name, named in error messages.
                analyzer: Analyzer callable, sync or returning an awaitable.
                session_ids: Imported session IDs passed to the analyzer. Analyzers
                    fetch any session details they need through the API client.
                params: Parameters passed to the analyzer.

            Raises:
                AnalysisError: The analyzer raised, returned a
                    non-InsightInput value, or returned duplicate result names.

            Returns:
                Insight inputs.
            """
            try:
                result = analyzer(session_ids, **params)
                if inspect.isawaitable(result):
                    result = await result
            except Exception as exc:
                raise AnalysisError(f"Analyzer '{name}' raised an error: {exc}") from exc
            results = result if isinstance(result, list) else [result]
            if not all(isinstance(item, InsightInput) for item in results):
                raise AnalysisError(f"Analyzer '{name}' returned a non-InsightInput value")
            names = [item.name for item in results]
            if len(set(names)) != len(names):
                raise AnalysisError(f"Analyzer '{name}' returned duplicate result names")
            return results
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="undefined">
          Analyzer name, named in error messages.
        </PyParameter>

        <PyParameter name="&#x22;analyzer&#x22;" type="&#x22;Callable[..., AnalyzerReturn | Awaitable[AnalyzerReturn]]&#x22;" value="undefined">
          Analyzer callable, sync or returning an awaitable.
        </PyParameter>

        <PyParameter name="&#x22;session_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="undefined">
          Imported session IDs passed to the analyzer. Analyzers
          fetch any session details they need through the API client.
        </PyParameter>

        <PyParameter name="&#x22;params&#x22;" type="&#x22;dict[str, Any]&#x22;" value="undefined">
          Parameters passed to the analyzer.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;list&#x22;">
        Insight inputs.
      </PyFunctionReturn>
    </PyFunction>
  </Tab>
</Tabs>


# EvaluationError



Raised when loading or invoking an evaluator plugin fails.


# EvaluationResult



Evaluation result.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;EvaluationName&#x22;" value="&#x22;Field(description='Evaluation name.')&#x22;" />

<PyAttribute name="&#x22;score&#x22;" type="&#x22;FiniteFloat | bool | None&#x22;" value="&#x22;Field(default=None, description='Numeric or boolean score.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Label or string value.')&#x22;" />

<PyAttribute name="&#x22;explanation&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Free-form explanation.')&#x22;" />

<PyAttribute name="&#x22;passed&#x22;" type="&#x22;bool | None&#x22;" value="&#x22;Field(default=None, description='Pass or fail verdict.')&#x22;" />

<PyAttribute name="&#x22;min_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Lower bound of the score scale.')&#x22;" />

<PyAttribute name="&#x22;max_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Upper bound of the score scale.')&#x22;" />

<PyAttribute name="&#x22;target_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Score to beat.')&#x22;" />

<PyAttribute name="&#x22;data_type&#x22;" type="&#x22;EvaluationDataType&#x22;" value="null">
  Data type derived from which of score and value are set.
</PyAttribute>

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, value=None, **data) -> None&#x22;">
  Route a single positional score or value by type.

  <PySourceCode>
    ```python
    def __init__(self, value: float | bool | str | None = None, **data: Any) -> None:
        """Route a single positional score or value by type.

        Args:
            value: Positional score, bool or float routes to score and str
                routes to value.
            data: Remaining fields, passed as keywords.
        """
        if isinstance(value, str):
            data.setdefault("value", value)
        elif value is not None:
            data.setdefault("score", value)
        super().__init__(**data)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;value&#x22;" type="&#x22;float | bool | str | None&#x22;" value="&#x22;None&#x22;">
      Positional score, bool or float routes to score and str
      routes to value.
    </PyParameter>

    <PyParameter name="&#x22;data&#x22;" type="&#x22;Any&#x22;" value="&#x22;{}&#x22;">
      Remaining fields, passed as keywords.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# SessionView



Session view.

## Attributes [#attributes]

<PyAttribute name="&#x22;session&#x22;" type="&#x22;SessionDetailResponse&#x22;" value="null" />

<PyAttribute name="&#x22;nodes&#x22;" type="&#x22;list[SessionNodeResponse]&#x22;" value="null" />


# evaluator



Evaluator plugin contract and the evaluation flow.

<PyAttribute name="&#x22;EvaluatorReturn&#x22;" type="null" value="&#x22;EvaluationResult | list[EvaluationResult]&#x22;" />

<Tabs items="[&#x22;Class&#x22;,&#x22;Functions&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;EvaluationError&#x22;" href="&#x22;/reference/python/task/evaluator/EvaluationError&#x22;" />

      <Card title="&#x22;SessionView&#x22;" href="&#x22;/reference/python/task/evaluator/SessionView&#x22;" />

      <Card title="&#x22;EvaluationResult&#x22;" href="&#x22;/reference/python/task/evaluator/EvaluationResult&#x22;" />
    </Cards>
  </Tab>

  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;call_evaluator&#x22;" type="&#x22;(name, evaluator, session, params) -> list[EvaluationResult]&#x22;">
      Invoke an evaluator and validate its results.

      <PySourceCode>
        ```python
        async def call_evaluator(
            name: str,
            evaluator: Callable[..., EvaluatorReturn | Awaitable[EvaluatorReturn]],
            session: SessionView,
            params: dict[str, Any],
        ) -> list[EvaluationResult]:
            """Invoke an evaluator and validate its results.

            Args:
                name: Evaluator name, named in error messages.
                evaluator: Evaluator callable, sync or returning an awaitable.
                session: Session view passed to the evaluator.
                params: Parameters passed to the evaluator.

            Raises:
                EvaluationError: The evaluator raised, returned no results, returned
                    a non-EvaluationResult value, or returned duplicate result names.

            Returns:
                Evaluation results.
            """
            try:
                result = evaluator(session, **params)
                if inspect.isawaitable(result):
                    result = await result
            except Exception as exc:
                raise EvaluationError(f"Evaluator '{name}' raised an error: {exc}") from exc
            results = result if isinstance(result, list) else [result]
            if not results:
                raise EvaluationError(f"Evaluator '{name}' returned no results")
            if not all(isinstance(item, EvaluationResult) for item in results):
                raise EvaluationError(
                    f"Evaluator '{name}' returned a non-EvaluationResult value"
                )
            names = [item.name for item in results]
            if len(set(names)) != len(names):
                raise EvaluationError(f"Evaluator '{name}' returned duplicate result names")
            return results
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="undefined">
          Evaluator name, named in error messages.
        </PyParameter>

        <PyParameter name="&#x22;evaluator&#x22;" type="&#x22;Callable[..., EvaluatorReturn | Awaitable[EvaluatorReturn]]&#x22;" value="undefined">
          Evaluator callable, sync or returning an awaitable.
        </PyParameter>

        <PyParameter name="&#x22;session&#x22;" type="&#x22;SessionView&#x22;" value="undefined">
          Session view passed to the evaluator.
        </PyParameter>

        <PyParameter name="&#x22;params&#x22;" type="&#x22;dict[str, Any]&#x22;" value="undefined">
          Parameters passed to the evaluator.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;list&#x22;">
        Evaluation results.
      </PyFunctionReturn>
    </PyFunction>
  </Tab>
</Tabs>


# FetchingImporter



Importer object that also fetches payloads from a provider API.

## Functions [#functions]

<PyFunction name="&#x22;fetch&#x22;" type="&#x22;(self, query) -> Iterator[bytes] | AsyncIterator[bytes]&#x22;">
  Fetch payloads matching a query, sync or async.

  <PySourceCode>
    ```python
    def fetch(self, query: dict[str, Any]) -> Iterator[bytes] | AsyncIterator[bytes]:
        """Fetch payloads matching a query, sync or async."""
        ...
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;query&#x22;" type="&#x22;dict[str, Any]&#x22;" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator[bytes] | collections.abc.AsyncIterator[bytes]&#x22;" />
</PyFunction>


# ImportFailure



Import failure.

## Attributes [#attributes]

<PyAttribute name="&#x22;line&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Line the failure occurred at.')&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='External id of the failed item.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Failure reason.')&#x22;" />


# ImportStats



Import stats.

## Attributes [#attributes]

<PyAttribute name="&#x22;created&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Sessions created.')&#x22;" />

<PyAttribute name="&#x22;skipped&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Sessions skipped as duplicates.')&#x22;" />

<PyAttribute name="&#x22;failed&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Items that failed to import.')&#x22;" />

<PyAttribute name="&#x22;failures&#x22;" type="&#x22;list[ImportFailure]&#x22;" value="&#x22;Field(default_factory=list, max_length=MAX_IMPORT_FAILURES, description='Sample of failures.')&#x22;" />

<PyAttribute name="&#x22;limit_reached&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=False, description='Whether the import stopped at its session limit.')&#x22;" />


# ImportedNode



Provider data normalized for node ingestion.

## Attributes [#attributes]

<PyAttribute name="&#x22;index&#x22;" type="&#x22;int | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;parent_index&#x22;" type="&#x22;int | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;secondary_parent_indexes&#x22;" type="&#x22;list[int]&#x22;" value="&#x22;Field(default_factory=list)&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;trace_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;node_type&#x22;" type="&#x22;NodeType&#x22;" value="null" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="null" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;NodeStatus&#x22;" value="null" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;system_prompt_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;reasoning&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="null" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="null" />

<PyAttribute name="&#x22;requested_model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;model_provider&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;tokens&#x22;" type="&#x22;TokenUsage | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;cost&#x22;" type="&#x22;Decimal | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;model_params&#x22;" type="&#x22;dict[str, Any] | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;tool_name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;subagent_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;attributes&#x22;" type="&#x22;Any&#x22;" value="null" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, Any]&#x22;" value="&#x22;Field(default_factory=dict)&#x22;" />

<PyAttribute name="&#x22;children&#x22;" type="&#x22;list[ImportedNode]&#x22;" value="&#x22;Field(default_factory=list)&#x22;" />


# ImportedSession



Provider data normalized for session ingestion.

## Attributes [#attributes]

<PyAttribute name="&#x22;status&#x22;" type="&#x22;SessionStatus&#x22;" value="null" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="null" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="null" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str&#x22;" value="null" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, Any]&#x22;" value="&#x22;Field(default_factory=dict)&#x22;" />

<PyAttribute name="&#x22;framework&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;" />

<PyAttribute name="&#x22;nodes&#x22;" type="&#x22;list[ImportedNode]&#x22;" value="null" />


# Importer



Importer object.

## Functions [#functions]

<PyFunction name="&#x22;parse&#x22;" type="&#x22;(self, payload, params) -> Iterator[ImportedItem] | AsyncIterator[ImportedItem]&#x22;">
  Parse one payload into imported items, sync or async.

  <PySourceCode>
    ```python
    def parse(
        self, payload: bytes, params: dict[str, Any]
    ) -> Iterator[ImportedItem] | AsyncIterator[ImportedItem]:
        """Parse one payload into imported items, sync or async."""
        ...
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;payload&#x22;" type="&#x22;bytes&#x22;" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;dict[str, Any]&#x22;" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.Iterator[kitaru.task.importer.ImportedItem] | collections.abc.AsyncIterator[kitaru.task.importer.ImportedItem]&#x22;" />
</PyFunction>


# SessionImportError



Raised when a parser fails while starting or advancing.


# importer



Importer plugin contract and the import flow.

<PyAttribute name="&#x22;Fetcher&#x22;" type="null" value="&#x22;Callable[[dict[str, Any]], Iterator[bytes] | AsyncIterator[bytes]]&#x22;" />

<PyAttribute name="&#x22;ImportedItem&#x22;" type="null" value="&#x22;ImportedSession | ImportFailure&#x22;" />

<PyAttribute name="&#x22;NODE_BATCH_SIZE&#x22;" type="null" value="&#x22;200&#x22;" />

<PyAttribute name="&#x22;Parser&#x22;" type="null" value="&#x22;Callable[[bytes, dict[str, Any]], Iterator[ImportedItem] | AsyncIterator[ImportedItem]]&#x22;" />

<PyAttribute name="&#x22;MAX_IMPORT_FAILURES&#x22;" type="null" value="&#x22;20&#x22;" />

<Tabs items="[&#x22;Class&#x22;,&#x22;Functions&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;FetchingImporter&#x22;" href="&#x22;/reference/python/task/importer/FetchingImporter&#x22;" />

      <Card title="&#x22;ImportedNode&#x22;" href="&#x22;/reference/python/task/importer/ImportedNode&#x22;" />

      <Card title="&#x22;ImportedSession&#x22;" href="&#x22;/reference/python/task/importer/ImportedSession&#x22;" />

      <Card title="&#x22;Importer&#x22;" href="&#x22;/reference/python/task/importer/Importer&#x22;" />

      <Card title="&#x22;SessionImportError&#x22;" href="&#x22;/reference/python/task/importer/SessionImportError&#x22;" />

      <Card title="&#x22;ImportFailure&#x22;" href="&#x22;/reference/python/task/importer/ImportFailure&#x22;" />

      <Card title="&#x22;ImportStats&#x22;" href="&#x22;/reference/python/task/importer/ImportStats&#x22;" />
    </Cards>
  </Tab>

  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;call_fetcher&#x22;" type="&#x22;(fetcher, query) -> AsyncIterator[bytes]&#x22;">
      Advance a fetcher one payload at a time, wrapping any failure.

      Wrapping only the fetcher call would protect nothing, since a generator
      function runs no code until iterated. This wraps every step of the
      iteration instead.

      <PySourceCode>
        ```python
        async def call_fetcher(fetcher: Fetcher, query: dict[str, Any]) -> AsyncIterator[bytes]:
            """Advance a fetcher one payload at a time, wrapping any failure.

            Wrapping only the fetcher call would protect nothing, since a generator
            function runs no code until iterated. This wraps every step of the
            iteration instead.

            Args:
                fetcher: Fetcher callable, sync or async.
                query: Importer-defined selection of what to fetch.

            Raises:
                SessionImportError: The fetcher raised while starting or advancing,
                    or yielded an item that is not bytes.

            Yields:
                Fetched payloads.
            """
            try:
                result = fetcher(query)
                iterator = result if isinstance(result, AsyncIterator) else iter(result)
            except Exception as exc:
                raise SessionImportError(
                    f"Fetcher raised an error: {type(exc).__name__}: {exc}"
                ) from exc
            while True:
                try:
                    payload = await _advance(iterator)
                except StopAsyncIteration:
                    return
                except Exception as exc:
                    raise SessionImportError(
                        f"Fetcher raised an error: {type(exc).__name__}: {exc}"
                    ) from exc
                if not isinstance(payload, bytes):
                    raise SessionImportError(
                        f"Fetcher yielded an item that is not bytes: {payload!r}"
                    )
                yield payload
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;fetcher&#x22;" type="&#x22;Fetcher&#x22;" value="undefined">
          Fetcher callable, sync or async.
        </PyParameter>

        <PyParameter name="&#x22;query&#x22;" type="&#x22;dict[str, Any]&#x22;" value="undefined">
          Importer-defined selection of what to fetch.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator[bytes]&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;call_parser&#x22;" type="&#x22;(parser, payload, params) -> AsyncIterator[ImportedItem]&#x22;">
      Advance a parser one item at a time, wrapping any failure.

      Wrapping only the parser call would protect nothing, since a generator
      function runs no code until iterated. This wraps every step of the
      iteration instead.

      <PySourceCode>
        ```python
        async def call_parser(
            parser: Parser, payload: bytes, params: dict[str, Any]
        ) -> AsyncIterator[ImportedItem]:
            """Advance a parser one item at a time, wrapping any failure.

            Wrapping only the parser call would protect nothing, since a generator
            function runs no code until iterated. This wraps every step of the
            iteration instead.

            Args:
                parser: Parser callable, sync or async.
                payload: Raw payload bytes.
                params: Parameters passed to the parser.

            Raises:
                SessionImportError: The parser raised while starting or advancing, or
                    yielded an item that is not an ImportedSession or ImportFailure.

            Yields:
                Imported items.
            """
            try:
                result = parser(payload, params)
                iterator = result if isinstance(result, AsyncIterator) else iter(result)
            except Exception as exc:
                raise SessionImportError(
                    f"Parser raised an error: {type(exc).__name__}: {exc}"
                ) from exc
            while True:
                try:
                    item = await _advance(iterator)
                except StopAsyncIteration:
                    return
                except Exception as exc:
                    raise SessionImportError(
                        f"Parser raised an error: {type(exc).__name__}: {exc}"
                    ) from exc
                if not isinstance(item, ImportedSession | ImportFailure):
                    raise SessionImportError(
                        f"Parser yielded an item that is not an ImportedSession or "
                        f"ImportFailure: {item!r}"
                    )
                yield item
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;parser&#x22;" type="&#x22;Parser&#x22;" value="undefined">
          Parser callable, sync or async.
        </PyParameter>

        <PyParameter name="&#x22;payload&#x22;" type="&#x22;bytes&#x22;" value="undefined">
          Raw payload bytes.
        </PyParameter>

        <PyParameter name="&#x22;params&#x22;" type="&#x22;dict[str, Any]&#x22;" value="undefined">
          Parameters passed to the parser.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator[kitaru.task.importer.ImportedItem]&#x22;" />
    </PyFunction>

    <PyFunction name="&#x22;flatten_nodes&#x22;" type="&#x22;(nodes) -> list[SessionNodeCreateRequest]&#x22;">
      Flatten an imported node tree into indexed ingest requests, depth-first.

      <PySourceCode>
        ```python
        def flatten_nodes(nodes: list[ImportedNode]) -> list[SessionNodeCreateRequest]:
            """Flatten an imported node tree into indexed ingest requests, depth-first.

            Args:
                nodes: Top-level imported nodes.

            Returns:
                Flat session node create requests in depth-first order.
            """
            explicit_indexes = [node.index is not None for node in nodes]
            if any(explicit_indexes):
                if not all(explicit_indexes) or any(node.children for node in nodes):
                    raise SessionImportError(
                        "Indexed imported nodes must all have indexes and cannot have children"
                    )
                indexed_nodes = sorted(
                    nodes, key=lambda node: node.index if node.index is not None else -1
                )
                direct = [
                    _node_request(
                        node,
                        index=node.index,
                        parent_index=node.parent_index,
                    )
                    for node in indexed_nodes
                    if node.index is not None
                ]
                return SessionNodeBatchRequest(nodes=direct).nodes

            flattened: list[SessionNodeCreateRequest] = []

            active: set[int] = set()
            stack: list[tuple[ImportedNode, int | None, bool]] = [
                (node, None, False) for node in reversed(nodes)
            ]
            while stack:
                node, parent_index, exiting = stack.pop()
                if exiting:
                    active.remove(id(node))
                    continue
                if id(node) in active:
                    raise SessionImportError("Imported node tree contains a cycle")
                active.add(id(node))
                index = len(flattened)
                flattened.append(_node_request(node, index=index, parent_index=parent_index))
                stack.append((node, parent_index, True))
                stack.extend((child, index, False) for child in reversed(node.children))
            return flattened
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;nodes&#x22;" type="&#x22;list[ImportedNode]&#x22;" value="undefined">
          Top-level imported nodes.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;list&#x22;">
        Flat session node create requests in depth-first order.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;gather_bounded&#x22;" type="&#x22;(awaitables, concurrency) -> list[T]&#x22;">
      Await every awaitable with at most concurrency in flight, in input order.

      <PySourceCode>
        ```python
        async def gather_bounded(
            awaitables: Iterable[Awaitable[T]], concurrency: int
        ) -> list[T]:
            """Await every awaitable with at most concurrency in flight, in input order.

            Args:
                awaitables: Awaitables to run.
                concurrency: Maximum number in flight at once.

            Returns:
                Results in input order.
            """
            semaphore = asyncio.Semaphore(concurrency)

            async def _run(awaitable: Awaitable[T]) -> T:
                async with semaphore:
                    return await awaitable

            return list(await asyncio.gather(*(_run(item) for item in awaitables)))
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;awaitables&#x22;" type="&#x22;Iterable[Awaitable[T]]&#x22;" value="undefined">
          Awaitables to run.
        </PyParameter>

        <PyParameter name="&#x22;concurrency&#x22;" type="&#x22;int&#x22;" value="undefined">
          Maximum number in flight at once.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;list&#x22;">
        Results in input order.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;ingest_session&#x22;" type="&#x22;(client, parsed, agent_id, provider, origin=SessionOrigin.IMPORTED) -> SessionResponse | None&#x22;">
      Create a session for one parsed import item and ingest its nodes.

      <PySourceCode>
        ```python
        async def ingest_session(
            client: KitaruAPIClient,
            parsed: ImportedSession,
            agent_id: uuid.UUID | None,
            provider: str | None,
            origin: SessionOrigin = SessionOrigin.IMPORTED,
        ) -> SessionResponse | None:
            """Create a session for one parsed import item and ingest its nodes.

            Args:
                client: API client.
                parsed: Imported session.
                agent_id: Agent the session is created under, None resolves it from
                    the task.
                provider: Source system named on the import.
                origin: Session origin.

            Raises:
                APIError: Session creation or node ingestion failed.
                SessionImportError: The imported node tree is invalid.

            Returns:
                Created session, None when a session with the external id already
                exists.
            """
            request = session_request(parsed, agent_id, provider, origin)
            try:
                session = await client.sessions.create(request)
            except APIError as exc:
                if exc.status_code == httpx.codes.CONFLICT:
                    return None
                raise
            nodes = flatten_nodes(parsed.nodes)
            for start in range(0, len(nodes), NODE_BATCH_SIZE):
                batch = nodes[start : start + NODE_BATCH_SIZE]
                await client.sessions.ingest_nodes(
                    session.id, SessionNodeBatchRequest(nodes=batch)
                )
            return session
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
          API client.
        </PyParameter>

        <PyParameter name="&#x22;parsed&#x22;" type="&#x22;ImportedSession&#x22;" value="undefined">
          Imported session.
        </PyParameter>

        <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="undefined">
          Agent the session is created under, None resolves it from
          the task.
        </PyParameter>

        <PyParameter name="&#x22;provider&#x22;" type="&#x22;str | None&#x22;" value="undefined">
          Source system named on the import.
        </PyParameter>

        <PyParameter name="&#x22;origin&#x22;" type="&#x22;SessionOrigin&#x22;" value="&#x22;SessionOrigin.IMPORTED&#x22;">
          Session origin.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;SessionResponse | None&#x22;">
        Created session, None when a session with the external id already
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;retry_rate_limited&#x22;" type="&#x22;(call, get_retry_after, max_retries=MAX_RATE_LIMIT_RETRIES) -> T&#x22;">
      Await a call, sleeping and retrying while it reports a rate limit.

      <PySourceCode>
        ```python
        async def retry_rate_limited(
            call: Callable[[], Awaitable[T]],
            get_retry_after: Callable[[Exception], float | None],
            max_retries: int = MAX_RATE_LIMIT_RETRIES,
        ) -> T:
            """Await a call, sleeping and retrying while it reports a rate limit.

            Args:
                call: Factory of the awaitable to run.
                get_retry_after: Seconds to wait when the exception is a rate limit,
                    None when it is not.
                max_retries: Retries before the rate limit error propagates.

            Returns:
                Result of the call.
            """
            retries = 0
            while True:
                try:
                    return await call()
                except Exception as exc:
                    retry_after = get_retry_after(exc)
                    if retry_after is None or retries >= max_retries:
                        raise
                    retries += 1
                    await asyncio.sleep(retry_after)
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;call&#x22;" type="&#x22;Callable[[], Awaitable[T]]&#x22;" value="undefined">
          Factory of the awaitable to run.
        </PyParameter>

        <PyParameter name="&#x22;get_retry_after&#x22;" type="&#x22;Callable[[Exception], float | None]&#x22;" value="undefined">
          Seconds to wait when the exception is a rate limit,
          None when it is not.
        </PyParameter>

        <PyParameter name="&#x22;max_retries&#x22;" type="&#x22;int&#x22;" value="&#x22;MAX_RATE_LIMIT_RETRIES&#x22;">
          Retries before the rate limit error propagates.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;kitaru.task.importer.T&#x22;">
        Result of the call.
      </PyFunctionReturn>
    </PyFunction>

    <PyFunction name="&#x22;session_request&#x22;" type="&#x22;(parsed, agent_id, provider, origin=SessionOrigin.IMPORTED) -> SessionCreateRequest&#x22;">
      Build a session create request for one parsed import item.

      <PySourceCode>
        ```python
        def session_request(
            parsed: ImportedSession,
            agent_id: uuid.UUID | None,
            provider: str | None,
            origin: SessionOrigin = SessionOrigin.IMPORTED,
        ) -> SessionCreateRequest:
            """Build a session create request for one parsed import item.

            Args:
                parsed: Imported session.
                agent_id: Agent the session is created under, None resolves it from
                    the task.
                provider: Source system named on the import.
                origin: Session origin.

            Returns:
                Session create request.
            """
            return SessionCreateRequest(
                agent_id=agent_id,
                origin=origin,
                status=parsed.status,
                name=parsed.name,
                input_text_selector=parsed.input_text_selector,
                output_text_selector=parsed.output_text_selector,
                inputs=parsed.inputs,
                outputs=parsed.outputs,
                error=parsed.error,
                started_at=parsed.started_at,
                ended_at=parsed.ended_at,
                external_id=parsed.external_id,
                metadata=parsed.metadata,
                imported_from=provider,
                framework=parsed.framework,
            )
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;parsed&#x22;" type="&#x22;ImportedSession&#x22;" value="undefined">
          Imported session.
        </PyParameter>

        <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="undefined">
          Agent the session is created under, None resolves it from
          the task.
        </PyParameter>

        <PyParameter name="&#x22;provider&#x22;" type="&#x22;str | None&#x22;" value="undefined">
          Source system named on the import.
        </PyParameter>

        <PyParameter name="&#x22;origin&#x22;" type="&#x22;SessionOrigin&#x22;" value="&#x22;SessionOrigin.IMPORTED&#x22;">
          Session origin.
        </PyParameter>
      </div>

      <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionCreateRequest&#x22;">
        Session create request.
      </PyFunctionReturn>
    </PyFunction>
  </Tab>
</Tabs>


# AgentVersionsResource



Agent version API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, agent_version_id) -> AgentVersionResponse&#x22;">
  Get an agent version by id.

  <PySourceCode>
    ```python
    async def get(self, agent_version_id: uuid.UUID) -> AgentVersionResponse:
        """Get an agent version by id.

        Args:
            agent_version_id: Id of the agent version.

        Raises:
            APIError: The request failed, including 404 for a missing agent
                version.

        Returns:
            Stored agent version.
        """
        response = await self._client.request(
            "GET", f"/api/v1/agent-versions/{agent_version_id}"
        )
        return AgentVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent version.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent_version.AgentVersionResponse&#x22;">
    Stored agent version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, agent_version_id, request) -> AgentVersionResponse&#x22;">
  Update an agent version.

  <PySourceCode>
    ```python
    async def update(
        self, agent_version_id: uuid.UUID, request: AgentVersionUpdateRequest
    ) -> AgentVersionResponse:
        """Update an agent version.

        Args:
            agent_version_id: Id of the agent version.
            request: Agent version update request, unset fields stay
                unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing agent
                version.

        Returns:
            Updated agent version.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/agent-versions/{agent_version_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return AgentVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent version.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AgentVersionUpdateRequest&#x22;" value="undefined">
      Agent version update request, unset fields stay
      unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent_version.AgentVersionResponse&#x22;">
    Updated agent version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, agent_version_id) -> None&#x22;">
  Delete an agent version.

  <PySourceCode>
    ```python
    async def delete(self, agent_version_id: uuid.UUID) -> None:
        """Delete an agent version.

        Args:
            agent_version_id: Id of the agent version.

        Raises:
            APIError: The request failed, including 404 for a missing agent
                version and 409 when an experiment run references it.
        """
        await self._client.request(
            "DELETE", f"/api/v1/agent-versions/{agent_version_id}"
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent version.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# AgentsResource



Agent API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> AgentResponse&#x22;">
  Create an agent.

  <PySourceCode>
    ```python
    async def create(
        self, request: AgentCreateRequest, idempotency_key: str | None = None
    ) -> AgentResponse:
        """Create an agent.

        Args:
            request: Agent create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 409 for a duplicate name.

        Returns:
            Created agent.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/agents",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return AgentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AgentCreateRequest&#x22;" value="undefined">
      Agent create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent.AgentResponse&#x22;">
    Created agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, agent_id) -> AgentResponse&#x22;">
  Get an agent by id.

  <PySourceCode>
    ```python
    async def get(self, agent_id: uuid.UUID) -> AgentResponse:
        """Get an agent by id.

        Args:
            agent_id: Id of the agent.

        Raises:
            APIError: The request failed, including 404 for a missing agent.

        Returns:
            Stored agent.
        """
        response = await self._client.request("GET", f"/api/v1/agents/{agent_id}")
        return AgentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent.AgentResponse&#x22;">
    Stored agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[AgentResponse]&#x22;">
  List agents.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: AgentListParams | None = None,
    ) -> Page[AgentResponse]:
        """List agents.

        Args:
            params: Agent list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of agents.
        """
        params = params or AgentListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/agents",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[AgentResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AgentListParams | None&#x22;" value="&#x22;None&#x22;">
      Agent list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of agents.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[AgentResponse]&#x22;">
  Iterate over all agents.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: AgentListParams | None = None,
    ) -> AsyncIterator[AgentResponse]:
        """Iterate over all agents.

        Args:
            params: Agent list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every agent.
        """
        async for item in iterate_pages(params or AgentListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AgentListParams | None&#x22;" value="&#x22;None&#x22;">
      Agent list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, agent_id, request) -> AgentResponse&#x22;">
  Update an agent.

  <PySourceCode>
    ```python
    async def update(
        self, agent_id: uuid.UUID, request: AgentUpdateRequest
    ) -> AgentResponse:
        """Update an agent.

        Args:
            agent_id: Id of the agent.
            request: Agent update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing agent.

        Returns:
            Updated agent.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/agents/{agent_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return AgentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AgentUpdateRequest&#x22;" value="undefined">
      Agent update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent.AgentResponse&#x22;">
    Updated agent.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, agent_id) -> None&#x22;">
  Delete an agent, hiding the agent and retaining its subtree.

  The agent's stored sessions, versions, cohorts, experiments, and
  investigations are retained and stay readable through their own
  resources. Creating new ones for the agent fails.

  <PySourceCode>
    ```python
    async def delete(self, agent_id: uuid.UUID) -> None:
        """Delete an agent, hiding the agent and retaining its subtree.

        The agent's stored sessions, versions, cohorts, experiments, and
        investigations are retained and stay readable through their own
        resources. Creating new ones for the agent fails.

        Args:
            agent_id: Id of the agent.

        Raises:
            APIError: The request failed, including 404 for a missing agent.
        """
        await self._client.request("DELETE", f"/api/v1/agents/{agent_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create_version&#x22;" type="&#x22;(self, agent_id, request, idempotency_key=None) -> AgentVersionResponse&#x22;">
  Create a new version of an agent.

  <PySourceCode>
    ```python
    async def create_version(
        self,
        agent_id: uuid.UUID,
        request: AgentVersionCreateRequest,
        idempotency_key: str | None = None,
    ) -> AgentVersionResponse:
        """Create a new version of an agent.

        Args:
            agent_id: Id of the agent.
            request: Agent version create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing agent.

        Returns:
            Created agent version.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/agents/{agent_id}/versions",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return AgentVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AgentVersionCreateRequest&#x22;" value="undefined">
      Agent version create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.agent_version.AgentVersionResponse&#x22;">
    Created agent version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_versions&#x22;" type="&#x22;(self, agent_id, params=None) -> Page[AgentVersionResponse]&#x22;">
  List the versions of an agent.

  <PySourceCode>
    ```python
    async def list_versions(
        self, agent_id: uuid.UUID, params: AgentVersionListParams | None = None
    ) -> Page[AgentVersionResponse]:
        """List the versions of an agent.

        Args:
            agent_id: Id of the agent.
            params: Agent version list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of agent versions.
        """
        params = params or AgentVersionListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/agents/{agent_id}/versions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[AgentVersionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AgentVersionListParams | None&#x22;" value="&#x22;None&#x22;">
      Agent version list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of agent versions.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_versions&#x22;" type="&#x22;(self, agent_id, params=None) -> AsyncIterator[AgentVersionResponse]&#x22;">
  Iterate over every version of an agent.

  <PySourceCode>
    ```python
    async def iter_versions(
        self, agent_id: uuid.UUID, params: AgentVersionListParams | None = None
    ) -> AsyncIterator[AgentVersionResponse]:
        """Iterate over every version of an agent.

        Args:
            agent_id: Id of the agent.
            params: Agent version list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every version of the agent.
        """
        async for item in iterate_pages(
            params or AgentVersionListParams(),
            lambda page_params: self.list_versions(agent_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the agent.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AgentVersionListParams | None&#x22;" value="&#x22;None&#x22;">
      Agent version list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every version of the agent.
  </PyFunctionReturn>
</PyFunction>


# AnalyzersResource



Analyzer API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> AnalyzerResponse&#x22;">
  Create an analyzer.

  <PySourceCode>
    ```python
    async def create(
        self, request: AnalyzerCreateRequest, idempotency_key: str | None = None
    ) -> AnalyzerResponse:
        """Create an analyzer.

        Args:
            request: Analyzer create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 409 for a duplicate name.

        Returns:
            Created analyzer.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/analyzers",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return AnalyzerResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AnalyzerCreateRequest&#x22;" value="undefined">
      Analyzer create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerResponse&#x22;">
    Created analyzer.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, analyzer_id) -> AnalyzerResponse&#x22;">
  Get an analyzer by id.

  <PySourceCode>
    ```python
    async def get(self, analyzer_id: uuid.UUID) -> AnalyzerResponse:
        """Get an analyzer by id.

        Args:
            analyzer_id: Id of the analyzer.

        Raises:
            APIError: The request failed, including 404 for a missing
                analyzer.

        Returns:
            Stored analyzer.
        """
        response = await self._client.request("GET", f"/api/v1/analyzers/{analyzer_id}")
        return AnalyzerResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerResponse&#x22;">
    Stored analyzer.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[AnalyzerResponse]&#x22;">
  List analyzers.

  <PySourceCode>
    ```python
    async def list(
        self, params: AnalyzerListParams | None = None
    ) -> Page[AnalyzerResponse]:
        """List analyzers.

        Args:
            params: Analyzer list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of analyzers.
        """
        params = params or AnalyzerListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/analyzers",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[AnalyzerResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AnalyzerListParams | None&#x22;" value="&#x22;None&#x22;">
      Analyzer list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of analyzers.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[AnalyzerResponse]&#x22;">
  Iterate over all analyzers.

  <PySourceCode>
    ```python
    async def iter(
        self, params: AnalyzerListParams | None = None
    ) -> AsyncIterator[AnalyzerResponse]:
        """Iterate over all analyzers.

        Args:
            params: Analyzer list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every analyzer.
        """
        async for item in iterate_pages(params or AnalyzerListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;AnalyzerListParams | None&#x22;" value="&#x22;None&#x22;">
      Analyzer list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every analyzer.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, analyzer_id, request) -> AnalyzerResponse&#x22;">
  Update an analyzer.

  <PySourceCode>
    ```python
    async def update(
        self, analyzer_id: uuid.UUID, request: AnalyzerUpdateRequest
    ) -> AnalyzerResponse:
        """Update an analyzer.

        Args:
            analyzer_id: Id of the analyzer.
            request: Analyzer update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                analyzer.

        Returns:
            Updated analyzer.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/analyzers/{analyzer_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return AnalyzerResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AnalyzerUpdateRequest&#x22;" value="undefined">
      Analyzer update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerResponse&#x22;">
    Updated analyzer.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, analyzer_id) -> None&#x22;">
  Delete an analyzer, cascading its versions.

  <PySourceCode>
    ```python
    async def delete(self, analyzer_id: uuid.UUID) -> None:
        """Delete an analyzer, cascading its versions.

        Args:
            analyzer_id: Id of the analyzer.

        Raises:
            APIError: The request failed, including 404 for a missing
                analyzer.
        """
        await self._client.request("DELETE", f"/api/v1/analyzers/{analyzer_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create_version&#x22;" type="&#x22;(self, analyzer_id, request, idempotency_key=None) -> AnalyzerVersionResponse&#x22;">
  Create an analyzer version.

  <PySourceCode>
    ```python
    async def create_version(
        self,
        analyzer_id: uuid.UUID,
        request: AnalyzerVersionCreateRequest,
        idempotency_key: str | None = None,
    ) -> AnalyzerVersionResponse:
        """Create an analyzer version.

        Args:
            analyzer_id: Id of the analyzer.
            request: Analyzer version create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing
                analyzer or blob.

        Returns:
            Created analyzer version.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/analyzers/{analyzer_id}/versions",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return AnalyzerVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AnalyzerVersionCreateRequest&#x22;" value="undefined">
      Analyzer version create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerVersionResponse&#x22;">
    Created analyzer version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_versions&#x22;" type="&#x22;(self, analyzer_id, params=None) -> Page[AnalyzerVersionResponse]&#x22;">
  List an analyzer's versions.

  <PySourceCode>
    ```python
    async def list_versions(
        self, analyzer_id: uuid.UUID, params: ListParams | None = None
    ) -> Page[AnalyzerVersionResponse]:
        """List an analyzer's versions.

        Args:
            analyzer_id: Id of the analyzer.
            params: List params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of analyzer versions.
        """
        params = params or ListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/analyzers/{analyzer_id}/versions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[AnalyzerVersionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ListParams | None&#x22;" value="&#x22;None&#x22;">
      List params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of analyzer versions.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_versions&#x22;" type="&#x22;(self, analyzer_id, params=None) -> AsyncIterator[AnalyzerVersionResponse]&#x22;">
  Iterate over all of an analyzer's versions.

  <PySourceCode>
    ```python
    async def iter_versions(
        self, analyzer_id: uuid.UUID, params: ListParams | None = None
    ) -> AsyncIterator[AnalyzerVersionResponse]:
        """Iterate over all of an analyzer's versions.

        Args:
            analyzer_id: Id of the analyzer.
            params: List params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every analyzer version.
        """
        async for item in iterate_pages(
            params or ListParams(),
            lambda page_params: self.list_versions(analyzer_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ListParams | None&#x22;" value="&#x22;None&#x22;">
      List params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every analyzer version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_version&#x22;" type="&#x22;(self, analyzer_id, version) -> AnalyzerVersionResponse&#x22;">
  Get an analyzer version by version number.

  <PySourceCode>
    ```python
    async def get_version(
        self, analyzer_id: uuid.UUID, version: int
    ) -> AnalyzerVersionResponse:
        """Get an analyzer version by version number.

        Args:
            analyzer_id: Id of the analyzer.
            version: Version number.

        Raises:
            APIError: The request failed, including 404 for a missing
                version.

        Returns:
            Stored analyzer version.
        """
        response = await self._client.request(
            "GET", f"/api/v1/analyzers/{analyzer_id}/versions/{version}"
        )
        return AnalyzerVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="undefined">
      Version number.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerVersionResponse&#x22;">
    Stored analyzer version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update_version&#x22;" type="&#x22;(self, analyzer_id, version, request) -> AnalyzerVersionResponse&#x22;">
  Update an analyzer version's display version.

  <PySourceCode>
    ```python
    async def update_version(
        self,
        analyzer_id: uuid.UUID,
        version: int,
        request: AnalyzerVersionUpdateRequest,
    ) -> AnalyzerVersionResponse:
        """Update an analyzer version's display version.

        Args:
            analyzer_id: Id of the analyzer.
            version: Version number.
            request: Analyzer version update request, unset fields stay
                unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                version.

        Returns:
            Updated analyzer version.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/analyzers/{analyzer_id}/versions/{version}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return AnalyzerVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the analyzer.
    </PyParameter>

    <PyParameter name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="undefined">
      Version number.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;AnalyzerVersionUpdateRequest&#x22;" value="undefined">
      Analyzer version update request, unset fields stay
      unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.analyzer.AnalyzerVersionResponse&#x22;">
    Updated analyzer version.
  </PyFunctionReturn>
</PyFunction>


# CohortVersionsResource



Cohort version API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, cohort_version_id) -> CohortVersionResponse&#x22;">
  Get a cohort version by id.

  <PySourceCode>
    ```python
    async def get(self, cohort_version_id: uuid.UUID) -> CohortVersionResponse:
        """Get a cohort version by id.

        Args:
            cohort_version_id: Id of the cohort version.

        Raises:
            APIError: The request failed, including 404 for a missing cohort
                version.

        Returns:
            Stored cohort version.
        """
        response = await self._client.request(
            "GET", f"/api/v1/cohort-versions/{cohort_version_id}"
        )
        return CohortVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort version.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort_version.CohortVersionResponse&#x22;">
    Stored cohort version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, cohort_version_id, request) -> CohortVersionResponse&#x22;">
  Update a cohort version.

  <PySourceCode>
    ```python
    async def update(
        self, cohort_version_id: uuid.UUID, request: CohortVersionUpdateRequest
    ) -> CohortVersionResponse:
        """Update a cohort version.

        Args:
            cohort_version_id: Id of the cohort version.
            request: Cohort version update request, unset fields stay
                unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing cohort
                version.

        Returns:
            Updated cohort version.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/cohort-versions/{cohort_version_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return CohortVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort version.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;CohortVersionUpdateRequest&#x22;" value="undefined">
      Cohort version update request, unset fields stay
      unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort_version.CohortVersionResponse&#x22;">
    Updated cohort version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, cohort_version_id) -> None&#x22;">
  Delete a cohort version.

  <PySourceCode>
    ```python
    async def delete(self, cohort_version_id: uuid.UUID) -> None:
        """Delete a cohort version.

        Args:
            cohort_version_id: Id of the cohort version.

        Raises:
            APIError: The request failed, including 404 for a missing cohort
                version.
        """
        await self._client.request(
            "DELETE", f"/api/v1/cohort-versions/{cohort_version_id}"
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort version.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# CohortsResource



Cohort API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> CohortResponse&#x22;">
  Create a cohort.

  <PySourceCode>
    ```python
    async def create(
        self, request: CohortCreateRequest, idempotency_key: str | None = None
    ) -> CohortResponse:
        """Create a cohort.

        Args:
            request: Cohort create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 when the agent does
                not exist, 409 for a duplicate name, and 422 for an invalid
                or mismatched member list.

        Returns:
            Created cohort.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/cohorts",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return CohortResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;CohortCreateRequest&#x22;" value="undefined">
      Cohort create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort.CohortResponse&#x22;">
    Created cohort.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, cohort_id) -> CohortResponse&#x22;">
  Get a cohort by id.

  <PySourceCode>
    ```python
    async def get(self, cohort_id: uuid.UUID) -> CohortResponse:
        """Get a cohort by id.

        Args:
            cohort_id: Id of the cohort.

        Raises:
            APIError: The request failed, including 404 for a missing
                cohort.

        Returns:
            Stored cohort.
        """
        response = await self._client.request("GET", f"/api/v1/cohorts/{cohort_id}")
        return CohortResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort.CohortResponse&#x22;">
    Stored cohort.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[CohortResponse]&#x22;">
  List cohorts.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: CohortListParams | None = None,
    ) -> Page[CohortResponse]:
        """List cohorts.

        Args:
            params: Cohort list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of cohorts.
        """
        params = params or CohortListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/cohorts",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[CohortResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;CohortListParams | None&#x22;" value="&#x22;None&#x22;">
      Cohort list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of cohorts.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[CohortResponse]&#x22;">
  Iterate over all cohorts.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: CohortListParams | None = None,
    ) -> AsyncIterator[CohortResponse]:
        """Iterate over all cohorts.

        Args:
            params: Cohort list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every cohort.
        """
        async for item in iterate_pages(params or CohortListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;CohortListParams | None&#x22;" value="&#x22;None&#x22;">
      Cohort list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every cohort.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, cohort_id, request) -> CohortResponse&#x22;">
  Update a cohort's name and description.

  <PySourceCode>
    ```python
    async def update(
        self, cohort_id: uuid.UUID, request: CohortUpdateRequest
    ) -> CohortResponse:
        """Update a cohort's name and description.

        Args:
            cohort_id: Id of the cohort.
            request: Cohort update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                cohort.

        Returns:
            Updated cohort.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/cohorts/{cohort_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return CohortResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;CohortUpdateRequest&#x22;" value="undefined">
      Cohort update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort.CohortResponse&#x22;">
    Updated cohort.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, cohort_id) -> None&#x22;">
  Delete a cohort.

  <PySourceCode>
    ```python
    async def delete(self, cohort_id: uuid.UUID) -> None:
        """Delete a cohort.

        Args:
            cohort_id: Id of the cohort.

        Raises:
            APIError: The request failed, including 404 for a missing
                cohort and 409 when an experiment run references one of
                its versions.
        """
        await self._client.request("DELETE", f"/api/v1/cohorts/{cohort_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create_version&#x22;" type="&#x22;(self, cohort_id, request, idempotency_key=None) -> CohortVersionResponse&#x22;">
  Create a new version of a cohort.

  <PySourceCode>
    ```python
    async def create_version(
        self,
        cohort_id: uuid.UUID,
        request: CohortVersionCreateRequest,
        idempotency_key: str | None = None,
    ) -> CohortVersionResponse:
        """Create a new version of a cohort.

        Args:
            cohort_id: Id of the cohort.
            request: Cohort version create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing
                cohort or baseline version and 422 for an invalid or
                mismatched member list.

        Returns:
            Created cohort version.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/cohorts/{cohort_id}/versions",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return CohortVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;CohortVersionCreateRequest&#x22;" value="undefined">
      Cohort version create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.cohort_version.CohortVersionResponse&#x22;">
    Created cohort version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_versions&#x22;" type="&#x22;(self, cohort_id, params=None) -> Page[CohortVersionResponse]&#x22;">
  List the versions of a cohort.

  <PySourceCode>
    ```python
    async def list_versions(
        self, cohort_id: uuid.UUID, params: CohortVersionListParams | None = None
    ) -> Page[CohortVersionResponse]:
        """List the versions of a cohort.

        Args:
            cohort_id: Id of the cohort.
            params: Cohort version list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of cohort versions.
        """
        params = params or CohortVersionListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/cohorts/{cohort_id}/versions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[CohortVersionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;CohortVersionListParams | None&#x22;" value="&#x22;None&#x22;">
      Cohort version list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of cohort versions.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_versions&#x22;" type="&#x22;(self, cohort_id, params=None) -> AsyncIterator[CohortVersionResponse]&#x22;">
  Iterate over every version of a cohort.

  <PySourceCode>
    ```python
    async def iter_versions(
        self, cohort_id: uuid.UUID, params: CohortVersionListParams | None = None
    ) -> AsyncIterator[CohortVersionResponse]:
        """Iterate over every version of a cohort.

        Args:
            cohort_id: Id of the cohort.
            params: Cohort version list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every version of the cohort.
        """
        async for item in iterate_pages(
            params or CohortVersionListParams(),
            lambda page_params: self.list_versions(cohort_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the cohort.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;CohortVersionListParams | None&#x22;" value="&#x22;None&#x22;">
      Cohort version list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every version of the cohort.
  </PyFunctionReturn>
</PyFunction>


# EvaluationsResource



Evaluation API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> JobResponse&#x22;">
  Score every input session with every evaluator.

  <PySourceCode>
    ```python
    async def create(
        self, request: EvaluationBatchCreateRequest, idempotency_key: str | None = None
    ) -> JobResponse:
        """Score every input session with every evaluator.

        Args:
            request: Evaluation batch create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 422 when the pair count
                exceeds the cap or an input session does not exist.

        Returns:
            Created job.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/evaluations",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return JobResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;EvaluationBatchCreateRequest&#x22;" value="undefined">
      Evaluation batch create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.job.JobResponse&#x22;">
    Created job.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, evaluation_id) -> EvaluationResponse&#x22;">
  Get an evaluation by id.

  <PySourceCode>
    ```python
    async def get(self, evaluation_id: uuid.UUID) -> EvaluationResponse:
        """Get an evaluation by id.

        Args:
            evaluation_id: Id of the evaluation.

        Raises:
            APIError: The request failed, including 404 for a missing
                evaluation.

        Returns:
            Stored evaluation.
        """
        response = await self._client.request(
            "GET", f"/api/v1/evaluations/{evaluation_id}"
        )
        return EvaluationResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluation.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluation.EvaluationResponse&#x22;">
    Stored evaluation.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[EvaluationResponse]&#x22;">
  List evaluations.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: EvaluationListParams | None = None,
    ) -> Page[EvaluationResponse]:
        """List evaluations.

        Args:
            params: Evaluation list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of evaluations.
        """
        params = params or EvaluationListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/evaluations",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[EvaluationResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;EvaluationListParams | None&#x22;" value="&#x22;None&#x22;">
      Evaluation list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of evaluations.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[EvaluationResponse]&#x22;">
  Iterate over all evaluations.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: EvaluationListParams | None = None,
    ) -> AsyncIterator[EvaluationResponse]:
        """Iterate over all evaluations.

        Args:
            params: Evaluation list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every evaluation.
        """
        async for item in iterate_pages(params or EvaluationListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;EvaluationListParams | None&#x22;" value="&#x22;None&#x22;">
      Evaluation list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every evaluation.
  </PyFunctionReturn>
</PyFunction>


# EvaluatorsResource



Evaluator API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> EvaluatorResponse&#x22;">
  Create an evaluator.

  <PySourceCode>
    ```python
    async def create(
        self, request: EvaluatorCreateRequest, idempotency_key: str | None = None
    ) -> EvaluatorResponse:
        """Create an evaluator.

        Args:
            request: Evaluator create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 409 for a duplicate name.

        Returns:
            Created evaluator.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/evaluators",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return EvaluatorResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;EvaluatorCreateRequest&#x22;" value="undefined">
      Evaluator create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorResponse&#x22;">
    Created evaluator.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, evaluator_id) -> EvaluatorResponse&#x22;">
  Get an evaluator by id.

  <PySourceCode>
    ```python
    async def get(self, evaluator_id: uuid.UUID) -> EvaluatorResponse:
        """Get an evaluator by id.

        Args:
            evaluator_id: Id of the evaluator.

        Raises:
            APIError: The request failed, including 404 for a missing
                evaluator.

        Returns:
            Stored evaluator.
        """
        response = await self._client.request(
            "GET", f"/api/v1/evaluators/{evaluator_id}"
        )
        return EvaluatorResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorResponse&#x22;">
    Stored evaluator.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[EvaluatorResponse]&#x22;">
  List evaluators.

  <PySourceCode>
    ```python
    async def list(
        self, params: EvaluatorListParams | None = None
    ) -> Page[EvaluatorResponse]:
        """List evaluators.

        Args:
            params: Evaluator list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of evaluators.
        """
        params = params or EvaluatorListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/evaluators",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[EvaluatorResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;EvaluatorListParams | None&#x22;" value="&#x22;None&#x22;">
      Evaluator list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of evaluators.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[EvaluatorResponse]&#x22;">
  Iterate over all evaluators.

  <PySourceCode>
    ```python
    async def iter(
        self, params: EvaluatorListParams | None = None
    ) -> AsyncIterator[EvaluatorResponse]:
        """Iterate over all evaluators.

        Args:
            params: Evaluator list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every evaluator.
        """
        async for item in iterate_pages(params or EvaluatorListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;EvaluatorListParams | None&#x22;" value="&#x22;None&#x22;">
      Evaluator list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every evaluator.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, evaluator_id, request) -> EvaluatorResponse&#x22;">
  Update an evaluator.

  <PySourceCode>
    ```python
    async def update(
        self, evaluator_id: uuid.UUID, request: EvaluatorUpdateRequest
    ) -> EvaluatorResponse:
        """Update an evaluator.

        Args:
            evaluator_id: Id of the evaluator.
            request: Evaluator update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                evaluator.

        Returns:
            Updated evaluator.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/evaluators/{evaluator_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return EvaluatorResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;EvaluatorUpdateRequest&#x22;" value="undefined">
      Evaluator update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorResponse&#x22;">
    Updated evaluator.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, evaluator_id) -> None&#x22;">
  Delete an evaluator, cascading its versions.

  <PySourceCode>
    ```python
    async def delete(self, evaluator_id: uuid.UUID) -> None:
        """Delete an evaluator, cascading its versions.

        Args:
            evaluator_id: Id of the evaluator.

        Raises:
            APIError: The request failed, including 404 for a missing
                evaluator.
        """
        await self._client.request("DELETE", f"/api/v1/evaluators/{evaluator_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create_version&#x22;" type="&#x22;(self, evaluator_id, request, idempotency_key=None) -> EvaluatorVersionResponse&#x22;">
  Create an evaluator version.

  <PySourceCode>
    ```python
    async def create_version(
        self,
        evaluator_id: uuid.UUID,
        request: EvaluatorVersionCreateRequest,
        idempotency_key: str | None = None,
    ) -> EvaluatorVersionResponse:
        """Create an evaluator version.

        Args:
            evaluator_id: Id of the evaluator.
            request: Evaluator version create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing
                evaluator or blob.

        Returns:
            Created evaluator version.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/evaluators/{evaluator_id}/versions",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return EvaluatorVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;EvaluatorVersionCreateRequest&#x22;" value="undefined">
      Evaluator version create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorVersionResponse&#x22;">
    Created evaluator version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_versions&#x22;" type="&#x22;(self, evaluator_id, params=None) -> Page[EvaluatorVersionResponse]&#x22;">
  List an evaluator's versions.

  <PySourceCode>
    ```python
    async def list_versions(
        self, evaluator_id: uuid.UUID, params: ListParams | None = None
    ) -> Page[EvaluatorVersionResponse]:
        """List an evaluator's versions.

        Args:
            evaluator_id: Id of the evaluator.
            params: List params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of evaluator versions.
        """
        params = params or ListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/evaluators/{evaluator_id}/versions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[EvaluatorVersionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ListParams | None&#x22;" value="&#x22;None&#x22;">
      List params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of evaluator versions.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_versions&#x22;" type="&#x22;(self, evaluator_id, params=None) -> AsyncIterator[EvaluatorVersionResponse]&#x22;">
  Iterate over all of an evaluator's versions.

  <PySourceCode>
    ```python
    async def iter_versions(
        self, evaluator_id: uuid.UUID, params: ListParams | None = None
    ) -> AsyncIterator[EvaluatorVersionResponse]:
        """Iterate over all of an evaluator's versions.

        Args:
            evaluator_id: Id of the evaluator.
            params: List params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every evaluator version.
        """
        async for item in iterate_pages(
            params or ListParams(),
            lambda page_params: self.list_versions(evaluator_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ListParams | None&#x22;" value="&#x22;None&#x22;">
      List params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every evaluator version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_version&#x22;" type="&#x22;(self, evaluator_id, version) -> EvaluatorVersionResponse&#x22;">
  Get an evaluator version by version number.

  <PySourceCode>
    ```python
    async def get_version(
        self, evaluator_id: uuid.UUID, version: int
    ) -> EvaluatorVersionResponse:
        """Get an evaluator version by version number.

        Args:
            evaluator_id: Id of the evaluator.
            version: Version number.

        Raises:
            APIError: The request failed, including 404 for a missing
                version.

        Returns:
            Stored evaluator version.
        """
        response = await self._client.request(
            "GET", f"/api/v1/evaluators/{evaluator_id}/versions/{version}"
        )
        return EvaluatorVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="undefined">
      Version number.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorVersionResponse&#x22;">
    Stored evaluator version.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update_version&#x22;" type="&#x22;(self, evaluator_id, version, request) -> EvaluatorVersionResponse&#x22;">
  Update an evaluator version's display version.

  <PySourceCode>
    ```python
    async def update_version(
        self,
        evaluator_id: uuid.UUID,
        version: int,
        request: EvaluatorVersionUpdateRequest,
    ) -> EvaluatorVersionResponse:
        """Update an evaluator version's display version.

        Args:
            evaluator_id: Id of the evaluator.
            version: Version number.
            request: Evaluator version update request, unset fields stay
                unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                version.

        Returns:
            Updated evaluator version.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/evaluators/{evaluator_id}/versions/{version}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return EvaluatorVersionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the evaluator.
    </PyParameter>

    <PyParameter name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="undefined">
      Version number.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;EvaluatorVersionUpdateRequest&#x22;" value="undefined">
      Evaluator version update request, unset fields stay
      unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.evaluator.EvaluatorVersionResponse&#x22;">
    Updated evaluator version.
  </PyFunctionReturn>
</PyFunction>


# ExperimentRunsResource



Experiment run API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, experiment_run_id) -> ExperimentRunResponse&#x22;">
  Get an experiment run by id.

  <PySourceCode>
    ```python
    async def get(self, experiment_run_id: uuid.UUID) -> ExperimentRunResponse:
        """Get an experiment run by id.

        Args:
            experiment_run_id: Id of the run.

        Raises:
            APIError: The request failed, including 404 for a missing run.

        Returns:
            Stored experiment run.
        """
        response = await self._client.request(
            "GET", f"/api/v1/experiment-runs/{experiment_run_id}"
        )
        return ExperimentRunResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the run.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Stored experiment run.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[ExperimentRunResponse]&#x22;">
  List experiment runs.

  <PySourceCode>
    ```python
    async def list(
        self, params: ExperimentRunListParams | None = None
    ) -> Page[ExperimentRunResponse]:
        """List experiment runs.

        Args:
            params: Experiment run list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of experiment runs.
        """
        params = params or ExperimentRunListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/experiment-runs",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[ExperimentRunResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentRunListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment run list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of experiment runs.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[ExperimentRunResponse]&#x22;">
  Iterate over all experiment runs.

  <PySourceCode>
    ```python
    async def iter(
        self, params: ExperimentRunListParams | None = None
    ) -> AsyncIterator[ExperimentRunResponse]:
        """Iterate over all experiment runs.

        Args:
            params: Experiment run list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every experiment run.
        """
        async for item in iterate_pages(params or ExperimentRunListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentRunListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment run list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every experiment run.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, experiment_run_id) -> None&#x22;">
  Delete an experiment run and its jobs.

  <PySourceCode>
    ```python
    async def delete(self, experiment_run_id: uuid.UUID) -> None:
        """Delete an experiment run and its jobs.

        Args:
            experiment_run_id: Id of the run.

        Raises:
            APIError: The request failed, including 404 for a missing run.
        """
        await self._client.request(
            "DELETE", f"/api/v1/experiment-runs/{experiment_run_id}"
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the run.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;list_jobs&#x22;" type="&#x22;(self, experiment_run_id, params=None) -> Page[JobResponse]&#x22;">
  List the jobs backing an experiment run's replays.

  <PySourceCode>
    ```python
    async def list_jobs(
        self,
        experiment_run_id: uuid.UUID,
        params: ExperimentRunJobsListParams | None = None,
    ) -> Page[JobResponse]:
        """List the jobs backing an experiment run's replays.

        Args:
            experiment_run_id: Id of the run.
            params: Experiment run jobs list params.

        Raises:
            APIError: The request failed, including 404 for a missing run.

        Returns:
            Page of jobs.
        """
        params = params or ExperimentRunJobsListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/experiment-runs/{experiment_run_id}/jobs",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[JobResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the run.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentRunJobsListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment run jobs list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of jobs.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_jobs&#x22;" type="&#x22;(self, experiment_run_id, params=None) -> AsyncIterator[JobResponse]&#x22;">
  Iterate over all jobs backing an experiment run's replays.

  <PySourceCode>
    ```python
    async def iter_jobs(
        self,
        experiment_run_id: uuid.UUID,
        params: ExperimentRunJobsListParams | None = None,
    ) -> AsyncIterator[JobResponse]:
        """Iterate over all jobs backing an experiment run's replays.

        Args:
            experiment_run_id: Id of the run.
            params: Experiment run jobs list params.

        Raises:
            APIError: The request failed, including 404 for a missing run.

        Returns:
            Async iterator over every job of the run.
        """
        async for item in iterate_pages(
            params or ExperimentRunJobsListParams(),
            lambda page_params: self.list_jobs(experiment_run_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the run.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentRunJobsListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment run jobs list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every job of the run.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;cancel&#x22;" type="&#x22;(self, experiment_run_id) -> ExperimentRunResponse&#x22;">
  Request cancellation of a running experiment run.

  <PySourceCode>
    ```python
    async def cancel(self, experiment_run_id: uuid.UUID) -> ExperimentRunResponse:
        """Request cancellation of a running experiment run.

        Args:
            experiment_run_id: Id of the run.

        Raises:
            APIError: The request failed, including 404 for a missing run
                and 409 when the run is not running.

        Returns:
            Run carrying the cancel request.
        """
        response = await self._client.request(
            "POST", f"/api/v1/experiment-runs/{experiment_run_id}/cancel"
        )
        return ExperimentRunResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the run.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Run carrying the cancel request.
  </PyFunctionReturn>
</PyFunction>


# ExperimentsResource



Experiment API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> ExperimentResponse&#x22;">
  Create an experiment.

  <PySourceCode>
    ```python
    async def create(
        self, request: ExperimentCreateRequest, idempotency_key: str | None = None
    ) -> ExperimentResponse:
        """Create an experiment.

        Args:
            request: Experiment create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 when the agent does
                not exist or an evaluator name or version is unknown, and
                409 for a duplicate name.

        Returns:
            Created experiment.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/experiments",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return ExperimentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;ExperimentCreateRequest&#x22;" value="undefined">
      Experiment create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment.ExperimentResponse&#x22;">
    Created experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, experiment_id) -> ExperimentResponse&#x22;">
  Get an experiment by id.

  <PySourceCode>
    ```python
    async def get(self, experiment_id: uuid.UUID) -> ExperimentResponse:
        """Get an experiment by id.

        Args:
            experiment_id: Id of the experiment.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment.

        Returns:
            Stored experiment.
        """
        response = await self._client.request(
            "GET", f"/api/v1/experiments/{experiment_id}"
        )
        return ExperimentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment.ExperimentResponse&#x22;">
    Stored experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[ExperimentResponse]&#x22;">
  List experiments.

  <PySourceCode>
    ```python
    async def list(
        self, params: ExperimentListParams | None = None
    ) -> Page[ExperimentResponse]:
        """List experiments.

        Args:
            params: Experiment list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of experiments.
        """
        params = params or ExperimentListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/experiments",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[ExperimentResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of experiments.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[ExperimentResponse]&#x22;">
  Iterate over all experiments.

  <PySourceCode>
    ```python
    async def iter(
        self, params: ExperimentListParams | None = None
    ) -> AsyncIterator[ExperimentResponse]:
        """Iterate over all experiments.

        Args:
            params: Experiment list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every experiment.
        """
        async for item in iterate_pages(params or ExperimentListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ExperimentListParams | None&#x22;" value="&#x22;None&#x22;">
      Experiment list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, experiment_id, request) -> ExperimentResponse&#x22;">
  Update an experiment.

  <PySourceCode>
    ```python
    async def update(
        self, experiment_id: uuid.UUID, request: ExperimentUpdateRequest
    ) -> ExperimentResponse:
        """Update an experiment.

        Args:
            experiment_id: Id of the experiment.
            request: Experiment update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment or an unknown evaluator name or version.

        Returns:
            Updated experiment.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/experiments/{experiment_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return ExperimentResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;ExperimentUpdateRequest&#x22;" value="undefined">
      Experiment update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment.ExperimentResponse&#x22;">
    Updated experiment.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, experiment_id) -> None&#x22;">
  Delete an experiment.

  <PySourceCode>
    ```python
    async def delete(self, experiment_id: uuid.UUID) -> None:
        """Delete an experiment.

        Args:
            experiment_id: Id of the experiment.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment.
        """
        await self._client.request("DELETE", f"/api/v1/experiments/{experiment_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;start_run&#x22;" type="&#x22;(self, experiment_id, request, idempotency_key=None) -> ExperimentRunResponse&#x22;">
  Start an experiment run, fanning out one replay per cohort version session.

  <PySourceCode>
    ```python
    async def start_run(
        self,
        experiment_id: uuid.UUID,
        request: ExperimentRunCreateRequest,
        idempotency_key: str | None = None,
    ) -> ExperimentRunResponse:
        """Start an experiment run, fanning out one replay per cohort version session.

        Args:
            experiment_id: Id of the experiment.
            request: Experiment run create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing
                experiment, cohort version, or agent version, and 422 for an
                empty or mismatched cohort version, a mismatched agent
                version, or a missing agent version resolution.

        Returns:
            Created run.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/experiments/{experiment_id}/runs",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return ExperimentRunResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;experiment_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the experiment.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;ExperimentRunCreateRequest&#x22;" value="undefined">
      Experiment run create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.experiment_run.ExperimentRunResponse&#x22;">
    Created run.
  </PyFunctionReturn>
</PyFunction>


# InsightsResource



Insight API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, agent_id, insights, idempotency_key=None) -> list[InsightResponse]&#x22;">
  Create a batch of insights for one agent in one shot.

  <PySourceCode>
    ```python
    async def create(
        self,
        agent_id: uuid.UUID,
        insights: list[InsightInput],
        idempotency_key: str | None = None,
    ) -> list[InsightResponse]:
        """Create a batch of insights for one agent in one shot.

        Args:
            agent_id: Agent the insights belong to.
            insights: Insights to create, in input order.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 when the agent does
                not exist.

        Returns:
            Created insights in input order.
        """
        request = InsightBatchCreateRequest(agent_id=agent_id, insights=insights)
        response = await self._client.request(
            "POST",
            "/api/v1/insights",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return [InsightResponse.model_validate(item) for item in response.json()]
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Agent the insights belong to.
    </PyParameter>

    <PyParameter name="&#x22;insights&#x22;" type="&#x22;list[InsightInput]&#x22;" value="undefined">
      Insights to create, in input order.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;list&#x22;">
    Created insights in input order.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, insight_id) -> InsightResponse&#x22;">
  Get an insight by id.

  <PySourceCode>
    ```python
    async def get(self, insight_id: uuid.UUID) -> InsightResponse:
        """Get an insight by id.

        Args:
            insight_id: Id of the insight.

        Raises:
            APIError: The request failed, including 404 for a missing
                insight.

        Returns:
            Stored insight.
        """
        response = await self._client.request("GET", f"/api/v1/insights/{insight_id}")
        return InsightResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;insight_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the insight.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.insight.InsightResponse&#x22;">
    Stored insight.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[InsightResponse]&#x22;">
  List insights.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: InsightListParams | None = None,
    ) -> Page[InsightResponse]:
        """List insights.

        Args:
            params: Insight list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of insights.
        """
        params = params or InsightListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/insights",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[InsightResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InsightListParams | None&#x22;" value="&#x22;None&#x22;">
      Insight list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of insights.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[InsightResponse]&#x22;">
  Iterate over all insights.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: InsightListParams | None = None,
    ) -> AsyncIterator[InsightResponse]:
        """Iterate over all insights.

        Args:
            params: Insight list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every insight.
        """
        async for item in iterate_pages(params or InsightListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InsightListParams | None&#x22;" value="&#x22;None&#x22;">
      Insight list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every insight.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, insight_id, request) -> InsightResponse&#x22;">
  Update an insight's title and description.

  <PySourceCode>
    ```python
    async def update(
        self, insight_id: uuid.UUID, request: InsightUpdateRequest
    ) -> InsightResponse:
        """Update an insight's title and description.

        Args:
            insight_id: Id of the insight.
            request: Insight update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                insight.

        Returns:
            Updated insight.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/insights/{insight_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return InsightResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;insight_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the insight.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;InsightUpdateRequest&#x22;" value="undefined">
      Insight update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.insight.InsightResponse&#x22;">
    Updated insight.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, insight_id) -> None&#x22;">
  Delete an insight.

  <PySourceCode>
    ```python
    async def delete(self, insight_id: uuid.UUID) -> None:
        """Delete an insight.

        Args:
            insight_id: Id of the insight.

        Raises:
            APIError: The request failed, including 404 for a missing
                insight.
        """
        await self._client.request("DELETE", f"/api/v1/insights/{insight_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;insight_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the insight.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# InvestigationsResource



Investigation API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> InvestigationResponse&#x22;">
  Create an investigation with its sessions in one shot.

  <PySourceCode>
    ```python
    async def create(
        self,
        request: InvestigationCreateRequest,
        idempotency_key: str | None = None,
    ) -> InvestigationResponse:
        """Create an investigation with its sessions in one shot.

        Args:
            request: Investigation create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 when the agent or a
                session does not exist.

        Returns:
            Created investigation.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/investigations",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return InvestigationResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;InvestigationCreateRequest&#x22;" value="undefined">
      Investigation create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.investigation.InvestigationResponse&#x22;">
    Created investigation.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, investigation_id) -> InvestigationResponse&#x22;">
  Get an investigation by id.

  <PySourceCode>
    ```python
    async def get(self, investigation_id: uuid.UUID) -> InvestigationResponse:
        """Get an investigation by id.

        Args:
            investigation_id: Id of the investigation.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation.

        Returns:
            Stored investigation.
        """
        response = await self._client.request(
            "GET", f"/api/v1/investigations/{investigation_id}"
        )
        return InvestigationResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.investigation.InvestigationResponse&#x22;">
    Stored investigation.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[InvestigationResponse]&#x22;">
  List investigations.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: InvestigationListParams | None = None,
    ) -> Page[InvestigationResponse]:
        """List investigations.

        Args:
            params: Investigation list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of investigations.
        """
        params = params or InvestigationListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/investigations",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[InvestigationResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InvestigationListParams | None&#x22;" value="&#x22;None&#x22;">
      Investigation list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of investigations.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[InvestigationResponse]&#x22;">
  Iterate over all investigations.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: InvestigationListParams | None = None,
    ) -> AsyncIterator[InvestigationResponse]:
        """Iterate over all investigations.

        Args:
            params: Investigation list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every investigation.
        """
        async for item in iterate_pages(params or InvestigationListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InvestigationListParams | None&#x22;" value="&#x22;None&#x22;">
      Investigation list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every investigation.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, investigation_id, request) -> InvestigationResponse&#x22;">
  Update an investigation's name, description, and status.

  <PySourceCode>
    ```python
    async def update(
        self, investigation_id: uuid.UUID, request: InvestigationUpdateRequest
    ) -> InvestigationResponse:
        """Update an investigation's name, description, and status.

        Args:
            investigation_id: Id of the investigation.
            request: Investigation update request, unset fields stay
                unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation.

        Returns:
            Updated investigation.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/investigations/{investigation_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return InvestigationResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;InvestigationUpdateRequest&#x22;" value="undefined">
      Investigation update request, unset fields stay
      unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.investigation.InvestigationResponse&#x22;">
    Updated investigation.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, investigation_id) -> None&#x22;">
  Delete an investigation, cascading its sessions and answers.

  <PySourceCode>
    ```python
    async def delete(self, investigation_id: uuid.UUID) -> None:
        """Delete an investigation, cascading its sessions and answers.

        Args:
            investigation_id: Id of the investigation.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation.
        """
        await self._client.request(
            "DELETE", f"/api/v1/investigations/{investigation_id}"
        )
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;list_sessions&#x22;" type="&#x22;(self, investigation_id, params=None) -> Page[InvestigationSessionResponse]&#x22;">
  List the sessions of an investigation, ordered by position.

  <PySourceCode>
    ```python
    async def list_sessions(
        self,
        investigation_id: uuid.UUID,
        params: InvestigationSessionsListParams | None = None,
    ) -> Page[InvestigationSessionResponse]:
        """List the sessions of an investigation, ordered by position.

        Args:
            investigation_id: Id of the investigation.
            params: Investigation sessions list params.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation.

        Returns:
            Page of investigation sessions, ordered by position.
        """
        params = params or InvestigationSessionsListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/investigations/{investigation_id}/sessions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[InvestigationSessionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InvestigationSessionsListParams | None&#x22;" value="&#x22;None&#x22;">
      Investigation sessions list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of investigation sessions, ordered by position.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_sessions&#x22;" type="&#x22;(self, investigation_id, params=None) -> AsyncIterator[InvestigationSessionResponse]&#x22;">
  Iterate over all sessions of an investigation, ordered by position.

  <PySourceCode>
    ```python
    async def iter_sessions(
        self,
        investigation_id: uuid.UUID,
        params: InvestigationSessionsListParams | None = None,
    ) -> AsyncIterator[InvestigationSessionResponse]:
        """Iterate over all sessions of an investigation, ordered by position.

        Args:
            investigation_id: Id of the investigation.
            params: Investigation sessions list params.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation.

        Returns:
            Async iterator over every session of the investigation, ordered
            by position.
        """
        async for item in iterate_pages(
            params or InvestigationSessionsListParams(),
            lambda page_params: self.list_sessions(investigation_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;InvestigationSessionsListParams | None&#x22;" value="&#x22;None&#x22;">
      Investigation sessions list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every session of the investigation, ordered
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update_session&#x22;" type="&#x22;(self, investigation_id, session_id, request) -> InvestigationSessionResponse&#x22;">
  Set or clear an investigation session's verdict.

  <PySourceCode>
    ```python
    async def update_session(
        self,
        investigation_id: uuid.UUID,
        session_id: uuid.UUID,
        request: InvestigationSessionUpdateRequest,
    ) -> InvestigationSessionResponse:
        """Set or clear an investigation session's verdict.

        Args:
            investigation_id: Id of the investigation.
            session_id: Id of the session.
            request: Investigation session update request.

        Raises:
            APIError: The request failed, including 404 for a missing
                investigation session.

        Returns:
            Updated investigation session.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/investigations/{investigation_id}/sessions/{session_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return InvestigationSessionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the investigation.
    </PyParameter>

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;InvestigationSessionUpdateRequest&#x22;" value="undefined">
      Investigation session update request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.investigation.InvestigationSessionResponse&#x22;">
    Updated investigation session.
  </PyFunctionReturn>
</PyFunction>


# JobsResource



Job API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, job_id) -> JobResponse&#x22;">
  Get a job by id.

  <PySourceCode>
    ```python
    async def get(self, job_id: uuid.UUID) -> JobResponse:
        """Get a job by id.

        Args:
            job_id: Id of the job.

        Raises:
            APIError: The request failed, including 404 for a missing job.

        Returns:
            Stored job.
        """
        response = await self._client.request("GET", f"/api/v1/jobs/{job_id}")
        return JobResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the job.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.job.JobResponse&#x22;">
    Stored job.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[JobResponse]&#x22;">
  List jobs.

  <PySourceCode>
    ```python
    async def list(self, params: JobListParams | None = None) -> Page[JobResponse]:
        """List jobs.

        Args:
            params: Job list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of jobs.
        """
        params = params or JobListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/jobs",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[JobResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;JobListParams | None&#x22;" value="&#x22;None&#x22;">
      Job list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of jobs.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[JobResponse]&#x22;">
  Iterate over all jobs.

  <PySourceCode>
    ```python
    async def iter(
        self, params: JobListParams | None = None
    ) -> AsyncIterator[JobResponse]:
        """Iterate over all jobs.

        Args:
            params: Job list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every job.
        """
        async for item in iterate_pages(params or JobListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;JobListParams | None&#x22;" value="&#x22;None&#x22;">
      Job list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every job.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list_tasks&#x22;" type="&#x22;(self, job_id, params=None) -> Page[TaskResponse]&#x22;">
  List the tasks of a job.

  <PySourceCode>
    ```python
    async def list_tasks(
        self, job_id: uuid.UUID, params: JobTasksListParams | None = None
    ) -> Page[TaskResponse]:
        """List the tasks of a job.

        Args:
            job_id: Id of the job.
            params: Job tasks list params.

        Raises:
            APIError: The request failed, including 404 for a missing job.

        Returns:
            Page of tasks.
        """
        params = params or JobTasksListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/jobs/{job_id}/tasks",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[TaskResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the job.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;JobTasksListParams | None&#x22;" value="&#x22;None&#x22;">
      Job tasks list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of tasks.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_tasks&#x22;" type="&#x22;(self, job_id, params=None) -> AsyncIterator[TaskResponse]&#x22;">
  Iterate over all tasks of a job.

  <PySourceCode>
    ```python
    async def iter_tasks(
        self, job_id: uuid.UUID, params: JobTasksListParams | None = None
    ) -> AsyncIterator[TaskResponse]:
        """Iterate over all tasks of a job.

        Args:
            job_id: Id of the job.
            params: Job tasks list params.

        Raises:
            APIError: The request failed, including 404 for a missing job.

        Returns:
            Async iterator over every task of the job.
        """
        async for item in iterate_pages(
            params or JobTasksListParams(),
            lambda page_params: self.list_tasks(job_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the job.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;JobTasksListParams | None&#x22;" value="&#x22;None&#x22;">
      Job tasks list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every task of the job.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;cancel&#x22;" type="&#x22;(self, job_id) -> JobResponse&#x22;">
  Request cancellation of a job.

  <PySourceCode>
    ```python
    async def cancel(self, job_id: uuid.UUID) -> JobResponse:
        """Request cancellation of a job.

        Args:
            job_id: Id of the job.

        Raises:
            APIError: The request failed, including 409 for a settled job.

        Returns:
            Job carrying the cancel request.
        """
        response = await self._client.request("POST", f"/api/v1/jobs/{job_id}/cancel")
        return JobResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the job.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.job.JobResponse&#x22;">
    Job carrying the cancel request.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, job_id) -> None&#x22;">
  Delete a settled job, cascading its tasks.

  <PySourceCode>
    ```python
    async def delete(self, job_id: uuid.UUID) -> None:
        """Delete a settled job, cascading its tasks.

        Args:
            job_id: Id of the job.

        Raises:
            APIError: The request failed, including 404 for a missing job
                and 409 for a job that has not settled.
        """
        await self._client.request("DELETE", f"/api/v1/jobs/{job_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the job.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>


# ReplaysResource



Replay API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> ReplayResponse&#x22;">
  Create a standalone replay of a recorded or imported session.

  <PySourceCode>
    ```python
    async def create(
        self, request: ReplayCreateRequest, idempotency_key: str | None = None
    ) -> ReplayResponse:
        """Create a standalone replay of a recorded or imported session.

        Args:
            request: Replay create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 404 for a missing
                baseline session, agent version, or evaluator, and 422 for
                a missing agent version resolution or an invalid tool
                policy.

        Returns:
            Created replay.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/replays",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return ReplayResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;ReplayCreateRequest&#x22;" value="undefined">
      Replay create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Created replay.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, replay_id) -> ReplayResponse&#x22;">
  Get a replay by id.

  <PySourceCode>
    ```python
    async def get(self, replay_id: uuid.UUID) -> ReplayResponse:
        """Get a replay by id.

        Args:
            replay_id: Id of the replay.

        Raises:
            APIError: The request failed, including 404 for a missing
                replay.

        Returns:
            Stored replay.
        """
        response = await self._client.request("GET", f"/api/v1/replays/{replay_id}")
        return ReplayResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ReplayResponse&#x22;">
    Stored replay.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[ReplayResponse]&#x22;">
  List replays.

  <PySourceCode>
    ```python
    async def list(
        self, params: ReplayListParams | None = None
    ) -> Page[ReplayResponse]:
        """List replays.

        Args:
            params: Replay list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of replays.
        """
        params = params or ReplayListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/replays",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[ReplayResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ReplayListParams | None&#x22;" value="&#x22;None&#x22;">
      Replay list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of replays.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[ReplayResponse]&#x22;">
  Iterate over all replays.

  <PySourceCode>
    ```python
    async def iter(
        self, params: ReplayListParams | None = None
    ) -> AsyncIterator[ReplayResponse]:
        """Iterate over all replays.

        Args:
            params: Replay list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every replay.
        """
        async for item in iterate_pages(params or ReplayListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;ReplayListParams | None&#x22;" value="&#x22;None&#x22;">
      Replay list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every replay.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, replay_id) -> None&#x22;">
  Delete a replay.

  <PySourceCode>
    ```python
    async def delete(self, replay_id: uuid.UUID) -> None:
        """Delete a replay.

        Args:
            replay_id: Id of the replay.

        Raises:
            APIError: The request failed, including 404 for a missing replay
                and 409 when the replay belongs to an experiment run.
        """
        await self._client.request("DELETE", f"/api/v1/replays/{replay_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;tool_lookup&#x22;" type="&#x22;(self, replay_id, request) -> ToolLookupResponse&#x22;">
  Search recorded tool-call history for a cached result.

  <PySourceCode>
    ```python
    async def tool_lookup(
        self, replay_id: uuid.UUID, request: ToolLookupRequest
    ) -> ToolLookupResponse:
        """Search recorded tool-call history for a cached result.

        Args:
            replay_id: Id of the replay.
            request: Tool lookup request.

        Raises:
            APIError: The request failed, including 404 for a missing
                replay and 422 for a tool not configured for history or an
                occurrence given for a non-baseline history scope.

        Returns:
            Matching recorded tool call, unset on a miss.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/replays/{replay_id}/tool-lookup",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return ToolLookupResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;replay_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the replay.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;ToolLookupRequest&#x22;" value="undefined">
      Tool lookup request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.replay.ToolLookupResponse&#x22;">
    Matching recorded tool call, unset on a miss.
  </PyFunctionReturn>
</PyFunction>


# SessionsResource



Session API methods.

## Functions [#functions]

<PyFunction name="&#x22;__init__&#x22;" type="&#x22;(self, client) -> None&#x22;">
  Initialize the resource.

  <PySourceCode>
    ```python
    def __init__(self, client: "KitaruAPIClient") -> None:
        """Initialize the resource.

        Args:
            client: API client used to send requests.
        """
        self._client = client
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;client&#x22;" type="&#x22;KitaruAPIClient&#x22;" value="undefined">
      API client used to send requests.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;create&#x22;" type="&#x22;(self, request, idempotency_key=None) -> SessionResponse&#x22;">
  Create a session.

  <PySourceCode>
    ```python
    async def create(
        self, request: SessionCreateRequest, idempotency_key: str | None = None
    ) -> SessionResponse:
        """Create a session.

        Args:
            request: Session create request.
            idempotency_key: Idempotency key overriding the transport's
                random default.

        Raises:
            APIError: The request failed, including 409 for a duplicate
                imported_from and external id pair.

        Returns:
            Created session.
        """
        response = await self._client.request(
            "POST",
            "/api/v1/sessions",
            json=request.model_dump(mode="json", exclude_unset=True),
            idempotency_key=idempotency_key,
        )
        return SessionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;request&#x22;" type="&#x22;SessionCreateRequest&#x22;" value="undefined">
      Session create request.
    </PyParameter>

    <PyParameter name="&#x22;idempotency_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;None&#x22;">
      Idempotency key overriding the transport's
      random default.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionResponse&#x22;">
    Created session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get&#x22;" type="&#x22;(self, session_id) -> SessionDetailResponse&#x22;">
  Get a session by id.

  <PySourceCode>
    ```python
    async def get(self, session_id: uuid.UUID) -> SessionDetailResponse:
        """Get a session by id.

        Args:
            session_id: Id of the session.

        Raises:
            APIError: The request failed, including 404 for a missing
                session.

        Returns:
            Stored session.
        """
        response = await self._client.request("GET", f"/api/v1/sessions/{session_id}")
        return SessionDetailResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionDetailResponse&#x22;">
    Stored session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;get_with_nodes&#x22;" type="&#x22;(self, session_id) -> SessionWithNodesResponse&#x22;">
  Get a session together with every one of its nodes.

  The node list is not paginated, so one call carries a whole session.

  <PySourceCode>
    ```python
    async def get_with_nodes(self, session_id: uuid.UUID) -> SessionWithNodesResponse:
        """Get a session together with every one of its nodes.

        The node list is not paginated, so one call carries a whole session.

        Args:
            session_id: Id of the session.

        Raises:
            APIError: The request failed, including 404 for a missing
                session.

        Returns:
            Session with every node, ordered by index.
        """
        response = await self._client.request(
            "GET", f"/api/v1/sessions/{session_id}/full"
        )
        return SessionWithNodesResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session_node.SessionWithNodesResponse&#x22;">
    Session with every node, ordered by index.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;ingest_nodes&#x22;" type="&#x22;(self, session_id, batch) -> list[SessionNodeResponse]&#x22;">
  Ingest a batch of session nodes.

  An index already stored is replaced whole.

  <PySourceCode>
    ```python
    async def ingest_nodes(
        self, session_id: uuid.UUID, batch: SessionNodeBatchRequest
    ) -> list[SessionNodeResponse]:
        """Ingest a batch of session nodes.

        An index already stored is replaced whole.

        Args:
            session_id: Id of the session to ingest into.
            batch: Session node batch request.

        Raises:
            APIError: The request failed, including 409 when the session
                does not currently accept node ingestion.

        Returns:
            Stored nodes in batch order.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/sessions/{session_id}/nodes",
            json=batch.model_dump(mode="json", exclude_unset=True),
        )
        return [SessionNodeResponse.model_validate(item) for item in response.json()]
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session to ingest into.
    </PyParameter>

    <PyParameter name="&#x22;batch&#x22;" type="&#x22;SessionNodeBatchRequest&#x22;" value="undefined">
      Session node batch request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;list&#x22;">
    Stored nodes in batch order.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;create_evaluations&#x22;" type="&#x22;(self, session_id, request) -> list[EvaluationResponse]&#x22;">
  Create manual evaluations on a session.

  <PySourceCode>
    ```python
    async def create_evaluations(
        self, session_id: uuid.UUID, request: SessionEvaluationsRequest
    ) -> list[EvaluationResponse]:
        """Create manual evaluations on a session.

        Args:
            session_id: Id of the session to create evaluations on.
            request: Session evaluations request.

        Raises:
            APIError: The request failed, including 404 for a missing
                session, 409 when an evaluation name already exists for the
                session, and 422 when the request names the same evaluation
                twice.

        Returns:
            Stored evaluations in request order.
        """
        response = await self._client.request(
            "POST",
            f"/api/v1/sessions/{session_id}/evaluations",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return [EvaluationResponse.model_validate(item) for item in response.json()]
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session to create evaluations on.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;SessionEvaluationsRequest&#x22;" value="undefined">
      Session evaluations request.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;list&#x22;">
    Stored evaluations in request order.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;list&#x22;" type="&#x22;(self, params=None) -> Page[SessionResponse] | Page[SessionDetailResponse]&#x22;">
  List sessions.

  <PySourceCode>
    ```python
    async def list(
        self,
        params: SessionListParams | None = None,
    ) -> Page[SessionResponse] | Page[SessionDetailResponse]:
        """List sessions.

        Args:
            params: Session list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of sessions, with payloads when include_payloads is set.
        """
        params = params or SessionListParams()
        response = await self._client.request(
            "GET",
            "/api/v1/sessions",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        if params.include_payloads:
            return Page[SessionDetailResponse].model_validate(response.json())
        return Page[SessionResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;SessionListParams | None&#x22;" value="&#x22;None&#x22;">
      Session list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;Page[SessionResponse] | Page[SessionDetailResponse]&#x22;">
    Page of sessions, with payloads when include\_payloads is set.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter&#x22;" type="&#x22;(self, params=None) -> AsyncIterator[SessionResponse]&#x22;">
  Iterate over all sessions.

  <PySourceCode>
    ```python
    async def iter(
        self,
        params: SessionListParams | None = None,
    ) -> AsyncIterator[SessionResponse]:
        """Iterate over all sessions.

        Args:
            params: Session list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every session.
        """
        async for item in iterate_pages(params or SessionListParams(), self.list):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;params&#x22;" type="&#x22;SessionListParams | None&#x22;" value="&#x22;None&#x22;">
      Session list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;update&#x22;" type="&#x22;(self, session_id, request) -> SessionResponse&#x22;">
  Update a session.

  <PySourceCode>
    ```python
    async def update(
        self, session_id: uuid.UUID, request: SessionUpdateRequest
    ) -> SessionResponse:
        """Update a session.

        Args:
            session_id: Id of the session.
            request: Session update request, unset fields stay unchanged.

        Raises:
            APIError: The request failed, including 404 for a missing
                session and 409 for an illegal status transition.

        Returns:
            Updated session.
        """
        response = await self._client.request(
            "PATCH",
            f"/api/v1/sessions/{session_id}",
            json=request.model_dump(mode="json", exclude_unset=True),
        )
        return SessionResponse.model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>

    <PyParameter name="&#x22;request&#x22;" type="&#x22;SessionUpdateRequest&#x22;" value="undefined">
      Session update request, unset fields stay unchanged.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.session.SessionResponse&#x22;">
    Updated session.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;delete&#x22;" type="&#x22;(self, session_id) -> None&#x22;">
  Delete a session.

  <PySourceCode>
    ```python
    async def delete(self, session_id: uuid.UUID) -> None:
        """Delete a session.

        Args:
            session_id: Id of the session.

        Raises:
            APIError: The request failed, including 404 for a missing
                session and 409 when the session is referenced by a
                cohort version, investigation, or replay.
        """
        await self._client.request("DELETE", f"/api/v1/sessions/{session_id}")
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;None&#x22;" />
</PyFunction>

<PyFunction name="&#x22;list_nodes&#x22;" type="&#x22;(self, session_id, params=None) -> Page[SessionNodeResponse]&#x22;">
  List the nodes of a session, ordered by index ascending.

  <PySourceCode>
    ```python
    async def list_nodes(
        self,
        session_id: uuid.UUID,
        params: SessionNodeListParams | None = None,
    ) -> Page[SessionNodeResponse]:
        """List the nodes of a session, ordered by index ascending.

        Args:
            session_id: Id of the session.
            params: Session node list params.

        Raises:
            APIError: The request failed.

        Returns:
            Page of session nodes, ordered by index.
        """
        params = params or SessionNodeListParams()
        response = await self._client.request(
            "GET",
            f"/api/v1/sessions/{session_id}/nodes",
            params=params.model_dump(mode="json", exclude_unset=True),
        )
        return Page[SessionNodeResponse].model_validate(response.json())
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;SessionNodeListParams | None&#x22;" value="&#x22;None&#x22;">
      Session node list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.base.Page&#x22;">
    Page of session nodes, ordered by index.
  </PyFunctionReturn>
</PyFunction>

<PyFunction name="&#x22;iter_nodes&#x22;" type="&#x22;(self, session_id, params=None) -> AsyncIterator[SessionNodeResponse]&#x22;">
  Iterate over every node of a session, ordered by index ascending.

  <PySourceCode>
    ```python
    async def iter_nodes(
        self,
        session_id: uuid.UUID,
        params: SessionNodeListParams | None = None,
    ) -> AsyncIterator[SessionNodeResponse]:
        """Iterate over every node of a session, ordered by index ascending.

        Args:
            session_id: Id of the session.
            params: Session node list params.

        Raises:
            APIError: The request failed.

        Returns:
            Async iterator over every node of the session.
        """
        async for item in iterate_pages(
            params or SessionNodeListParams(),
            lambda page_params: self.list_nodes(session_id, page_params),
        ):
            yield item
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />

    <PyParameter name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="undefined">
      Id of the session.
    </PyParameter>

    <PyParameter name="&#x22;params&#x22;" type="&#x22;SessionNodeListParams | None&#x22;" value="&#x22;None&#x22;">
      Session node list params.
    </PyParameter>
  </div>

  <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator&#x22;">
    Async iterator over every node of the session.
  </PyFunctionReturn>
</PyFunction>


# resources



Resource method groups.

<Tabs items="[&#x22;Class&#x22;,&#x22;Functions&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AgentVersionsResource&#x22;" href="&#x22;/reference/python/client/resources/AgentVersionsResource&#x22;" />

      <Card title="&#x22;AgentsResource&#x22;" href="&#x22;/reference/python/client/resources/AgentsResource&#x22;" />

      <Card title="&#x22;AnalyzersResource&#x22;" href="&#x22;/reference/python/client/resources/AnalyzersResource&#x22;" />

      <Card title="&#x22;CohortVersionsResource&#x22;" href="&#x22;/reference/python/client/resources/CohortVersionsResource&#x22;" />

      <Card title="&#x22;CohortsResource&#x22;" href="&#x22;/reference/python/client/resources/CohortsResource&#x22;" />

      <Card title="&#x22;EvaluationsResource&#x22;" href="&#x22;/reference/python/client/resources/EvaluationsResource&#x22;" />

      <Card title="&#x22;EvaluatorsResource&#x22;" href="&#x22;/reference/python/client/resources/EvaluatorsResource&#x22;" />

      <Card title="&#x22;ExperimentRunsResource&#x22;" href="&#x22;/reference/python/client/resources/ExperimentRunsResource&#x22;" />

      <Card title="&#x22;ExperimentsResource&#x22;" href="&#x22;/reference/python/client/resources/ExperimentsResource&#x22;" />

      <Card title="&#x22;InsightsResource&#x22;" href="&#x22;/reference/python/client/resources/InsightsResource&#x22;" />

      <Card title="&#x22;InvestigationsResource&#x22;" href="&#x22;/reference/python/client/resources/InvestigationsResource&#x22;" />

      <Card title="&#x22;JobsResource&#x22;" href="&#x22;/reference/python/client/resources/JobsResource&#x22;" />

      <Card title="&#x22;ReplaysResource&#x22;" href="&#x22;/reference/python/client/resources/ReplaysResource&#x22;" />

      <Card title="&#x22;SessionsResource&#x22;" href="&#x22;/reference/python/client/resources/SessionsResource&#x22;" />
    </Cards>
  </Tab>

  <Tab value="&#x22;Functions&#x22;">
    <PyFunction name="&#x22;iterate_pages&#x22;" type="&#x22;(params, load_page) -> AsyncIterator[ItemT]&#x22;">
      Yield every item while following opaque page cursors.

      <PySourceCode>
        ```python
        async def iterate_pages(
            params: ParamsT,
            load_page: Callable[[ParamsT], Awaitable[Page[ItemT]]],
        ) -> AsyncIterator[ItemT]:
            """Yield every item while following opaque page cursors."""
            while True:
                page = await load_page(params)
                for item in page.items:
                    yield item
                if page.next_cursor is None:
                    return
                params = params.model_copy(update={"cursor": page.next_cursor})
        ```
      </PySourceCode>

      <div>
        <PyParameter name="&#x22;params&#x22;" type="&#x22;ParamsT&#x22;" value="null" />

        <PyParameter name="&#x22;load_page&#x22;" type="&#x22;Callable[[ParamsT], Awaitable[Page[ItemT]]]&#x22;" value="null" />
      </div>

      <PyFunctionReturn type="&#x22;collections.abc.AsyncIterator[kitaru.client.resources.pagination.ItemT]&#x22;" />
    </PyFunction>
  </Tab>
</Tabs>


# AgentCreateRequest



Agent create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Agent name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Agent description.')&#x22;" />


# AgentListParams



Agent list params.


# AgentResponse



Agent response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent id.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Agent name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Agent description.')&#x22;" />

<PyAttribute name="&#x22;latest_version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Highest version number created for this agent.')&#x22;" />


# AgentUpdateRequest



Agent update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New agent name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New agent description.')&#x22;" />


# agent



Agent API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AgentCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/agent/AgentCreateRequest&#x22;" />

      <Card title="&#x22;AgentListParams&#x22;" href="&#x22;/reference/python/api_models/v1/agent/AgentListParams&#x22;" />

      <Card title="&#x22;AgentResponse&#x22;" href="&#x22;/reference/python/api_models/v1/agent/AgentResponse&#x22;" />

      <Card title="&#x22;AgentUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/agent/AgentUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AnnotationListParams



Annotation list params.


# AnnotationResponse



Annotation response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Annotation id.')&#x22;" />

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session being annotated.')&#x22;" />

<PyAttribute name="&#x22;investigation_session_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Investigation session being answered.')&#x22;" />

<PyAttribute name="&#x22;question_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Key of the question being answered.')&#x22;" />

<PyAttribute name="&#x22;selector&#x22;" type="&#x22;AnnotationSelector | None&#x22;" value="&#x22;Field(default=None, description='Part of the session being annotated.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(description='Annotation value.')&#x22;" />


# AnnotationSelector



Annotation selector.

## Attributes [#attributes]

<PyAttribute name="&#x22;node_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Targeted node.')&#x22;" />

<PyAttribute name="&#x22;path&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer into the targeted node or the session response.')&#x22;" />

<PyAttribute name="&#x22;span&#x22;" type="&#x22;AnnotationSpan | None&#x22;" value="&#x22;Field(default=None, description='Character range within the resolved string.')&#x22;" />


# AnnotationSpan



Annotation span.

## Attributes [#attributes]

<PyAttribute name="&#x22;start&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(ge=0, description='Start offset of the character range.')&#x22;" />

<PyAttribute name="&#x22;end&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(ge=0, description='End offset of the character range.')&#x22;" />


# AnnotationUpdateRequest



Annotation update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;value&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(description='New annotation value.')&#x22;" />


# InvestigationAnswerCreateRequest



Investigation answer create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;investigation_session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Investigation session being answered.')&#x22;" />

<PyAttribute name="&#x22;question_key&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Key of the question being answered.')&#x22;" />

<PyAttribute name="&#x22;selector&#x22;" type="&#x22;AnnotationSelector | None&#x22;" value="&#x22;Field(default=None, description='Part of the session being annotated.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(description='Annotation value.')&#x22;" />


# ManualAnnotationCreateRequest



Manual annotation create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session being annotated.')&#x22;" />

<PyAttribute name="&#x22;selector&#x22;" type="&#x22;AnnotationSelector | None&#x22;" value="&#x22;Field(default=None, description='Part of the session being annotated.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(description='Annotation value.')&#x22;" />


# annotation



Annotation API models.

<PyAttribute name="&#x22;AnnotationCreateRequest&#x22;" type="null" value="&#x22;ManualAnnotationCreateRequest | InvestigationAnswerCreateRequest&#x22;" />

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AnnotationListParams&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/AnnotationListParams&#x22;" />

      <Card title="&#x22;AnnotationResponse&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/AnnotationResponse&#x22;" />

      <Card title="&#x22;AnnotationSelector&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/AnnotationSelector&#x22;" />

      <Card title="&#x22;AnnotationSpan&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/AnnotationSpan&#x22;" />

      <Card title="&#x22;AnnotationUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/AnnotationUpdateRequest&#x22;" />

      <Card title="&#x22;InvestigationAnswerCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/InvestigationAnswerCreateRequest&#x22;" />

      <Card title="&#x22;ManualAnnotationCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/annotation/ManualAnnotationCreateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AgentCapabilities



Agent capabilities.

## Attributes [#attributes]

<PyAttribute name="&#x22;tools&#x22;" type="&#x22;list[str]&#x22;" value="&#x22;Field(default_factory=list, description='Tools the agent exposes.')&#x22;" />

<PyAttribute name="&#x22;mcp_servers&#x22;" type="&#x22;list[str]&#x22;" value="&#x22;Field(default_factory=list, description='MCP servers the agent connects to.')&#x22;" />

<PyAttribute name="&#x22;skills&#x22;" type="&#x22;list[str]&#x22;" value="&#x22;Field(default_factory=list, description='Skills the agent exposes.')&#x22;" />


# AgentVersionCreateRequest



Agent version create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Version description.')&#x22;" />

<PyAttribute name="&#x22;run_spec&#x22;" type="&#x22;RunSpec | None&#x22;" value="&#x22;Field(default=None, description='Run spec.')&#x22;" />

<PyAttribute name="&#x22;capabilities&#x22;" type="&#x22;AgentCapabilities | None&#x22;" value="&#x22;Field(default=None, description='Agent capabilities.')&#x22;" />


# AgentVersionListParams



Agent version list params.


# AgentVersionResponse



Agent version response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent version id.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent this version belongs to.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Server-assigned version number.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Version description.')&#x22;" />

<PyAttribute name="&#x22;run_spec&#x22;" type="&#x22;RunSpec | None&#x22;" value="&#x22;Field(description='Run spec.')&#x22;" />

<PyAttribute name="&#x22;capabilities&#x22;" type="&#x22;AgentCapabilities&#x22;" value="&#x22;Field(description='Agent capabilities.')&#x22;" />


# AgentVersionUpdateRequest



Agent version update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New version description.')&#x22;" />

<PyAttribute name="&#x22;run_spec&#x22;" type="&#x22;RunSpec | None&#x22;" value="&#x22;Field(default=None, description='New run spec.')&#x22;" />

<PyAttribute name="&#x22;capabilities&#x22;" type="&#x22;AgentCapabilities | None&#x22;" value="&#x22;Field(default=None, description='New agent capabilities.')&#x22;" />


# RunSpec



Run spec.

## Attributes [#attributes]

<PyAttribute name="&#x22;command&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Shell command to run.')&#x22;" />

<PyAttribute name="&#x22;working_dir&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Working directory.')&#x22;" />

<PyAttribute name="&#x22;env&#x22;" type="&#x22;dict[str, str]&#x22;" value="&#x22;Field(default_factory=dict, description='Process environment.')&#x22;" />

<PyAttribute name="&#x22;secret_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="&#x22;Field(default_factory=list, description='Secrets merged into the process environment.')&#x22;" />

<PyAttribute name="&#x22;hooks&#x22;" type="&#x22;list[TaskHook]&#x22;" value="&#x22;Field(default_factory=list, description='Hooks run around the task process.')&#x22;" />

<PyAttribute name="&#x22;runtime_capabilities&#x22;" type="&#x22;RuntimeCapabilities&#x22;" value="&#x22;Field(default_factory=RuntimeCapabilities, description='Runtime capabilities.')&#x22;" />

<PyAttribute name="&#x22;timeout_seconds&#x22;" type="&#x22;PositiveInt&#x22;" value="&#x22;Field(default=3600, description='Process timeout.')&#x22;" />


# RuntimeCapabilities



Runtime capabilities.

## Attributes [#attributes]

<PyAttribute name="&#x22;overrides&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=True, description='Whether the runtime can apply replay overrides.')&#x22;" />

<PyAttribute name="&#x22;tool_policies&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=True, description='Whether the runtime can apply non-passthrough tool policies.')&#x22;" />


# agent_version



Agent version API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AgentCapabilities&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/AgentCapabilities&#x22;" />

      <Card title="&#x22;AgentVersionCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/AgentVersionCreateRequest&#x22;" />

      <Card title="&#x22;AgentVersionListParams&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/AgentVersionListParams&#x22;" />

      <Card title="&#x22;AgentVersionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/AgentVersionResponse&#x22;" />

      <Card title="&#x22;AgentVersionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/AgentVersionUpdateRequest&#x22;" />

      <Card title="&#x22;RunSpec&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/RunSpec&#x22;" />

      <Card title="&#x22;RuntimeCapabilities&#x22;" href="&#x22;/reference/python/api_models/v1/agent_version/RuntimeCapabilities&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AnalyzerCreateRequest



Analyzer create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Analyzer name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Analyzer description.')&#x22;" />

<PyAttribute name="&#x22;provider&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='External service this analyzer calls.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Analyzer logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;connection_schema&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='JSON Schema of the connection values this analyzer reads.')&#x22;" />


# AnalyzerListParams



Analyzer list params.


# AnalyzerResponse



Analyzer response.

## Attributes [#attributes]

<PyAttribute name="&#x22;owner_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(description='Id of the owning account, null for a default plugin.')&#x22;" />

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Analyzer id.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Analyzer name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Analyzer description.')&#x22;" />

<PyAttribute name="&#x22;provider&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='External service this analyzer calls.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Analyzer logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;connection_schema&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(description='JSON Schema of the connection values this analyzer reads.')&#x22;" />

<PyAttribute name="&#x22;latest_version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Highest version number created for this analyzer.')&#x22;" />


# AnalyzerUpdateRequest



Analyzer update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New analyzer description.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New metadata.')&#x22;" />

<PyAttribute name="&#x22;connection_schema&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New connection schema.')&#x22;" />


# AnalyzerVersionCreateRequest



Analyzer version create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;source&#x22;" type="&#x22;PluginSource&#x22;" value="&#x22;Field(description='Analyzer code to load.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Human-readable designator.')&#x22;" />


# AnalyzerVersionResponse



Analyzer version response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Analyzer version id.')&#x22;" />

<PyAttribute name="&#x22;analyzer_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Analyzer this version belongs to.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Server-assigned version number.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;source&#x22;" type="&#x22;PluginSource&#x22;" value="&#x22;Field(description='Analyzer code to load.')&#x22;" />


# AnalyzerVersionUpdateRequest



Analyzer version update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New human-readable designator.')&#x22;" />


# analyzer



Analyzer API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AnalyzerCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerCreateRequest&#x22;" />

      <Card title="&#x22;AnalyzerListParams&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerListParams&#x22;" />

      <Card title="&#x22;AnalyzerResponse&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerResponse&#x22;" />

      <Card title="&#x22;AnalyzerUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerUpdateRequest&#x22;" />

      <Card title="&#x22;AnalyzerVersionCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerVersionCreateRequest&#x22;" />

      <Card title="&#x22;AnalyzerVersionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerVersionResponse&#x22;" />

      <Card title="&#x22;AnalyzerVersionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/analyzer/AnalyzerVersionUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# CohortCreateRequest



Cohort create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Cohort name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Cohort description.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the cohort's sessions belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />


# CohortListParams



Cohort list params.


# CohortResponse



Cohort response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Cohort id.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Cohort name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Cohort description.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the cohort's sessions belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;latest_version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Highest version number created for this cohort.')&#x22;" />


# CohortUpdateRequest



Cohort update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New cohort name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New cohort description.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New metadata.')&#x22;" />


# cohort



Cohort API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;CohortCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/cohort/CohortCreateRequest&#x22;" />

      <Card title="&#x22;CohortListParams&#x22;" href="&#x22;/reference/python/api_models/v1/cohort/CohortListParams&#x22;" />

      <Card title="&#x22;CohortResponse&#x22;" href="&#x22;/reference/python/api_models/v1/cohort/CohortResponse&#x22;" />

      <Card title="&#x22;CohortUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/cohort/CohortUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# CohortVersionCreateRequest



Cohort version create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;baseline_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Version the delta applies to, None uses the latest version.')&#x22;" />

<PyAttribute name="&#x22;add_session_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="&#x22;Field(default_factory=list, description='Sessions to add to the new version.')&#x22;" />

<PyAttribute name="&#x22;remove_session_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="&#x22;Field(default_factory=list, description='Sessions to remove from the new version.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Human-readable designator.')&#x22;" />


# CohortVersionListParams



Cohort version list params.


# CohortVersionResponse



Cohort version response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Cohort version id.')&#x22;" />

<PyAttribute name="&#x22;cohort_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Cohort this version belongs to.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Server-assigned version number.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;session_count&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Number of sessions in the version.')&#x22;" />


# CohortVersionUpdateRequest



Cohort version update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New human-readable designator.')&#x22;" />


# cohort_version



Cohort version API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;CohortVersionCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/cohort_version/CohortVersionCreateRequest&#x22;" />

      <Card title="&#x22;CohortVersionListParams&#x22;" href="&#x22;/reference/python/api_models/v1/cohort_version/CohortVersionListParams&#x22;" />

      <Card title="&#x22;CohortVersionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/cohort_version/CohortVersionResponse&#x22;" />

      <Card title="&#x22;CohortVersionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/cohort_version/CohortVersionUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# EvaluationBatchCreateRequest



Evaluation batch create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;input_session_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="&#x22;Field(min_length=1, description='Sessions to score, all belonging to one agent.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(min_length=1, description='Evaluators run against every session.')&#x22;" />


# EvaluationDataType



Data type an evaluation result carries.

## Attributes [#attributes]

<PyAttribute name="&#x22;FLOAT&#x22;" type="null" value="&#x22;'float'&#x22;" />

<PyAttribute name="&#x22;BOOL&#x22;" type="null" value="&#x22;'bool'&#x22;" />

<PyAttribute name="&#x22;STR&#x22;" type="null" value="&#x22;'str'&#x22;" />

<PyAttribute name="&#x22;CATEGORICAL&#x22;" type="null" value="&#x22;'categorical'&#x22;" />


# EvaluationListParams



Evaluation list params.


# EvaluationResponse



Evaluation response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Evaluation id.')&#x22;" />

<PyAttribute name="&#x22;evaluator_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Evaluator version that produced the result.')&#x22;" />

<PyAttribute name="&#x22;evaluator_name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Name of the evaluator that produced the result.')&#x22;" />

<PyAttribute name="&#x22;evaluator_version&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Version of the evaluator that produced the result.')&#x22;" />

<PyAttribute name="&#x22;evaluator_params&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='Params the evaluator ran with.')&#x22;" />

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session being scored.')&#x22;" />

<PyAttribute name="&#x22;task_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Evaluator task that produced the result.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Evaluation name.')&#x22;" />

<PyAttribute name="&#x22;data_type&#x22;" type="&#x22;EvaluationDataType&#x22;" value="&#x22;Field(description='Data type of the result.')&#x22;" />

<PyAttribute name="&#x22;score&#x22;" type="&#x22;FiniteFloat | bool | None&#x22;" value="&#x22;Field(default=None, description='Numeric or boolean score.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Label or string value.')&#x22;" />

<PyAttribute name="&#x22;explanation&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Free-form explanation.')&#x22;" />

<PyAttribute name="&#x22;passed&#x22;" type="&#x22;bool | None&#x22;" value="&#x22;Field(default=None, description='Pass or fail verdict.')&#x22;" />

<PyAttribute name="&#x22;min_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Lower bound of the score scale.')&#x22;" />

<PyAttribute name="&#x22;max_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Upper bound of the score scale.')&#x22;" />

<PyAttribute name="&#x22;target_score&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Score to beat.')&#x22;" />


# evaluation



Evaluation API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;EvaluationBatchCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/evaluation/EvaluationBatchCreateRequest&#x22;" />

      <Card title="&#x22;EvaluationDataType&#x22;" href="&#x22;/reference/python/api_models/v1/evaluation/EvaluationDataType&#x22;" />

      <Card title="&#x22;EvaluationListParams&#x22;" href="&#x22;/reference/python/api_models/v1/evaluation/EvaluationListParams&#x22;" />

      <Card title="&#x22;EvaluationResponse&#x22;" href="&#x22;/reference/python/api_models/v1/evaluation/EvaluationResponse&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# EvaluatorCreateRequest



Evaluator create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Evaluator name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Evaluator description.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Evaluator logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Id of the agent this evaluator is scoped to, null for a global evaluator.')&#x22;" />


# EvaluatorListParams



Evaluator list params.


# EvaluatorResponse



Evaluator response.

## Attributes [#attributes]

<PyAttribute name="&#x22;owner_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(description='Id of the owning account, null for a default plugin.')&#x22;" />

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Evaluator id.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Evaluator name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Evaluator description.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Evaluator logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;latest_version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Highest version number created for this evaluator.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(description='Id of the agent this evaluator is scoped to, null for a global evaluator.')&#x22;" />


# EvaluatorUpdateRequest



Evaluator update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New evaluator description.')&#x22;" />

<PyAttribute name="&#x22;logo_url&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New logo URL.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New metadata.')&#x22;" />


# EvaluatorVersionCreateRequest



Evaluator version create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;source&#x22;" type="&#x22;PluginSource&#x22;" value="&#x22;Field(description='Evaluator code to load.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Human-readable designator.')&#x22;" />


# EvaluatorVersionResponse



Evaluator version response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Evaluator version id.')&#x22;" />

<PyAttribute name="&#x22;evaluator_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Evaluator this version belongs to.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Server-assigned version number.')&#x22;" />

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Human-readable designator.')&#x22;" />

<PyAttribute name="&#x22;source&#x22;" type="&#x22;PluginSource&#x22;" value="&#x22;Field(description='Evaluator code to load.')&#x22;" />


# EvaluatorVersionUpdateRequest



Evaluator version update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;display_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New human-readable designator.')&#x22;" />


# evaluator



Evaluator API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;EvaluatorCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorCreateRequest&#x22;" />

      <Card title="&#x22;EvaluatorListParams&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorListParams&#x22;" />

      <Card title="&#x22;EvaluatorResponse&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorResponse&#x22;" />

      <Card title="&#x22;EvaluatorUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorUpdateRequest&#x22;" />

      <Card title="&#x22;EvaluatorVersionCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorVersionCreateRequest&#x22;" />

      <Card title="&#x22;EvaluatorVersionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorVersionResponse&#x22;" />

      <Card title="&#x22;EvaluatorVersionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/evaluator/EvaluatorVersionUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# ExperimentCreateRequest



Experiment create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Experiment name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Experiment description.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the experiment's runs belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;Override applied to every run's replays.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;Tool policy applied to every run's replays.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(min_length=1, description=\&#x22;Evaluators run against every run's replays.\&#x22;)&#x22;" />


# ExperimentListParams



Experiment list params.


# ExperimentResponse



Experiment response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Experiment id.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Experiment name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Experiment description.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the experiment's runs belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;Field(description=\&#x22;Override applied to every run's replays.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy&#x22;" value="&#x22;Field(description=\&#x22;Tool policy applied to every run's replays.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(description=\&#x22;Evaluators run against every run's replays.\&#x22;)&#x22;" />


# ExperimentUpdateRequest



Experiment update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New experiment name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New experiment description.')&#x22;" />

<PyAttribute name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;Field(default=None, description='New override.')&#x22;" />

<PyAttribute name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy | None&#x22;" value="&#x22;Field(default=None, description='New tool policy.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig] | None&#x22;" value="&#x22;Field(default=None, description='New evaluators.')&#x22;" />


# experiment



Experiment API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;ExperimentCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/experiment/ExperimentCreateRequest&#x22;" />

      <Card title="&#x22;ExperimentListParams&#x22;" href="&#x22;/reference/python/api_models/v1/experiment/ExperimentListParams&#x22;" />

      <Card title="&#x22;ExperimentResponse&#x22;" href="&#x22;/reference/python/api_models/v1/experiment/ExperimentResponse&#x22;" />

      <Card title="&#x22;ExperimentUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/experiment/ExperimentUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# ExperimentRunCreateRequest



Experiment run create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Cohort version whose sessions are replayed.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent version to replay with.')&#x22;" />

<PyAttribute name="&#x22;evaluate_baselines&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=False, deprecated='Use baseline_evaluation_mode instead.', description='Whether to also score each baseline session.')&#x22;" />

<PyAttribute name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode | None&#x22;" value="&#x22;Field(default=None, description='How to score each baseline session.')&#x22;" />


# ExperimentRunJobsListParams



Experiment run jobs list params.


# ExperimentRunListParams



Experiment run list params.


# ExperimentRunProgress



Experiment run progress.

## Attributes [#attributes]

<PyAttribute name="&#x22;pending&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Replays pending.')&#x22;" />

<PyAttribute name="&#x22;evaluating&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Replays evaluating.')&#x22;" />

<PyAttribute name="&#x22;completed&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Replays completed.')&#x22;" />

<PyAttribute name="&#x22;failed&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Replays failed.')&#x22;" />

<PyAttribute name="&#x22;canceled&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Replays canceled.')&#x22;" />

<PyAttribute name="&#x22;total&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Total replays in the run.')&#x22;" />


# ExperimentRunResponse



Experiment run response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Experiment run id.')&#x22;" />

<PyAttribute name="&#x22;experiment_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Experiment this run belongs to.')&#x22;" />

<PyAttribute name="&#x22;number&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Run number within the experiment.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;ExperimentRunStatus&#x22;" value="&#x22;Field(description='Run status.')&#x22;" />

<PyAttribute name="&#x22;cohort_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Cohort version whose sessions are replayed.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent version to replay with.')&#x22;" />

<PyAttribute name="&#x22;evaluate_baselines&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(deprecated='Use baseline_evaluation_mode instead.', description='Whether baseline sessions are also scored.')&#x22;" />

<PyAttribute name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;Field(description='How baseline sessions are scored.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the run started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the run settled.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed run.')&#x22;" />

<PyAttribute name="&#x22;progress&#x22;" type="&#x22;ExperimentRunProgress&#x22;" value="&#x22;Field(description='Replay counts by status.')&#x22;" />


# ExperimentRunStatus



Experiment run status.

## Attributes [#attributes]

<PyAttribute name="&#x22;RUNNING&#x22;" type="null" value="&#x22;'running'&#x22;" />

<PyAttribute name="&#x22;CANCELING&#x22;" type="null" value="&#x22;'canceling'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />

<PyAttribute name="&#x22;FAILED&#x22;" type="null" value="&#x22;'failed'&#x22;" />

<PyAttribute name="&#x22;CANCELED&#x22;" type="null" value="&#x22;'canceled'&#x22;" />


# experiment_run



Experiment run API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;ExperimentRunCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunCreateRequest&#x22;" />

      <Card title="&#x22;ExperimentRunJobsListParams&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunJobsListParams&#x22;" />

      <Card title="&#x22;ExperimentRunListParams&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunListParams&#x22;" />

      <Card title="&#x22;ExperimentRunProgress&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunProgress&#x22;" />

      <Card title="&#x22;ExperimentRunResponse&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunResponse&#x22;" />

      <Card title="&#x22;ExperimentRunStatus&#x22;" href="&#x22;/reference/python/api_models/v1/experiment_run/ExperimentRunStatus&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AndFilter



And filter.

## Attributes [#attributes]

<PyAttribute name="&#x22;and_&#x22;" type="&#x22;list[Filter]&#x22;" value="&#x22;Field(alias='and', min_length=1, description='Operands.')&#x22;" />


# FilterCondition



Filter condition.

## Attributes [#attributes]

<PyAttribute name="&#x22;field&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(pattern='^[a-z][a-z0-9_]*$', description='Field to filter on.')&#x22;" />

<PyAttribute name="&#x22;op&#x22;" type="&#x22;FilterOp&#x22;" value="&#x22;Field(description='Comparison operator.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(default=None, description='Comparison value.')&#x22;" />


# FilterOp



Filter condition operator.

## Attributes [#attributes]

<PyAttribute name="&#x22;EQ&#x22;" type="null" value="&#x22;'eq'&#x22;" />

<PyAttribute name="&#x22;NE&#x22;" type="null" value="&#x22;'ne'&#x22;" />

<PyAttribute name="&#x22;LT&#x22;" type="null" value="&#x22;'lt'&#x22;" />

<PyAttribute name="&#x22;LE&#x22;" type="null" value="&#x22;'le'&#x22;" />

<PyAttribute name="&#x22;GT&#x22;" type="null" value="&#x22;'gt'&#x22;" />

<PyAttribute name="&#x22;GE&#x22;" type="null" value="&#x22;'ge'&#x22;" />

<PyAttribute name="&#x22;IN&#x22;" type="null" value="&#x22;'in'&#x22;" />

<PyAttribute name="&#x22;IS_NULL&#x22;" type="null" value="&#x22;'is_null'&#x22;" />

<PyAttribute name="&#x22;STARTSWITH&#x22;" type="null" value="&#x22;'startswith'&#x22;" />

<PyAttribute name="&#x22;ENDSWITH&#x22;" type="null" value="&#x22;'endswith'&#x22;" />

<PyAttribute name="&#x22;CONTAINS&#x22;" type="null" value="&#x22;'contains'&#x22;" />


# FilterableListParams



List params with a filter expression.

## Attributes [#attributes]

<PyAttribute name="&#x22;filter&#x22;" type="&#x22;FilterParam | None&#x22;" value="&#x22;Field(default=None, description='Filter expression, JSON-encoded in the query string.')&#x22;" />


# NotFilter



Not filter.

## Attributes [#attributes]

<PyAttribute name="&#x22;not_&#x22;" type="&#x22;Filter&#x22;" value="&#x22;Field(alias='not', description='Operand.')&#x22;" />


# OrFilter



Or filter.

## Attributes [#attributes]

<PyAttribute name="&#x22;or_&#x22;" type="&#x22;list[Filter]&#x22;" value="&#x22;Field(alias='or', min_length=1, description='Operands.')&#x22;" />


# filter



Filter API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AndFilter&#x22;" href="&#x22;/reference/python/api_models/v1/filter/AndFilter&#x22;" />

      <Card title="&#x22;FilterCondition&#x22;" href="&#x22;/reference/python/api_models/v1/filter/FilterCondition&#x22;" />

      <Card title="&#x22;FilterOp&#x22;" href="&#x22;/reference/python/api_models/v1/filter/FilterOp&#x22;" />

      <Card title="&#x22;FilterableListParams&#x22;" href="&#x22;/reference/python/api_models/v1/filter/FilterableListParams&#x22;" />

      <Card title="&#x22;NotFilter&#x22;" href="&#x22;/reference/python/api_models/v1/filter/NotFilter&#x22;" />

      <Card title="&#x22;OrFilter&#x22;" href="&#x22;/reference/python/api_models/v1/filter/OrFilter&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# ApiImportSource



API import source.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['api']&#x22;" value="&#x22;Field(default='api')&#x22;" />

<PyAttribute name="&#x22;query&#x22;" type="&#x22;ImportQuery&#x22;" value="&#x22;Field(description='Importer-defined selection of what to fetch.')&#x22;" />

<PyAttribute name="&#x22;connection_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;Connection supplying provider credentials, an omitted value resolves to the provider's default.\&#x22;)&#x22;" />


# BlobImportSource



Blob import source.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['blob']&#x22;" value="&#x22;Field(default='blob')&#x22;" />

<PyAttribute name="&#x22;blob_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Blob holding the payload to parse.')&#x22;" />


# ImportAnalyzeRequest



Import analyze request.

## Attributes [#attributes]

<PyAttribute name="&#x22;analyzers&#x22;" type="&#x22;list[AnalyzerConfig]&#x22;" value="&#x22;Field(min_length=1, description=\&#x22;Analyzers run across the import's sessions.\&#x22;)&#x22;" />


# ImportCreateRequest



Import create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;importer&#x22;" type="&#x22;PlainStr&#x22;" value="&#x22;Field(description='Importer name.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent imported sessions are created under.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Agent version recorded on the imported sessions.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Importer version, an omitted value resolves to latest.')&#x22;" />

<PyAttribute name="&#x22;source&#x22;" type="&#x22;ImportSource | None&#x22;" value="&#x22;Field(default=None, description='Where the payload comes from.')&#x22;" />

<PyAttribute name="&#x22;payload_blob_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, deprecated='Use source instead.', description='Blob holding the payload to parse.')&#x22;" />

<PyAttribute name="&#x22;params&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Parameters passed to the importer.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(default_factory=list, description='Evaluators run against every imported session.')&#x22;" />

<PyAttribute name="&#x22;analyzers&#x22;" type="&#x22;list[AnalyzerConfig]&#x22;" value="&#x22;Field(default_factory=list, description='Analyzers selected to run across the imported sessions.')&#x22;" />

<PyAttribute name="&#x22;max_sessions&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, ge=1, description='Maximum number of sessions created by the import.')&#x22;" />

## Functions [#functions]

<PyFunction name="&#x22;get_source&#x22;" type="&#x22;(self) -> ImportSource&#x22;">
  Return the import source, mapping the deprecated blob id to it.

  <PySourceCode>
    ```python
    def get_source(self) -> ImportSource:
        """Return the import source, mapping the deprecated blob id to it.

        Returns:
            Import source.
        """
        if self.source is not None:
            return self.source
        blob_id = self.payload_blob_id
        assert blob_id is not None
        return BlobImportSource(blob_id=blob_id)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;kitaru.api_models.v1.imports.ImportSource&#x22;">
    Import source.
  </PyFunctionReturn>
</PyFunction>


# ImportListParams



Import list params.


# ImportQuery



Import query.

## Attributes [#attributes]

<PyAttribute name="&#x22;trace_ids&#x22;" type="&#x22;list[str] | None&#x22;" value="&#x22;Field(default=None, description='Exact trace ids to fetch, instead of a time window.')&#x22;" />

<PyAttribute name="&#x22;since&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='Start of the time window to fetch.')&#x22;" />

<PyAttribute name="&#x22;until&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='End of the time window to fetch.')&#x22;" />

<PyAttribute name="&#x22;concurrency&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(default=DEFAULT_FETCH_CONCURRENCY, ge=1, description='Fetches the importer runs at once.')&#x22;" />

## Functions [#functions]

<PyFunction name="&#x22;get_window&#x22;" type="&#x22;(self) -> tuple[datetime, datetime]&#x22;">
  Return the time window, with until defaulting to now.

  <PySourceCode>
    ```python
    def get_window(self) -> tuple[datetime, datetime]:
        """Return the time window, with until defaulting to now.

        Returns:
            Window bounds.
        """
        assert self.since is not None
        return self.since, self.until or datetime.now(UTC)
    ```
  </PySourceCode>

  <div>
    <PyParameter name="&#x22;self&#x22;" type="null" value="null" />
  </div>

  <PyFunctionReturn type="&#x22;tuple&#x22;">
    Window bounds.
  </PyFunctionReturn>
</PyFunction>


# ImportResponse



Import response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Import id.')&#x22;" />

<PyAttribute name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Job running the import.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent imported sessions are created under.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Agent version recorded on the imported sessions.')&#x22;" />

<PyAttribute name="&#x22;importer_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Importer version run.')&#x22;" />

<PyAttribute name="&#x22;connection_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Connection resolved for the import.')&#x22;" />

<PyAttribute name="&#x22;source&#x22;" type="&#x22;ImportSource&#x22;" value="&#x22;Field(description='Where the payload comes from.')&#x22;" />

<PyAttribute name="&#x22;params&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Parameters passed to the importer.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(description='Evaluators run against every imported session.')&#x22;" />

<PyAttribute name="&#x22;analyzers&#x22;" type="&#x22;list[AnalyzerConfig]&#x22;" value="&#x22;Field(description='Analyzers run against every imported session.')&#x22;" />

<PyAttribute name="&#x22;max_sessions&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Maximum number of sessions created by the import.')&#x22;" />

<PyAttribute name="&#x22;stats&#x22;" type="&#x22;ImportStats | None&#x22;" value="&#x22;Field(default=None, description='Stats from a completed import.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed import.')&#x22;" />


# imports



Import API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;ApiImportSource&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ApiImportSource&#x22;" />

      <Card title="&#x22;BlobImportSource&#x22;" href="&#x22;/reference/python/api_models/v1/imports/BlobImportSource&#x22;" />

      <Card title="&#x22;ImportAnalyzeRequest&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ImportAnalyzeRequest&#x22;" />

      <Card title="&#x22;ImportCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ImportCreateRequest&#x22;" />

      <Card title="&#x22;ImportListParams&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ImportListParams&#x22;" />

      <Card title="&#x22;ImportQuery&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ImportQuery&#x22;" />

      <Card title="&#x22;ImportResponse&#x22;" href="&#x22;/reference/python/api_models/v1/imports/ImportResponse&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# Bin



Bin.

## Attributes [#attributes]

<PyAttribute name="&#x22;lower_bound&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Inclusive lower bound, None on an open-ended first bin.')&#x22;" />

<PyAttribute name="&#x22;upper_bound&#x22;" type="&#x22;FiniteFloat | None&#x22;" value="&#x22;Field(default=None, description='Exclusive upper bound, None on an open-ended last bin.')&#x22;" />

<PyAttribute name="&#x22;count&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(ge=0, description='Observations in the bin.')&#x22;" />


# BinnedInsightData



Binned insight data.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['binned']&#x22;" value="&#x22;Field(default='binned')&#x22;" />

<PyAttribute name="&#x22;unit&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Unit of the values.')&#x22;" />

<PyAttribute name="&#x22;bins&#x22;" type="&#x22;list[Bin]&#x22;" value="&#x22;Field(min_length=1, description='Bins, in ascending order.')&#x22;" />


# CategoricalInsightData



Categorical insight data.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['categorical']&#x22;" value="&#x22;Field(default='categorical')&#x22;" />

<PyAttribute name="&#x22;unit&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Unit of the values.')&#x22;" />

<PyAttribute name="&#x22;values&#x22;" type="&#x22;list[CategoryValue]&#x22;" value="&#x22;Field(min_length=1, description='Values per category.')&#x22;" />


# CategoryValue



Category value.

## Attributes [#attributes]

<PyAttribute name="&#x22;label&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Category label.')&#x22;" />

<PyAttribute name="&#x22;value&#x22;" type="&#x22;FiniteFloat&#x22;" value="&#x22;Field(ge=0, description='Measured value.')&#x22;" />


# InsightBatchCreateRequest



Insight batch create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent the insights belong to.')&#x22;" />

<PyAttribute name="&#x22;insights&#x22;" type="&#x22;list[InsightInput]&#x22;" value="&#x22;Field(min_length=1, max_length=MAX_INSIGHT_BATCH_SIZE, description='Insights to create, in input order.')&#x22;" />


# InsightListParams



Insight list params.


# InsightResponse



Insight response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Insight id.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent the insight belongs to.')&#x22;" />

<PyAttribute name="&#x22;import_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Import whose sessions produced the insight.')&#x22;" />

<PyAttribute name="&#x22;analyzer_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Analyzer version that produced the insight.')&#x22;" />

<PyAttribute name="&#x22;analyzer_params&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='Params the analyzer ran with.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Insight name.')&#x22;" />

<PyAttribute name="&#x22;title&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Insight title.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Insight description.')&#x22;" />

<PyAttribute name="&#x22;data&#x22;" type="&#x22;InsightData&#x22;" value="&#x22;Field(description='Insight data.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />


# InsightUpdateRequest



Insight update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;title&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New insight title.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New insight description.')&#x22;" />


# TextInsightData



Text insight data.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['text']&#x22;" value="&#x22;Field(default='text')&#x22;" />

<PyAttribute name="&#x22;content&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Markdown content.')&#x22;" />


# insight



Insight API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;Bin&#x22;" href="&#x22;/reference/python/api_models/v1/insight/Bin&#x22;" />

      <Card title="&#x22;BinnedInsightData&#x22;" href="&#x22;/reference/python/api_models/v1/insight/BinnedInsightData&#x22;" />

      <Card title="&#x22;CategoricalInsightData&#x22;" href="&#x22;/reference/python/api_models/v1/insight/CategoricalInsightData&#x22;" />

      <Card title="&#x22;CategoryValue&#x22;" href="&#x22;/reference/python/api_models/v1/insight/CategoryValue&#x22;" />

      <Card title="&#x22;InsightBatchCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/insight/InsightBatchCreateRequest&#x22;" />

      <Card title="&#x22;InsightInput&#x22;" href="&#x22;/reference/python/task/analyzer/InsightInput&#x22;" />

      <Card title="&#x22;InsightListParams&#x22;" href="&#x22;/reference/python/api_models/v1/insight/InsightListParams&#x22;" />

      <Card title="&#x22;InsightResponse&#x22;" href="&#x22;/reference/python/api_models/v1/insight/InsightResponse&#x22;" />

      <Card title="&#x22;InsightUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/insight/InsightUpdateRequest&#x22;" />

      <Card title="&#x22;TextInsightData&#x22;" href="&#x22;/reference/python/api_models/v1/insight/TextInsightData&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# InvestigationCreateRequest



Investigation create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the investigation's sessions belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Investigation name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Curator rationale.')&#x22;" />

<PyAttribute name="&#x22;sessions&#x22;" type="&#x22;list[InvestigationSessionInput]&#x22;" value="&#x22;Field(description='Sessions to investigate, in presentation order.')&#x22;" />


# InvestigationListParams



Investigation list params.


# InvestigationResponse



Investigation response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Investigation id.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description=\&#x22;Agent the investigation's sessions belong to.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Investigation name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Curator rationale.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;InvestigationStatus&#x22;" value="&#x22;Field(description='Investigation status.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the first answer was recorded.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the last session settled.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;total_sessions&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Number of linked sessions.')&#x22;" />

<PyAttribute name="&#x22;completed_sessions&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Number of linked sessions with a verdict.')&#x22;" />


# InvestigationSessionHighlight



Investigation session highlight.

## Attributes [#attributes]

<PyAttribute name="&#x22;selector&#x22;" type="&#x22;AnnotationSelector&#x22;" value="&#x22;Field(description='Part of the session highlighted.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Prose explaining what the highlight shows.')&#x22;" />


# InvestigationSessionInput



Investigation session input.

## Attributes [#attributes]

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session to link.')&#x22;" />

<PyAttribute name="&#x22;questions&#x22;" type="&#x22;list[InvestigationSessionQuestion]&#x22;" value="&#x22;Field(min_length=1, description='Questions to answer about the session.')&#x22;" />


# InvestigationSessionQuestion



Investigation session question.

## Attributes [#attributes]

<PyAttribute name="&#x22;key&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Question key, unique within the session.')&#x22;" />

<PyAttribute name="&#x22;question&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Question to answer about the session.')&#x22;" />

<PyAttribute name="&#x22;highlights&#x22;" type="&#x22;list[InvestigationSessionHighlight]&#x22;" value="&#x22;Field(default_factory=list, description='Curated highlights for the question.')&#x22;" />


# InvestigationSessionResponse



Investigation session response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Investigation session id.')&#x22;" />

<PyAttribute name="&#x22;investigation_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Investigation this session belongs to.')&#x22;" />

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session being investigated.')&#x22;" />

<PyAttribute name="&#x22;position&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Presentation order within the investigation.')&#x22;" />

<PyAttribute name="&#x22;questions&#x22;" type="&#x22;list[InvestigationSessionQuestion]&#x22;" value="&#x22;Field(description='Questions to answer about the session.')&#x22;" />

<PyAttribute name="&#x22;verdict&#x22;" type="&#x22;InvestigationSessionVerdict | None&#x22;" value="&#x22;Field(description='Investigation session verdict.')&#x22;" />


# InvestigationSessionUpdateRequest



Investigation session update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;verdict&#x22;" type="&#x22;InvestigationSessionVerdict | None&#x22;" value="&#x22;Field(description='New investigation session verdict, None clears it.')&#x22;" />


# InvestigationSessionVerdict



Investigation session verdict.

## Attributes [#attributes]

<PyAttribute name="&#x22;ACCEPTABLE&#x22;" type="null" value="&#x22;'acceptable'&#x22;" />

<PyAttribute name="&#x22;PROBLEMATIC&#x22;" type="null" value="&#x22;'problematic'&#x22;" />

<PyAttribute name="&#x22;UNCERTAIN&#x22;" type="null" value="&#x22;'uncertain'&#x22;" />


# InvestigationSessionsListParams



Investigation sessions list params.


# InvestigationStatus



Investigation status.

## Attributes [#attributes]

<PyAttribute name="&#x22;PENDING&#x22;" type="null" value="&#x22;'pending'&#x22;" />

<PyAttribute name="&#x22;IN_PROGRESS&#x22;" type="null" value="&#x22;'in_progress'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />


# InvestigationUpdateRequest



Investigation update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New investigation name.')&#x22;" />

<PyAttribute name="&#x22;description&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New curator rationale.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;InvestigationStatus | None&#x22;" value="&#x22;Field(default=None, description='New investigation status.')&#x22;" />


# investigation



Investigation and investigation session API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;InvestigationCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationCreateRequest&#x22;" />

      <Card title="&#x22;InvestigationListParams&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationListParams&#x22;" />

      <Card title="&#x22;InvestigationResponse&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationResponse&#x22;" />

      <Card title="&#x22;InvestigationSessionHighlight&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionHighlight&#x22;" />

      <Card title="&#x22;InvestigationSessionInput&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionInput&#x22;" />

      <Card title="&#x22;InvestigationSessionQuestion&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionQuestion&#x22;" />

      <Card title="&#x22;InvestigationSessionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionResponse&#x22;" />

      <Card title="&#x22;InvestigationSessionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionUpdateRequest&#x22;" />

      <Card title="&#x22;InvestigationSessionVerdict&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionVerdict&#x22;" />

      <Card title="&#x22;InvestigationSessionsListParams&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationSessionsListParams&#x22;" />

      <Card title="&#x22;InvestigationStatus&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationStatus&#x22;" />

      <Card title="&#x22;InvestigationUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/investigation/InvestigationUpdateRequest&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# JobKind



Job kind.

## Attributes [#attributes]

<PyAttribute name="&#x22;SESSION_RUN&#x22;" type="null" value="&#x22;'session_run'&#x22;" />

<PyAttribute name="&#x22;IMPORT&#x22;" type="null" value="&#x22;'import'&#x22;" />

<PyAttribute name="&#x22;EVALUATION&#x22;" type="null" value="&#x22;'evaluation'&#x22;" />

<PyAttribute name="&#x22;REPLAY&#x22;" type="null" value="&#x22;'replay'&#x22;" />

<PyAttribute name="&#x22;ANALYSIS&#x22;" type="null" value="&#x22;'analysis'&#x22;" />


# JobListParams



Job list params.


# JobResponse



Job response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Job id.')&#x22;" />

<PyAttribute name="&#x22;kind&#x22;" type="&#x22;JobKind&#x22;" value="&#x22;Field(description='Kind of workflow that created the job.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;JobStatus&#x22;" value="&#x22;Field(description='Job status.')&#x22;" />

<PyAttribute name="&#x22;cancel_requested_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time cancellation was requested.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the job started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the job settled.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;First counted task failure's error.\&#x22;)&#x22;" />


# JobStatus



Job status.

## Attributes [#attributes]

<PyAttribute name="&#x22;PENDING&#x22;" type="null" value="&#x22;'pending'&#x22;" />

<PyAttribute name="&#x22;RUNNING&#x22;" type="null" value="&#x22;'running'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />

<PyAttribute name="&#x22;FAILED&#x22;" type="null" value="&#x22;'failed'&#x22;" />

<PyAttribute name="&#x22;CANCELED&#x22;" type="null" value="&#x22;'canceled'&#x22;" />


# JobTasksListParams



Job tasks list params.


# job



Job API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;JobKind&#x22;" href="&#x22;/reference/python/api_models/v1/job/JobKind&#x22;" />

      <Card title="&#x22;JobListParams&#x22;" href="&#x22;/reference/python/api_models/v1/job/JobListParams&#x22;" />

      <Card title="&#x22;JobResponse&#x22;" href="&#x22;/reference/python/api_models/v1/job/JobResponse&#x22;" />

      <Card title="&#x22;JobStatus&#x22;" href="&#x22;/reference/python/api_models/v1/job/JobStatus&#x22;" />

      <Card title="&#x22;JobTasksListParams&#x22;" href="&#x22;/reference/python/api_models/v1/job/JobTasksListParams&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# BaselineEvaluationMode



Baseline evaluation mode.

## Attributes [#attributes]

<PyAttribute name="&#x22;NONE&#x22;" type="null" value="&#x22;'none'&#x22;" />

<PyAttribute name="&#x22;IF_MISSING&#x22;" type="null" value="&#x22;'if_missing'&#x22;" />

<PyAttribute name="&#x22;FORCE&#x22;" type="null" value="&#x22;'force'&#x22;" />


# ReplayCreateRequest



Replay create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;baseline_session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session to replay.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;Agent version to replay with, the baseline session's recorded version when unset.\&#x22;)&#x22;" />

<PyAttribute name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;Field(default=None, description='Override to apply.')&#x22;" />

<PyAttribute name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy | None&#x22;" value="&#x22;Field(default=None, description='Tool policy to apply.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(min_length=1, description='Evaluators run against the result session.')&#x22;" />

<PyAttribute name="&#x22;evaluate_baselines&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=False, deprecated='Use baseline_evaluation_mode instead.', description='Whether to also score the baseline session.')&#x22;" />

<PyAttribute name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode | None&#x22;" value="&#x22;Field(default=None, description='How to score the baseline session.')&#x22;" />


# ReplayListParams



Replay list params.


# ReplayResponse



Replay response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Replay id.')&#x22;" />

<PyAttribute name="&#x22;job_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Job running the replay.')&#x22;" />

<PyAttribute name="&#x22;experiment_run_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Experiment run this replay belongs to.')&#x22;" />

<PyAttribute name="&#x22;baseline_session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session replayed.')&#x22;" />

<PyAttribute name="&#x22;result_session_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Session produced by the replay.')&#x22;" />

<PyAttribute name="&#x22;override&#x22;" type="&#x22;ReplayOverride | None&#x22;" value="&#x22;Field(description='Override applied.')&#x22;" />

<PyAttribute name="&#x22;tool_policy&#x22;" type="&#x22;ToolPolicy&#x22;" value="&#x22;Field(description='Tool policy applied.')&#x22;" />

<PyAttribute name="&#x22;evaluators&#x22;" type="&#x22;list[EvaluatorConfig]&#x22;" value="&#x22;Field(description='Evaluators run against the result session.')&#x22;" />

<PyAttribute name="&#x22;evaluate_baselines&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(deprecated='Use baseline_evaluation_mode instead.', description='Whether the baseline session is also scored.')&#x22;" />

<PyAttribute name="&#x22;baseline_evaluation_mode&#x22;" type="&#x22;BaselineEvaluationMode&#x22;" value="&#x22;Field(description='How the baseline session is scored.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;ReplayStatus&#x22;" value="&#x22;Field(description='Replay status.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed replay.')&#x22;" />


# ReplayStatus



Replay status.

## Attributes [#attributes]

<PyAttribute name="&#x22;PENDING&#x22;" type="null" value="&#x22;'pending'&#x22;" />

<PyAttribute name="&#x22;EVALUATING&#x22;" type="null" value="&#x22;'evaluating'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />

<PyAttribute name="&#x22;FAILED&#x22;" type="null" value="&#x22;'failed'&#x22;" />

<PyAttribute name="&#x22;CANCELED&#x22;" type="null" value="&#x22;'canceled'&#x22;" />


# ToolLookupMatch



Tool lookup match.

## Attributes [#attributes]

<PyAttribute name="&#x22;result&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Cached tool result.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;NodeStatus&#x22;" value="&#x22;Field(description='Tool call status.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed tool call.')&#x22;" />


# ToolLookupRequest



Tool lookup request.

## Attributes [#attributes]

<PyAttribute name="&#x22;tool_name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Tool being called.')&#x22;" />

<PyAttribute name="&#x22;cache_key&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(min_length=64, max_length=64, description='Call cache key.')&#x22;" />

<PyAttribute name="&#x22;occurrence&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, ge=0, description='Zero-based match position in baseline order, the newest match when unset.')&#x22;" />


# ToolLookupResponse



Tool lookup response.

## Attributes [#attributes]

<PyAttribute name="&#x22;match&#x22;" type="&#x22;ToolLookupMatch | None&#x22;" value="&#x22;Field(default=None, description='Matching recorded tool call.')&#x22;" />


# replay



Replay API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;BaselineEvaluationMode&#x22;" href="&#x22;/reference/python/api_models/v1/replay/BaselineEvaluationMode&#x22;" />

      <Card title="&#x22;ReplayCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ReplayCreateRequest&#x22;" />

      <Card title="&#x22;ReplayListParams&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ReplayListParams&#x22;" />

      <Card title="&#x22;ReplayResponse&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ReplayResponse&#x22;" />

      <Card title="&#x22;ReplayStatus&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ReplayStatus&#x22;" />

      <Card title="&#x22;ToolLookupMatch&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ToolLookupMatch&#x22;" />

      <Card title="&#x22;ToolLookupRequest&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ToolLookupRequest&#x22;" />

      <Card title="&#x22;ToolLookupResponse&#x22;" href="&#x22;/reference/python/api_models/v1/replay/ToolLookupResponse&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# NodeStatus



Session node status.

## Attributes [#attributes]

<PyAttribute name="&#x22;IN_PROGRESS&#x22;" type="null" value="&#x22;'in_progress'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />

<PyAttribute name="&#x22;FAILED&#x22;" type="null" value="&#x22;'failed'&#x22;" />


# NodeType



Kind of work a session node records.

## Attributes [#attributes]

<PyAttribute name="&#x22;LLM_CALL&#x22;" type="null" value="&#x22;'llm_call'&#x22;" />

<PyAttribute name="&#x22;TOOL_CALL&#x22;" type="null" value="&#x22;'tool_call'&#x22;" />

<PyAttribute name="&#x22;SUBAGENT_CALL&#x22;" type="null" value="&#x22;'subagent_call'&#x22;" />

<PyAttribute name="&#x22;SPAN&#x22;" type="null" value="&#x22;'span'&#x22;" />


# SessionNodeBatchRequest



Session node batch request.

## Attributes [#attributes]

<PyAttribute name="&#x22;nodes&#x22;" type="&#x22;list[SessionNodeCreateRequest]&#x22;" value="&#x22;Field(max_length=500, description='Nodes to upsert, parent before child.')&#x22;" />


# SessionNodeCreateRequest



Session node create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;index&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(ge=0, description='Position within the session, the wire identity.')&#x22;" />

<PyAttribute name="&#x22;parent_index&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, ge=0, description='Index of the parent node.')&#x22;" />

<PyAttribute name="&#x22;secondary_parent_indexes&#x22;" type="&#x22;list[Annotated[int, Field(ge=0)]]&#x22;" value="&#x22;Field(default_factory=list, description='Indexes of additional parent nodes.')&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Id from the source system.')&#x22;" />

<PyAttribute name="&#x22;trace_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Distributed trace id.')&#x22;" />

<PyAttribute name="&#x22;node_type&#x22;" type="&#x22;NodeType&#x22;" value="&#x22;Field(description='Kind of work the node records.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Node name.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;NodeStatus&#x22;" value="&#x22;Field(description='Node status.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed node.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='Time the node started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='Time the node ended.')&#x22;" />

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from node inputs.')&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from node outputs.')&#x22;" />

<PyAttribute name="&#x22;system_prompt_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting the system prompt from node inputs.')&#x22;" />

<PyAttribute name="&#x22;reasoning&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Visible reasoning produced by the model call.')&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Node inputs.')&#x22;" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Node outputs.')&#x22;" />

<PyAttribute name="&#x22;requested_model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model requested by the call.')&#x22;" />

<PyAttribute name="&#x22;model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model that served the call.')&#x22;" />

<PyAttribute name="&#x22;model_provider&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model provider.')&#x22;" />

<PyAttribute name="&#x22;tokens&#x22;" type="&#x22;TokenUsage | None&#x22;" value="&#x22;Field(default=None, description='Token usage.')&#x22;" />

<PyAttribute name="&#x22;cost&#x22;" type="&#x22;Decimal | None&#x22;" value="&#x22;Field(default=None, description='Cost of the call.')&#x22;" />

<PyAttribute name="&#x22;model_params&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='Parameters passed to the model.')&#x22;" />

<PyAttribute name="&#x22;tool_name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Tool called.')&#x22;" />

<PyAttribute name="&#x22;subagent_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Subagent invoked.')&#x22;" />

<PyAttribute name="&#x22;attributes&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Arbitrary span attributes.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />


# SessionNodeListParams



Session node list params.

## Attributes [#attributes]

<PyAttribute name="&#x22;sort&#x22;" type="&#x22;Literal['index:asc']&#x22;" value="&#x22;Field(default='index:asc', description='Nodes are ordered by ascending index.')&#x22;" />

<PyAttribute name="&#x22;include_payloads&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=False, description='Include reasoning, inputs, outputs, and attributes.')&#x22;" />


# SessionNodeResponse



Session node response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Node id.')&#x22;" />

<PyAttribute name="&#x22;session_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session this node belongs to.')&#x22;" />

<PyAttribute name="&#x22;index&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Position within the session.')&#x22;" />

<PyAttribute name="&#x22;parent_index&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(description='Parent node index.')&#x22;" />

<PyAttribute name="&#x22;secondary_parent_indexes&#x22;" type="&#x22;list[int]&#x22;" value="&#x22;Field(description='Secondary parent indexes.')&#x22;" />

<PyAttribute name="&#x22;parent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Parent node.')&#x22;" />

<PyAttribute name="&#x22;secondary_parent_ids&#x22;" type="&#x22;list[uuid.UUID]&#x22;" value="&#x22;Field(description='Additional parent nodes.')&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Id from the source system.')&#x22;" />

<PyAttribute name="&#x22;trace_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Distributed trace id.')&#x22;" />

<PyAttribute name="&#x22;node_type&#x22;" type="&#x22;NodeType&#x22;" value="&#x22;Field(description='Kind of work the node records.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Node name.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;NodeStatus&#x22;" value="&#x22;Field(description='Node status.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed node.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the node started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the node ended.')&#x22;" />

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from node inputs.')&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from node outputs.')&#x22;" />

<PyAttribute name="&#x22;system_prompt_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting the system prompt from node inputs.')&#x22;" />

<PyAttribute name="&#x22;reasoning&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Visible reasoning, null unless payloads are included.')&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(default=None, description='Node inputs, null unless include_payloads.')&#x22;" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(default=None, description='Node outputs, null unless include_payloads.')&#x22;" />

<PyAttribute name="&#x22;requested_model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model requested by the call.')&#x22;" />

<PyAttribute name="&#x22;model&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model that served the call.')&#x22;" />

<PyAttribute name="&#x22;model_provider&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Model provider.')&#x22;" />

<PyAttribute name="&#x22;tokens&#x22;" type="&#x22;TokenUsage | None&#x22;" value="&#x22;Field(default=None, description='Token usage.')&#x22;" />

<PyAttribute name="&#x22;cost&#x22;" type="&#x22;Decimal | None&#x22;" value="&#x22;Field(default=None, description='Cost of the call.')&#x22;" />

<PyAttribute name="&#x22;model_params&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='Parameters passed to the model.')&#x22;" />

<PyAttribute name="&#x22;tool_name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Tool called.')&#x22;" />

<PyAttribute name="&#x22;subagent_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Subagent invoked.')&#x22;" />

<PyAttribute name="&#x22;cache_key&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Cache key for a replayed tool call.')&#x22;" />

<PyAttribute name="&#x22;attributes&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(default=None, description='Arbitrary span attributes, null unless include_payloads.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />


# SessionWithNodesResponse



Session with nodes response.

## Attributes [#attributes]

<PyAttribute name="&#x22;session&#x22;" type="&#x22;SessionDetailResponse&#x22;" value="&#x22;Field(description='Session.')&#x22;" />

<PyAttribute name="&#x22;nodes&#x22;" type="&#x22;list[SessionNodeResponse]&#x22;" value="&#x22;Field(description='Every node of the session, ordered by index ascending.')&#x22;" />


# session_node



Session node API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;NodeStatus&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/NodeStatus&#x22;" />

      <Card title="&#x22;NodeType&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/NodeType&#x22;" />

      <Card title="&#x22;SessionNodeBatchRequest&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/SessionNodeBatchRequest&#x22;" />

      <Card title="&#x22;SessionNodeCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/SessionNodeCreateRequest&#x22;" />

      <Card title="&#x22;SessionNodeListParams&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/SessionNodeListParams&#x22;" />

      <Card title="&#x22;SessionNodeResponse&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/SessionNodeResponse&#x22;" />

      <Card title="&#x22;SessionWithNodesResponse&#x22;" href="&#x22;/reference/python/api_models/v1/session_node/SessionWithNodesResponse&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# SessionCreateRequest



Session create request.

## Attributes [#attributes]

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Agent the session belongs to, inferred from the task or the agent version when unset.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Agent version recorded for the session, inferred from the task when unset.')&#x22;" />

<PyAttribute name="&#x22;origin&#x22;" type="&#x22;SessionOrigin&#x22;" value="&#x22;Field(description='How the session came to exist.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;SessionStatus | None&#x22;" value="&#x22;Field(default=None, description='Initial session status.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Session name.')&#x22;" />

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from session inputs.')&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from session outputs.')&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Session inputs.')&#x22;" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Session outputs.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed session.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='Time the session started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='Time the session ended.')&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Id from the source system.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;imported_from&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Source system the session was imported from.')&#x22;" />

<PyAttribute name="&#x22;framework&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Agent framework used.')&#x22;" />

<PyAttribute name="&#x22;adapter_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Recording adapter version.')&#x22;" />


# SessionDetailResponse



Session detail response.

## Attributes [#attributes]

<PyAttribute name="&#x22;input_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from session inputs.')&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='RFC 6901 JSON Pointer selecting display text from session outputs.')&#x22;" />

<PyAttribute name="&#x22;inputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Session inputs.')&#x22;" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(description='Session outputs.')&#x22;" />


# SessionEvaluationsRequest



Session evaluations request.

## Attributes [#attributes]

<PyAttribute name="&#x22;evaluations&#x22;" type="&#x22;list[EvaluationResult]&#x22;" value="&#x22;Field(min_length=1, description='Evaluations to merge into the session.')&#x22;" />


# SessionListParams



Session list params.

## Attributes [#attributes]

<PyAttribute name="&#x22;include_payloads&#x22;" type="&#x22;bool&#x22;" value="&#x22;Field(default=False, description='Include inputs and outputs.')&#x22;" />


# SessionOrigin



How a session came to exist.

## Attributes [#attributes]

<PyAttribute name="&#x22;IMPORTED&#x22;" type="null" value="&#x22;'imported'&#x22;" />

<PyAttribute name="&#x22;RECORDED&#x22;" type="null" value="&#x22;'recorded'&#x22;" />

<PyAttribute name="&#x22;REPLAY&#x22;" type="null" value="&#x22;'replay'&#x22;" />


# SessionResponse



Session response.

## Attributes [#attributes]

<PyAttribute name="&#x22;id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Session id.')&#x22;" />

<PyAttribute name="&#x22;agent_id&#x22;" type="&#x22;uuid.UUID&#x22;" value="&#x22;Field(description='Agent the session belongs to.')&#x22;" />

<PyAttribute name="&#x22;number&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Session number within the agent.')&#x22;" />

<PyAttribute name="&#x22;agent_version_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Agent version recorded for the session.')&#x22;" />

<PyAttribute name="&#x22;task_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Task the session was produced by.')&#x22;" />

<PyAttribute name="&#x22;import_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description='Import the session was created by.')&#x22;" />

<PyAttribute name="&#x22;origin&#x22;" type="&#x22;SessionOrigin&#x22;" value="&#x22;Field(description='How the session came to exist.')&#x22;" />

<PyAttribute name="&#x22;status&#x22;" type="&#x22;SessionStatus&#x22;" value="&#x22;Field(description='Session status.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Session name.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Error from a failed session.')&#x22;" />

<PyAttribute name="&#x22;started_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the session started.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;datetime | None&#x22;" value="&#x22;Field(default=None, description='Time the session ended.')&#x22;" />

<PyAttribute name="&#x22;external_id&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Id from the source system.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(description='Arbitrary metadata.')&#x22;" />

<PyAttribute name="&#x22;imported_from&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Source system the session was imported from.')&#x22;" />

<PyAttribute name="&#x22;framework&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Agent framework used.')&#x22;" />

<PyAttribute name="&#x22;adapter_version&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Recording adapter version.')&#x22;" />

<PyAttribute name="&#x22;cost&#x22;" type="&#x22;Decimal | None&#x22;" value="&#x22;Field(default=None, description='Total cost.')&#x22;" />

<PyAttribute name="&#x22;tokens&#x22;" type="&#x22;TokenUsage | None&#x22;" value="&#x22;Field(default=None, description='Total token usage.')&#x22;" />

<PyAttribute name="&#x22;llm_call_count&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Number of LLM call nodes.')&#x22;" />

<PyAttribute name="&#x22;tool_call_count&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(description='Number of tool call nodes.')&#x22;" />


# SessionStatus



Session status.

## Attributes [#attributes]

<PyAttribute name="&#x22;IN_PROGRESS&#x22;" type="null" value="&#x22;'in_progress'&#x22;" />

<PyAttribute name="&#x22;COMPLETED&#x22;" type="null" value="&#x22;'completed'&#x22;" />

<PyAttribute name="&#x22;FAILED&#x22;" type="null" value="&#x22;'failed'&#x22;" />


# SessionUpdateRequest



Session update request.

## Attributes [#attributes]

<PyAttribute name="&#x22;status&#x22;" type="&#x22;SessionStatus | None&#x22;" value="&#x22;Field(default=None, description='New session status.')&#x22;" />

<PyAttribute name="&#x22;outputs&#x22;" type="&#x22;Any&#x22;" value="&#x22;Field(default=None, description='New session outputs.')&#x22;" />

<PyAttribute name="&#x22;output_text_selector&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New output text selector.')&#x22;" />

<PyAttribute name="&#x22;error&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New error.')&#x22;" />

<PyAttribute name="&#x22;ended_at&#x22;" type="&#x22;AwareDatetime | None&#x22;" value="&#x22;Field(default=None, description='New end time.')&#x22;" />

<PyAttribute name="&#x22;name&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New session name.')&#x22;" />

<PyAttribute name="&#x22;metadata&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New metadata.')&#x22;" />


# TokenUsage



Token usage.

## Attributes [#attributes]

<PyAttribute name="&#x22;input_tokens&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Input tokens.')&#x22;" />

<PyAttribute name="&#x22;output_tokens&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Output tokens.')&#x22;" />

<PyAttribute name="&#x22;cached_input_tokens&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Cached input tokens.')&#x22;" />

<PyAttribute name="&#x22;reasoning_tokens&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Reasoning tokens.')&#x22;" />


# session



Session API models.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;SessionCreateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionCreateRequest&#x22;" />

      <Card title="&#x22;SessionDetailResponse&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionDetailResponse&#x22;" />

      <Card title="&#x22;SessionEvaluationsRequest&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionEvaluationsRequest&#x22;" />

      <Card title="&#x22;SessionListParams&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionListParams&#x22;" />

      <Card title="&#x22;SessionOrigin&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionOrigin&#x22;" />

      <Card title="&#x22;SessionResponse&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionResponse&#x22;" />

      <Card title="&#x22;SessionStatus&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionStatus&#x22;" />

      <Card title="&#x22;SessionUpdateRequest&#x22;" href="&#x22;/reference/python/api_models/v1/session/SessionUpdateRequest&#x22;" />

      <Card title="&#x22;TokenUsage&#x22;" href="&#x22;/reference/python/api_models/v1/session/TokenUsage&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# AnalyzerConfig



Analyzer config.

## Attributes [#attributes]

<PyAttribute name="&#x22;analyzer&#x22;" type="&#x22;PlainStr&#x22;" value="&#x22;Field(description='Analyzer name.')&#x22;" />

<PyAttribute name="&#x22;min_sessions&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, ge=1, description='Session minimum (built-in insights: 5; others: 1).')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Analyzer version; defaults to latest.')&#x22;" />

<PyAttribute name="&#x22;params&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Plugin arguments.')&#x22;" />

<PyAttribute name="&#x22;connection_id&#x22;" type="&#x22;uuid.UUID | None&#x22;" value="&#x22;Field(default=None, description=\&#x22;Credential connection; defaults to the provider's default.\&#x22;)&#x22;" />


# EvaluatorConfig



Evaluator config.

## Attributes [#attributes]

<PyAttribute name="&#x22;evaluator&#x22;" type="&#x22;PlainStr&#x22;" value="&#x22;Field(description='Evaluator name.')&#x22;" />

<PyAttribute name="&#x22;version&#x22;" type="&#x22;int | None&#x22;" value="&#x22;Field(default=None, description='Evaluator version, an omitted value resolves to latest.')&#x22;" />

<PyAttribute name="&#x22;params&#x22;" type="&#x22;dict[str, JsonValue]&#x22;" value="&#x22;Field(default_factory=dict, description='Parameters passed to the evaluator.')&#x22;" />


# HistoryConfig



History tool config.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['history']&#x22;" value="&#x22;Field(default='history')&#x22;" />

<PyAttribute name="&#x22;scope&#x22;" type="&#x22;HistoryScope&#x22;" value="&#x22;Field(description='Source of recorded calls to replay from.')&#x22;" />

<PyAttribute name="&#x22;on_miss&#x22;" type="&#x22;ToolPolicyOnMiss&#x22;" value="&#x22;Field(description='Behavior when no recorded call matches.')&#x22;" />


# HistoryScope



Scope a history tool config draws recorded calls from.

## Attributes [#attributes]

<PyAttribute name="&#x22;BASELINE&#x22;" type="null" value="&#x22;'baseline'&#x22;" />

<PyAttribute name="&#x22;COHORT_VERSION&#x22;" type="null" value="&#x22;'cohort_version'&#x22;" />

<PyAttribute name="&#x22;AGENT&#x22;" type="null" value="&#x22;'agent'&#x22;" />


# LLMConfig



LLM tool config.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['llm']&#x22;" value="&#x22;Field(default='llm')&#x22;" />

<PyAttribute name="&#x22;model&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(description='Model used to generate the tool result.')&#x22;" />

<PyAttribute name="&#x22;instructions&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Instructions guiding the generated result.')&#x22;" />


# PassthroughConfig



Passthrough tool config.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['passthrough']&#x22;" value="&#x22;Field(default='passthrough')&#x22;" />


# ReplayOverride



Replay override.

## Attributes [#attributes]

<PyAttribute name="&#x22;model&#x22;" type="&#x22;str | dict[str, str] | None&#x22;" value="&#x22;Field(default=None, description='New model, or a map from old to new model.')&#x22;" />

<PyAttribute name="&#x22;system_prompt&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New system prompt.')&#x22;" />

<PyAttribute name="&#x22;prompt&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='New prompt.')&#x22;" />

<PyAttribute name="&#x22;model_params&#x22;" type="&#x22;dict[str, JsonValue] | None&#x22;" value="&#x22;Field(default=None, description='New model parameters.')&#x22;" />


# StaticCase



Static tool call case.

## Attributes [#attributes]

<PyAttribute name="&#x22;match&#x22;" type="&#x22;JsonValue | None&#x22;" value="&#x22;Field(default=None, description='Call arguments to match, unset matches any call.')&#x22;" />

<PyAttribute name="&#x22;match_mode&#x22;" type="&#x22;StaticMatchMode&#x22;" value="&#x22;Field(description='How the call arguments are matched.')&#x22;" />

<PyAttribute name="&#x22;result&#x22;" type="&#x22;JsonValue&#x22;" value="&#x22;Field(description='Result returned for a matching call.')&#x22;" />


# StaticConfig



Static tool config.

## Attributes [#attributes]

<PyAttribute name="&#x22;type&#x22;" type="&#x22;Literal['static']&#x22;" value="&#x22;Field(default='static')&#x22;" />

<PyAttribute name="&#x22;cases&#x22;" type="&#x22;list[StaticCase]&#x22;" value="&#x22;Field(description='Cases tried in order for a matching call.')&#x22;" />

<PyAttribute name="&#x22;on_miss&#x22;" type="&#x22;ToolPolicyOnMiss&#x22;" value="&#x22;Field(description='Behavior when no case matches.')&#x22;" />


# StaticMatchMode



How a static case matches a tool call.

## Attributes [#attributes]

<PyAttribute name="&#x22;EXACT&#x22;" type="null" value="&#x22;'exact'&#x22;" />

<PyAttribute name="&#x22;SUBSET&#x22;" type="null" value="&#x22;'subset'&#x22;" />


# ToolPolicy



Tool policy.

## Attributes [#attributes]

<PyAttribute name="&#x22;default&#x22;" type="&#x22;ToolConfig&#x22;" value="&#x22;Field(description='Config applied to tools without an override.')&#x22;" />

<PyAttribute name="&#x22;tools&#x22;" type="&#x22;dict[str, ToolConfig]&#x22;" value="&#x22;Field(default_factory=dict, description='Per-tool config overrides.')&#x22;" />


# ToolPolicyOnMiss



Behavior when a replayed tool call has no match.

## Attributes [#attributes]

<PyAttribute name="&#x22;FAIL&#x22;" type="null" value="&#x22;'fail'&#x22;" />

<PyAttribute name="&#x22;PASSTHROUGH&#x22;" type="null" value="&#x22;'passthrough'&#x22;" />

<PyAttribute name="&#x22;ERROR_RESULT&#x22;" type="null" value="&#x22;'error_result'&#x22;" />


# replay_config



Replay configuration API models, shared by experiments, replays, and evaluations.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;AnalyzerConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/AnalyzerConfig&#x22;" />

      <Card title="&#x22;EvaluatorConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/EvaluatorConfig&#x22;" />

      <Card title="&#x22;HistoryConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/HistoryConfig&#x22;" />

      <Card title="&#x22;HistoryScope&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/HistoryScope&#x22;" />

      <Card title="&#x22;LLMConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/LLMConfig&#x22;" />

      <Card title="&#x22;PassthroughConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/PassthroughConfig&#x22;" />

      <Card title="&#x22;ReplayOverride&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/ReplayOverride&#x22;" />

      <Card title="&#x22;StaticCase&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/StaticCase&#x22;" />

      <Card title="&#x22;StaticConfig&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/StaticConfig&#x22;" />

      <Card title="&#x22;StaticMatchMode&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/StaticMatchMode&#x22;" />

      <Card title="&#x22;ToolPolicy&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/ToolPolicy&#x22;" />

      <Card title="&#x22;ToolPolicyOnMiss&#x22;" href="&#x22;/reference/python/api_models/v1/replay_config/ToolPolicyOnMiss&#x22;" />
    </Cards>
  </Tab>
</Tabs>


# CursorParams



Cursor params.

## Attributes [#attributes]

<PyAttribute name="&#x22;cursor&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(default=None, description='Cursor from the previous page.')&#x22;" />

<PyAttribute name="&#x22;size&#x22;" type="&#x22;int&#x22;" value="&#x22;Field(default=20, ge=1, le=1000, description='Items per page.')&#x22;" />


# ListParams



List params.

## Attributes [#attributes]

<PyAttribute name="&#x22;sort&#x22;" type="&#x22;str&#x22;" value="&#x22;Field(default='created:desc', description='Sort field and direction, as field:asc or field:desc.', pattern='^[a-z][a-z0-9_]*:(asc|desc)$')&#x22;" />


# Page



Pagination envelope.

## Attributes [#attributes]

<PyAttribute name="&#x22;items&#x22;" type="&#x22;list[ItemT]&#x22;" value="&#x22;Field(description='Items on this page.')&#x22;" />

<PyAttribute name="&#x22;next_cursor&#x22;" type="&#x22;str | None&#x22;" value="&#x22;Field(description='Cursor for the next page, null on the last page.')&#x22;" />


# base



Shared DTO bases, pagination envelope, and error body.

<Tabs items="[&#x22;Class&#x22;]">
  <Tab value="&#x22;Class&#x22;">
    <Cards>
      <Card title="&#x22;CursorParams&#x22;" href="&#x22;/reference/python/api_models/v1/base/CursorParams&#x22;" />

      <Card title="&#x22;ListParams&#x22;" href="&#x22;/reference/python/api_models/v1/base/ListParams&#x22;" />

      <Card title="&#x22;Page&#x22;" href="&#x22;/reference/python/api_models/v1/base/Page&#x22;" />
    </Cards>
  </Tab>
</Tabs>