beaker-sdk 0.3.5__py3-none-any.whl

beaker/__init__.py

@@ -0,0 +1,126 @@
+"""Beaker SDK package.
+
+``beaker`` gives developers the contract types, decorators, client, and CLI
+support needed to define optimization specs, validate them locally, upload
+datasets, launch hosted optimization runs, and inspect results.
+
+The spec-authoring contract surface is exported directly from this module, so
+customer specs can write ``from beaker import Spec, Case, OptimizationTargets``
+without going through an internal-looking submodule. The optional
+custom-finalizer types (``OptimizationFinalizerResult``, ``OptimizationCandidateRecord``,
+``OptimizationEvalReportRecord``, and friends) are advanced and live under
+``beaker.sdk`` — this keeps the headline surface on spec authoring and stops
+``OptimizationCandidateRecord`` (an optimizer *output*) from sitting beside
+``OptimizationTargets`` (your *input*) as a look-alike. The HTTP client remains
+lazy-loaded so build-worker and bundle-inspection paths that only need SDK
+contracts do not import client/config dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from beaker.dataset_schema import STANDARD_JSONL_CASE_SCHEMA, DatasetSchema
+from beaker.sdk import (
+    Case,
+    CaseDataLoader,
+    CaseFailure,
+    CaseResult,
+    CaseScore,
+    CaseScorer,
+    ContextSearchEvidence,
+    DatasetRowContext,
+    DirectoryResource,
+    ErrorOutput,
+    EvaluationReport,
+    Evidence,
+    EvidenceProvider,
+    FieldConfig,
+    FieldDiff,
+    InferenceTarget,
+    OptimizationContext,
+    OptimizationTargets,
+    Result,
+    RolloutBatch,
+    RolloutContext,
+    RunCase,
+    Spec,
+    SpecRegistration,
+    Trajectory,
+    ValueNormalizer,
+    build_cases_by_split,
+    extract_field_from_object,
+    inference_target,
+    load_cases_by_split,
+    load_spec_from_target,
+    materialize_dataset,
+    objective_score,
+    optimization_targets_from_prompts,
+    result_to_dict,
+    serialize_cases,
+    spec,
+    validate_spec,
+)
+
+
+if TYPE_CHECKING:
+    from beaker.client import BeakerClient, BeakerClientError
+
+
+__version__ = "0.3.5"
+
+__all__ = [
+    "Case",
+    "CaseDataLoader",
+    "CaseFailure",
+    "CaseResult",
+    "CaseScore",
+    "CaseScorer",
+    "ContextSearchEvidence",
+    "BeakerClient",
+    "BeakerClientError",
+    "DatasetSchema",
+    "DatasetRowContext",
+    "ErrorOutput",
+    "EvaluationReport",
+    "Evidence",
+    "EvidenceProvider",
+    "FieldConfig",
+    "FieldDiff",
+    "InferenceTarget",
+    "OptimizationContext",
+    "OptimizationTargets",
+    "Result",
+    "RolloutBatch",
+    "RolloutContext",
+    "RunCase",
+    "Spec",
+    "SpecRegistration",
+    "STANDARD_JSONL_CASE_SCHEMA",
+    "Trajectory",
+    "ValueNormalizer",
+    "__version__",
+    "build_cases_by_split",
+    "extract_field_from_object",
+    "inference_target",
+    "load_cases_by_split",
+    "load_spec_from_target",
+    "materialize_dataset",
+    "objective_score",
+    "DirectoryResource",
+    "optimization_targets_from_prompts",
+    "result_to_dict",
+    "serialize_cases",
+    "spec",
+    "validate_spec",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazily expose HTTP client types; SDK contract types are eager exports."""
+
+    if name in {"BeakerClient", "BeakerClientError"}:
+        from beaker import client as _client
+
+        return getattr(_client, name)
+    raise AttributeError(f"module 'beaker' has no attribute {name!r}")

beaker/_bundle_digest.py

