ushabti 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ushabti
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 Summary: SDK for Ushabti, an open-source DevOps agent harness: spells, implements, weighing, and papyrus.
 Keywords: devops,sre,agents,monitoring,kubernetes,proxmox,shabti,shawabti
 License-Expression: Apache-2.0
@@ -45,6 +45,8 @@ It holds the vocabulary every other package shares:
 pip install ushabti                 # core only
 pip install "ushabti[anthropic]"    # with the Anthropic SDK
 pip install "ushabti[openai]"       # with the OpenAI SDK, for any OpenAI-compatible endpoint
+pip install "ushabti[kubernetes]"   # with the Kubernetes client, for the kubernetes.* implements
+pip install "ushabti[prometheus]"   # with httpx, for the prometheus.* implements
 ```
 
 This is the only Ushabti package on PyPI. The agent and the overseer ship as container images,

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/README.md

@@ -14,6 +14,8 @@ It holds the vocabulary every other package shares:
 pip install ushabti                 # core only
 pip install "ushabti[anthropic]"    # with the Anthropic SDK
 pip install "ushabti[openai]"       # with the OpenAI SDK, for any OpenAI-compatible endpoint
+pip install "ushabti[kubernetes]"   # with the Kubernetes client, for the kubernetes.* implements
+pip install "ushabti[prometheus]"   # with httpx, for the prometheus.* implements
 ```
 
 This is the only Ushabti package on PyPI. The agent and the overseer ship as container images,

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ushabti"
-version = "0.1.0.dev0"
+version = "0.1.0.dev1"
 description = "SDK for Ushabti, an open-source DevOps agent harness: spells, implements, weighing, and papyrus."
 readme = "README.md"
 requires-python = ">=3.12"

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ushabti"
-version = "0.1.0.dev0"
+version = "0.1.0.dev1"
 description = "SDK for Ushabti, an open-source DevOps agent harness: spells, implements, weighing, and papyrus."
 readme = "README.md"
 requires-python = ">=3.12"

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/src/ushabti/errors.py

@@ -50,6 +50,14 @@ class UnknownImplementError(UshabtiError, LookupError):
         super().__init__(f"{name} is not a registered implement")
 
 
