dirigent-contrib 0.28.0__py3-none-any.whl

dirigent_contrib/__init__.py

@@ -0,0 +1 @@
+"""Block packs for dirigent that reach outside systems, each a subpackage with an entry point of its own."""

dirigent_contrib/chap/__init__.py

@@ -0,0 +1,103 @@
+"""The Chap pack: the ``chap`` connection kind and the blocks for one Chap server."""
+
+from collections.abc import Sequence
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+from dirigent_contrib.chap.alerts import (
+    ChapAlertCounts,
+    ChapAlertsListConfig,
+    ChapAlertsListOperator,
+    ChapAlertsOutput,
+    ChapAlertsRecordConfig,
+    ChapAlertsRecordOperator,
+    ChapAlertsRecordOutput,
+    ChapAlertsReviewedConfig,
+    ChapAlertsReviewedSensor,
+)
+from dirigent_contrib.chap.backtests import ChapBacktestRunConfig, ChapBacktestRunOperator, ChapBacktestRunOutput
+from dirigent_contrib.chap.configured_models import ChapModelsListConfig, ChapModelsListOperator, ChapModelsListOutput
+from dirigent_contrib.chap.connection import ChapConnectionConfig, ChapConnectionKind, build_client, client_for
+from dirigent_contrib.chap.datasets import ChapDatasetImportConfig, ChapDatasetImportOperator, ChapDatasetImportOutput
+from dirigent_contrib.chap.messages import CHAP
+from dirigent_contrib.chap.predictions import (
+    ChapPredictionReadConfig,
+    ChapPredictionReadOperator,
+    ChapPredictionReadOutput,
+    ChapPredictionRunConfig,
+    ChapPredictionRunOperator,
+    ChapPredictionRunOutput,
+)
+from dirigent_contrib.chap.thresholds import ChapThresholdsConfig, ChapThresholdsOperator, ChapThresholdsOutput
+from dirigent_plugin import Contribution, extension
+
+#: The directory the pack's example shelves live in, inside this distribution.
+SHELVES_DIRECTORY = "shelves"
+
+
+class ChapPlugin:
+    """The plugin object the host discovers under the dirigent.plugins.v1 entry-point group."""
+
+    @extension
+    def contribute(self) -> Contribution:
+        """Contribute the Chap blocks and the ``chap`` connection kind they are configured from."""
+        return Contribution(
+            operators=[
+                ChapDatasetImportOperator(),
+                ChapBacktestRunOperator(),
+                ChapPredictionRunOperator(),
+                ChapPredictionReadOperator(),
+                ChapModelsListOperator(),
+                ChapThresholdsOperator(),
+                ChapAlertsRecordOperator(),
+                ChapAlertsListOperator(),
+            ],
+            sensors=[ChapAlertsReviewedSensor()],
+            connection_kinds=[ChapConnectionKind()],
+            labels=[CHAP],
+        )
+
+    @extension
+    def examples(self) -> Sequence[Traversable]:
+        """Contribute the example shelves this distribution carries."""
+        return [files(__package__ or "dirigent_contrib.chap") / SHELVES_DIRECTORY]
+
+
+plugin = ChapPlugin()
+
+__all__ = [
+    "SHELVES_DIRECTORY",
+    "ChapAlertCounts",
+    "ChapAlertsListConfig",
+    "ChapAlertsListOperator",
+    "ChapAlertsOutput",
+    "ChapAlertsRecordConfig",
+    "ChapAlertsRecordOperator",
+    "ChapAlertsRecordOutput",
+    "ChapAlertsReviewedConfig",
+    "ChapAlertsReviewedSensor",
+    "ChapBacktestRunConfig",
+    "ChapBacktestRunOperator",
+    "ChapBacktestRunOutput",
+    "ChapConnectionConfig",
+    "ChapConnectionKind",
+    "ChapDatasetImportConfig",
+    "ChapDatasetImportOperator",
+    "ChapDatasetImportOutput",
+    "ChapModelsListConfig",
+    "ChapModelsListOperator",
+    "ChapModelsListOutput",
+    "ChapPlugin",
+    "ChapPredictionReadConfig",
+    "ChapPredictionReadOperator",
+    "ChapPredictionReadOutput",
+    "ChapPredictionRunConfig",
+    "ChapPredictionRunOperator",
+    "ChapPredictionRunOutput",
+    "ChapThresholdsConfig",
+    "ChapThresholdsOperator",
+    "ChapThresholdsOutput",
+    "build_client",
+    "client_for",
+    "plugin",
+]

