value-stream 0.1.1__py3-none-any.whl

value_stream/app/gateway.py

@@ -0,0 +1,130 @@
+"""HTTP-only simulation boundary with bounded reads and owned startup."""
+
+import asyncio
+from typing import Protocol
+from uuid import UUID
+import httpx
+from value_stream.service.schemas import JobRequest, JobAccepted, JobStatus, OutcomePage
+from .errors import AppError
+
+
+class SimulationGateway(Protocol):
+    """Defines the interface for submitting simulation jobs."""
+
+    async def start(self): ...
+    async def ready(self): ...
+    async def submit(self, request: JobRequest) -> JobAccepted: ...
+    async def status(self, job_id: UUID) -> JobStatus: ...
+    async def outcomes(self, job_id: UUID, after: int) -> OutcomePage: ...
+    async def cancel(self, job_id: UUID) -> JobStatus: ...
+    async def close(self): ...
+
+
+class HttpSimulationGateway:
+    """Submits simulation jobs through the HTTP service."""
+
+    def __init__(self, url=None, max_response_bytes=65 * 1024 * 1024):
+        self.url = url
+        self.owned = False
+        self.client = None
+        self.max_response_bytes = max_response_bytes
+        self.download = asyncio.Semaphore(1)
+
+    async def start(self):
+        if not self.url:
+            from value_stream.client.web.local_service import acquire_local_service
+
+            self.url = await asyncio.to_thread(acquire_local_service)
+            self.owned = True
+        self.client = httpx.AsyncClient(
+            base_url=self.url, timeout=httpx.Timeout(10, connect=3), trust_env=False
+        )
+
+    async def request(self, method, path, body=None):
+        if self.client is None or self.client.is_closed:
+            raise AppError("SERVICE_UNAVAILABLE", "Simulation service is not connected", 503)
+        try:
+            async with self.download:
+                async with self.client.stream(method, path, json=body) as response:
+                    data = bytearray()
+                    async for chunk in response.aiter_bytes():
+                        data.extend(chunk)
+                        if len(data) > self.max_response_bytes:
+                            raise AppError(
+                                "RESULT_TOO_LARGE",
+                                "Service response exceeds the configured limit",
+                                502,
+                            )
+                    import json
+
+                    try:
+                        value = json.loads(data)
+                    except ValueError as exc:
+                        raise AppError(
+                            "SERVICE_INVALID_RESPONSE",
+                            "Service returned invalid JSON",
+                            502,
+                        ) from exc
+                    if not isinstance(value, dict):
+                        raise AppError(
+                            "SERVICE_INVALID_RESPONSE",
+                            "Service returned a non-object JSON response",
+                            502,
+                        )
+                    if response.is_error:
+                        raise AppError(
+                            value.get("code", "SERVICE_ERROR"),
+                            value.get("message", "Simulation service request failed"),
+                            response.status_code,
+                            value.get("details"),
+                        )
+                    return value
+        except httpx.RequestError as exc:
+            raise AppError(
+                "SERVICE_UNAVAILABLE",
+                "Cannot reach the simulation service. Retained results are still available.",
+                503,
+            ) from exc
+
+    async def ready(self):
+        await self.request("GET", "/health")
+        schema = await self.request("GET", "/openapi.json")
+        properties = (
+            schema.get("components", {})
+            .get("schemas", {})
+            .get("JobRequest", {})
+            .get("properties", {})
+        )
+        if not {"model_seeds", "submission_id"} <= properties.keys():
+            raise AppError(
+                "SERVICE_INCOMPATIBLE",
+                "Update the simulation service: model seeds and submission identifiers are required.",
+                503,
+            )
+
+    async def submit(self, request):
+        return JobAccepted.model_validate(
+            await self.request("POST", "/v1/simulation-jobs", request.model_dump(mode="json"))
+        )
+
+    async def status(self, job_id):
+        return JobStatus.model_validate(await self.request("GET", f"/v1/simulation-jobs/{job_id}"))
+
+    async def outcomes(self, job_id, after):
+        return OutcomePage.model_validate(
+            await self.request("GET", f"/v1/simulation-jobs/{job_id}/outcomes?after={after}")
+        )
+
+    async def cancel(self, job_id):
+        return JobStatus.model_validate(
+            await self.request("DELETE", f"/v1/simulation-jobs/{job_id}")
+        )
+
+    async def close(self):
+        if self.client:
+            await self.client.aclose()
+        if self.owned:
+            from value_stream.client.web.local_service import release_local_service
+
+            await asyncio.to_thread(release_local_service)
+            self.owned = False

