londonaicentre-mesa-runtime 0.1.0__tar.gz

londonaicentre_mesa_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.3
+Name: londonaicentre-mesa-runtime
+Version: 0.1.0
+Author: Martin Chapman
+Author-email: Martin Chapman <contact@martinchapman.co.uk>
+Requires-Dist: boto3>=1.35
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mesa-runtime/lib
+
+A thin, programmatic wrapper around CI in this repo comprising a simple [backend](../frontend/deploy/) and a library that communicates with it.
+
+## Usage
+
+```python
+from mesa_runtime import MesaRuntime
+
+client = MesaRuntime("https://example.cloudfront.net", "username", "password")
+
+run_id = client.dispatch("batch-2026-01", "foo", "onco")
+print(client.get_run(run_id))
+```
+
+Batch inference uploads the batch file with the caller's AWS credentials:
+
+```python
+run_id = client.run_batch_inference("foo/bar", "baz", "qux.jsonl", "quux")
+print(client.get_inference_run(run_id))
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `list_training_data()` | List available training data objects from S3 |
+| `dispatch(training_batch_name, model_name, schema, ...)` | Trigger a workflow run, returns its ID |
+| `get_run(run_id)` | Fetch a single run by ID |
+| `list_runs()` | List the ten most recent runs |
+| `list_queued_runs()` | List all pending runs |
+| `cancel(run_id)` | Cancel a run |
+| `get_logs(run_id, ...)` | Fetch step logs for a run |
+| `get_step_inputs(run_id)` | Extract dispatch inputs from step env vars |
+| `get_runner_status()` | Get runner online/busy status |
+| `run_batch_inference(job_id, model_id, batch_file, bucket, ...)` | Upload a Bedrock batch file and trigger an inference run, returns its ID |
+| `get_inference_run(run_id)` | Fetch a single inference run by ID |
+| `list_inference_runs()` | List the ten most recent inference runs |
+| `cancel_inference(run_id)` | Cancel an inference run |
+| `get_inference_logs(run_id, ...)` | Fetch step logs for an inference run |

londonaicentre_mesa_runtime-0.1.0/README.md

@@ -0,0 +1,40 @@
+# mesa-runtime/lib
+
+A thin, programmatic wrapper around CI in this repo comprising a simple [backend](../frontend/deploy/) and a library that communicates with it.
+
+## Usage
+
+```python
+from mesa_runtime import MesaRuntime
+
+client = MesaRuntime("https://example.cloudfront.net", "username", "password")
+
+run_id = client.dispatch("batch-2026-01", "foo", "onco")
+print(client.get_run(run_id))
+```
+
+Batch inference uploads the batch file with the caller's AWS credentials:
+
+```python
+run_id = client.run_batch_inference("foo/bar", "baz", "qux.jsonl", "quux")
+print(client.get_inference_run(run_id))
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `list_training_data()` | List available training data objects from S3 |
+| `dispatch(training_batch_name, model_name, schema, ...)` | Trigger a workflow run, returns its ID |
+| `get_run(run_id)` | Fetch a single run by ID |
+| `list_runs()` | List the ten most recent runs |
+| `list_queued_runs()` | List all pending runs |
+| `cancel(run_id)` | Cancel a run |
+| `get_logs(run_id, ...)` | Fetch step logs for a run |
+| `get_step_inputs(run_id)` | Extract dispatch inputs from step env vars |
+| `get_runner_status()` | Get runner online/busy status |
+| `run_batch_inference(job_id, model_id, batch_file, bucket, ...)` | Upload a Bedrock batch file and trigger an inference run, returns its ID |
+| `get_inference_run(run_id)` | Fetch a single inference run by ID |
+| `list_inference_runs()` | List the ten most recent inference runs |
+| `cancel_inference(run_id)` | Cancel an inference run |
+| `get_inference_logs(run_id, ...)` | Fetch step logs for an inference run |

