value-stream 0.1.1__py3-none-any.whl

value_stream/resources/resource_tracker.py

@@ -0,0 +1,160 @@
+from typing import Optional, Protocol, runtime_checkable
+
+from simpy import Environment
+
+from value_stream.task import TaskState
+from value_stream.task import EventStatus
+
+from .resource_metadata import ResourceMetadata
+
+
+class ResourceTracker(Protocol):
+    """Defines hooks for tracking resource work and wait times."""
+
+    @property
+    def data(self) -> list[ResourceMetadata]: ...
+    def register(self, workflow_state: TaskState) -> None: ...
+    def start_work(self, workflow_state: TaskState, elapsed_t: float) -> None: ...
+    def complete_work(
+        self, workflow_state: TaskState, status: EventStatus, elapsed_t: Optional[float] = None
+    ) -> None: ...
+    def interruption(self, workflow_state: TaskState, elapsed_t: float) -> None: ...
+    def start_waiting(self, workflow_state: TaskState) -> None: ...
+    def complete_waiting(self, workflow_state: TaskState, waiting_t: float) -> None: ...
+
+
+class NoOpResourceTracker:  # pylint: disable=W0613
+    """Implements resource tracking hooks without recording data."""
+
+    @property
+    def data(self) -> list[ResourceMetadata]:
+        return []
+
+    def register(self, workflow_state: TaskState):
+        return
+
+    def start_work(self, workflow_state: TaskState, elapsed_t: float):
+        return
+
+    def complete_work(
+        self, workflow_state: TaskState, status: EventStatus, elapsed_t: Optional[float] = None
+    ):
+        return
+
+    def interruption(self, workflow_state: TaskState, elapsed_t: float):
+        return
+
+    def start_waiting(self, workflow_state: TaskState):
+        return
+
+    def complete_waiting(self, workflow_state: TaskState, waiting_t: float):
+        return
+
+
+class InMemoryResourceTracker:
+    """Records resource work and wait times in memory."""
+
+    def __init__(self, env: Environment) -> None:
+        """Initialize the resource activity records.
+
+        Args:
+            env (Environment): Simulation environment.
+        """
+        self._env = env
+        self._epoch_t = env.now
+        self._data: list[ResourceMetadata] = []
+
+    @property
+    def data(self):
+        return self._data.copy()
+
+    def register(self, workflow_state: TaskState) -> None:
+        """Register a simulation run.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+        """
+        self._data.append(
+            ResourceMetadata(time=self._env.now - self._epoch_t, state=workflow_state, allocated=1)
+        )
+
+    def start_work(self, workflow_state: TaskState, elapsed_t: float) -> None:
+        """Record the start of resource work.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+            elapsed_t (float): Elapsed t.
+        """
+        self._data.append(
+            ResourceMetadata(
+                time=self._env.now - self._epoch_t, state=workflow_state, active=1, idle_t=elapsed_t
+            )
+        )
+
+    def complete_work(
+        self, workflow_state: TaskState, status: EventStatus, elapsed_t: Optional[float] = None
+    ) -> None:
+        """Record completed resource work.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+            status (EventStatus): Current outcome status.
+            elapsed_t (Optional[float]): Elapsed t.
+        """
+        if status == EventStatus.FAILURE:
+            self._data.append(
+                ResourceMetadata(
+                    time=self._env.now - self._epoch_t,
+                    state=workflow_state,
+                    active=-1,
+                    failure_t=elapsed_t,
+                )
+            )
+        else:
+            self._data.append(
+                ResourceMetadata(
+                    time=self._env.now - self._epoch_t,
+                    state=workflow_state,
+                    active=-1,
+                    success_t=elapsed_t,
+                )
+            )
+
+    def interruption(self, workflow_state: TaskState, elapsed_t: float) -> None:
+        """Record an interruption to resource work.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+            elapsed_t (float): Elapsed t.
+        """
+        self._data.append(
+            ResourceMetadata(
+                time=self._env.now - self._epoch_t, state=workflow_state, interruption_t=elapsed_t
+            )
+        )
+
+    def start_waiting(self, workflow_state: TaskState) -> None:
+        """Record that a resource began waiting.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+        """
+        self._data.append(
+            ResourceMetadata(time=self._env.now - self._epoch_t, state=workflow_state, waiting=1)
+        )
+
+    def complete_waiting(self, workflow_state: TaskState, waiting_t: float) -> None:
+        """Record that a resource stopped waiting.
+
+        Args:
+            workflow_state (TaskState): Workflow state associated with the operation.
+            waiting_t (float): Waiting t.
+        """
+        self._data.append(
+            ResourceMetadata(
+                time=self._env.now - self._epoch_t,
+                state=workflow_state,
+                waiting=-1,
+                waiting_t=waiting_t,
+            )
+        )