@@ -0,0 +1,59 @@
+"""Shared bundle-digest algorithm for spec source bundles.
+
+The digest binds a spec version to the exact source tree it was built
+from: it's computed over a bundle's files before upload and recomputed
+after extraction, and the two must match. This prevents a source change
+between hashing and packaging, or a stale upload, from producing a build
+whose contents differ from what was recorded.
+
+Both computations must agree byte-for-byte on the input to ``sha256``.
+The canonical input for one file is::
+
+    rel_posix.encode("utf-8") || 0x00 || file_content || 0x00
+
+concatenated in ascending ``rel_posix`` order over every regular file in
+the bundle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from pathlib import Path
+
+
+_CHUNK_SIZE = 64 * 1024
+
+
+def digest_bundle_files(files: Iterable[tuple[str, Path]]) -> str:
+    """Hash a sequence of ``(rel_posix, file_path)`` pairs into a sha256 hex.
+
+    Callers must supply pairs already sorted by ``rel_posix`` so the
+    digest is order-stable.
+    """
+    digest = hashlib.sha256()
+    for rel_posix, file_path in files:
+        digest.update(rel_posix.encode("utf-8"))
+        digest.update(b"\x00")
+        with file_path.open("rb") as fh:
+            for chunk in iter(lambda: fh.read(_CHUNK_SIZE), b""):
+                digest.update(chunk)
+        digest.update(b"\x00")
+    return digest.hexdigest()
+
+
+def digest_extracted_bundle(root: Path) -> str:
+    """Hash every regular file under ``root`` in ``sorted(rglob("*"))`` order.
+
+    Used to recompute the digest over an already-extracted bundle. Any
+    file filtering must be applied before packaging, so the walk here is
+    unfiltered and its result matches a :func:`digest_bundle_files` digest
+    of the same files.
+    """
+    files: list[tuple[str, Path]] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        rel_posix = path.relative_to(root).as_posix()
+        files.append((rel_posix, path))
+    return digest_bundle_files(files)

beaker/_image_dependency_validation.py

@@ -0,0 +1,171 @@
+"""Validation for managed-environment ``pip_install`` / ``apt_install`` entries.
+
+These strings are forwarded to ``pip install <entry>`` /
+``apt-get install <entry>`` while preparing an optimization environment, so
+entries that smuggle in flags, extra tokens, shell metacharacters, or bare URLs
+are rejected before they can reconfigure package managers. The same rules are
+enforced for every client, not just the CLI.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+
+# Distribution names customers cannot pin themselves: these packages are managed
+# by Beaker so the execution environment stays compatible with the service.
+RESERVED_PIP_INSTALL_NAMES: frozenset[str] = frozenset(
+    {
+        "beaker-sdk",
+        "beaker" + "-runtime",
+    }
+)
+
+_PIP_REQUIREMENT_NAME_RE = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)")
+
+# Shell metacharacters that have no legitimate place in a PEP 508 spec.
+# Each entry is passed to ``pip install <entry>``, so any of these would
+# let it escape its argument slot. Whitespace is rejected separately
+# below because a multi-token entry like ``"--index-url http://x pkg"``
+# would split into two arguments and reconfigure the resolver.
+_PIP_FORBIDDEN_CHARS: frozenset[str] = frozenset({";", "|", "&", "`", "$", "\n", "\r", "\t"})
+
+# Bare-URL prefixes pip accepts as a full requirement. Without a leading
+# ``name @``, pip will fetch and execute setup.py / build hooks from
+# whatever the URL points to. The ``name @ <https-url>`` form is allowed
+# because the distribution is named explicitly; bare URLs are refused.
+_PIP_BARE_URL_SCHEMES: tuple[str, ...] = (
+    "http://",
+    "https://",
+    "ftp://",
+    "file://",
+    "git+",
+    "hg+",
+    "svn+",
+    "bzr+",
+    "ssh://",
+)
+
+# Allowed apt entry shape: a Debian package name, optionally pinned to
+# a specific version (``name=version``). Excludes shell metacharacters,
+# whitespace, flags, repository specs, and anything else that would let
+# an entry reconfigure ``apt-get`` (``-t target-release``,
+# ``-o Dpkg::Options::=...``, etc.).
+_APT_ENTRY_RE = re.compile(r"^[a-z0-9][a-z0-9.+\-]*(?:=[A-Za-z0-9.+:~\-]+)?$")
+
+
+class ImageInstallValidationError(ValueError):
+    """Raised when a ``pip_install`` / ``apt_install`` entry is unsafe.
+
+    Subclasses :class:`ValueError` so callers can treat it as a standard
+    validation error.
+    """
+
+
+def canonicalize_distribution_name(value: str) -> str:
+    """PEP 503-normalize the leading distribution name in a pip spec.
+
+    ``beaker-sdk``, ``BEAKER_SDK``, ``beaker-sdk[aws]``, and
+    ``beaker-sdk==0.1.0`` all
+    canonicalize consistently so the
+    reserved-name check works regardless of casing, extras, or pinning
+    syntax.
+    """
+    match = _PIP_REQUIREMENT_NAME_RE.match(value)
+    if match is None:
+        return ""
+    return re.sub(r"[-_.]+", "-", match.group(1)).lower()
+
+
+def validate_pip_install_entries(pip_install: Sequence[str]) -> None:
+    """Reject pip entries that are unsafe to install.
+
+    Each string is passed to ``pip install``. An entry starting with
+    ``-`` is treated as a flag (``--index-url``, ``-e <url>``, ``-r``)
+    that could redirect the resolver or pull in arbitrary code, and a
+    bare URL (``https://...``, ``git+...``) tells pip to fetch and run
+    setup hooks from that URL. Only PEP 508 requirements are allowed,
+    including the explicitly-named ``name @ https://...`` form.
+    """
+    for entry in pip_install:
+        if canonicalize_distribution_name(entry) in RESERVED_PIP_INSTALL_NAMES:
+            raise ImageInstallValidationError(
+                f"pip_install {entry!r} is not allowed: Beaker-managed "
+                "packages are pinned automatically. Remove this entry from "
+                "your pip-install list."
+            )
+        stripped = entry.strip()
+        if not stripped:
+            raise ImageInstallValidationError("pip_install entries must be non-empty.")
+        if stripped.startswith("-"):
+            raise ImageInstallValidationError(
+                f"pip_install {entry!r} is not allowed: pip flags (entries "
+                "starting with '-') cannot be passed through. Use a PEP 508 "
+                "requirement spec like 'pkg==1.2' or 'pkg @ https://...'."
+            )
+        forbidden = _PIP_FORBIDDEN_CHARS.intersection(stripped)
+        if forbidden:
+            raise ImageInstallValidationError(
+                f"pip_install {entry!r} contains shell metacharacters "
+                f"({''.join(sorted(forbidden))!r}); refuse to forward."
+            )
+        # Reject internal whitespace EXCEPT the single ``name @ url``
+        # form, which PEP 508 requires to contain spaces around the
+        # ``@``.
+        if any(ch.isspace() for ch in stripped) and " @ " not in stripped:
+            raise ImageInstallValidationError(
+                f"pip_install {entry!r} contains whitespace; pass exactly "
+                "one PEP 508 requirement per entry (no embedded flags or "
+                "multi-token strings)."
+            )
+        # If this is the URL-requirement form, the URL portion has to be
+        # HTTPS. PEP 508 spells it ``name @ url``, but pip also accepts
+        # ``name@url`` with no spaces, so an entry like ``pkg@file:///x``
+        # would slip past the bare-URL and whitespace checks. Partition
+        # on the first ``@`` so both shapes are gated here. Non-HTTPS
+        # schemes (``file://``, ``git+``, ``ssh://``, ``http://`` and
+        # other VCS/transport schemes) can make pip read local files or
+        # fetch and execute remote code, so they're refused.
+        if "@" in stripped:
+            name_portion, _, url_portion = stripped.partition("@")
+            # The distribution name before ``@`` must be a real PEP 508
+            # name. An entry like ``"@https://wrong.example/x.tar.gz"`` has
+            # no name before ``@`` and would otherwise pass the checks
+            # below, so require a well-formed name here.
+            if not _PIP_REQUIREMENT_NAME_RE.match(name_portion):
+                raise ImageInstallValidationError(
+                    f"pip_install {entry!r} is missing a distribution "
+                    "name before '@'. Use 'name @ https://...' (or "
+                    "'name@https://...') with an explicit PEP 508 name."
+                )
+            if not url_portion.strip().lower().startswith("https://"):
+                raise ImageInstallValidationError(
+                    f"pip_install {entry!r} has a non-https URL after '@'. "
+                    "Only 'name @ https://...' (or 'name@https://...') is "
+                    "allowed; file://, http://, git+, ssh://, ftp://, and "
+                    "VCS schemes can let pip resolve to arbitrary code or "
+                    "read sensitive files during environment preparation."
+                )
+        if any(stripped.lower().startswith(scheme) for scheme in _PIP_BARE_URL_SCHEMES):
+            raise ImageInstallValidationError(
+                f"pip_install {entry!r} is a bare URL; use the 'name @ https://...' form so the distribution is named."
+            )
+
+
+def validate_apt_install_entries(apt_install: Sequence[str]) -> None:
+    """Reject apt entries that aren't a plain ``name`` or ``name=version``.
+
+    Each string is passed to ``apt-get install``, so an entry like
+    ``"-t bullseye-backports libfoo"`` or
+    ``"-o APT::Get::AllowUnauthenticated=true libfoo"`` would reconfigure
+    the package manager. The allowed shape forbids whitespace, flags,
+    repository overrides, and shell metacharacters.
+    """
+    for entry in apt_install:
+        if not _APT_ENTRY_RE.fullmatch(entry):
+            raise ImageInstallValidationError(
+                f"apt_install {entry!r} is not a valid Debian package "
+                "spec. Expected 'name' or 'name=version' with no flags, "
+                "whitespace, or shell metacharacters."
+            )