dirigent_contrib/chap/alerts.py

@@ -0,0 +1,240 @@
+"""Chap's alert release gate: ``chap.alerts.record`` raises alerts, ``chap.alerts.reviewed`` waits on their review.
+
+An alert lands in Chap as ``pending``, and a reviewer moves it to ``approved`` or ``declined``
+through ``POST /v1/crud/alerts/$approve`` from wherever they work. These blocks never decide
+on an alert: they record them, read where each one stands, and hand the decided ones on.
+"""
+
+from datetime import timedelta
+from typing import ClassVar, Final, Literal
+
+from pydantic import BaseModel, Field, JsonValue
+
+from dirigent_common import BlockModel
+from dirigent_contrib.chap.bodies import PassThroughConfig, body_of
+from dirigent_contrib.chap.connection import client_for
+from dirigent_contrib.chap.messages import ALERTS_NOT_A_LIST, ALERTS_NOT_RECORDED, ALERTS_OUTSIDE, ALERTS_REVIEWING
+from dirigent_contrib.chap.web import call_json, mapping
+from dirigent_contrib.limits import BoundedClient
+from dirigent_plugin import (
+    BlockFailure,
+    ConnectionRef,
+    ErrorClass,
+    NotYet,
+    Operator,
+    OperatorSpec,
+    Sensor,
+    SensorSpec,
+    StepContext,
+)
+
+ALERTS_PATH: Final = "/v1/crud/alerts"
+
+#: The gate states that are a reviewer's decision. Any other state, ``pending`` or one Chap adds
+#: later, is still waiting on one.
+APPROVED: Final = "approved"
+DECLINED: Final = "declined"
+
+#: How often the review is looked at when the step does not say: a person decides, not a job.
+REVIEW_POLL: Final = timedelta(minutes=5)
+
+#: How long the review may take when the step does not say.
+REVIEW_DEADLINE: Final = timedelta(days=3)
+
+type Release = Literal["all", "any"]
+
+
+class ChapAlertsListConfig(BlockModel):
+    """Which alerts a step looks at."""
+
+    connection: ConnectionRef
+    """The code of the chap connection naming the server."""
+
+    prediction_id: int | None = None
+    """Only the alerts this prediction raised; every prediction's when unset."""
+
+    alert_policy_id: int | None = None
+    """Only the alerts raised against this policy; every policy when unset."""
+
+    org_units: list[str] | None = None
+    """Only the alerts for these org units; every org unit when unset."""
+
+
+class ChapAlertCounts(BlockModel):
+    """How many alerts stand where in the release gate."""
+
+    total: int = 0
+    """Every alert the step looked at."""
+
+    approved: int = 0
+    """The alerts cleared for release."""
+
+    declined: int = 0
+    """The alerts decided against."""
+
+    pending: int = 0
+    """The alerts still waiting on a reviewer."""
+
+
+class ChapAlertsOutput(BlockModel):
+    """The alerts, split by where they stand in the release gate."""
+
+    approved: list[JsonValue] = Field(default_factory=list[JsonValue])
+    """The alerts a reviewer cleared for release, as Chap answers with them: `{id, timePeriod, orgUnit,
+    alertPolicyId, level, predictionId, approvedBy, approvedAt, ...}`."""
+
+    declined: list[JsonValue] = Field(default_factory=list[JsonValue])
+    """The alerts a reviewer decided not to release, in the same shape."""
+
+    pending: list[JsonValue] = Field(default_factory=list[JsonValue])
+    """The alerts nobody has decided on yet, in the same shape."""
+
+    counts: ChapAlertCounts = Field(default_factory=ChapAlertCounts)
+    """How many alerts there are, and how many of them are approved, declined and pending."""
+
+
+async def list_alerts(
+    client: BoundedClient, config: "ChapAlertsListConfig | ChapAlertsReviewedConfig"
+) -> ChapAlertsOutput:
+    """Read the alerts a step looks at, and split them by their gate state.
+
+    A row outside the prediction or policy the step named is refused, not skipped.
+    """
+    params: dict[str, int] = {}
+    if config.prediction_id is not None:
+        params["predictionId"] = config.prediction_id
+    if config.alert_policy_id is not None:
+        params["alertPolicyId"] = config.alert_policy_id
+    answer = await call_json(client, "GET", ALERTS_PATH, params=params)
+    if not isinstance(answer, list):
+        raise BlockFailure(ALERTS_NOT_A_LIST, error_class=ErrorClass.UNKNOWN, where=f"GET {ALERTS_PATH}")
+    wanted = set(config.org_units) if config.org_units is not None else None
+    output = ChapAlertsOutput()
+    for alert in answer:
+        for field, asked in params.items():
+            if mapping(alert).get(field) != asked:
+                raise BlockFailure(
+                    ALERTS_OUTSIDE, error_class=ErrorClass.UNKNOWN, where=f"GET {ALERTS_PATH}", field=field, asked=asked
+                )
+        if wanted is not None and mapping(alert).get("orgUnit") not in wanted:
+            continue
+        state = mapping(alert).get("approved")
+        if state == APPROVED:
+            output.approved.append(alert)
+        elif state == DECLINED:
+            output.declined.append(alert)
+        else:
+            output.pending.append(alert)
+    output.counts = ChapAlertCounts(
+        total=len(output.approved) + len(output.declined) + len(output.pending),
+        approved=len(output.approved),
+        declined=len(output.declined),
+        pending=len(output.pending),
+    )
+    return output
+
+
+class ChapAlertsReviewedConfig(BlockModel):
+    """Which prediction's alerts to wait on, and when their review counts as done."""
+
+    connection: ConnectionRef
+    """The code of the chap connection naming the server."""
+
+    prediction_id: int
+    """The prediction whose alerts are waited on, as `chap.prediction.run` outputs it."""
+
+    alert_policy_id: int | None = None
+    """Only the alerts raised against this policy; every policy when unset."""
+
+    org_units: list[str] | None = None
+    """Only the alerts for these org units; every org unit when unset."""
+
+    release: Release = "all"
+    """When the wait ends: `all` once no alert is pending, `any` as soon as one is decided. A
+    prediction that raised no alerts ends it at once either way."""
+
+
+class ChapAlertsReviewedSensor(Sensor[ChapAlertsReviewedConfig, ChapAlertsOutput]):
+    """Waits for a reviewer to decide on a prediction's alerts in Chap; each poke is one listing."""
+
+    spec = SensorSpec(
+        id="chap.alerts.reviewed",
+        summary="Wait for a Chap prediction's alerts to be reviewed.",
+        default_poll=REVIEW_POLL,
+        default_deadline=REVIEW_DEADLINE,
+    )
+    config_model: ClassVar[type[BaseModel]] = ChapAlertsReviewedConfig
+    output_model: ClassVar[type[BaseModel]] = ChapAlertsOutput
+
+    async def poke(self, config: ChapAlertsReviewedConfig, ctx: StepContext) -> ChapAlertsOutput | NotYet:
+        """List the prediction's alerts once, and succeed when the review is as far as `release` asks.
+
+        A refusal Chap answers with fails the poke, classified as every block in the pack
+        classifies one: a 5xx and a 429 are retried, any other 4xx is not.
+        """
+        async with client_for(ctx, config.connection) as client:
+            alerts = await list_alerts(client, config)
+        counts = alerts.counts
+        reviewed = counts.approved + counts.declined
+        done = counts.pending == 0 if config.release == "all" else reviewed > 0
+        if counts.total == 0 or done:
+            return alerts
+        return NotYet(
+            message=ALERTS_REVIEWING.render(reviewed=reviewed, total=counts.total),
+            progress=reviewed / counts.total,
+        )
+
+
+class ChapAlertsListOperator(Operator[ChapAlertsListConfig, ChapAlertsOutput]):
+    """Reads where alerts stand in the release gate, once, without waiting on anything."""
+
+    spec = OperatorSpec(id="chap.alerts.list", summary="List Chap alerts by their review state.", idempotent=True)
+    config_model: ClassVar[type[BaseModel]] = ChapAlertsListConfig
+    output_model: ClassVar[type[BaseModel]] = ChapAlertsOutput
+
+    async def execute(self, config: ChapAlertsListConfig, ctx: StepContext) -> ChapAlertsOutput:
+        """List the alerts once."""
+        async with client_for(ctx, config.connection) as client:
+            return await list_alerts(client, config)
+
+
+class ChapAlertsRecordConfig(PassThroughConfig):
+    """The alerts to record; any undeclared key is sent to Chap as written."""
+
+    alerts: list[dict[str, JsonValue]] = Field(min_length=1)
+    """The alerts as Chap spells them: `{timePeriod, orgUnit, alertPolicyId, level, predictionId}`, each
+    `level` one the policy defines."""
+
+
+class ChapAlertsRecordOutput(BlockModel):
+    """The alerts Chap recorded."""
+
+    alert_ids: list[int]
+    """The recorded alerts' ids, in the order they were sent; each starts `pending`."""
+
+    count: int
+    """How many alerts were recorded."""
+
+
+class ChapAlertsRecordOperator(Operator[ChapAlertsRecordConfig, ChapAlertsRecordOutput]):
+    """Records a batch of alerts against a policy, all of them or none."""
+
+    spec = OperatorSpec(id="chap.alerts.record", summary="Record alerts in Chap's review queue.")
+    config_model: ClassVar[type[BaseModel]] = ChapAlertsRecordConfig
+    output_model: ClassVar[type[BaseModel]] = ChapAlertsRecordOutput
+
+    async def execute(self, config: ChapAlertsRecordConfig, ctx: StepContext) -> ChapAlertsRecordOutput:
+        """Record the batch once.
+
+        An unknown policy, level or prediction, and a second alert for the same prediction,
+        org unit and period, are answered 422 and never retried.
+        """
+        body = body_of(config, "alerts")
+        async with client_for(ctx, config.connection) as client:
+            answer = mapping(await call_json(client, "POST", ALERTS_PATH, json=body))
+        ids = answer.get("ids")
+        if not isinstance(ids, list) or not all(isinstance(alert_id, int) for alert_id in ids):
+            raise BlockFailure(ALERTS_NOT_RECORDED, error_class=ErrorClass.UNKNOWN, where=f"POST {ALERTS_PATH}")
+        alert_ids = [alert_id for alert_id in ids if isinstance(alert_id, int)]
+        ctx.log.info("alerts recorded", count=len(alert_ids))
+        return ChapAlertsRecordOutput(alert_ids=alert_ids, count=len(alert_ids))

