value-stream 0.1.1__py3-none-any.whl

value_stream/app/schemas.py

@@ -0,0 +1,288 @@
+"""Versioned browser/application wire contract."""
+
+from typing import Annotated, Literal
+from uuid import UUID, uuid4
+from pydantic import ConfigDict, Field, FiniteFloat, model_validator
+from value_stream.service.schemas import WireModel, ModelInput, TaskInput, ErrorEnvelope, Status
+
+GENERATOR_VERSION = "1"
+ENGINE_VERSION = "value-stream-app-1"
+
+
+class AppModel(WireModel):
+    """Base model for application request and response data."""
+
+    model_config = ConfigDict(extra="forbid", json_schema_serialization_defaults_required=True)
+
+
+class ConstantValue(AppModel):
+    """Defines a fixed value for a model setting."""
+
+    kind: Literal["constant"] = "constant"
+    value: FiniteFloat = Field(default=1, ge=0)
+
+
+class UniformValue(AppModel):
+    """Defines a uniformly sampled value for a model setting."""
+
+    kind: Literal["uniform"] = "uniform"
+    minimum: FiniteFloat = Field(ge=0)
+    maximum: FiniteFloat = Field(ge=0)
+
+    @model_validator(mode="after")
+    def ordered(self):
+        if self.minimum > self.maximum:
+            raise ValueError("minimum must not exceed maximum")
+        return self
+
+
+ValueSpec = Annotated[ConstantValue | UniformValue, Field(discriminator="kind")]
+
+
+class TaskSetSpec(AppModel):
+    """Describes a task set used to build a simulation."""
+
+    name: str = Field(default="Task set", min_length=1, max_length=120)
+    count: int = Field(default=500, gt=0)
+    story_points: ValueSpec = Field(default_factory=lambda: UniformValue(minimum=0.5, maximum=2))
+    initial_value: ValueSpec = Field(default_factory=ConstantValue)
+    depreciation_rate: FiniteFloat = Field(default=0.02, ge=0, le=1)
+    seed: int = Field(default=42, ge=0, le=2**53 - 1)
+
+
+class ModelSettings(AppModel):
+    """Defines resource and workflow settings for a simulation model."""
+
+    team_size: int = Field(default=4, gt=0)
+    efficiency_min: FiniteFloat = Field(default=0.5, gt=0)
+    efficiency_max: FiniteFloat = Field(default=1.5, gt=0)
+    distribution: Literal["linear", "normal"] = "linear"
+    deployment_cadence: int = Field(default=5, ge=0)
+    qa_size: int = Field(default=5, gt=0)
+    qa_time_cost: FiniteFloat = Field(default=0.1, ge=0)
+    qa_failure_rate: FiniteFloat = Field(default=0.15, ge=0, le=1)
+    qa_failure_cost: FiniteFloat = Field(default=0.25, ge=0, le=1)
+    toolchain_size: int = Field(default=20, gt=0)
+    deployment_duration: FiniteFloat = Field(default=0.25, ge=0)
+    deployment_failure_rate: FiniteFloat = Field(default=0.1, ge=0, le=1)
+    support_interval: FiniteFloat | None = Field(default=5, gt=0)
+    support_task_story_points: FiniteFloat = Field(default=2, ge=0)
+
+    @model_validator(mode="after")
+    def ordered(self):
+        if self.efficiency_min > self.efficiency_max:
+            raise ValueError("minimum efficiency must not exceed maximum")
+        return self
+
+
+SweepValue = FiniteFloat | str | None
+
+
+class SweepRange(AppModel):
+    """Defines a numeric range of values to sweep."""
+
+    start: FiniteFloat
+    end: FiniteFloat
+    step: FiniteFloat = Field(gt=0)
+
+
+class ScenarioDefinition(AppModel):
+    """Defines a simulation scenario and its parameter values."""
+
+    id: UUID = Field(default_factory=uuid4)
+    name: str = Field(default="Delivery model", min_length=1, max_length=120)
+    revision: int = Field(default=1, gt=0)
+    settings: ModelSettings = Field(default_factory=ModelSettings)
+    sweeps: dict[str, list[SweepValue] | SweepRange] = Field(default_factory=dict)
+    team_seed: int = Field(default=123, ge=0, le=2**53 - 1)
+    execution_seed: int = Field(default=456, ge=0, le=2**53 - 1)
+
+
+class ConcreteScenario(AppModel):
+    """Stores one fully expanded simulation scenario."""
+
+    id: UUID
+    definition_id: UUID
+    revision: int
+    name: str
+    settings: ModelSettings
+    team_seed: int
+    execution_seed: int
+    model: ModelInput
+
+
+class TaskSet(AppModel):
+    """Stores task-generation settings for a workspace."""
+
+    id: UUID = Field(default_factory=uuid4)
+    revision: int = 1
+    spec: TaskSetSpec
+    content_hash: str
+    tasks: list[TaskInput]
+    generator_version: str = GENERATOR_VERSION
+
+
+class EditorRequest(AppModel):
+    """Carries editor changes submitted by a client."""
+
+    expected_revision: int = Field(ge=0)
+    task_spec: TaskSetSpec
+    definitions: list[ScenarioDefinition] = Field(min_length=1, max_length=100)
+
+
+class Preview(AppModel):
+    """Stores the result of validating an editor request."""
+
+    digest: str
+    task_set_id: UUID
+    workspace_revision: int
+    scenarios: list[ConcreteScenario]
+    count: int
+
+
+class RunRequest(AppModel):
+    """Describes a simulation run requested by a client."""
+
+    request_id: UUID
+    preview_digest: str
+    name: str = Field(default="Baseline", min_length=1, max_length=120)
+    intent: Literal["manual", "interactive"] = "manual"
+    source_run_id: UUID | None = None
+    property: str | None = None
+    value: SweepValue = None
+    definition_id: UUID | None = None
+    family_value: SweepValue = None
+
+
+RunState = Literal[
+    "submitting",
+    "queued",
+    "running",
+    "reconnecting",
+    "cancelling",
+    "completed",
+    "completed_with_errors",
+    "cancelled",
+    "failed",
+]
+TERMINAL = {"completed", "completed_with_errors", "cancelled", "failed"}
+
+
+class OutcomeSummary(AppModel):
+    """Summarizes the result of one simulated outcome."""
+
+    scenario: ConcreteScenario
+    status: Status = Status.QUEUED
+    cursor: int = 0
+    cached: bool = False
+    loss_percent: float | None = None
+    completion_time: float | None = None
+    delivered_value: float | None = None
+    error: ErrorEnvelope | None = None
+
+
+class RunStatus(AppModel):
+    """Tracks the state and outcomes of a simulation run."""
+
+    id: UUID
+    name: str
+    task_set_id: UUID
+    state: RunState
+    intent: str
+    job_id: UUID | None = None
+    outcomes: list[OutcomeSummary]
+    last_cursor: int = 0
+    error: ErrorEnvelope | None = None
+    pinned: bool = False
+    superseded: bool = False
+    cancel_requested: bool = False
+    retry_paused: bool = False
+
+
+class Workspace(AppModel):
+    """Stores editable simulation inputs and run history."""
+
+    id: UUID = Field(default_factory=uuid4)
+    revision: int = 0
+    task_spec: TaskSetSpec = Field(default_factory=TaskSetSpec)
+    definitions: list[ScenarioDefinition] = Field(
+        default_factory=lambda: [
+            ScenarioDefinition(sweeps={"team_size": [1, 13, 25], "deployment_cadence": [0, 5, 10]})
+        ]
+    )
+    task_sets: list[TaskSet] = Field(default_factory=list)
+    current_task_set: UUID | None = None
+    baseline_id: UUID | None = None
+    latest_id: UUID | None = None
+    runs: list[RunStatus] = Field(default_factory=list)
+
+
+class ComparisonMutation(AppModel):
+    """Describes a change to a comparison workspace."""
+
+    action: Literal["pin", "unpin", "baseline", "delete"]
+
+
+class StageLoss(AppModel):
+    """Stores value lost during one workflow stage."""
+
+    stage: str
+    label: str
+    loss_percent: float
+    visits: int
+
+
+class ResourceActivity(AppModel):
+    """Summarizes activity for one simulation resource."""
+
+    stage: str
+    label: str
+    durations: dict[str, float]
+    shares: dict[str, float | None]
+
+
+class Backlog(AppModel):
+    """Stores backlog counts for a simulation stage."""
+
+    stage: str
+    label: str
+    time: list[float]
+    waiting: list[int]
+    reduced: bool = False
+
+
+class PlotData(AppModel):
+    """Stores chart labels and series values."""
+
+    loss_percent: float | None
+    stages: list[StageLoss]
+    activity: list[ResourceActivity]
+    backlog: list[Backlog]
+
+
+class Observation(AppModel):
+    """Stores a derived observation about simulation results."""
+
+    rule: str
+    message: str
+    evidence: str
+    property: str | None = None
+    value: SweepValue = None
+
+
+class ResultView(AppModel):
+    """Collects metrics and observations for a result view."""
+
+    scenario_id: UUID
+    metrics: PlotData
+    observations: list[Observation]
+
+
+class AppConfig(AppModel):
+    """Stores application runtime configuration."""
+
+    limits: dict[str, int | float]
+    ready: bool
+    error: ErrorEnvelope | None = None
+    generator_version: str = GENERATOR_VERSION
+    engine_version: str = ENGINE_VERSION