value_stream/resources/toolchain.py

@@ -0,0 +1,43 @@
+from typing import Any, Generator
+import random
+
+from pydantic import FiniteFloat, Field
+from simpy import Environment, Timeout
+
+from value_stream.task import EventStatus, Task
+
+from .resource_pool import PooledResource
+from .resource import Resource
+
+
+class Toolchain(Resource, PooledResource):
+    """Simulates actions performed on tasks by SDLC tooling"""
+
+    deployment_duration: FiniteFloat = Field(ge=0)
+    failure_rate: FiniteFloat = Field(default=0, ge=0, le=1)
+
+    def do_work(
+        self, env: Environment, tasks: list[Task]
+    ) -> Generator[Timeout, Any, dict[str, EventStatus]]:
+        """Deploy tasks and yield until the deployment completes.
+
+        Args:
+            env (Environment): Simulation environment.
+            tasks (list[Task]): Tasks to process.
+
+        Yields:
+            Timeout: Event that completes the deployment.
+
+        Returns:
+            dict[str, EventStatus]: Deployment result and completion status.
+        """
+        if random.random() < self.failure_rate:
+            result = EventStatus.FAILURE
+        else:
+            result = EventStatus.SUCCESS
+
+        work = env.timeout(self.deployment_duration, value={"result": result})
+
+        yield work
+
+        return work.value

value_stream/service/SPEC.md

@@ -0,0 +1,46 @@
+# Simulation service specification
+
+The implementation design and validation milestones are in `.agent/SIMULATION_SERVICE_EXECPLAN.md`, maintained according to `.agent/PLANS.md`. This specification records the agreed behavior; the ExecPlan resolves version 1 implementation choices.
+
+## Goals
+
+- Create an HTTP service that executes `value_stream.simulation.Simulation` and returns its results.
+- Create a Python HTTP client under `src/value_stream/client/web`.
+- Update `value_stream.client.SimulationRunner` to use the client for remote execution and to support a local service instance when no service URL is supplied.
+- Keep the service contract suitable for a later web application that accepts simulation inputs and renders results. The web application is outside version 1.
+
+## Version 1 requirements
+
+- Service source files belong under `src/value_stream/service`.
+- Define the HTTP API using OpenAPI 3.1. Specify request, response, and error schemas rather than passing arbitrary Python objects across the wire.
+- Keep the public API language-neutral: ordinary HTTP requests and JSON bodies must be usable by a later browser client or another language without importing Python package classes. Python `SimulationResult` reconstruction is specific to the version 1 Python client.
+- Accept a batch of models with a shared set of tasks in one request. Preserve the association between each submitted model and its result, and return results in a form that the Python client can reconstruct as the existing `SimulationResult` types. Existing `ResultViewer` and `MetadataViewer` behavior must continue to work, including summary, task-event, and resource metadata.
+- Use `DefaultSimulationPolicy` in version 1. Supporting other policies is a future extension.
+- Allow a caller above `SimulationRunner` to supply a service URL; support an environment override. Service discovery is deferred.
+- If neither the caller nor the environment supplies a service URL, `SimulationRunner` starts and uses a local HTTP service bound to loopback. Reuse one local instance across runner objects in the same Python process, and stop it when the last owning runner closes. `SimulationRunner` does not call `Simulation` directly.
+- Submit the shared tasks and batch of models through a job API. Submission returns a job identifier promptly; clients can obtain status and each model's result as it completes through separate API calls. Define job expiration and cancellation behavior in the API contract.
+- Allow concurrent execution of models in a batch. Label each result with its submitted model index so the Python client can return the final `list[SimulationResult]` in submission order, regardless of completion order.
+- If one model fails, continue executing the others. Report the failed model's index and a structured error alongside successful results. A job reaches a terminal state after every model has either succeeded or failed.
+- After a partially failed job reaches its terminal state, `SimulationRunner.execute` raises a dedicated batch error that carries successful `SimulationResult` objects in submission order and model-indexed errors. A fully successful job retains the existing `list[SimulationResult]` return type. The client must not silently omit failed models or put error objects in a list consumed by the existing viewers.
+- Accept an optional seed with each job. Derive an independent, repeatable random stream for each submitted model from the job seed and model index, so scheduling and completion order do not change seeded simulation outcomes. The seed governs randomness during simulation; task/model factory randomness before submission is outside its scope.
+- Accept optional `model_seeds`, containing one nonnegative seed per submitted model, as an alternative to the job-level `seed`. Explicit seeds are used directly and remain stable when models are reordered or submitted as a subset. Supplying both seed forms or a mismatched seed count is invalid. Existing job-level seed derivation remains unchanged.
+- Accept an optional UUID `submission_id`. Identical retries return the original job without rescheduling; reuse with different content returns HTTP 409 `SUBMISSION_CONFLICT`. Reservation is atomic, and retry lookup precedes admission checks. Idempotency lasts until job expiry or server shutdown; it is not persistent exactly-once execution across service restarts.
+- Include unit and integration tests, including a service/client round trip and compatibility checks for the existing viewers.
+- Handle invalid input, execution failures, and client connection failures with a documented error contract.
+- Provide an option to package and run the service as a Docker image.
+- Keep simulation state isolated per model. Put job state behind a replaceable storage interface so a later multi-instance deployment can use shared storage. Version 1 may store jobs in memory; results need not survive service restarts.
+- Add configurable protections against excessive resource use, including admission and execution limits. Select initial defaults during design and document their errors in the API contract.
+
+## Intended use and future scope
+
+Version 1 is for individuals demonstrating the value-stream project. A shared, multi-user deployment, authentication, policy extensibility, service discovery, persistent results, and a browser web application are later phases. The version 1 design should leave room for these capabilities; it does not need to expose unused authentication or multi-user behavior.
+
+## Implementation design prerequisites
+
+- Write an ExecPlan for this significant feature before coding, following `.agent/PLANS.md` as required by `AGENTS.md`.
+- Select a worker strategy that keeps model execution and random state isolated without blocking HTTP request handling. Verify that seeded results do not depend on concurrent scheduling. Document concurrency limits and cancellation semantics.
+- Define OpenAPI 3.1 schemas for tasks, models, resource pools, summary results, task events, resource metadata, job status, and errors. Preserve fields and types needed by current viewers; account for enums and UUIDs. Decide whether the Python client reuses submitted model objects in reconstructed results or creates equivalent objects.
+- Define job-state retention and expiry, behavior when a job ID is unknown or expired, and what happens to running jobs when the in-memory service stops. Expose per-model progress and errors without losing successful results.
+- Choose configurable defaults for task count, model count, concurrency, run duration, and request/response size. Reject excess load with documented errors.
+- Establish a round-trip test that passes reconstructed results through `ResultViewer` and `MetadataViewer`, and test local service startup and shutdown as well as remote connection failures.
+- Add a CI contract-alignment check that detects new simulation input fields omitted from the wire schemas or codecs. Review the generated OpenAPI contract when the server schema changes, and test the HTTP contract without the Python client.