londonaicentre_mesa_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "londonaicentre-mesa-runtime"
+version = "0.1.0"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "boto3>=1.35",
+    "httpx>=0.28",
+    "pydantic>=2.0",
+]
+
+[[project.authors]]
+name = "Martin Chapman"
+email = "contact@martinchapman.co.uk"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "boto3-stubs[s3]>=1.35",
+    "pytest>=9.1.0",
+    "pytest-cov>=6.0",
+    "pytest-mock>=3.0",
+    "ruff>=0.15.17",
+    "ty>=0.0.49",
+]
+
+[tool.uv.build-backend]
+module-name = "mesa_runtime"

londonaicentre_mesa_runtime-0.1.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "londonaicentre-mesa-runtime"
+version = "0.1.0"
+readme = "README.md"
+authors = [
+    { name = "Martin Chapman", email = "contact@martinchapman.co.uk" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "boto3>=1.35",
+    "httpx>=0.28",
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "boto3-stubs[s3]>=1.35",
+    "pytest>=9.1.0",
+    "pytest-cov>=6.0",
+    "pytest-mock>=3.0",
+    "ruff>=0.15.17",
+    "ty>=0.0.49",
+]
+
+[tool.uv.build-backend]
+module-name = "mesa_runtime"

londonaicentre_mesa_runtime-0.1.0/src/mesa_runtime/__init__.py

@@ -0,0 +1,19 @@
+from mesa_runtime.client import MesaRuntime
+from mesa_runtime.types import (
+    BucketObject,
+    RunnerStatus,
+    RunnerStatusResponse,
+    WorkflowConclusion,
+    WorkflowRun,
+    WorkflowStatus,
+)
+
+__all__ = [
+    "BucketObject",
+    "MesaRuntime",
+    "RunnerStatus",
+    "RunnerStatusResponse",
+    "WorkflowConclusion",
+    "WorkflowRun",
+    "WorkflowStatus",
+]

londonaicentre_mesa_runtime-0.1.0/src/mesa_runtime/client.py

@@ -0,0 +1,331 @@
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import boto3
+from httpx import BasicAuth, Client, Response
+
+from mesa_runtime.types import (
+    BucketObject,
+    InferenceInputs,
+    RunnerStatusResponse,
+    TrainingInputs,
+    WorkflowRun,
+)
+
+
+class MesaRuntime:
+    """A synchronous Python client for the MESA Runtime Lambda API.
+
+    Args:
+        base_url (str): Base URL of the Lambda/CloudFront endpoint
+            (e.g. ``"https://example.cloudfront.net"``).
+        username (str): Basic auth username.
+        password (str): Basic auth password.
+
+    """
+
+    __TRAINING: str = "/api/workflows"
+    __INFERENCE: str = "/api/inference"
+
+    def __init__(self, base_url: str, username: str, password: str) -> None:
+        self.__base_url: str = base_url.rstrip("/")
+        self.__auth: BasicAuth = BasicAuth(username, password)
+
+    @staticmethod
+    def _upload(batch_file: str, bucket: str, job_id: str) -> None:
+        boto3.client("s3").upload_file(
+            batch_file, bucket, f"{job_id}/input/{Path(batch_file).name}"
+        )
+
+    def _list_runs(self, prefix: str) -> list[WorkflowRun]:
+        return [
+            WorkflowRun.model_validate(run)
+            for run in self._request("GET", prefix).json()
+        ]
+
+    def _get_run(self, prefix: str, run_id: int) -> WorkflowRun:
+        return WorkflowRun.model_validate(
+            self._request("GET", f"{prefix}/{run_id}").json()
+        )
+
+    def _cancel(self, prefix: str, run_id: int) -> None:
+        self._request("DELETE", f"{prefix}/{run_id}")
+
+    def _get_logs(self, prefix: str, run_id: int, job: str, step: str) -> str:
+        return self._request(
+            "GET", f"{prefix}/{run_id}/logs", None, {"job": job, "step": step}
+        ).text
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Response:
+        headers: dict[str, str] = {"x-requested-with": "fetch"}
+        content: bytes | None = None
+        if body is not None:
+            content = json.dumps(body).encode()
+            headers["content-type"] = "application/json"
+            headers["x-amz-content-sha256"] = hashlib.sha256(content).hexdigest()
+        with Client(auth=self.__auth, follow_redirects=True, timeout=timeout) as client:
+            response: Response = client.request(
+                method,
+                self.__base_url + path,
+                content=content,
+                headers=headers,
+                params=params,
+            )
+        response.raise_for_status()
+        return response
+
+    def list_training_data(self) -> list[BucketObject]:
+        """Lists available training data objects from S3.
+
+        Returns:
+            list[BucketObject]: Training data objects with key,
+            last_modified, and size.
+
+        """
+        return [
+            BucketObject.model_validate(obj)
+            for obj in self._request("GET", "/api/trainingdata").json()
+        ]
+
+    def list_runs(self) -> list[WorkflowRun]:
+        """Lists the ten most recent workflow runs.
+
+        Returns:
+            list[WorkflowRun]: Most recent runs, newest first.
+
+        """
+        return self._list_runs(MesaRuntime.__TRAINING)
+
+    def list_queued_runs(self) -> list[WorkflowRun]:
+        """Lists all pending workflow runs.
+
+        Returns:
+            list[WorkflowRun]: All queued/pending runs.
+
+        """
+        return [
+            WorkflowRun.model_validate(run)
+            for run in self._request("GET", f"{MesaRuntime.__TRAINING}/queued").json()
+        ]
+
+    def dispatch(
+        self,
+        training_batch_name: str,
+        model_name: str,
+        schema: str,
+        description: str = "",
+        version: str = "1.0.0",
+        config: str = "../../../mesa-runtime/config.build.finetune.yaml",
+        config_from_file: bool = False,
+        push_public: bool = False,
+        resume: bool = False,
+        post_process_only: bool = False,
+    ) -> int:
+        """Dispatches a workflow run and returns its run ID.
+
+        Args:
+            training_batch_name (str): Name of the training data batch.
+            model_name (str): Model name (normalised to lowercase-hyphenated).
+            schema (str): Schema type (e.g. ``"onco"``).
+            description (str): Optional run description. Defaults to ``""``.
+            version (str): Model version string. Defaults to ``"1.0.0"``.
+            config (str): Path to a YAML config file. Interpreted by the
+                runner unless ``config_from_file`` is set, in which case it
+                is instead read locally and sent as ``config_yaml``.
+                Defaults to ``"../../../mesa-runtime/config.build.finetune.yaml"``.
+            config_from_file (bool): Read ``config`` as a local file and
+                send its contents as ``config_yaml`` instead of sending
+                ``config`` as a path. Defaults to ``False``.
+            push_public (bool): Push the trained model to the public
+                registry after post-processing. Defaults to ``False``.
+            resume (bool): Resume the runner's currently crashed run from
+                its on-disk checkpoint instead of starting a new one.
+                Defaults to ``False``.
+            post_process_only (bool): Skip training; fuse and publish the
+                existing trainer.json's already-trained adapter. Mutually
+                exclusive with ``resume``. Defaults to ``False``.
+
+        Returns:
+            int: The ID of the dispatched run.
+
+        """
+        return self._request(
+            "POST",
+            MesaRuntime.__TRAINING,
+            TrainingInputs(
+                training_batch_name=training_batch_name,
+                model_name=model_name,
+                schema=schema,
+                description=description,
+                version=version,
+                config="" if config_from_file else config,
+                config_yaml=Path(config).read_text() if config_from_file else "",
+                push_public=push_public,
+                resume=resume,
+                post_process_only=post_process_only,
+            ).model_dump(by_alias=True),
+            timeout=30.0,
+        ).json()["run_id"]
+
+    def get_run(self, run_id: int) -> WorkflowRun:
+        """Gets a single workflow run by ID.
+
+        Args:
+            run_id (int): The run ID.
+
+        Returns:
+            WorkflowRun: The run's current state.
+
+        """
+        return self._get_run(MesaRuntime.__TRAINING, run_id)
+
+    def cancel(self, run_id: int) -> None:
+        """Cancels a workflow run.
+
+        Args:
+            run_id (int): The run ID.
+
+        """
+        self._cancel(MesaRuntime.__TRAINING, run_id)
+
+    def get_logs(
+        self,
+        run_id: int,
+        job: str = "run",
+        step: str = "Run uv run mesa-build-mlx-finetune",
+    ) -> str:
+        """Gets the log output for a named step within a job.
+
+        Args:
+            run_id (int): The run ID.
+            job (str): Name of the job to target. Defaults to ``"run"``.
+            step (str): Name of the step within the job. Defaults to
+                ``"Run uv run mesa-build-mlx-finetune"``.
+
+        Returns:
+            str: The step's log output.
+
+        """
+        return self._get_logs(MesaRuntime.__TRAINING, run_id, job, step)
+
+    def get_step_inputs(self, run_id: int) -> dict[str, str]:
+        """Gets the dispatch inputs for a run by parsing its step logs.
+
+        Args:
+            run_id (int): The run ID.
+
+        Returns:
+            dict[str, str]: Env vars from the step setup block.
+
+        """
+        return self._request("GET", f"{MesaRuntime.__TRAINING}/{run_id}/inputs").json()
+
+    def get_runner_status(self) -> RunnerStatusResponse:
+        """Gets the current runner online/busy status.
+
+        Returns:
+            RunnerStatusResponse: Runner status and busy flag.
+
+        """
+        return RunnerStatusResponse.model_validate(
+            self._request("GET", "/api/workflows/runner/status").json()
+        )
+
+    def run_batch_inference(
+        self,
+        job_id: str,
+        model_id: str,
+        batch_file: str,
+        bucket: str,
+        config: str = "../mesa-runtime/config.build.inference.yml",
+        config_from_file: bool = False,
+    ) -> int:
+        """Uploads a Bedrock batch file to S3 and dispatches an inference run
+            over it, in place of a Bedrock batch inference job.
+
+        Args:
+            job_id (str): The id of the batch job, used as its S3 prefix.
+            model_id (str): Name of the model served by the runner's
+                OpenAI-compatible endpoint.
+            batch_file (str): Path to the local Bedrock batch input file.
+            bucket (str): The name of the bucket to which the batch file
+                should be uploaded and the runner should write output.
+            config (str): Path to a YAML config file. Interpreted by the
+                runner unless ``config_from_file`` is set, in which case it
+                is instead read locally and sent as ``config_yaml``.
+                Defaults to ``"../mesa-runtime/config.build.inference.yml"``.
+            config_from_file (bool): Read ``config`` as a local file and
+                send its contents as ``config_yaml`` instead of sending
+                ``config`` as a path. Defaults to ``False``.
+
+        Returns:
+            int: The ID of the dispatched run.
+
+        """
+        inputs: InferenceInputs = InferenceInputs(
+            job_id=job_id,
+            model_name=model_id,
+            bucket=bucket,
+            config="" if config_from_file else config,
+            config_yaml=Path(config).read_text() if config_from_file else "",
+        )
+        MesaRuntime._upload(batch_file, inputs.bucket, inputs.job_id)
+        return self._request(
+            "POST", MesaRuntime.__INFERENCE, inputs.model_dump(), timeout=30.0
+        ).json()["run_id"]
+
+    def list_inference_runs(self) -> list[WorkflowRun]:
+        """Lists the ten most recent inference runs.
+
+        Returns:
+            list[WorkflowRun]: Most recent runs, newest first.
+
+        """
+        return self._list_runs(MesaRuntime.__INFERENCE)
+
+    def get_inference_run(self, run_id: int) -> WorkflowRun:
+        """Gets a single inference run by ID.
+
+        Args:
+            run_id (int): The run ID.
+
+        Returns:
+            WorkflowRun: The run's current state.
+
+        """
+        return self._get_run(MesaRuntime.__INFERENCE, run_id)
+
+    def cancel_inference(self, run_id: int) -> None:
+        """Cancels an inference run.
+
+        Args:
+            run_id (int): The run ID.
+
+        """
+        self._cancel(MesaRuntime.__INFERENCE, run_id)
+
+    def get_inference_logs(
+        self, run_id: int, job: str = "run", step: str = "Infer"
+    ) -> str:
+        """Gets the log output for a named step within an inference job.
+
+        Args:
+            run_id (int): The run ID.
+            job (str): Name of the job to target. Defaults to ``"run"``.
+            step (str): Name of the step within the job. Defaults to
+                ``"Infer"``.
+
+        Returns:
+            str: The step's log output.
+
+        """
+        return self._get_logs(MesaRuntime.__INFERENCE, run_id, job, step)

londonaicentre_mesa_runtime-0.1.0/src/mesa_runtime/types.py

@@ -0,0 +1,97 @@
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    field_validator,
+    model_validator,
+)
+
+
+class BucketObject(BaseModel):
+    key: str
+    last_modified: str
+    size: int
+
+
+class WorkflowStatus(StrEnum):
+    QUEUED = "queued"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    WAITING = "waiting"
+    REQUESTED = "requested"
+    PENDING = "pending"
+
+
+class WorkflowConclusion(StrEnum):
+    ACTION_REQUIRED = "action_required"
+    CANCELLED = "cancelled"
+    FAILURE = "failure"
+    NEUTRAL = "neutral"
+    SUCCESS = "success"
+    SKIPPED = "skipped"
+    STALE = "stale"
+    TIMED_OUT = "timed_out"
+    STARTUP_FAILURE = "startup_failure"
+
+
+class WorkflowRun(BaseModel):
+    id: int
+    status: WorkflowStatus
+    conclusion: WorkflowConclusion | None
+    created_at: datetime
+    html_url: HttpUrl
+
+
+class DispatchInputs(BaseModel):
+    config: str = Field(default="", max_length=256)
+    config_yaml: str = Field(default="", max_length=65536)
+
+    @model_validator(mode="after")
+    def _validate_config_exclusive(self) -> "DispatchInputs":
+        if self.config and self.config_yaml:
+            raise ValueError("cannot supply both config and config_yaml")
+        return self
+
+
+class TrainingInputs(DispatchInputs):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    training_batch_name: str = Field(default="", max_length=256)
+    model_name: str = Field(default="", max_length=256)
+    schema_: str = Field(default="", alias="schema", max_length=256)
+    description: str = Field(default="", max_length=256)
+    version: str = Field(default="", max_length=64)
+    push_public: bool = Field(default=False)
+    resume: bool = Field(default=False)
+    post_process_only: bool = Field(default=False)
+
+    @field_validator("model_name", mode="before")
+    @classmethod
+    def _normalise_model_name(cls, value: str) -> str:
+        return value.replace(" ", "-").lower()
+
+    @model_validator(mode="after")
+    def _validate_resume_exclusive(self) -> "TrainingInputs":
+        if self.resume and self.post_process_only:
+            raise ValueError("cannot supply both resume and post_process_only")
+        return self
+
+
+class InferenceInputs(DispatchInputs):
+    job_id: str = Field(max_length=256, pattern=r"^[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*$")
+    model_name: str = Field(min_length=1, max_length=256)
+    bucket: str = Field(default="", pattern=r"^([a-z0-9][a-z0-9.-]{1,61}[a-z0-9])?$")
+
+
+class RunnerStatus(StrEnum):
+    ONLINE = "online"
+    OFFLINE = "offline"
+
+
+class RunnerStatusResponse(BaseModel):
+    status: RunnerStatus
+    busy: bool