value-stream 0.1.1__py3-none-any.whl

value_stream/client/simulation_runner.py

@@ -0,0 +1,83 @@
+import os
+import weakref
+from collections.abc import Iterable
+from typing import Optional, Type
+
+from tqdm import tqdm
+
+from value_stream.policy import SimulationPolicy
+from value_stream.simulation import Model, Simulation, DefaultSimulationPolicy, SimulationResult
+from value_stream.task import Task, TaskState
+
+from .web import WebSimulationClient
+from .web.local_service import acquire_local_service, release_local_service
+
+
+class SimulationRunner:
+    """Submits model batches and retrieves their simulation results."""
+
+    @classmethod
+    def task_states(cls) -> Type[TaskState]:
+        return Simulation.task_states
+
+    def __init__(self, service_url: str | None = None) -> None:
+        """Connect the runner to the configured simulation service.
+
+        Args:
+            service_url (str | None): Service url.
+        """
+
+        configured_url = service_url or os.environ.get("VALUE_STREAM_SERVICE_URL") or None
+        self._local_finalizer = None
+        if configured_url is None:
+            configured_url = acquire_local_service()
+            self._local_finalizer = weakref.finalize(self, release_local_service)
+        self.client = WebSimulationClient(configured_url)
+        self._closed = False
+
+    def close(self) -> None:
+        """Close the client and release its resources."""
+
+        if self._closed:
+            return
+        self._closed = True
+        self.client.close()
+        if self._local_finalizer is not None:
+            self._local_finalizer()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, _type, _value, _traceback):
+        self.close()
+
+    def execute(
+        self,
+        tasks: list[Task],
+        models: Iterable[Model],
+        pbar: Optional[tqdm] = None,
+        policy: SimulationPolicy = DefaultSimulationPolicy(),
+        seed: int | None = None,
+    ) -> list[SimulationResult]:
+        """Run the model batch and return results in submission order.
+
+        Args:
+            tasks (list[Task]): Tasks to process.
+            models (Iterable[Model]): Models to simulate.
+            pbar (Optional[tqdm]): Optional progress bar to update.
+            policy (SimulationPolicy): Policy used to make simulation decisions.
+            seed (int | None): Random seed for repeatable simulation.
+
+        Raises:
+            RuntimeError: If the runner is closed or the requested policy is unsupported.
+            ValueError: If the runner is closed or the requested policy is unsupported.
+
+        Returns:
+            list[SimulationResult]: Results in the same order as the submitted models.
+        """
+
+        if self._closed:
+            raise RuntimeError("SimulationRunner is closed")
+        if type(policy) is not DefaultSimulationPolicy:
+            raise ValueError("version 1 supports only DefaultSimulationPolicy")
+        return self.client.execute(tasks=tasks, models=models, pbar=pbar, seed=seed)

value_stream/client/views/__init__.py

@@ -0,0 +1,4 @@
+from .metadata_viewer import MetadataViewer
+from .result_viewer import ResultViewer
+
+__all__ = ["MetadataViewer", "ResultViewer"]

value_stream/client/views/metadata_viewer.py