value_stream/app/server.py

@@ -0,0 +1,298 @@
+"""Single-origin web application and JSON contract."""
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Optional
+from uuid import UUID
+from fastapi import FastAPI, Query
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.types import ASGIApp, Scope, Receive, Send
+from pydantic import ValidationError
+from value_stream.service.schemas import ErrorEnvelope, HealthResponse
+from .settings import AppSettings
+from .storage import InMemoryWorkspaceStore, WorkspaceStore
+from .gateway import HttpSimulationGateway
+from .coordinator import RunCoordinator
+from .errors import AppError
+from .schemas import (
+    Workspace,
+    EditorRequest,
+    Preview,
+    RunRequest,
+    RunStatus,
+    OutcomeSummary,
+    ComparisonMutation,
+    ResultView,
+    AppConfig,
+    TERMINAL,
+)
+from .metrics import plot_data
+from .insights import observations
+from .exports import export_csv
+
+logger = logging.getLogger(__name__)
+
+
+class BodyLimitMiddleware:
+    """Rejects requests whose bodies exceed the configured size limit."""
+
+    def __init__(self, app: ASGIApp, limit: int):
+        self.app, self.limit = app, limit
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] != "http" or scope["method"] not in {"POST", "PUT", "PATCH"}:
+            return await self.app(scope, receive, send)
+        size, messages = 0, []
+        while True:
+            message = await receive()
+            if message["type"] == "http.disconnect":
+                return
+            size += len(message.get("body", b""))
+            if size > self.limit:
+                return await JSONResponse(
+                    AppError(
+                        "BODY_TOO_LARGE",
+                        "Request exceeds the configured body limit",
+                        413,
+                    ).body(),
+                    status_code=413,
+                )(scope, receive, send)
+            messages.append(message)
+            if not message.get("more_body"):
+                break
+        iterator = iter(messages)
+
+        async def replay():
+            return next(iterator)
+
+        await self.app(scope, replay, send)
+
+
+def create_app(
+    settings: Optional[AppSettings] = None,
+    store: Optional[WorkspaceStore] = None,
+    gateway=None,
+    service_url=None,
+):
+    settings = settings or AppSettings.from_environment()
+    _store: WorkspaceStore = store or InMemoryWorkspaceStore(settings)
+    gateway = gateway or HttpSimulationGateway(
+        service_url or os.getenv("VALUE_STREAM_SERVICE_URL"),
+        settings.max_run_bytes + 1024 * 1024,
+    )
+    coordinator = RunCoordinator(_store, gateway)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        try:
+            await gateway.start()
+        except Exception:
+            logger.exception("Simulation service startup failed; workspace UI remains available")
+        yield
+        await coordinator.close()
+        await gateway.close()
+
+    app = FastAPI(title="Value Stream Application", version="1.0.0", lifespan=lifespan)
+    app.state.store, app.state.coordinator, app.state.gateway = (
+        _store,
+        coordinator,
+        gateway,
+    )
+    app.add_middleware(BodyLimitMiddleware, limit=settings.max_body_bytes)
+
+    @app.exception_handler(AppError)
+    async def app_error(request, exc):
+        return JSONResponse(exc.body(), status_code=exc.status)
+
+    @app.exception_handler(RequestValidationError)
+    @app.exception_handler(ValidationError)
+    async def invalid(request, exc):
+        issues = [{"location": list(e["loc"]), "message": e["msg"]} for e in exc.errors()]
+        return JSONResponse(
+            AppError(
+                "INVALID_INPUT",
+                "Please correct the highlighted inputs.",
+                details={"issues": issues},
+            ).body(),
+            status_code=422,
+        )
+
+    @app.exception_handler(Exception)
+    async def unexpected(request, exc):
+        logger.exception("Unexpected application error", exc_info=exc)
+        return JSONResponse(
+            AppError("INTERNAL_ERROR", "Unexpected application error", 500).body(),
+            status_code=500,
+        )
+
+    errors: dict[int | str, dict[str, Any]] = {
+        code: {"model": ErrorEnvelope} for code in [404, 409, 413, 422, 429, 500, 502, 503]
+    }
+    prefix = "/api/v1/workspaces/{workspace_id}"
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health():
+        return HealthResponse()
+
+    @app.get("/ready", response_model=HealthResponse, responses=errors)
+    async def ready():
+        await gateway.ready()
+        return HealthResponse()
+
+    @app.get("/api/v1/config", response_model=AppConfig)
+    async def config():
+        try:
+            await gateway.ready()
+            return AppConfig(limits=asdict(settings), ready=True)
+        except AppError as exc:
+            return AppConfig(
+                limits=asdict(settings), ready=False, error=ErrorEnvelope(**exc.body())
+            )
+
+    @app.post(
+        "/api/v1/workspaces",
+        response_model=Workspace,
+        status_code=201,
+        responses=errors,
+    )
+    async def create_workspace():
+        return _store.create()
+
+    @app.get(prefix, response_model=Workspace, responses=errors)
+    async def workspace(workspace_id: UUID):
+        return _store.get(workspace_id)
+
+    @app.delete(prefix, status_code=204, responses=errors)
+    async def delete_workspace(workspace_id: UUID):
+        _store.delete_workspace(workspace_id)
+
+    @app.put(prefix + "/editor", response_model=Preview, responses=errors)
+    async def save_editor(workspace_id: UUID, request: EditorRequest):
+        return _store.save_editor(workspace_id, request)
+
+    @app.post(prefix + "/preview", response_model=Preview, responses=errors)
+    async def preview(workspace_id: UUID):
+        return _store.preview(workspace_id)
+
+    @app.delete(prefix + "/task-sets/{task_set_id}", status_code=204, responses=errors)
+    async def delete_task_set(workspace_id: UUID, task_set_id: UUID, expected_revision: int):
+        _store.delete_task_set(workspace_id, task_set_id, expected_revision)
+
+    @app.post(prefix + "/runs", response_model=RunStatus, status_code=202, responses=errors)
+    async def start_run(workspace_id: UUID, request: RunRequest):
+        return await coordinator.start_run(workspace_id, request)
+
+    @app.get(prefix + "/runs/{run_id}", response_model=RunStatus, responses=errors)
+    async def run(workspace_id: UUID, run_id: UUID):
+        return _store.run(workspace_id, run_id).status
+
+    @app.get(
+        prefix + "/runs/{run_id}/outcomes",
+        response_model=list[OutcomeSummary],
+        responses=errors,
+    )
+    async def outcomes(workspace_id: UUID, run_id: UUID, after: int = Query(0, ge=0)):
+        return sorted(
+            [o for o in _store.run(workspace_id, run_id).status.outcomes if o.cursor > after],
+            key=lambda o: o.cursor,
+        )
+
+    @app.delete(
+        prefix + "/runs/{run_id}",
+        response_model=RunStatus,
+        status_code=202,
+        responses=errors,
+    )
+    async def cancel(workspace_id: UUID, run_id: UUID):
+        return await coordinator.cancel_run(workspace_id, run_id)
+
+    @app.post(prefix + "/runs/{run_id}/resume", response_model=RunStatus, responses=errors)
+    async def resume(workspace_id: UUID, run_id: UUID):
+        return coordinator.resume(workspace_id, run_id)
+
+    @app.post(prefix + "/runs/{run_id}/comparison", response_model=Workspace, responses=errors)
+    async def comparison(workspace_id: UUID, run_id: UUID, mutation: ComparisonMutation):
+        return _store.comparison(workspace_id, run_id, mutation.action)
+
+    @app.get(
+        prefix + "/runs/{run_id}/results/{scenario_id}",
+        response_model=ResultView,
+        responses=errors,
+    )
+    async def result(workspace_id: UUID, run_id: UUID, scenario_id: UUID):
+        record = _store.run(workspace_id, run_id)
+        result = _store.result(record, scenario_id)
+        scenario = next(o.scenario for o in record.status.outcomes if o.scenario.id == scenario_id)
+        metrics = plot_data(result, sum(t.initial_value for t in record.task_set.tasks))
+        insights = [
+            o
+            for o in observations(metrics, scenario.settings)
+            if o.property not in {"qa_size", "team_size", "toolchain_size"}
+            or ((o.value is not None) and (int(o.value) <= settings.max_resources))
+        ]
+        return ResultView(scenario_id=scenario_id, metrics=metrics, observations=insights)
+
+    @app.get(
+        prefix + "/runs/{run_id}/exports/{kind}",
+        responses={200: {"content": {"text/csv": {}}}, **errors},
+    )
+    async def export(workspace_id: UUID, run_id: UUID, kind: str):
+        if kind not in {"summary", "events", "resources"}:
+            raise AppError("INVALID_INPUT", "Choose summary, events, or resources")
+        record = _store.run(workspace_id, run_id)
+        if record.status.state not in TERMINAL:
+            raise AppError(
+                "RUN_ACTIVE",
+                "Wait for completion or cancel before exporting a stable comparison",
+                409,
+            )
+        # Snapshot both rows and result references before streaming across threads.
+        import copy
+
+        snapshot = copy.copy(record)
+        snapshot.status = record.status.model_copy(deep=True)
+        frozen_results = {sid: _store.result(record, sid) for sid in record.results}
+
+        class ExportStore:
+            """Stores generated exports for later download."""
+
+            def result(self, record, sid):
+                return frozen_results[sid]
+
+        return StreamingResponse(
+            export_csv(ExportStore(), snapshot, kind),
+            media_type="text/csv; charset=utf-8",
+            headers={"Content-Disposition": f'attachment; filename="{kind}-{run_id}.csv"'},
+        )
+
+    class CachedAssets(StaticFiles):
+        """Serves cached frontend assets."""
+
+        async def get_response(self, path, scope):
+            response = await super().get_response(path, scope)
+            if response.status_code == 200:
+                response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
+            return response
+
+    static = Path(__file__).parent / "static"
+    if (static / "assets").exists():
+        app.mount("/assets", CachedAssets(directory=static / "assets"), name="assets")
+
+    @app.get("/", include_in_schema=False)
+    async def index():
+        if not (static / "index.html").is_file():
+            return JSONResponse(
+                {
+                    "code": "ASSETS_MISSING",
+                    "message": "Build the UI: npm run build --prefix src/value_stream/app/frontend",
+                },
+                status_code=503,
+            )
+        return FileResponse(static / "index.html", headers={"Cache-Control": "no-cache"})
+
+    return app