+class ImplementError(UshabtiError):
+    """An implement could not do its work: bad arguments, no endpoint, or a failed call.
+
+    The message is safe to record in Papyrus. It never carries a secret or a
+    credential-bearing URL.
+    """
+
+
 class UnweighedWriteError(UshabtiError):
     """An implement was asked to run without a PASS verdict from the weighing.
 

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/src/ushabti/field.py

@@ -25,7 +25,13 @@ class Field(StrictModel):
     """What the field is: `kubernetes`, `proxmox`, `prometheus`, or `service`."""
 
     namespaces: tuple[str, ...] = ()
-    """Kubernetes namespaces to tend. Only valid when `kind` is `kubernetes`."""
+    """Kubernetes namespaces to tend. The Kubernetes implements refuse any other
+    namespace. Only valid when `kind` is `kubernetes`."""
+
+    context: str | None = None
+    """Kubeconfig context to reach the cluster through when the ushabti runs outside
+    it. Inside a cluster the pod's service account is used and this is ignored. Only
+    valid when `kind` is `kubernetes`."""
 
     nodes: tuple[str, ...] = ()
     """Proxmox node names to tend. Only valid when `kind` is `proxmox`."""
@@ -39,4 +45,6 @@ class Field(StrictModel):
             raise ValueError("namespaces is only valid when kind is kubernetes")
         if self.nodes and self.kind is not FieldKind.PROXMOX:
             raise ValueError("nodes is only valid when kind is proxmox")
+        if self.context is not None and self.kind is not FieldKind.KUBERNETES:
+            raise ValueError("context is only valid when kind is kubernetes")
         return self

{ushabti-0.1.0.dev0 → ushabti-0.1.0.dev1}/src/ushabti/implements/__init__.py

@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING, ClassVar, Final, final
 from pydantic import JsonValue
 
 from ushabti._base import WireModel
-from ushabti.errors import UnknownImplementError, UnweighedWriteError
+from ushabti.errors import ImplementError, UnknownImplementError, UnweighedWriteError
 from ushabti.field import Field
 
 if TYPE_CHECKING:
@@ -167,6 +167,26 @@ class ImplementRegistry:
         return len(self._implements)
 
 
+def text_argument(implement: str, arguments: Mapping[str, JsonValue], key: str) -> str:
+    """A required text argument. Numbers are accepted and written out; anything else is refused."""
+    value = optional_text_argument(implement, arguments, key)
+    if value is None:
+        raise ImplementError(f"{implement}: the argument '{key}' is required")
+    return value
+
+
+def optional_text_argument(
+    implement: str, arguments: Mapping[str, JsonValue], key: str
+) -> str | None:
+    """An optional text argument: None when absent, ImplementError when it is not text."""
+    value = arguments.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, str | int | float):
+        raise ImplementError(f"{implement}: the argument '{key}' must be a string")
+    return str(value)
+
+
 def builtin_implements() -> tuple[Implement, ...]:
     """Fresh instances of every implement that ships with the SDK."""
     # Imported here because these modules import Implement from this one.

ushabti-0.1.0.dev1/src/ushabti/implements/kubernetes.py

@@ -0,0 +1,444 @@
+"""Kubernetes implements: pods and deployments through the Kubernetes API.
+
+The two read implements are built. The two write implements are still scaffold
+stubs. All four need the ``kubernetes`` extra: pip install "ushabti[kubernetes]".
+The extra is imported only when an implement runs, so the core imports without
+it.
+
+The field (the target) names the namespaces an ushabti tends, and may name a
+kubeconfig context for runs outside the cluster::
+
+    fields:
+      - name: homelab-k3s
+        kind: kubernetes
+        namespaces: [default, monitoring]
+        context: homelab   # only used outside the cluster
+
+Inside a cluster the pod's service account is used. Outside it, the kubeconfig
+that ``KUBECONFIG`` names, or ``~/.kube/config``, is read and never written. An
+implement refuses a namespace the field does not list before it makes any call:
+a spell can only look where it says it looks.
+
+Results are shaped for Ma'at conditions. ``kubernetes.list_pods`` exposes
+``not_ready``, the number of pods that are not running with every container
+ready, so a spell can write ``expect: {path: not_ready, op: eq, value: 0}``.
+``kubernetes.get_deployment`` exposes ``missing``, the desired replicas minus
+the ready ones.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
+
+from pydantic import JsonValue
+
+from ushabti._base import utc_now
+from ushabti.errors import ImplementError, MissingExtraError, UshabtiError
+from ushabti.field import Field, FieldKind
+from ushabti.implements import Implement, ImplementKind, optional_text_argument, text_argument
+
+if TYPE_CHECKING:
+    from kubernetes.aio.client import V1ContainerStatus, V1Deployment, V1Pod
+
+TIMEOUT_SECONDS: Final = 15.0
+_DETAIL_LIMIT: Final = 300
+
+_NAMESPACE: dict[str, JsonValue] = {
+    "type": "string",
+    "description": "Namespace to look in. Must be one of the field's namespaces.",
+}
+_DEPLOYMENT: dict[str, JsonValue] = {"type": "string", "description": "Name of the deployment."}
+
+
+@dataclass(frozen=True, slots=True)
+class Cluster:
+    """The API objects one call uses. Tests build one around fakes."""
+
+    core: Any
+    """A ``CoreV1Api``, for pods."""
+
+    apps: Any
+    """An ``AppsV1Api``, for deployments."""
+
+
+Connect = Callable[[Field], AbstractAsyncContextManager[Cluster]]
+"""Opens the field's cluster for the duration of one call."""
+
+
+class _KubernetesImplement(Implement):
+    """What the Kubernetes reads share: the namespace check and the connection."""
+
+    kind: ClassVar[ImplementKind] = ImplementKind.READ
+
+    def __init__(
+        self, *, connect: Connect | None = None, clock: Callable[[], datetime] = utc_now
+    ) -> None:
+        # Both are only given by tests: a fake cluster, and a fixed "now" for ages.
+        self._connect = connect
+        self._clock = clock
+
+    def _scope(self, arguments: Mapping[str, JsonValue], field: Field | None) -> tuple[Field, str]:
+        """The field and the namespace argument, refused unless the field lists it."""
+        namespace = text_argument(self.name, arguments, "namespace")
+        if field is None or field.kind is not FieldKind.KUBERNETES:
+            raise ImplementError(
+                f"{self.name} needs a field of kind kubernetes; "
+                "name one on the assertion or the summons"
+            )
+        if not field.namespaces:
+            raise ImplementError(
+                f"{self.name}: field {field.name} lists no namespaces; add the ones it tends"
+            )
+        if namespace not in field.namespaces:
+            raise ImplementError(
+                f"{self.name}: namespace {namespace} is not one of field {field.name}'s "
+                f"namespaces ({', '.join(field.namespaces)})"
+            )
+        return field, namespace
+
+    async def _call[T](self, field: Field, request: Callable[[Cluster], Awaitable[T]]) -> T:
+        """Open the cluster, make one request, and explain the client's failures."""
+        connect = _connect if self._connect is None else self._connect
+        try:
+            async with connect(field) as cluster:
+                return await request(cluster)
+        except UshabtiError:
+            raise
+        except Exception as error:
+            explained = _explain(self.name, error)
+            if explained is None:
+                raise
+            raise explained from error
+
+
+class ListPods(_KubernetesImplement):
+    """The pods of one namespace: phase, readiness, restarts, and what is wrong."""
+
+    name: ClassVar[str] = "kubernetes.list_pods"
+    description: ClassVar[str] = (
+        "List the pods in a namespace with their phase and readiness. Returns each pod, "
+        "the count, `not_ready` (pods that are not running with every container ready, "
+        "finished jobs excluded), the total restarts, and the reasons containers are "
+        "waiting or have failed, such as CrashLoopBackOff."
+    )
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {
+            "namespace": _NAMESPACE,
+            "label_selector": {
+                "type": "string",
+                "description": "Optional label selector, such as app=web.",
+            },
+        },
+        "required": ["namespace"],
+        "additionalProperties": False,
+    }
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        field, namespace = self._scope(arguments, field)
+        selector = optional_text_argument(self.name, arguments, "label_selector")
+
+        async def request(cluster: Cluster) -> Any:
+            return await cluster.core.list_namespaced_pod(
+                namespace, label_selector=selector, _request_timeout=TIMEOUT_SECONDS
+            )
+
+        listed = await self._call(field, request)
+        return _pods(namespace, selector, listed.items or [], self._clock())
+
+
+class GetDeployment(_KubernetesImplement):
+    """One deployment: how many replicas it wants, how many it has, and why not."""
+
+    name: ClassVar[str] = "kubernetes.get_deployment"
+    description: ClassVar[str] = (
+        "Get one deployment with its desired and ready replica counts. Returns the "
+        "counts under `replicas`, `missing` (desired minus ready), whether it is `ready`, "
+        "its conditions, and the images it runs."
+    )
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {"namespace": _NAMESPACE, "name": _DEPLOYMENT},
+        "required": ["namespace", "name"],
+        "additionalProperties": False,
+    }
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        field, namespace = self._scope(arguments, field)
+        name = text_argument(self.name, arguments, "name")
+
+        async def request(cluster: Cluster) -> Any:
+            return await cluster.apps.read_namespaced_deployment(
+                name, namespace, _request_timeout=TIMEOUT_SECONDS
+            )
+
+        deployment = await self._call(field, request)
+        return _deployment(namespace, name, deployment, self._clock())
+
+
+class RestartDeployment(Implement):
+    name: ClassVar[str] = "kubernetes.restart_deployment"
+    kind: ClassVar[ImplementKind] = ImplementKind.WRITE
+    description: ClassVar[str] = "Restart a deployment by rolling its pods."
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {"namespace": _NAMESPACE, "name": _DEPLOYMENT},
+        "required": ["namespace", "name"],
+        "additionalProperties": False,
+    }
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        # TODO(scaffold): trigger a rolling restart of the deployment with the Kubernetes client.
+        raise NotImplementedError(
+            "kubernetes.restart_deployment is a scaffold stub: the rolling restart through "
+            "the Kubernetes client (the `kubernetes` extra) is not implemented yet"
+        )
+
+
+class ScaleDeployment(Implement):
+    name: ClassVar[str] = "kubernetes.scale_deployment"
+    kind: ClassVar[ImplementKind] = ImplementKind.WRITE
+    description: ClassVar[str] = "Set the replica count of a deployment."
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {
+            "namespace": _NAMESPACE,
+            "name": _DEPLOYMENT,
+            "replicas": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Replica count to set.",
+            },
+        },
+        "required": ["namespace", "name", "replicas"],
+        "additionalProperties": False,
+    }
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        # TODO(scaffold): set the deployment's replica count with the Kubernetes client.
+        raise NotImplementedError(
+            "kubernetes.scale_deployment is a scaffold stub: scaling a deployment through "
+            "the Kubernetes client (the `kubernetes` extra) is not implemented yet"
+        )
+
+
+def implements() -> tuple[Implement, ...]:
+    return (ListPods(), GetDeployment(), RestartDeployment(), ScaleDeployment())
+
+
+# Reaching the cluster
+
+
+@asynccontextmanager
+async def _connect(field: Field) -> AsyncIterator[Cluster]:
+    """The field's cluster: this pod's service account, or a kubeconfig context."""
+    try:
+        from kubernetes.aio import client, config
+    except ImportError as error:
+        raise MissingExtraError("kubernetes", "kubernetes") from error
+
+    configuration = client.Configuration()
+    try:
+        config.load_incluster_config(client_configuration=configuration)  # type: ignore[no-untyped-call]
+    except config.ConfigException:
+        try:
+            # Never persist: a refreshed token is not written back to the kubeconfig.
+            await config.load_kube_config(  # type: ignore[no-untyped-call]
+                context=field.context, client_configuration=configuration, persist_config=False
+            )
+        except config.ConfigException as error:
+            raise ImplementError(
+                f"kubernetes: no cluster to reach for field {field.name}: not inside one, "
+                f"and no kubeconfig could be loaded ({error})"
+            ) from error
+    async with client.ApiClient(configuration) as api:
+        yield Cluster(core=client.CoreV1Api(api), apps=client.AppsV1Api(api))
+
+
+def _explain(name: str, error: Exception) -> ImplementError | None:
+    """The ImplementError for a failure of the client, or None when the error is not one."""
+    try:
+        import aiohttp
+        from kubernetes.aio.client import ApiException
+    except ImportError:  # pragma: no cover  (only with the extra half installed)
+        return None
+    if isinstance(error, ApiException):
+        return ImplementError(
+            f"{name}: the cluster answered HTTP {error.status} ({error.reason}): "
+            f"{_detail(error.body)}"
+        )
+    if isinstance(error, aiohttp.ClientError | TimeoutError | OSError):
+        # The error text can carry the server address; the type name is enough.
+        return ImplementError(f"{name}: could not reach the cluster ({type(error).__name__})")
+    return None
+
+
+def _detail(body: object) -> str:
+    """The message of an API Status body, or the body itself, cut short."""
+    text = body.decode(errors="replace") if isinstance(body, bytes) else str(body or "")
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        parsed = None
+    message = parsed.get("message") if isinstance(parsed, dict) else None
+    detail = str(message) if message else text
+    return detail[:_DETAIL_LIMIT] or "no detail given"
+
+
+# Shaping the results
+
+
+@dataclass(frozen=True, slots=True)
+class _Pod:
+    name: str | None
+    phase: str | None
+    ready: bool
+    containers_ready: int
+    containers: int
+    restarts: int
+    reasons: tuple[str, ...]
+    node: str | None
+    age_seconds: int | None
+
+    def as_json(self) -> dict[str, JsonValue]:
+        return {
+            "name": self.name,
+            "phase": self.phase,
+            "ready": self.ready,
+            "containers_ready": self.containers_ready,
+            "containers": self.containers,
+            "restarts": self.restarts,
+            "reasons": list(self.reasons),
+            "node": self.node,
+            "age_seconds": self.age_seconds,
+        }
+
+
+def _pods(
+    namespace: str, selector: str | None, items: list[V1Pod], now: datetime
+) -> dict[str, JsonValue]:
+    pods = [_pod(item, now) for item in items]
+    counted = Counter(pod.phase or "Unknown" for pod in pods)
+    phases: dict[str, JsonValue] = dict(sorted(counted.items()))
+    reasons = cast("list[JsonValue]", sorted({reason for pod in pods for reason in pod.reasons}))
+    listed: list[JsonValue] = [pod.as_json() for pod in pods]
+    return {
+        "namespace": namespace,
+        "label_selector": selector,
+        "count": len(pods),
+        "not_ready": sum(1 for pod in pods if not pod.ready and pod.phase != "Succeeded"),
+        "restarts": sum(pod.restarts for pod in pods),
+        "phases": phases,
+        "reasons": reasons,
+        "pods": listed,
+    }
+
+
+def _pod(item: V1Pod, now: datetime) -> _Pod:
+    metadata, spec, status = item.metadata, item.spec, item.status
+    statuses = list(status.container_statuses or []) if status is not None else []
+    init_statuses = list(status.init_container_statuses or []) if status is not None else []
+    containers = len(spec.containers) if spec is not None else len(statuses)
+    containers_ready = sum(1 for container in statuses if container.ready)
+    phase = status.phase if status is not None else None
+    reasons: set[str] = set()
+    if status is not None and status.reason:
+        reasons.add(status.reason)
+    for container in (*init_statuses, *statuses):
+        reasons.update(_container_reasons(container))
+    return _Pod(
+        name=metadata.name if metadata is not None else None,
+        phase=phase,
+        ready=phase == "Running" and containers > 0 and containers_ready == containers,
+        containers_ready=containers_ready,
+        containers=containers,
+        restarts=sum(container.restart_count for container in statuses),
+        reasons=tuple(sorted(reasons)),
+        node=spec.node_name if spec is not None else None,
+        age_seconds=_age(metadata.creation_timestamp if metadata is not None else None, now),
+    )
+
+
+def _container_reasons(status: V1ContainerStatus) -> set[str]:
+    """Why a container is waiting or has stopped, such as CrashLoopBackOff."""
+    found: set[str] = set()
+    state = status.state
+    if state is None:
+        return found
+    if state.waiting is not None and state.waiting.reason:
+        found.add(state.waiting.reason)
+    stopped = state.terminated.reason if state.terminated is not None else None
+    if stopped and stopped != "Completed":
+        found.add(stopped)
+    return found
+
+
+def _deployment(
+    namespace: str, name: str, deployment: V1Deployment, now: datetime
+) -> dict[str, JsonValue]:
+    metadata, spec, status = deployment.metadata, deployment.spec, deployment.status
+    desired = spec.replicas if spec.replicas is not None else 1
+    ready = _count(status.ready_replicas if status is not None else None)
+    generation = metadata.generation if metadata is not None else None
+    observed = status.observed_generation if status is not None else None
+    current = generation is None or observed is None or observed >= generation
+    missing = max(desired - ready, 0)
+    conditions: list[JsonValue] = [
+        {
+            "type": condition.type,
+            "status": condition.status,
+            "reason": condition.reason,
+            "message": condition.message,
+            "since": (
+                condition.last_transition_time.isoformat()
+                if condition.last_transition_time is not None
+                else None
+            ),
+        }
+        for condition in (status.conditions or [] if status is not None else [])
+    ]
+    template = spec.template.spec
+    images: list[JsonValue] = [
+        container.image
+        for container in (template.containers if template is not None else [])
+        if container.image
+    ]
+    return {
+        "namespace": namespace,
+        "name": name,
+        "replicas": {
+            "desired": desired,
+            "ready": ready,
+            "available": _count(status.available_replicas if status is not None else None),
+            "updated": _count(status.updated_replicas if status is not None else None),
+            "unavailable": _count(status.unavailable_replicas if status is not None else None),
+        },
+        "missing": missing,
+        "ready": missing == 0 and current,
+        "paused": bool(spec.paused),
+        "generation": generation,
+        "observed_generation": observed,
+        "strategy": spec.strategy.type if spec.strategy is not None else None,
+        "images": images,
+        "conditions": conditions,
+        "age_seconds": _age(metadata.creation_timestamp if metadata is not None else None, now),
+    }
+
+
+def _count(value: int | None) -> int:
+    return 0 if value is None else value
+
+
+def _age(created: datetime | None, now: datetime) -> int | None:
+    """Seconds since creation. A naive timestamp is taken as UTC."""
+    if created is None:
+        return None
+    if created.tzinfo is None:
+        created = created.replace(tzinfo=UTC)
+    return max(int((now - created).total_seconds()), 0)