@@ -0,0 +1,235 @@
+from typing import Any, Type
+import matplotlib.pyplot as plt
+from matplotlib import ticker
+import numpy as np
+from pandas import json_normalize, Categorical
+
+from value_stream.simulation import SimulationResult
+from value_stream.task import TaskState
+
+from .viewer import Viewer
+
+
+class MetadataViewer(Viewer):
+    """Displays simulation metadata."""
+
+    def __init__(
+        self,
+        results: list[SimulationResult],
+        task_states: Type[TaskState],
+        colormap: str = "plasma",
+    ):
+        super().__init__(colormap)
+        self._results_dict: list[Any] = []
+
+        self._task_states = task_states
+
+        for result in results:
+            self._results_dict.append(result.model_dump())
+
+    def mean_stage_loss(self):
+        df = json_normalize(
+            self._results_dict,
+            record_path=["metadata", "event_metadata"],
+            meta=[["metadata", "model", "deployment_cadence"], ["metadata", "model", "team_size"]],
+            errors="ignore",
+        )
+
+        df.set_index(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size"], inplace=True
+        )
+
+        df.sort_index(inplace=True)
+
+        df = df[(df["event_type"] == "end")][["event", "loss", "status"]]
+
+        df["event"] = Categorical(
+            df["event"], categories=[e.value for e in self._task_states], ordered=True
+        )
+
+        team_samples = df.groupby(["metadata.model.team_size"])
+
+        fig, axs = plt.subplots(
+            ncols=len(team_samples), nrows=1, sharex=True, sharey=True, squeeze=True
+        )
+
+        axs_i = 0
+
+        for name, team_sample in team_samples:
+            ax = axs[axs_i]
+            axs_i += 1
+
+            df = (
+                team_sample.groupby(["event", "metadata.model.deployment_cadence"])
+                .mean(numeric_only=True)["loss"]
+                .unstack(level=["metadata.model.deployment_cadence"])
+            )
+
+            df.plot.bar(ax=ax, xlabel="", ylabel="", legend=None, colormap=self.colormap)
+
+            ax.set_title(label=f"Team Size={name[0]}", fontsize=8)
+
+            ax.yaxis.set_inverted(True)
+            ax.yaxis.set_major_formatter(ticker.PercentFormatter(xmax=1.0, decimals=1))
+
+            if axs_i == 1:
+                ax.legend(title="Deployment Cadence")
+
+        fig.supxlabel("SDLC Workflow Stage")
+        fig.supylabel("Mean Loss")
+        fig.suptitle("Mean Stage Loss")
+
+        plt.tight_layout()
+        plt.show()
+
+    def resource_utilization(self):
+
+        df_all = json_normalize(
+            self._results_dict,
+            record_path=["metadata", "resource_metadata"],
+            meta=[["metadata", "model", "deployment_cadence"], ["metadata", "model", "team_size"]],
+            errors="ignore",
+        )
+
+        df_all["state"] = Categorical(
+            df_all["state"], categories=[e.value for e in self._task_states], ordered=True
+        )
+
+        df_all.set_index(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size", "state", "time"],
+            inplace=True,
+        )
+
+        df_all.sort_index(inplace=True)
+
+        df_all = df_all.groupby(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size", "state", "time"]
+        ).sum()
+
+        cadence_x_team_size_samples = df_all.groupby(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size"]
+        )
+
+        dataframes = {key: group for key, group in cadence_x_team_size_samples}
+
+        # detemrine the size of the subplot grid based on number of unique keys in each dimension
+
+        all_keys = np.array(list(dataframes.keys()))
+        cadences, team_sizes = list(all_keys[:, 0]), list(all_keys[:, 1])
+
+        # deduplicate
+        cadences = list(dict.fromkeys(cadences))
+        team_sizes = list(dict.fromkeys(team_sizes))
+
+        fig, axs = plt.subplots(
+            nrows=len(cadences),
+            ncols=len(team_sizes),
+            sharex=True,
+            sharey=True,
+            layout="constrained",
+            squeeze=False,
+        )
+
+        labels = ["Idle", "Productive", "Failure", "Unplanned Work"]
+
+        for team_i, team_size in enumerate(team_sizes):
+            for cadence_i, cadence in enumerate(cadences):
+                group = dataframes[(cadence, team_size)]
+
+                group = group.groupby(["state"]).sum()[
+                    ["idle_t", "success_t", "failure_t", "interruption_t"]
+                ]
+
+                df = group.divide(group.sum(axis=1), axis=0)
+
+                ax = axs[cadence_i, team_i]
+                df.plot(
+                    ax=ax,
+                    kind="bar",
+                    stacked=True,
+                    legend=False,
+                    xlabel="",
+                    ylabel="",
+                    colormap=self.colormap,
+                )
+                ax.set_title(label=f"Cadence={cadence},Team Size={team_size}", fontsize=8)
+
+                ax.yaxis.set_major_formatter(ticker.PercentFormatter(xmax=1.0, decimals=1))
+
+                plt.sca(ax)
+                plt.xticks(rotation=45)
+
+        fig.legend(title="Utilization Category", labels=labels)
+        fig.supylabel("Utilization")
+        fig.supxlabel("SDLC Workflow Stage")
+        fig.suptitle("Resource Utilization")
+        plt.show()
+
+    def resource_capacity(self):
+        df_all = json_normalize(
+            self._results_dict,
+            record_path=["metadata", "resource_metadata"],
+            meta=[["metadata", "model", "deployment_cadence"], ["metadata", "model", "team_size"]],
+            errors="ignore",
+        )
+
+        df_all["state"] = Categorical(
+            df_all["state"], categories=[e.value for e in self._task_states], ordered=True
+        )
+
+        df_all.sort_index(inplace=True)
+
+        df_all = df_all.groupby(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size", "state", "time"]
+        ).sum()
+
+        cadence_x_team_size_samples = df_all.groupby(
+            ["metadata.model.deployment_cadence", "metadata.model.team_size"]
+        )
+
+        dataframes = {key: group for key, group in cadence_x_team_size_samples}
+
+        # detemrine the size of the subplot grid based on number of unique keys in each dimension
+
+        all_keys = np.array(list(dataframes.keys()))
+        cadences, team_sizes = list(all_keys[:, 0]), list(all_keys[:, 1])
+
+        # deduplicate
+        cadences = list(dict.fromkeys(cadences))
+        team_sizes = list(dict.fromkeys(team_sizes))
+
+        fig, axs = plt.subplots(
+            nrows=len(cadences),
+            ncols=len(team_sizes),
+            sharey=True,
+            layout="constrained",
+            squeeze=False,
+        )
+
+        for team_i, team_size in enumerate(team_sizes):
+            for cadence_i, cadence in enumerate(cadences):
+                group = dataframes[(cadence, team_size)]
+
+                group = group.droplevel([0, 1])["waiting"].unstack(["state"])
+                # group = group.droplevel([0, 1])  # .unstack(['state'])
+                group.sort_index(inplace=True)
+
+                group = group.cumsum()
+
+                group.ffill(inplace=True)
+
+                ax = axs[cadence_i, team_i]
+                group.plot(ax=ax, legend=False, xlabel="", ylabel="", colormap=self.colormap)
+
+                ax.set_yscale("log")
+
+                ax.set_title(label=f"Cadence={cadence},Team Size={team_size}", fontsize=8)
+
+                plt.sca(ax)
+                plt.xticks(rotation=45)
+
+        fig.legend(title="Backlog", labels=["Development", "QA", "Deployment"])
+        fig.supylabel("# Waiting for Resource")
+        fig.supxlabel("Time")
+        fig.suptitle("Resource Capacity")
+        plt.show()