value_stream/app/generation.py

@@ -0,0 +1,269 @@
+"""Pure, bounded materialization independent of batch ordering."""
+
+from typing import Any
+
+import hashlib
+import itertools
+import json
+import math
+import random
+from decimal import Decimal
+from uuid import UUID, uuid5
+from pydantic import ValidationError
+from value_stream.service.schemas import (
+    DeveloperInput,
+    ModelInput,
+    QAPoolInput,
+    ToolchainPoolInput,
+    TaskInput,
+)
+from .errors import AppError
+from .schemas import (
+    ConstantValue,
+    TaskSetSpec,
+    ModelSettings,
+    ScenarioDefinition,
+    SweepRange,
+    ConcreteScenario,
+    GENERATOR_VERSION,
+)
+from .settings import AppSettings
+
+
+def canonical(value: Any) -> str:
+    """Serialize a value with stable key ordering and separators.
+
+    Args:
+        value (Any): Value to normalize or inspect.
+
+    Returns:
+        str: Canonical JSON representation of the value.
+    """
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), allow_nan=False, default=str)
+
+
+def fingerprint(value: Any) -> str:
+    """Return the SHA-256 fingerprint of a canonical value.
+
+    Args:
+        value (Any): Value to normalize or inspect.
+
+    Returns:
+        str: Hexadecimal SHA-256 digest.
+    """
+    return hashlib.sha256(canonical(value).encode()).hexdigest()
+
+
+def derive_seed(domain, *values):
+    # JSON numbers remain exactly representable in the browser.
+    return int(fingerprint([GENERATOR_VERSION, domain, *values])[:13], 16)
+
+
+def materialize_tasks(spec: TaskSetSpec) -> list[TaskInput]:
+    """Build task inputs from the task set settings.
+
+    Args:
+        spec (TaskSetSpec): Task set configuration used to generate tasks.
+
+    Returns:
+        list[TaskInput]: Generated task inputs.
+    """
+
+    rng = random.Random(derive_seed("tasks", spec.seed))
+
+    def sample(value):
+        return (
+            value.value
+            if isinstance(value, ConstantValue)
+            else rng.uniform(value.minimum, value.maximum)
+        )
+
+    return [
+        TaskInput(
+            task_name=str(i + 1),
+            initial_value=sample(spec.initial_value),
+            story_points=sample(spec.story_points),
+            depreciation_rate=spec.depreciation_rate,
+        )
+        for i in range(spec.count)
+    ]
+
+
+def materialize_team(settings: ModelSettings, seed: int) -> list[DeveloperInput]:
+    """Build a developer team using the configured efficiency distribution.
+
+    Args:
+        settings (ModelSettings): Settings to validate or use.
+        seed (int): Random seed for repeatable simulation.
+
+    Returns:
+        list[DeveloperInput]: Generated developer inputs.
+    """
+    low, high, n = settings.efficiency_min, settings.efficiency_max, settings.team_size
+    rng = random.Random(derive_seed("team", seed, low, high, settings.distribution))
+    values = []
+    for i in range(n):
+        if low == high:
+            value = low
+        elif settings.distribution == "linear":
+            value = low + (high - low) / 2 if n == 1 else low + (high - low) * (i / (n - 1))
+        else:
+            while True:
+                value = rng.gauss(low + (high - low) / 2, (high - low) / 6)
+                if low <= value <= high:
+                    break
+        values.append(DeveloperInput(name=f"Developer {i + 1}", efficiency=value))
+    return values
+
+
+def concrete_model(settings: ModelSettings, seed: int) -> ModelInput:
+    """Build a service model input from scenario settings.
+
+    Args:
+        settings (ModelSettings): Settings to validate or use.
+        seed (int): Random seed for repeatable simulation.
+
+    Returns:
+        ModelInput: Model configuration ready for submission.
+    """
+    return ModelInput(
+        developer_team=materialize_team(settings, seed),
+        deployment_cadence=settings.deployment_cadence,
+        qa_testers=QAPoolInput(
+            limit=settings.qa_size,
+            time_cost=settings.qa_time_cost,
+            failure_rate=settings.qa_failure_rate,
+            failure_cost=settings.qa_failure_cost,
+        ),
+        toolchain_pool=ToolchainPoolInput(
+            limit=settings.toolchain_size,
+            deployment_duration=settings.deployment_duration,
+            failure_rate=settings.deployment_failure_rate,
+        ),
+        support_interval=settings.support_interval,
+        support_task_story_points=settings.support_task_story_points,
+    )
+
+
+def axis_values(axis: SweepRange | list[Any], limit: int) -> list[Any]:
+    """Expand a sweep axis into its distinct values.
+
+    Args:
+        axis (SweepRange | list[Any]): Range or explicit values to expand.
+        limit (int): Maximum number of values allowed.
+
+    Raises:
+        AppError: If the axis is empty, invalid, or exceeds the configured value limit.
+
+    Returns:
+        list[Any]: Expanded sweep values.
+    """
+    if isinstance(axis, SweepRange):
+        start, end, step = (Decimal(str(v)) for v in (axis.start, axis.end, axis.step))
+        if start > end:
+            raise AppError("INVALID_INPUT", "Sweep start must not exceed end")
+        span = (end - start) / step
+        if span >= limit:
+            raise AppError("LIMIT_EXCEEDED", f"Each sweep can contain at most {limit} values")
+        count = int(span) + 1
+        values = [float(start + step * i) for i in range(count)]
+    else:
+        if len(axis) > limit:
+            raise AppError("LIMIT_EXCEEDED", f"Each sweep can contain at most {limit} values")
+        values = list(dict.fromkeys(axis))
+    if not values:
+        raise AppError("INVALID_INPUT", "A sweep needs at least one value")
+    return values
+
+
+def validate_model_limits(settings: ModelSettings, limits: AppSettings) -> None:
+    """Validate model settings against configured limits.
+
+    Args:
+        settings (ModelSettings): Model settings to validate.
+        limits (AppSettings): Application limits to enforce.
+
+    Raises:
+        AppError: If a model setting falls outside the configured limits.
+    """
+    if max(settings.team_size, settings.qa_size, settings.toolchain_size) > limits.max_resources:
+        raise AppError("LIMIT_EXCEEDED", f"Resource counts must not exceed {limits.max_resources}")
+
+
+def expand_scenarios(
+    definitions: list[ScenarioDefinition], limits: AppSettings
+) -> list[ConcreteScenario]:
+    """Expand scenario definitions into concrete scenarios.
+
+    Args:
+        definitions (list[ScenarioDefinition]): Definitions.
+        limits (AppSettings): Configured limits for validation.
+
+    Raises:
+        AppError: If scenario definitions are invalid or exceed the expansion limit.
+
+    Returns:
+        list[ConcreteScenario]: The resulting value.
+    """
+    axes = []
+    count = 0
+    if len(definitions) > limits.max_definitions:
+        raise AppError("LIMIT_EXCEEDED", "Too many definitions")
+    for definition in definitions:
+        unknown = set(definition.sweeps) - ModelSettings.model_fields.keys()
+        if unknown:
+            raise AppError(
+                "INVALID_INPUT",
+                f"Unknown sweep properties: {', '.join(sorted(unknown))}",
+            )
+        values = {
+            k: axis_values(v, limits.max_axis_values) for k, v in sorted(definition.sweeps.items())
+        }
+        count += math.prod(len(v) for v in values.values())
+        if count > limits.max_models:
+            raise AppError(
+                "LIMIT_EXCEEDED",
+                f"Sweep produces more than {limits.max_models} models. Reduce the sweep or configure a higher limit.",
+            )
+        axes.append(values)
+    scenarios: list[ConcreteScenario] = []
+    seen = set()
+    for definition, values in zip(definitions, axes):
+        for combination in itertools.product(*values.values()):
+            changed = dict(zip(values, combination))
+            try:
+                settings = ModelSettings.model_validate(
+                    {**definition.settings.model_dump(), **changed}
+                )
+            except ValidationError as exc:
+                raise AppError(
+                    "INVALID_INPUT",
+                    "Invalid sweep combination",
+                    details={
+                        "definition": definition.name,
+                        "values": changed,
+                        "issues": str(exc),
+                    },
+                ) from exc
+            validate_model_limits(settings, limits)
+            identity = canonical(settings.model_dump())
+            scenario_id = uuid5(definition.id, identity)
+            if scenario_id in seen:
+                continue
+            seen.add(scenario_id)
+            label = ", ".join(f"{k.replace('_', ' ')}={getattr(settings, k)}" for k in changed)
+            scenarios.append(
+                ConcreteScenario(
+                    id=scenario_id,
+                    definition_id=definition.id,
+                    revision=definition.revision,
+                    name=f"{definition.name} · {label}" if label else definition.name,
+                    settings=settings,
+                    team_seed=definition.team_seed,
+                    execution_seed=derive_seed(
+                        "simulation", definition.execution_seed, str(scenario_id)
+                    ),
+                    model=concrete_model(settings, definition.team_seed),
+                )
+            )
+    return scenarios