beaker/artifact_manifest.py

@@ -0,0 +1,126 @@
+"""Canonical artifact manifest helpers used by upload clients."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import posixpath
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+
+JsonDict = dict[str, Any]
+
+MAX_ARTIFACT_PATH_LENGTH = 1024
+SHA256_HEX_PATTERN = r"^[0-9a-fA-F]{64}$"
+
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
+_SHA256_HEX = re.compile(SHA256_HEX_PATTERN)
+
+
+def normalize_artifact_path(path: str) -> str:
+    """Normalize a caller-supplied relative path inside an artifact."""
+    if not isinstance(path, str):
+        raise ValueError(f"Artifact paths must be strings, got {type(path).__name__}.")
+    normalized = path.replace("\\", "/").strip()
+    if not normalized or normalized.startswith("/"):
+        raise ValueError(f"Artifact paths must be relative and non-empty: {path!r}.")
+    if _CONTROL_CHARS.search(normalized):
+        raise ValueError(f"Artifact paths must not contain control characters: {path!r}.")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    if not parts or any(part == ".." for part in parts):
+        raise ValueError(f"Artifact paths must not contain parent-directory segments: {path!r}.")
+    safe_path = posixpath.join(*parts)
+    if len(safe_path) > MAX_ARTIFACT_PATH_LENGTH:
+        raise ValueError(f"Artifact paths must be {MAX_ARTIFACT_PATH_LENGTH} characters or fewer: {path!r}.")
+    return safe_path
+
+
+def canonical_manifest_files(files: Sequence[Mapping[str, Any]]) -> list[JsonDict]:
+    """Return normalized file entries sorted by artifact path.
+
+    The digest identity includes path, byte size, and file SHA-256. Content type
+    is preserved for references and upload headers but intentionally excluded
+    from the digest.
+    """
+    normalized: list[JsonDict] = []
+    seen_paths: set[str] = set()
+    for file in files:
+        path = normalize_artifact_path(str(file.get("path") or ""))
+        if path in seen_paths:
+            raise ValueError(f"Duplicate artifact path after normalization: {path!r}.")
+        seen_paths.add(path)
+        size_bytes = _normalize_size_bytes(file.get("size_bytes"))
+        sha256 = normalize_sha256(str(file.get("sha256") or ""))
+        entry: JsonDict = {
+            "path": path,
+            "size_bytes": size_bytes,
+            "sha256": sha256,
+        }
+        content_type = file.get("content_type")
+        if content_type is not None:
+            entry["content_type"] = str(content_type)
+        normalized.append(entry)
+    return sorted(normalized, key=lambda item: str(item["path"]))
+
+
+def manifest_digest(files: Sequence[Mapping[str, Any]]) -> str:
+    """Compute the stable SHA-256 digest for an artifact manifest."""
+    return digest_canonical_manifest_files(canonical_manifest_files(files))
+
+
+def digest_canonical_manifest_files(canonical_files: Sequence[Mapping[str, Any]]) -> str:
+    """Compute the digest for files that have already been canonicalized.
+
+    Use this when the caller has just produced ``canonical_manifest_files``
+    output and wants to avoid re-running normalization, sorting, and
+    duplicate-detection a second time.
+    """
+    identity = [
+        {
+            "path": file["path"],
+            "size_bytes": file["size_bytes"],
+            "sha256": file["sha256"],
+        }
+        for file in canonical_files
+    ]
+    payload = json.dumps(identity, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def file_sha256_hex(path: Path) -> str:
+    """Hash a local file without loading it all into memory."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def normalize_sha256(value: str) -> str:
+    """Normalize and validate a SHA-256 hex digest."""
+    digest = value.strip().lower()
+    if not _SHA256_HEX.fullmatch(digest):
+        raise ValueError("sha256 must be a 64-character hex digest.")
+    return digest
+
+
+def sha256_hex_to_base64(value: str) -> str:
+    """Return the base64 form used by checksum upload headers."""
+    digest = normalize_sha256(value)
+    return base64.b64encode(bytes.fromhex(digest)).decode("ascii")
+
+
+def _normalize_size_bytes(value: Any) -> int:
+    if isinstance(value, bool) or value is None:
+        raise ValueError("size_bytes must be a non-negative integer.")
+    try:
+        size_bytes = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("size_bytes must be a non-negative integer.") from exc
+    if size_bytes < 0:
+        raise ValueError("size_bytes must be a non-negative integer.")
+    return size_bytes