value_stream/client/views/result_viewer.py

@@ -0,0 +1,76 @@
+from typing import Any
+from matplotlib import ticker
+import matplotlib.pyplot as plt
+from pandas import json_normalize
+from value_stream.simulation import SimulationResult
+from .viewer import Viewer
+
+
+class ResultViewer(Viewer):
+    """Displays simulation results."""
+
+    def __init__(self, results: list[SimulationResult], colormap="plasma"):
+        super().__init__(colormap)
+        self._results_dict: list[Any] = []
+
+        for result in results:
+            self._results_dict.append(result.model_dump())
+
+        self.data = json_normalize(
+            self._results_dict,
+            meta=[
+                ["summary_result", "model", "deployment_cadence"],
+                ["summary_result", "model", "team_size"],
+            ],
+            errors="ignore",
+            record_prefix="",
+        )
+
+        self.data.set_index(
+            ["summary_result.model.deployment_cadence", "summary_result.model.team_size"],
+            inplace=True,
+        )
+
+    def loss_vs_cadence(self):
+        df = self.data
+
+        df = df[["summary_result.loss", "summary_result.total_delivered_value"]].unstack(-1)[
+            ["summary_result.loss"]
+        ]
+
+        df.columns = df.columns.get_level_values(1)  # pyright: ignore[reportAttributeAccessIssue]
+
+        ax = df.plot(
+            title="Loss vs Cadence",
+            xlabel="Cadence",
+            ylabel="Loss",
+            grid=True,
+            colormap=self.colormap,
+        )
+
+        ax.yaxis.set_minor_locator(ticker.AutoMinorLocator())
+
+        plt.legend(title="Team Size")
+        plt.gca().invert_xaxis()
+        ax.yaxis.set_major_formatter(ticker.PercentFormatter(xmax=1.0))
+        plt.show()
+
+    def loss_vs_team_size(self):
+
+        df = self.data
+
+        df = df[["summary_result.loss"]].unstack(0)
+
+        df.columns = df.columns.get_level_values(1)  # pyright: ignore[reportAttributeAccessIssue]
+
+        ax = df.plot(
+            title="Loss vs Team Size",
+            xlabel="Team Size",
+            ylabel="Loss",
+            grid=True,
+            colormap=self.colormap,
+        )
+        ax.yaxis.set_minor_locator(ticker.AutoMinorLocator())
+        plt.legend(title="Deployment Cadence")
+        ax.yaxis.set_major_formatter(ticker.PercentFormatter(xmax=1.0))
+        plt.show()