dirigent_contrib/chap/backtests.py

@@ -0,0 +1,110 @@
+"""``chap.backtest.run``: train and evaluate a configured model on a stored dataset, as a Chap job."""
+
+from typing import ClassVar, Final
+
+from pydantic import BaseModel, Field, JsonValue
+
+from dirigent_common import BlockModel
+from dirigent_contrib.chap.bodies import PassThroughConfig, body_of
+from dirigent_contrib.chap.connection import client_for
+from dirigent_contrib.chap.jobs import JOB_POLL, ChapJobOperator, job_id_of, submit
+from dirigent_contrib.chap.web import mapping
+from dirigent_plugin import OperatorSpec, RemoteHandle, StepContext
+
+CREATE_BACKTEST_PATH: Final = "/v1/analytics/create-backtest"
+
+
+class ChapBacktestRunConfig(PassThroughConfig):
+    """What one backtest asks of Chap.
+
+    A parameter left unset takes the server's saved default, and any undeclared key is sent to
+    Chap as written.
+    """
+
+    name: str = Field(min_length=1)
+    """The name the backtest is stored under."""
+
+    model_id: int | str
+    """The configured model to evaluate, by its id or its name."""
+
+    dataset_id: int
+    """The stored dataset to evaluate it on, as `chap.dataset.import` outputs it."""
+
+    n_periods: int | None = Field(default=None, ge=1)
+    """How many periods ahead each split forecasts; Chap's default is 3."""
+
+    n_splits: int | None = Field(default=None, ge=1)
+    """How many train/test splits are evaluated; Chap's default is 7."""
+
+    stride: int | None = Field(default=None, ge=1)
+    """How many periods one split moves on from the last; Chap's default is 1."""
+
+    n_retrain: int | None = Field(default=None, ge=1)
+    """How many times the model is retrained across the splits; Chap's default is 1."""
+
+    future_weather_provider: str | None = None
+    """Where the forecast window's weather comes from; Chap's default is `climatology`."""
+
+    target_column: str | None = None
+    """The dataset column the model forecasts; Chap's default is `disease_cases`."""
+
+
+class ChapBacktestRunOutput(BlockModel):
+    """The backtest the finished job stored, as Chap describes it."""
+
+    backtest_id: int | None = None
+    """The stored backtest's id."""
+
+    job_id: str
+    """The evaluation job Chap ran."""
+
+    aggregate_metrics: JsonValue = None
+    """The backtest's `aggregateMetrics`, lifted out of it."""
+
+    backtest: JsonValue = None
+    """The backtest exactly as Chap's evaluation result answers with it."""
+
+
+class ChapBacktestRunOperator(ChapJobOperator[ChapBacktestRunConfig, ChapBacktestRunOutput]):
+    """Submits a backtest and waits for its evaluation job."""
+
+    spec = OperatorSpec(
+        id="chap.backtest.run", summary="Run a Chap backtest on a stored dataset.", default_poll=JOB_POLL
+    )
+    config_model: ClassVar[type[BaseModel]] = ChapBacktestRunConfig
+    output_model: ClassVar[type[BaseModel]] = ChapBacktestRunOutput
+    result_helper: ClassVar[str] = "evaluation_result"
+
+    async def execute(self, config: ChapBacktestRunConfig, ctx: StepContext) -> RemoteHandle:
+        """Submit the backtest and hand back its job."""
+        body = body_of(
+            config,
+            "name",
+            "model_id",
+            "dataset_id",
+            "n_periods",
+            "n_splits",
+            "stride",
+            "n_retrain",
+            "future_weather_provider",
+            "target_column",
+        )
+        async with client_for(ctx, config.connection) as client:
+            answer = await submit(client, CREATE_BACKTEST_PATH, body)
+        job_id = job_id_of(answer, f"POST {CREATE_BACKTEST_PATH}")
+        ctx.log.info("backtest submitted", job=job_id)
+        return self.handle(job_id)
+
+    async def fetch(
+        self, handle: RemoteHandle, config: ChapBacktestRunConfig, ctx: StepContext
+    ) -> ChapBacktestRunOutput:
+        """Read the stored backtest off the finished job."""
+        backtest = await self.result(handle, config, ctx)
+        described = mapping(backtest)
+        backtest_id = described.get("id")
+        return ChapBacktestRunOutput(
+            backtest_id=backtest_id if isinstance(backtest_id, int) else None,
+            job_id=handle.ref,
+            aggregate_metrics=described.get("aggregateMetrics"),
+            backtest=backtest,
+        )