ushabti-0.1.0.dev1/src/ushabti/implements/prometheus.py

@@ -0,0 +1,286 @@
+"""Prometheus implements: instant and range queries over the HTTP API.
+
+Both are read implements. They need the ``prometheus`` extra, which is httpx:
+pip install "ushabti[prometheus]". The extra is imported only when a query
+runs, so the core imports without it.
+
+The field (the target) names the server::
+
+    fields:
+      - name: homelab-metrics
+        kind: prometheus
+        endpoint: ${PROMETHEUS_URL}
+
+The endpoint is resolved when the implement runs, so it may be an environment
+reference. It is never written to Papyrus: an observation holds the query and
+the result, nothing about where they came from.
+
+Results are shaped for Ma'at conditions. An instant query that returns one
+sample exposes it at ``value``, so a spell can write
+``expect: {path: value, op: lt, value: 90}``. A range query with one series
+exposes ``last``, ``min``, and ``max``. ``NaN`` and infinities become ``null``,
+which Ma'at treats as unknown rather than as drift.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
+
+from pydantic import JsonValue
+
+from ushabti.errors import ImplementError, MissingExtraError, UnresolvedEnvError
+from ushabti.field import Field, FieldKind
+from ushabti.implements import Implement, ImplementKind, optional_text_argument, text_argument
+from ushabti.spell import expand_env
+
+if TYPE_CHECKING:
+    import httpx
+
+TIMEOUT_SECONDS: Final = 15.0
+_REASON_LIMIT: Final = 300
+
+_QUERY: dict[str, JsonValue] = {"type": "string", "description": "PromQL expression to evaluate."}
+_TIME: dict[str, JsonValue] = {
+    "type": "string",
+    "description": "Evaluation time, RFC 3339 or Unix seconds. Defaults to now.",
+}
+
+
+class _PrometheusImplement(Implement):
+    """What the two queries share: find the endpoint, call it, shape the errors."""
+
+    kind: ClassVar[ImplementKind] = ImplementKind.READ
+    path: ClassVar[str]
+
+    def __init__(
+        self,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        timeout: float = TIMEOUT_SECONDS,
+    ) -> None:
+        # A transport is only given by tests, to answer without a network.
+        self._transport = transport
+        self._timeout = timeout
+
+    async def _call(self, field: Field | None, params: dict[str, str]) -> dict[str, Any]:
+        base_url = _endpoint(self.name, field)
+        try:
+            import httpx
+        except ImportError as error:
+            raise MissingExtraError("prometheus", "httpx") from error
+        try:
+            async with httpx.AsyncClient(
+                base_url=base_url, timeout=self._timeout, transport=self._transport
+            ) as client:
+                response = await client.get(self.path, params=params)
+        except httpx.HTTPError as error:
+            # The error text can carry the URL, which can carry credentials.
+            raise ImplementError(
+                f"{self.name}: could not reach Prometheus ({type(error).__name__})"
+            ) from error
+        return _data(self.name, response)
+
+
+class Query(_PrometheusImplement):
+    """An instant query: the value of an expression at one point in time."""
+
+    name: ClassVar[str] = "prometheus.query"
+    description: ClassVar[str] = (
+        "Evaluate a PromQL expression at a single point in time. Returns the samples "
+        "with their labels, their count, and, when there is exactly one sample, its "
+        "number at `value`."
+    )
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {"query": _QUERY, "time": _TIME},
+        "required": ["query"],
+        "additionalProperties": False,
+    }
+    path: ClassVar[str] = "/api/v1/query"
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        query = text_argument(self.name, arguments, "query")
+        params = {"query": query}
+        at = optional_text_argument(self.name, arguments, "time")
+        if at is not None:
+            params["time"] = at
+        data = await self._call(field, params)
+        return _shape(self.name, query, data)
+
+
+class QueryRange(_PrometheusImplement):
+    """A range query: the values of an expression over a window of time."""
+
+    name: ClassVar[str] = "prometheus.query_range"
+    description: ClassVar[str] = (
+        "Evaluate a PromQL expression over a time range. Returns one series per label "
+        "set, each with its values and its first, last, min, and max, and, when there "
+        "is exactly one series, those four numbers at the top level."
+    )
+    parameters: ClassVar[Mapping[str, JsonValue]] = {
+        "type": "object",
+        "properties": {
+            "query": _QUERY,
+            "start": {
+                "type": "string",
+                "description": "Start of the range, RFC 3339 or Unix seconds.",
+            },
+            "end": {"type": "string", "description": "End of the range, RFC 3339 or Unix seconds."},
+            "step": {"type": "string", "description": "Resolution step, such as 60s, or seconds."},
+        },
+        "required": ["query", "start", "end", "step"],
+        "additionalProperties": False,
+    }
+    path: ClassVar[str] = "/api/v1/query_range"
+
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        params: dict[str, str] = {}
+        for key in ("query", "start", "end", "step"):
+            params[key] = text_argument(self.name, arguments, key)
+        data = await self._call(field, params)
+        return _shape(self.name, params["query"], data)
+
+
+def implements() -> tuple[Implement, ...]:
+    return (Query(), QueryRange())
+
+
+# Reaching the server
+
+
+def _endpoint(name: str, field: Field | None) -> str:
+    if field is None or field.kind is not FieldKind.PROMETHEUS:
+        raise ImplementError(
+            f"{name} needs a field of kind prometheus; name one on the assertion or the summons"
+        )
+    if not field.endpoint:
+        raise ImplementError(
+            f"{name}: field {field.name} has no endpoint; set it to the Prometheus base URL, "
+            "usually as ${PROMETHEUS_URL}"
+        )
+    try:
+        return expand_env(field.endpoint)
+    except UnresolvedEnvError as error:
+        raise ImplementError(f"{name}: field {field.name}: {error}") from None
+
+
+def _data(name: str, response: httpx.Response) -> dict[str, Any]:
+    try:
+        body = response.json()
+    except ValueError:
+        raise ImplementError(
+            f"{name}: Prometheus answered HTTP {response.status_code} with a body that is not JSON"
+        ) from None
+    if not isinstance(body, dict):
+        raise ImplementError(
+            f"{name}: Prometheus answered HTTP {response.status_code} with no object"
+        )
+    if body.get("status") != "success":
+        kind = body.get("errorType") or f"HTTP {response.status_code}"
+        reason = str(body.get("error") or "no reason given")[:_REASON_LIMIT]
+        raise ImplementError(f"{name}: Prometheus rejected the query ({kind}): {reason}")
+    data = body.get("data")
+    if not isinstance(data, dict):
+        raise ImplementError(f"{name}: Prometheus answered without a data object")
+    return data
+
+
+# Shaping the result
+
+
+def _shape(name: str, query: str, data: dict[str, Any]) -> dict[str, JsonValue]:
+    result_type = data.get("resultType")
+    result = data.get("result")
+    try:
+        if result_type == "vector":
+            return _vector(query, result)
+        if result_type == "scalar":
+            return _scalar(query, result)
+        if result_type == "string":
+            return _string(query, result)
+        if result_type == "matrix":
+            return _matrix(query, result)
+    except (KeyError, IndexError, TypeError, ValueError):
+        raise ImplementError(
+            f"{name}: Prometheus returned a {result_type} in an unexpected shape"
+        ) from None
+    raise ImplementError(f"{name}: Prometheus returned an unknown result type: {result_type!r}")
+
+
+def _vector(query: str, result: Any) -> dict[str, JsonValue]:
+    samples: list[JsonValue] = [
+        {
+            "metric": dict(item.get("metric", {})),
+            "timestamp": float(item["value"][0]),
+            "value": _number(item["value"][1]),
+        }
+        for item in result
+    ]
+    only = samples[0] if len(samples) == 1 else None
+    return {
+        "query": query,
+        "result_type": "vector",
+        "count": len(samples),
+        "value": only["value"] if isinstance(only, dict) else None,
+        "samples": samples,
+    }
+
+
+def _scalar(query: str, result: Any) -> dict[str, JsonValue]:
+    timestamp, text = result
+    value = _number(text)
+    return {
+        "query": query,
+        "result_type": "scalar",
+        "count": 1,
+        "value": value,
+        "samples": [{"metric": {}, "timestamp": float(timestamp), "value": value}],
+    }
+
+
+def _string(query: str, result: Any) -> dict[str, JsonValue]:
+    timestamp, text = result
+    return {
+        "query": query,
+        "result_type": "string",
+        "count": 1,
+        "value": None,
+        "text": str(text),
+        "timestamp": float(timestamp),
+    }
+
+
+def _matrix(query: str, result: Any) -> dict[str, JsonValue]:
+    series: list[dict[str, JsonValue]] = []
+    for item in result:
+        points: list[JsonValue] = [[float(ts), _number(text)] for ts, text in item["values"]]
+        numbers = [p[1] for p in points if isinstance(p, list) and isinstance(p[1], float)]
+        series.append(
+            {
+                "metric": dict(item.get("metric", {})),
+                "values": points,
+                "first": numbers[0] if numbers else None,
+                "last": numbers[-1] if numbers else None,
+                "min": min(numbers) if numbers else None,
+                "max": max(numbers) if numbers else None,
+            }
+        )
+    only = series[0] if len(series) == 1 else None
+    return {
+        "query": query,
+        "result_type": "matrix",
+        "count": len(series),
+        "first": only["first"] if only else None,
+        "last": only["last"] if only else None,
+        "min": only["min"] if only else None,
+        "max": only["max"] if only else None,
+        "series": cast("list[JsonValue]", series),
+    }
+
+
+def _number(text: Any) -> float | None:
+    """A sample value as a float, or None for NaN and infinities, which JSON cannot hold."""
+    value = float(text)
+    return value if math.isfinite(value) else None

ushabti-0.1.0.dev0/src/ushabti/implements/kubernetes.py

@@ -1,112 +0,0 @@
-"""Kubernetes implements. Scaffold stubs: the operations are declared, not built.
-
-Real versions need the ``kubernetes`` extra: pip install "ushabti[kubernetes]"
-"""
-
-from collections.abc import Mapping
-from typing import ClassVar
-
-from pydantic import JsonValue
-
-from ushabti.field import Field
-from ushabti.implements import Implement, ImplementKind
-
-_NAMESPACE: dict[str, JsonValue] = {
-    "type": "string",
-    "description": "Namespace to look in. Must be one of the field's namespaces.",
-}
-_DEPLOYMENT: dict[str, JsonValue] = {"type": "string", "description": "Name of the deployment."}
-
-
-class ListPods(Implement):
-    name: ClassVar[str] = "kubernetes.list_pods"
-    kind: ClassVar[ImplementKind] = ImplementKind.READ
-    description: ClassVar[str] = "List the pods in a namespace with their phase and readiness."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {
-            "namespace": _NAMESPACE,
-            "label_selector": {
-                "type": "string",
-                "description": "Optional label selector, such as app=web.",
-            },
-        },
-        "required": ["namespace"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): list pods in the field's cluster with the Kubernetes client.
-        raise NotImplementedError(
-            "kubernetes.list_pods is a scaffold stub: listing pods through the "
-            "Kubernetes client (the `kubernetes` extra) is not implemented yet"
-        )
-
-
-class GetDeployment(Implement):
-    name: ClassVar[str] = "kubernetes.get_deployment"
-    kind: ClassVar[ImplementKind] = ImplementKind.READ
-    description: ClassVar[str] = "Get one deployment with its desired and ready replica counts."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {"namespace": _NAMESPACE, "name": _DEPLOYMENT},
-        "required": ["namespace", "name"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): read the deployment and its status with the Kubernetes client.
-        raise NotImplementedError(
-            "kubernetes.get_deployment is a scaffold stub: reading a deployment through "
-            "the Kubernetes client (the `kubernetes` extra) is not implemented yet"
-        )
-
-
-class RestartDeployment(Implement):
-    name: ClassVar[str] = "kubernetes.restart_deployment"
-    kind: ClassVar[ImplementKind] = ImplementKind.WRITE
-    description: ClassVar[str] = "Restart a deployment by rolling its pods."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {"namespace": _NAMESPACE, "name": _DEPLOYMENT},
-        "required": ["namespace", "name"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): trigger a rolling restart of the deployment with the Kubernetes client.
-        raise NotImplementedError(
-            "kubernetes.restart_deployment is a scaffold stub: the rolling restart through "
-            "the Kubernetes client (the `kubernetes` extra) is not implemented yet"
-        )
-
-
-class ScaleDeployment(Implement):
-    name: ClassVar[str] = "kubernetes.scale_deployment"
-    kind: ClassVar[ImplementKind] = ImplementKind.WRITE
-    description: ClassVar[str] = "Set the replica count of a deployment."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {
-            "namespace": _NAMESPACE,
-            "name": _DEPLOYMENT,
-            "replicas": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Replica count to set.",
-            },
-        },
-        "required": ["namespace", "name", "replicas"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): set the deployment's replica count with the Kubernetes client.
-        raise NotImplementedError(
-            "kubernetes.scale_deployment is a scaffold stub: scaling a deployment through "
-            "the Kubernetes client (the `kubernetes` extra) is not implemented yet"
-        )
-
-
-def implements() -> tuple[Implement, ...]:
-    return (ListPods(), GetDeployment(), RestartDeployment(), ScaleDeployment())

ushabti-0.1.0.dev0/src/ushabti/implements/prometheus.py

@@ -1,61 +0,0 @@
-"""Prometheus implements. Scaffold stubs: the operations are declared, not built.
-
-Real versions need the ``prometheus`` extra: pip install "ushabti[prometheus]"
-"""
-
-from collections.abc import Mapping
-from typing import ClassVar
-
-from pydantic import JsonValue
-
-from ushabti.field import Field
-from ushabti.implements import Implement, ImplementKind
-
-_QUERY: dict[str, JsonValue] = {"type": "string", "description": "PromQL expression to evaluate."}
-
-
-class Query(Implement):
-    name: ClassVar[str] = "prometheus.query"
-    kind: ClassVar[ImplementKind] = ImplementKind.READ
-    description: ClassVar[str] = "Evaluate a PromQL expression at a single point in time."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {"query": _QUERY},
-        "required": ["query"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): send an instant query to the field's Prometheus endpoint over HTTP.
-        raise NotImplementedError(
-            "prometheus.query is a scaffold stub: the instant query over HTTP "
-            "(httpx, the `prometheus` extra) is not implemented yet"
-        )
-
-
-class QueryRange(Implement):
-    name: ClassVar[str] = "prometheus.query_range"
-    kind: ClassVar[ImplementKind] = ImplementKind.READ
-    description: ClassVar[str] = "Evaluate a PromQL expression over a time range."
-    parameters: ClassVar[Mapping[str, JsonValue]] = {
-        "type": "object",
-        "properties": {
-            "query": _QUERY,
-            "start": {"type": "string", "description": "Start of the range, RFC 3339."},
-            "end": {"type": "string", "description": "End of the range, RFC 3339."},
-            "step": {"type": "string", "description": "Resolution step, such as 60s."},
-        },
-        "required": ["query", "start", "end", "step"],
-        "additionalProperties": False,
-    }
-
-    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
-        # TODO(scaffold): send a range query to the field's Prometheus endpoint over HTTP.
-        raise NotImplementedError(
-            "prometheus.query_range is a scaffold stub: the range query over HTTP "
-            "(httpx, the `prometheus` extra) is not implemented yet"
-        )
-
-
-def implements() -> tuple[Implement, ...]:
-    return (Query(), QueryRange())