value_stream/client/views/viewer.py

@@ -0,0 +1,8 @@
+from matplotlib import colormaps
+
+
+class Viewer:
+    """Defines the interface for simulation result viewers."""
+
+    def __init__(self, colormap: str = "plasma"):
+        self.colormap = colormaps[colormap]

value_stream/client/web/__init__.py

@@ -0,0 +1,10 @@
+__all__ = []
+from .client import WebSimulationClient
+from .errors import BatchSimulationError, JobCancelledError, ServiceClientError
+
+__all__ = [
+    "WebSimulationClient",
+    "BatchSimulationError",
+    "JobCancelledError",
+    "ServiceClientError",
+]

value_stream/client/web/client.py

@@ -0,0 +1,115 @@
+"""Python HTTP client for simulation jobs."""
+
+import time
+from collections.abc import Iterable
+
+import httpx2 as httpx
+from pydantic import ValidationError
+from tqdm import tqdm
+
+from value_stream.service.codec import decode_result, encode_request
+from value_stream.service.schemas import JobAccepted, JobStatus, ModelError, OutcomePage
+from value_stream.simulation import Model, SimulationResult
+from value_stream.task import Task
+
+from .errors import BatchSimulationError, JobCancelledError, ServiceClientError
+
+
+class WebSimulationClient:
+    """Sends simulation requests to the web service."""
+
+    def __init__(
+        self,
+        service_url: str,
+        poll_interval: float = 0.1,
+        max_wait_seconds: float = 3600,
+    ):
+        self.service_url = service_url.rstrip("/")
+        self.poll_interval = poll_interval
+        self.max_wait_seconds = max_wait_seconds
+        self._http = httpx.Client(base_url=self.service_url, timeout=5, trust_env=False)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            response = self._http.request(method, path, **kwargs)
+            response.raise_for_status()
+            return response
+        except httpx.HTTPStatusError as exc:
+            try:
+                data = exc.response.json()
+                message = f"{data.get('code', 'HTTP_ERROR')}: {data.get('message', exc)}"
+            except ValueError:
+                message = str(exc)
+            raise ServiceClientError(message) from exc
+        except httpx.RequestError as exc:
+            raise ServiceClientError(f"service connection failed: {exc}") from exc
+
+    @staticmethod
+    def _validate(model_type, value: dict, description: str):
+        try:
+            return model_type.model_validate(value)
+        except ValidationError as exc:
+            raise ServiceClientError(f"service returned malformed {description}") from exc
+
+    def execute(
+        self,
+        tasks: list[Task],
+        models: Iterable[Model],
+        pbar: tqdm | None = None,
+        seed: int | None = None,
+    ) -> list[SimulationResult]:
+        model_list = list(models)
+        request = encode_request(tasks, model_list, seed)
+        submitted = self._validate(
+            JobAccepted,
+            self._request(
+                "POST", "/v1/simulation-jobs", json=request.model_dump(mode="json")
+            ).json(),
+            "job acceptance",
+        )
+        job_path = f"/v1/simulation-jobs/{submitted.job_id}"
+        results: dict[int, SimulationResult] = {}
+        errors: dict[int, ModelError] = {}
+        cursor = 0
+        deadline = time.monotonic() + self.max_wait_seconds
+        while True:
+            if time.monotonic() >= deadline:
+                raise ServiceClientError(f"job {submitted.job_id} exceeded client wait limit")
+            page = self._validate(
+                OutcomePage,
+                self._request("GET", f"{job_path}/outcomes", params={"after": cursor}).json(),
+                "outcomes",
+            )
+            for outcome in page.outcomes:
+                if not 0 <= outcome.model_index < len(model_list):
+                    raise ServiceClientError("service returned an invalid model index")
+                if outcome.status == "succeeded" and outcome.result is not None:
+                    results[outcome.model_index] = decode_result(
+                        outcome.result, model_list[outcome.model_index]
+                    )
+                elif outcome.status == "failed" and outcome.error is not None:
+                    errors[outcome.model_index] = outcome.error
+                if pbar:
+                    pbar.update()
+            cursor = page.next_cursor
+            status = self._validate(JobStatus, self._request("GET", job_path).json(), "job status")
+            if status.total_models != len(model_list):
+                raise ServiceClientError("service returned an unexpected model count")
+            if status.status in ("completed", "completed_with_errors", "cancelled"):
+                if cursor < status.total_models:
+                    continue
+                if status.status == "cancelled":
+                    raise JobCancelledError(f"job {submitted.job_id} was cancelled")
+                break
+            time.sleep(self.poll_interval)
+        successful = sorted(results.items())
+        if errors:
+            if len(successful) + len(errors) != len(model_list):
+                raise ServiceClientError("service omitted a model outcome")
+            raise BatchSimulationError(successful_results=successful, errors=errors)
+        if len(successful) != len(model_list):
+            raise ServiceClientError("service omitted a model result")
+        return [result for _, result in successful]