dirigent_contrib/chap/bodies.py

@@ -0,0 +1,120 @@
+"""A Chap request body, built from a step's config: its declared fields renamed, the rest passed through.
+
+Chap owns the shape of what it is sent and changes it often, so a block declares only the
+fields it reads and lets the rest through: a key a step writes that the block does not
+declare is sent to Chap exactly as written, in Chap's own camelCase spelling.
+"""
+
+import csv
+import io
+import math
+from typing import Final
+
+from pydantic import ConfigDict, Field, JsonValue, model_validator
+
+from dirigent_contrib.chap.jobs import ChapJobConfig
+from dirigent_contrib.chap.messages import CSV_BAD_VALUE, CSV_MISSING_COLUMN, CSV_TOO_LARGE, OBSERVATIONS_MISSING
+from dirigent_plugin import BlockFailure, ErrorClass
+
+#: The columns of a Chap CSV that are not features.
+PERIOD_COLUMN: Final = "time_period"
+LOCATION_COLUMN: Final = "location"
+
+#: How many observations a CSV may unfold to when the step does not say.
+MAX_OBSERVATIONS: Final = 500_000
+
+
+class PassThroughConfig(ChapJobConfig):
+    """A config whose undeclared keys are sent to Chap as written."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True, extra="allow")
+
+
+def camel(name: str) -> str:
+    """Spell a snake_case field the way Chap's JSON spells it."""
+    head, *rest = name.split("_")
+    return head + "".join(part.title() for part in rest)
+
+
+def body_of(config: PassThroughConfig, *declared: str) -> dict[str, JsonValue]:
+    """Build the body: each declared field that is set, renamed to camelCase, then every passed-through key.
+
+    A declared field left at None is left out, so Chap applies its own default to it.
+    """
+    body: dict[str, JsonValue] = {}
+    for name in declared:
+        value = getattr(config, name)
+        if value is not None:
+            body[camel(name)] = config.model_dump(mode="json", include={name})[name]
+    body.update(config.model_extra or {})
+    return body
+
+
+class ObservationsConfig(PassThroughConfig):
+    """The observations a step sends: rows as Chap spells them, a Chap CSV, or both."""
+
+    provided_data: list[dict[str, JsonValue]] = Field(default_factory=list[dict[str, JsonValue]])
+    """Observations as Chap spells them: `{period, orgUnit, value, featureName}`, one per row."""
+
+    csv: str | None = None
+    """A wide Chap CSV, the shape `aggregate_to_chap_csv` writes: `time_period`, `location`, and one
+    column per feature. Each feature cell becomes one observation, sent beside `provided_data`."""
+
+    max_observations: int = Field(default=MAX_OBSERVATIONS, ge=1)
+    """The most observations `csv` may unfold to, columns times rows; a larger one fails the step and sends nothing."""
+
+    @model_validator(mode="after")
+    def _require_observations(self) -> "ObservationsConfig":
+        """Refuse a step that sends no observations at all."""
+        if not self.provided_data and not self.csv:
+            raise ValueError(OBSERVATIONS_MISSING.render())
+        return self
+
+    def observations(self) -> list[JsonValue]:
+        """Every observation the step sends: the rows as written, then the CSV's cells."""
+        rows: list[JsonValue] = list(self.provided_data)
+        if self.csv:
+            rows.extend(csv_observations(self.csv, self.max_observations))
+        return rows
+
+
+def csv_observations(text: str, limit: int = MAX_OBSERVATIONS) -> list[JsonValue]:
+    """Unfold a wide Chap CSV into one observation per feature cell, refusing more than the limit before any is built.
+
+    An empty cell is a missing value and is sent as null, which Chap reads as missing. A row
+    counts for every feature whether or not it has a cell for it, as it is unfolded.
+    """
+    reader = csv.DictReader(io.StringIO(text))
+    columns = reader.fieldnames or []
+    for column in (PERIOD_COLUMN, LOCATION_COLUMN):
+        if column not in columns:
+            raise BlockFailure(CSV_MISSING_COLUMN, error_class=ErrorClass.REJECTED, column=column)
+    features = [column for column in columns if column not in (PERIOD_COLUMN, LOCATION_COLUMN)]
+    count = len(features) * (sum(1 for row in csv.reader(io.StringIO(text)) if row) - 1)
+    if count > limit:
+        raise BlockFailure(CSV_TOO_LARGE, error_class=ErrorClass.REJECTED, count=count, limit=limit)
+    rows: list[JsonValue] = []
+    for line, record in enumerate(reader, start=2):
+        for feature in features:
+            rows.append(
+                {
+                    "period": record[PERIOD_COLUMN],
+                    "orgUnit": record[LOCATION_COLUMN],
+                    "featureName": feature,
+                    "value": _number(record.get(feature), feature, line),
+                }
+            )
+    return rows
+
+
+def _number(cell: str | None, column: str, line: int) -> float | None:
+    """Read one CSV cell as a number, an empty one or a NaN as missing."""
+    if cell is None or not cell.strip():
+        return None
+    try:
+        number = float(cell)
+    except ValueError as error:
+        raise BlockFailure(
+            CSV_BAD_VALUE, error_class=ErrorClass.REJECTED, column=column, line=line, value=cell
+        ) from error
+    return number if math.isfinite(number) else None