value_stream/app/settings.py

@@ -0,0 +1,46 @@
+"""Bounded single-instance application configuration."""
+
+import os
+import math
+from dataclasses import dataclass, fields
+
+
+@dataclass(frozen=True)
+class AppSettings:
+    """Stores application settings."""
+
+    max_workspaces: int = 4
+    max_task_sets: int = 20
+    max_definitions: int = 100
+    max_tasks: int = 1000
+    max_models: int = 500
+    max_resources: int = 100
+    max_axis_values: int = 32
+    max_pins: int = 12
+    max_active_runs: int = 4
+    max_retained_runs: int = 32
+    max_body_bytes: int = 2 * 1024 * 1024
+    max_input_bytes: int = 16 * 1024 * 1024
+    max_result_bytes: int = 1024 * 1024 * 1024
+    max_run_bytes: int = 1024 * 1024 * 1024
+    max_model_bytes: int = 8 * 1024 * 1024
+    poll_seconds: float = 0.5
+    retry_seconds: float = 60.0
+    min_interactive_seconds: float = 1.0
+
+    def __post_init__(self):
+        if any(
+            not math.isfinite(getattr(self, f.name)) or getattr(self, f.name) <= 0
+            for f in fields(self)
+        ):
+            raise ValueError("application limits must be finite and positive")
+
+    @classmethod
+    def from_environment(cls):
+        defaults = cls()
+        values = {}
+        for f in fields(cls):
+            key = "VALUE_STREAM_APP_" + f.name.upper()
+            if key in os.environ:
+                values[f.name] = type(getattr(defaults, f.name))(os.environ[key])
+        return cls(**values)