value_stream/client/web/errors.py

@@ -0,0 +1,29 @@
+"""Client errors that preserve partial batch outcomes."""
+
+from value_stream.simulation import SimulationResult
+from value_stream.service.schemas import ModelError
+
+
+class ServiceClientError(RuntimeError):
+    """Base error raised by the web service client."""
+
+    pass
+
+
+class BatchSimulationError(ServiceClientError):
+    """Reports a failure while running a batch of simulations."""
+
+    def __init__(
+        self,
+        successful_results: list[tuple[int, SimulationResult]],
+        errors: dict[int, ModelError],
+    ):
+        self.successful_results = successful_results
+        self.errors = errors
+        super().__init__(f"{len(errors)} model(s) failed: {sorted(errors)}")
+
+
+class JobCancelledError(ServiceClientError):
+    """Reports that a simulation job was cancelled."""
+
+    pass

value_stream/client/web/local_service.py

@@ -0,0 +1,92 @@
+"""One reference-counted loopback HTTP server per Python process."""
+
+import atexit
+import socket
+import threading
+import time
+
+import httpx2 as httpx
+import uvicorn
+
+from value_stream.service.app import create_app
+
+
+class _LocalService:
+    """Manages the local simulation service process."""
+
+    def __init__(self):
+        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._socket.bind(("127.0.0.1", 0))
+        self._socket.listen(128)
+        self.url = f"http://127.0.0.1:{self._socket.getsockname()[1]}"
+        # Uvicorn loggers are shared with the hosting API. Reconfiguring them
+        # here can suppress its startup message (and VS Code's browser trigger).
+        config = uvicorn.Config(create_app(), host="127.0.0.1", log_config=None)
+        self._server = uvicorn.Server(config)
+        self._thread = threading.Thread(
+            target=self._server.run, kwargs={"sockets": [self._socket]}, daemon=True
+        )
+
+    def start(self):
+        self._thread.start()
+        deadline = time.monotonic() + 5
+        while time.monotonic() < deadline:
+            if not self._thread.is_alive():
+                break
+            try:
+                if httpx.get(f"{self.url}/health", timeout=0.2, trust_env=False).status_code == 200:
+                    return
+            except httpx.RequestError:
+                pass
+            time.sleep(0.05)
+        self.stop()
+        raise RuntimeError("local simulation service did not become ready")
+
+    def stop(self):
+        self._server.should_exit = True
+        if self._thread.is_alive():
+            self._thread.join(timeout=5)
+        self._socket.close()
+
+
+_lock = threading.RLock()
+_service: _LocalService | None = None
+_owners = 0
+
+
+def acquire_local_service() -> str:
+    global _service, _owners
+    with _lock:
+        if _service is None:
+            new_service = _LocalService()
+            new_service.start()
+            _service = new_service
+        _owners += 1
+        return _service.url
+
+
+def release_local_service() -> None:
+    global _service, _owners
+    with _lock:
+        if _owners <= 0:
+            return
+        _owners -= 1
+        if _owners:
+            return
+        service = _service
+        _service = None
+    if service is not None:
+        service.stop()
+
+
+def _cleanup() -> None:
+    global _service, _owners
+    with _lock:
+        service = _service
+        _service = None
+        _owners = 0
+    if service is not None:
+        service.stop()
+
+
+atexit.register(_cleanup)

value_stream/factory/__init__.py

@@ -0,0 +1,5 @@
+from .developer_factory import DeveloperFactory
+from .task_factory import TaskFactory
+from .task_generator import TaskGenerator
+
+__all__ = ["DeveloperFactory", "TaskFactory", "TaskGenerator"]