value_stream/app/insights.py

@@ -0,0 +1,75 @@
+"""Small evidence-backed observations; proposed interventions are untested."""
+
+from .schemas import ModelSettings, Observation, PlotData
+
+
+def observations(metrics: PlotData, settings: ModelSettings) -> list[Observation]:
+    """Build evidence-backed observations from simulation metrics.
+
+    Args:
+        metrics (PlotData): Simulation metrics to summarize.
+        settings (ModelSettings): Model settings used to suggest changes.
+
+    Returns:
+        list[Observation]: Findings derived from the supplied metrics.
+    """
+    if metrics.loss_percent is None:
+        return [
+            Observation(
+                rule="zero_value",
+                message="Value-loss comparisons are unavailable because initial value is zero.",
+                evidence="Total initial value is zero.",
+            )
+        ]
+    result: list[Observation] = []
+    if metrics.stages:
+        stage = max(metrics.stages, key=lambda item: item.loss_percent)
+        if stage.loss_percent > 0:
+            result.append(
+                Observation(
+                    rule="stage_loss",
+                    message=f"{stage.label} has the largest observed mean stage-visit loss.",
+                    evidence=f"{stage.loss_percent:.2f}% across {stage.visits} visits. These means are not an additive breakdown of total loss.",
+                    property=(
+                        "deployment_cadence"
+                        if stage.stage == "qa_complete" and settings.deployment_cadence
+                        else None
+                    ),
+                    value=max(0, settings.deployment_cadence // 2),
+                )
+            )
+    if metrics.backlog:
+        queue = max(metrics.backlog, key=lambda item: max(item.waiting, default=0))
+        peak = max(queue.waiting, default=0)
+        if peak > 0:
+            field = {
+                "qa_testing": "qa_size",
+                "development": "team_size",
+                "deployment": "toolchain_size",
+            }.get(queue.stage)
+            result.append(
+                Observation(
+                    rule="backlog",
+                    message=f"{queue.label} has the largest observed resource-request backlog. Try additional capacity.",
+                    evidence=f"Peak: {peak} waiting requests; a request may contain several tasks. Improvement is untested.",
+                    property=field,
+                    value=getattr(settings, field) + 1 if field else None,
+                )
+            )
+    for item in metrics.activity:
+        if item.durations["failure_t"] > 0:
+            field = (
+                "qa_failure_rate"
+                if item.stage == "qa_testing"
+                else "deployment_failure_rate" if item.stage == "deployment" else None
+            )
+            result.append(
+                Observation(
+                    rule="failed_work",
+                    message=f"{item.label} records time spent on failed work. Test a lower failure rate.",
+                    evidence=f"Recorded failed-work duration: {item.durations['failure_t']:.2f} time units. Improvement is untested.",
+                    property=field,
+                    value=getattr(settings, field) / 2 if field else None,
+                )
+            )
+    return result

value_stream/app/metrics.py

@@ -0,0 +1,132 @@
+"""Explicit display measures for the existing simulation telemetry."""
+
+from collections import defaultdict
+
+from value_stream.service.schemas import ResultData
+
+from .errors import AppError
+from .schemas import PlotData, StageLoss, ResourceActivity, Backlog
+
+STAGES = {
+    "pending": "Waiting for development",
+    "development": "Development",
+    "dev_complete": "Waiting for QA",
+    "qa_testing": "QA testing",
+    "qa_complete": "Waiting for deployment",
+    "deployment": "Deployment",
+    "delivery": "Delivery",
+    "support_pending": "Support waiting",
+    "support_complete": "Support complete",
+}
+CATEGORIES = ("idle_t", "success_t", "failure_t", "interruption_t")
+
+
+def loss_percent(initial, delivered):
+    return 100 * (initial - delivered) / initial if initial else None
+
+
+# thin out by chunking and returning start, end, min and max from each chunk
+def reduce_points(points: list[tuple[float, int]], limit: int = 5000) -> list[tuple[float, int]]:
+    """Keep representative extrema while reducing a series to the point limit.
+
+    Args:
+        points (list[tuple[float, int]]): Ordered (time, value) points to reduce.
+        limit (int): Maximum number of points to keep.
+
+    Returns:
+        list[tuple[float, int]]: Reduced points, preserving each chunk boundary and extreme value.
+    """
+    if len(points) <= limit:
+        return points
+    width = max(1, (len(points) + limit // 4 - 1) // (limit // 4))
+    result = []
+    for start in range(0, len(points), width):
+        chunk = points[start : start + width]
+        indices = {
+            0,
+            len(chunk) - 1,
+            min(range(len(chunk)), key=lambda i: chunk[i][1]),
+            max(range(len(chunk)), key=lambda i: chunk[i][1]),
+        }
+        result.extend(chunk[i] for i in sorted(indices))
+    return result
+
+
+def plot_data(result: ResultData, initial: float) -> PlotData:
+    """Build plot data from a simulation result.
+
+    Args:
+        result (ResultData): Simulation result to retain.
+        initial (float): Total initial task value used to calculate loss.
+
+    Raises:
+        AppError: If the requested operation is invalid.
+
+    Returns:
+        PlotData: PlotData containing stage loss, resource activity, and backlog series.
+    """
+    events: dict[str, list[float]] = defaultdict(list)
+    durations: dict[str, dict[str, float]] = defaultdict(lambda: dict.fromkeys(CATEGORIES, 0.0))
+    waiting: dict[str, dict[float, int]] = defaultdict(lambda: defaultdict(int))
+
+    # summarize loss by event (workflow state)
+    for event in result.metadata.event_metadata:
+        if event.event_type == "end" and event.task_type == "development":
+            events[event.event].append(-100 * event.loss)
+
+    for record in result.metadata.resource_metadata:
+        # track incremental increase/decrease in waiting resources by workflow state
+        waiting[record.state][record.time] += record.waiting
+
+        # summarize time spent by resource in each time category
+        for key in CATEGORIES:
+            durations[record.state][key] += getattr(record, key) or 0
+
+    stages, activity, backlog = [], [], []
+    for stage in dict.fromkeys([*STAGES, *events, *durations]):
+        label = STAGES.get(stage, stage)
+        if events[stage]:
+            stages.append(
+                StageLoss(
+                    stage=stage,
+                    label=label,
+                    visits=len(events[stage]),
+                    loss_percent=sum(events[stage]) / len(events[stage]),
+                )
+            )
+        if stage in durations:
+            total = sum(durations[stage].values())
+            activity.append(
+                ResourceActivity(
+                    stage=stage,
+                    label=label,
+                    durations=durations[stage],
+                    shares={
+                        k: 100 * v / total if total else None for k, v in durations[stage].items()
+                    },
+                )
+            )
+        if stage in waiting:
+            points, current = [(0.0, 0)], 0
+            for time, delta in sorted(waiting[stage].items()):
+                current += delta
+                if current < 0:
+                    raise AppError("INVALID_RESULT", "Resource backlog became negative", 502)
+                points.append((time, current))
+            points.append((result.summary_result.completion_time, current))
+            reduced = reduce_points(points)
+            backlog.append(
+                Backlog(
+                    stage=stage,
+                    label=label,
+                    time=[p[0] for p in reduced],
+                    waiting=[p[1] for p in reduced],
+                    reduced=len(points) != len(reduced),
+                )
+            )
+    return PlotData(
+        loss_percent=loss_percent(initial, result.summary_result.total_delivered_value),
+        stages=stages,
+        activity=activity,
+        backlog=backlog,
+    )