beaker/cli/__init__.py

@@ -0,0 +1,6 @@
+"""``beaker`` command-line entry point."""
+
+from beaker.cli.main import build_parser, main
+
+
+__all__ = ["build_parser", "main"]

beaker/cli/__main__.py

@@ -0,0 +1,13 @@
+"""Allow ``python -m beaker.cli ...`` in addition to the ``beaker`` console script."""
+
+from __future__ import annotations
+
+from beaker.cli.main import main
+
+
+if __name__ == "__main__":
+    # ``main()`` returns 0 / 1 / 2 (mirroring the ``beaker`` console
+    # script). Wrapping in ``SystemExit`` propagates that to the OS so CI
+    # and shell scripts can branch on ``$?`` — without this, a failed
+    # ``python -m beaker.cli push`` exits 0 and silently succeeds.
+    raise SystemExit(main())

beaker/cli/_common.py

@@ -0,0 +1,107 @@
+"""Small helpers shared across ``beaker`` CLI command modules."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from beaker.cli.beaker_config import BEAKER_CONFIG_RELATIVE_PATH, find_beaker_yaml, project_config_relative_path
+from beaker.client import BeakerClient
+from beaker.config import BeakerConfig
+
+
+DEFAULT_API_BASE_URL = "https://o9f72bncec.execute-api.us-east-2.amazonaws.com/prod/"
+DEFAULT_APP_BASE_URL = "https://platform.rilix.ai"
+
+
+def add_agent_key_argument(parser: argparse.ArgumentParser) -> None:
+    """Add the shared public-agent selector to an API-backed command."""
+    parser.add_argument(
+        "--agent",
+        "--agent-key",
+        dest="agent_key",
+        default=None,
+        help=(
+            "Public agent key to operate on. Defaults to $BEAKER_AGENT_KEY, then "
+            f"{BEAKER_CONFIG_RELATIVE_PATH.as_posix()} agent_key when present."
+        ),
+    )
+
+
+def client_from_args(
+    args: argparse.Namespace,
+    client_cls: type[BeakerClient] = BeakerClient,
+    *,
+    config_agent_key: str | None = None,
+) -> BeakerClient:
+    """Build a :class:`BeakerClient` from CLI credentials and agent selection.
+
+    Shared by every command group so the credential checks and error messages
+    stay identical across ``push``, ``spec``, ``dataset``, and ``run``.
+
+    ``client_cls`` lets each command module pass its own module-level
+    ``BeakerClient`` name so existing tests can monkeypatch the client at the
+    module they target.
+    """
+    if not args.api_key:
+        raise SystemExit(
+            "beaker: --api-key or $BEAKER_API_KEY is required. "
+            'Run `beaker auth status`, then `beaker login --agent --agent-name "<Agent Name>"` '
+            "to create repo-local credentials."
+        )
+    agent_key = require_agent_key(args, config_agent_key=config_agent_key)
+    return client_cls(base_url=args.base_url, api_key=args.api_key, agent_key=agent_key)
+
+
+def require_agent_key(args: argparse.Namespace, *, config_agent_key: str | None = None) -> str:
+    agent_key = resolve_agent_key(args, config_agent_key=config_agent_key)
+    if not agent_key:
+        raise SystemExit(
+            "beaker: --agent/--agent-key, $BEAKER_AGENT_KEY, or "
+            f"{project_config_relative_path().as_posix()} agent_key is required. "
+            'Run `beaker login --agent --agent-name "<Agent Name>"` after selecting the optimization target.'
+        )
+    return agent_key
+
+
+def resolve_agent_key(args: argparse.Namespace, *, config_agent_key: str | None = None) -> str | None:
+    """Resolve agent selection using flag > env > config precedence."""
+    flag_value = _clean_optional_text(getattr(args, "agent_key", None))
+    if flag_value:
+        return flag_value
+    env_value = _clean_optional_text(os.environ.get("BEAKER_AGENT_KEY"))
+    if env_value:
+        return env_value
+    return _clean_optional_text(config_agent_key)
+
+
+def config_agent_key_from_cwd(*, spec_table: Mapping[str, Any] | None = None) -> str | None:
+    """Read an agent key fallback from the nearest hidden config.
+
+    ``spec_table`` is the already-selected named/singular spec table for
+    commands that have one; it takes precedence over top-level config.
+    """
+    table_key = _agent_key_from_mapping(spec_table)
+    if table_key:
+        return table_key
+    found = find_beaker_yaml(Path.cwd())
+    if found is None:
+        return None
+    _config_path, raw = found
+    return _clean_optional_text(BeakerConfig.from_mapping(raw).agent_key)
+
+
+def _agent_key_from_mapping(raw: Mapping[str, Any] | None) -> str | None:
+    if raw is None:
+        return None
+    return _clean_optional_text(raw.get("agent_key") or raw.get("project_key"))
+
+
+def _clean_optional_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None

beaker/cli/_format.py

@@ -0,0 +1,75 @@
+"""Terminal color helpers for the ``beaker`` CLI."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import IO
+
+
+_STYLES: dict[str, str] = {
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "magenta": "35",
+    "cyan": "36",
+}
+_RESET = "\033[0m"
+
+
+def supports_color(stream: IO[str] | None = None) -> bool:
+    """Return whether the CLI should emit ANSI color."""
+    if os.environ.get("NO_COLOR") or os.environ.get("TERM") == "dumb":
+        return False
+    target = stream if stream is not None else sys.stdout
+    return hasattr(target, "isatty") and target.isatty()
+
+
+def paint(text: object, *styles: str, stream: IO[str] | None = None) -> str:
+    """Wrap ``text`` in ANSI styles."""
+    value = str(text)
+    if not styles or not supports_color(stream):
+        return value
+    codes = [_STYLES[style] for style in styles if style in _STYLES]
+    if not codes:
+        return value
+    return f"\033[{';'.join(codes)}m{value}{_RESET}"
+
+
+def heading(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "bold", stream=stream)
+
+
+def key(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "cyan", stream=stream)
+
+
+def ok(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "green", "bold", stream=stream)
+
+
+def warn(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "yellow", "bold", stream=stream)
+
+
+def error(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "red", "bold", stream=stream)
+
+
+def muted(text: object, *, stream: IO[str] | None = None) -> str:
+    return paint(text, "dim", stream=stream)
+
+
+def status(text: object, *, stream: IO[str] | None = None) -> str:
+    value = str(text)
+    normalized = value.upper()
+    if normalized in {"READY", "COMPLETED", "COMPLETE", "PASSED", "APPROVED"}:
+        return ok(value, stream=stream)
+    if normalized in {"FAILED", "ERROR", "DENIED", "EXPIRED", "CANCELLED", "CONSUMED"}:
+        return error(value, stream=stream)
+    if normalized in {"WARN", "WARNING", "BUILDING", "QUEUED", "RUNNING", "SCAFFOLD"}:
+        return warn(value, stream=stream)
+    return key(value, stream=stream)