beaker-sdk 0.3.5__tar.gz

beaker_sdk-0.3.5/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: beaker-sdk
+Version: 0.3.5
+Summary: Beaker prompt-optimization SDK and CLI by RilixAI.
+Author: RilixAI
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pyyaml>=6
+Requires-Dist: pydantic-ai>=1.74 ; extra == 'pydantic-ai'
+Requires-Dist: opentelemetry-api>=1.30,<2 ; extra == 'pydantic-ai'
+Requires-Dist: opentelemetry-sdk>=1.30,<2 ; extra == 'pydantic-ai'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30,<2 ; extra == 'pydantic-ai'
+Requires-Dist: opentelemetry-api>=1.30,<2 ; extra == 'tracing'
+Requires-Dist: opentelemetry-sdk>=1.30,<2 ; extra == 'tracing'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30,<2 ; extra == 'tracing'
+Requires-Dist: opentelemetry-proto>=1.30,<2 ; extra == 'tracing'
+Requires-Python: >=3.12
+Provides-Extra: pydantic-ai
+Provides-Extra: tracing
+Description-Content-Type: text/markdown
+
+# beaker
+
+Beaker SDK and CLI package.
+
+`beaker` gives developers the tools to define optimization specs,
+validate them locally, upload datasets, configure hosted run environments,
+launch optimization runs, and inspect results from code or the CLI.
+
+Customer specs import contract types directly from `beaker`:
+
+```python
+from beaker import Case, CaseDataLoader, CaseResult, CaseScore, Spec, spec
+```
+
+Hosted model-selection rollouts also expose a generic OpenAI-compatible target:
+
+```python
+from beaker import RolloutContext, inference_target
+
+
+def build_eval_client(runtime: RolloutContext):
+    target = inference_target(runtime)
+    return YourFrameworkClient(
+        base_url=target.base_url,
+        api_key=target.api_key,
+        model=target.model,
+    )
+```
+
+Call `inference_target` only in the evaluation path when `runtime.model` is
+set. Ordinary dry-runs and production application calls should retain the
+application's existing model and client defaults.

beaker_sdk-0.3.5/README.md

@@ -0,0 +1,32 @@
+# beaker
+
+Beaker SDK and CLI package.
+
+`beaker` gives developers the tools to define optimization specs,
+validate them locally, upload datasets, configure hosted run environments,
+launch optimization runs, and inspect results from code or the CLI.
+
+Customer specs import contract types directly from `beaker`:
+
+```python
+from beaker import Case, CaseDataLoader, CaseResult, CaseScore, Spec, spec
+```
+
+Hosted model-selection rollouts also expose a generic OpenAI-compatible target:
+
+```python
+from beaker import RolloutContext, inference_target
+
+
+def build_eval_client(runtime: RolloutContext):
+    target = inference_target(runtime)
+    return YourFrameworkClient(
+        base_url=target.base_url,
+        api_key=target.api_key,
+        model=target.model,
+    )
+```
+
+Call `inference_target` only in the evaluation path when `runtime.model` is
+set. Ordinary dry-runs and production application calls should retain the
+application's existing model and client defaults.

beaker_sdk-0.3.5/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "beaker-sdk"
+version = "0.3.5"
+description = "Beaker prompt-optimization SDK and CLI by RilixAI."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+  { name = "RilixAI" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "pyyaml>=6",
+]
+
+[project.optional-dependencies]
+tracing = [
+  "opentelemetry-api>=1.30,<2",
+  "opentelemetry-sdk>=1.30,<2",
+  "opentelemetry-exporter-otlp-proto-http>=1.30,<2",
+  "opentelemetry-proto>=1.30,<2",
+]
+pydantic-ai = [
+  "pydantic-ai>=1.74",
+  "opentelemetry-api>=1.30,<2",
+  "opentelemetry-sdk>=1.30,<2",
+  "opentelemetry-exporter-otlp-proto-http>=1.30,<2",
+]
+
+[project.scripts]
+beaker = "beaker.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "beaker"

beaker_sdk-0.3.5/src/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_sdk-0.3.5/src/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_sdk-0.3.5/src/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_sdk-0.3.5/src/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_sdk-0.3.5/src/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_sdk-0.3.5/src/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())