value_stream/service/__init__.py

@@ -0,0 +1 @@
+__all__ = []

value_stream/service/app.py

@@ -0,0 +1,218 @@
+"""HTTP application for version 1 simulation jobs."""
+
+from contextlib import asynccontextmanager
+import hashlib
+import json
+import logging
+from typing import Any
+from uuid import UUID
+
+from fastapi import FastAPI, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.datastructures import Headers
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from .job_store import (
+    CapacityExceeded,
+    InMemoryJobStore,
+    JobNotFound,
+    JobStorage,
+    SubmissionConflict,
+)
+from .scheduler import ModelScheduler
+from .schemas import (
+    ErrorEnvelope,
+    HealthResponse,
+    JobAccepted,
+    JobRequest,
+    JobStatus,
+    OutcomePage,
+)
+from .settings import ServiceSettings
+
+logger = logging.getLogger(__name__)
+
+
+def _error(
+    status: int, code: str, message: str, details: dict[str, object] | None = None
+) -> JSONResponse:
+    body = ErrorEnvelope(code=code, message=message, details=details)
+    return JSONResponse(status_code=status, content=body.model_dump(mode="json"))
+
+
+class BodyLimitMiddleware:
+    """Buffer at most the configured request size before passing it downstream."""
+
+    def __init__(self, app: ASGIApp, max_body_bytes: int) -> None:
+        self.app = app
+        self.max_body_bytes = max_body_bytes
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or (
+            scope["method"] != "POST" or scope["path"] != "/v1/simulation-jobs"
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        length = Headers(scope=scope).get("content-length")
+        if length is not None:
+            try:
+                declared_size = int(length)
+            except ValueError:
+                await _error(422, "INVALID_INPUT", "invalid content-length header")(
+                    scope, receive, send
+                )
+                return
+            if declared_size > self.max_body_bytes:
+                await _error(413, "BODY_TOO_LARGE", "request body exceeds configured limit")(
+                    scope, receive, send
+                )
+                return
+
+        buffered: list[Message] = []
+        size = 0
+        while True:
+            message = await receive()
+            if message["type"] == "http.disconnect":
+                return
+            chunk = message.get("body", b"")
+            size += len(chunk)
+            if size > self.max_body_bytes:
+                await _error(413, "BODY_TOO_LARGE", "request body exceeds configured limit")(
+                    scope, receive, send
+                )
+                return
+            buffered.append(message)
+            if not message.get("more_body", False):
+                break
+
+        cursor = 0
+
+        async def replay_receive() -> Message:
+            nonlocal cursor
+            if cursor < len(buffered):
+                message = buffered[cursor]
+                cursor += 1
+                return message
+            return await receive()
+
+        await self.app(scope, replay_receive, send)
+
+
+def create_app(
+    settings: ServiceSettings | None = None,
+    store: JobStorage | None = None,
+) -> FastAPI:
+    settings = settings or ServiceSettings.from_environment()
+    store = store or InMemoryJobStore(settings)
+    scheduler = ModelScheduler(store, settings)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        yield
+        scheduler.close()
+
+    application = FastAPI(
+        title="Value Stream Simulation Service",
+        version="1.0.0",
+        lifespan=lifespan,
+    )
+    application.add_middleware(BodyLimitMiddleware, max_body_bytes=settings.max_body_bytes)
+    application.state.store = store
+    application.state.scheduler = scheduler
+    application.state.settings = settings
+
+    @application.exception_handler(RequestValidationError)
+    async def invalid_input(_request: Request, exc: RequestValidationError):
+        issues = [{"location": list(item["loc"]), "message": item["msg"]} for item in exc.errors()]
+        return _error(422, "INVALID_INPUT", "request validation failed", {"issues": issues})
+
+    @application.exception_handler(Exception)
+    async def unexpected_error(_request: Request, exc: Exception):
+        logger.exception("unexpected service error", exc_info=exc)
+        return _error(500, "INTERNAL_ERROR", "unexpected service error")
+
+    errors: dict[int | str, dict[str, Any]] = {
+        404: {"model": ErrorEnvelope},
+        409: {"model": ErrorEnvelope},
+        413: {"model": ErrorEnvelope},
+        422: {"model": ErrorEnvelope},
+        429: {"model": ErrorEnvelope},
+        500: {"model": ErrorEnvelope},
+    }
+
+    @application.get("/health", response_model=HealthResponse)
+    def health():
+        return HealthResponse()
+
+    @application.post(
+        "/v1/simulation-jobs",
+        response_model=JobAccepted,
+        status_code=202,
+        responses=errors,
+    )
+    def submit(request: JobRequest):
+        if len(request.tasks) > settings.max_tasks or len(request.models) > settings.max_models:
+            return _error(422, "LIMIT_EXCEEDED", "task or model count exceeds configured limit")
+        try:
+            fingerprint = hashlib.sha256(
+                json.dumps(
+                    request.model_dump(mode="json", exclude={"submission_id"}),
+                    sort_keys=True,
+                    separators=(",", ":"),
+                    allow_nan=False,
+                ).encode()
+            ).hexdigest()
+            job_id, created = store.reserve(len(request.models), request.submission_id, fingerprint)
+        except SubmissionConflict as exc:
+            return _error(409, "SUBMISSION_CONFLICT", str(exc))
+        except CapacityExceeded:
+            return _error(429, "JOB_CAPACITY", "job capacity is full")
+        try:
+            if created:
+                scheduler.submit(job_id, request)
+        except Exception:
+            store.cancel(job_id)
+            raise
+        return JobAccepted(
+            job_id=job_id,
+            status=store.status(job_id).status,
+            status_url=f"/v1/simulation-jobs/{job_id}",
+        )
+
+    @application.get("/v1/simulation-jobs/{job_id}", response_model=JobStatus, responses=errors)
+    def status(job_id: UUID):
+        try:
+            return store.status(job_id)
+        except JobNotFound:
+            return _error(404, "JOB_NOT_FOUND", "job is unknown or expired")
+
+    @application.get(
+        "/v1/simulation-jobs/{job_id}/outcomes",
+        response_model=OutcomePage,
+        responses=errors,
+    )
+    def outcomes(job_id: UUID, after: int = Query(default=0, ge=0)):
+        try:
+            return store.page(job_id, after)
+        except JobNotFound:
+            return _error(404, "JOB_NOT_FOUND", "job is unknown or expired")
+
+    @application.delete(
+        "/v1/simulation-jobs/{job_id}",
+        response_model=JobStatus,
+        status_code=202,
+        responses=errors,
+    )
+    def cancel(job_id: UUID):
+        try:
+            scheduler.cancel(job_id)
+            return store.status(job_id)
+        except JobNotFound:
+            return _error(404, "JOB_NOT_FOUND", "job is unknown or expired")
+
+    return application
+
+
+app = create_app()