dirigent_contrib/chap/configured_models.py

@@ -0,0 +1,44 @@
+"""``chap.models.list``: the models a Chap server has configured, which a backtest names."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel, JsonValue
+
+from dirigent_common import BlockModel
+from dirigent_contrib.chap.connection import CONFIGURED_MODELS_PATH, client_for
+from dirigent_contrib.chap.messages import NOT_A_LIST
+from dirigent_contrib.chap.web import call_json
+from dirigent_plugin import BlockFailure, ConnectionRef, ErrorClass, Operator, OperatorSpec, StepContext
+
+
+class ChapModelsListConfig(BlockModel):
+    """Which server to list the models of."""
+
+    connection: ConnectionRef
+    """The code of the chap connection naming the server."""
+
+
+class ChapModelsListOutput(BlockModel):
+    """The configured models, as Chap describes them."""
+
+    models: list[JsonValue]
+    """Each configured model as Chap answers with it: its `id`, `name`, `covariates`, `target` and the rest."""
+
+    count: int
+    """How many models there are."""
+
+
+class ChapModelsListOperator(Operator[ChapModelsListConfig, ChapModelsListOutput]):
+    """Lists the configured models."""
+
+    spec = OperatorSpec(id="chap.models.list", summary="List the models a Chap server has configured.", idempotent=True)
+    config_model: ClassVar[type[BaseModel]] = ChapModelsListConfig
+    output_model: ClassVar[type[BaseModel]] = ChapModelsListOutput
+
+    async def execute(self, config: ChapModelsListConfig, ctx: StepContext) -> ChapModelsListOutput:
+        """Read the list once."""
+        async with client_for(ctx, config.connection) as client:
+            answer = await call_json(client, "GET", CONFIGURED_MODELS_PATH)
+        if not isinstance(answer, list):
+            raise BlockFailure(NOT_A_LIST, error_class=ErrorClass.UNKNOWN, where=f"GET {CONFIGURED_MODELS_PATH}")
+        return ChapModelsListOutput(models=list(answer), count=len(answer))