value-stream 0.1.1__py3-none-any.whl

value_stream/factory/developer_factory.py

@@ -0,0 +1,33 @@
+from typing import Any
+from value_stream.resources import Developer
+
+from .factory import Factory
+
+
+class DeveloperFactory(Factory):
+    """Utility for creating Developer objects"""
+
+    @classmethod
+    def create(cls, count: int, **kwargs: Any) -> list[Developer]:
+        """Creates Developer objects based on DeveloperFactory configuration.
+
+        Args:
+            count (int): number of developers to create
+            **kwargs (Any): Kwargs.
+        """
+
+        if count <= 0:
+            raise ValueError("count must be > 0")
+
+        developers: list[Developer] = []
+
+        for i in range(count):
+            args = cls._generate_args(**kwargs)
+
+            developers.append(Developer(name=cls._developer_name(i), **args))
+
+        return developers
+
+    @classmethod
+    def _developer_name(cls, index: int) -> str:
+        return f"Developer {index}"

value_stream/factory/factory.py

@@ -0,0 +1,43 @@
+from typing import Any, Generator
+import numpy as np
+
+
+class Factory:
+    """Provides shared helpers for creating configured simulation objects."""
+
+    _rng = np.random.default_rng()
+
+    @classmethod
+    def uniform(cls, low: float, high: float) -> Generator[float, Any, None]:
+        """Yield samples from a uniform distribution.
+
+        Args:
+            low (float): Lower bound of the range.
+            high (float): Upper bound of the range.
+
+        Yields:
+            float: Successive random samples.
+        """
+
+        while True:
+            yield cls._rng.uniform(low, high)
+
+    @classmethod
+    def _generate_args(cls, **kwargs: Any) -> dict[str, Any]:
+        """Resolve generator-valued arguments to their next values.
+
+        Args:
+            **kwargs (Any): Values to pass to a factory-created object.
+
+        Returns:
+            dict[str, Any]: Arguments with generator values sampled once.
+        """
+        args = {}
+
+        for k, v in kwargs.items():
+            if isinstance(v, Generator):
+                args[k] = next(v)
+            else:
+                args[k] = v
+
+        return args

value_stream/factory/task_factory.py

@@ -0,0 +1,64 @@
+from typing import Any, Type, Optional
+import random
+
+from simpy import Environment
+
+from value_stream.task import Task
+
+from .factory import Factory
+
+
+class TaskFactory(Factory):
+    """Utility for creating Tasks"""
+
+    def __init__(self, cls: Type[Task] = Task, **task_kwargs: Any) -> None:
+        """Initializes a TaskFactory.
+
+        Args:
+            **task_kwargs (Any): Default task constructor arguments.
+        """
+
+        self._task_kwargs = task_kwargs
+        self.cls = cls
+
+    def create(
+        self, count: int, env: Optional[Environment] = None, shuffle: bool = True
+    ) -> list[Task]:
+        """Creates Task objects based on TaskFactory configuration.
+
+        Args:
+            count (int): Number of objects to create.
+            env (Optional[Environment]): Simulation environment.
+            shuffle (bool): Whether to randomize the created task order.
+
+        Raises:
+            ValueError: If count is not positive or environment time conflicts with creation_sim_t.
+
+        Returns:
+            list[Task]: Tasks created with this factory configuration.
+        """
+
+        if count <= 0:
+            raise ValueError("count must be > 0")
+
+        if (env is not None) and ("creation_sim_t" in self._task_kwargs):
+            raise ValueError("env and creation_sim_t are mutually exclusive")
+
+        tasks: list[Task] = []
+
+        for i in range(count):
+
+            args = self._generate_args(**self._task_kwargs)
+
+            if "task_name" not in args:
+                args["task_name"] = f"{i+1}"
+
+            if env is not None:
+                args["creation_sim_t"] = env.now
+
+            tasks.append(self.cls(**args))
+
+        if shuffle is True:
+            random.shuffle(tasks)
+
+        return tasks

value_stream/factory/task_generator.py

@@ -0,0 +1,102 @@
+from typing import Optional
+
+from simpy import Environment, Interrupt, Process, Store
+from value_stream.task import Task
+from .task_factory import TaskFactory
+
+
+class TaskGenerator:
+    """creates a set of Tasks at a regular simulation time interval.
+    Useful for simulating task creation over time and the creation of unexpected toil.
+    """
+
+    def __init__(
+        self, factory: TaskFactory, group_size: int = 1, limit: Optional[int] = None
+    ) -> None:
+        """Configure task generation and its output limit.
+
+        Args:
+            factory (TaskFactory): Task factory used to create tasks.
+            group_size (int): Number of tasks generated in each group.
+            limit (Optional[int]): Maximum number of items allowed.
+        """
+
+        self.group_size = group_size
+        self.factory = factory
+
+        self.proc: Optional[Process] = None
+        self._batch_num = 0
+        self.limit = limit
+
+    def _get_tasks(self, env: Environment) -> list[Task]:
+        """Generate the next group of tasks.
+
+        Args:
+            env (Environment): Simulation environment.
+
+        Returns:
+            list[Task]: The generated task group.
+        """
+
+        self._batch_num += 1
+        serial_num = 0
+
+        tasks = self.factory.create(env=env, count=self.group_size)
+
+        for task in tasks:
+            if self.group_size == 1:
+                task.task_name = f"S{self._batch_num}"
+            else:
+                serial_num += 1
+                task.task_name = f"S{self._batch_num}-{serial_num}"
+
+        return tasks
+
+    def start(self, env: Environment, target: Store, interval: float) -> None:
+        """Start generating tasks at the requested interval.
+
+        Args:
+            env (Environment): Simulation environment.
+            target (Store): Target.
+            interval (float): Interval.
+
+        Raises:
+            ValueError: If the generation interval is not positive.
+
+        """
+
+        if interval <= 0:
+            raise ValueError("interval must be > 0")
+
+        self._batch_num = 0
+
+        def gen(limit: Optional[int]):
+
+            while True:
+
+                if limit is not None:
+                    if limit == 0:
+                        break
+
+                    limit -= 1
+
+                try:
+
+                    event = env.timeout(delay=interval)
+                    yield event
+
+                    value: list[Task] = self._get_tasks(env)
+
+                    for v in value:
+                        yield target.put(v)
+
+                except Interrupt:
+                    break
+
+        self.proc = env.process(gen(self.limit))
+
+    def stop(self) -> None:
+        """Stop the running operation."""
+
+        if self.proc is not None:
+            self.proc.interrupt()

value_stream/policy/__init__.py

@@ -0,0 +1,3 @@
+from .simulation_policy import SimulationPolicy
+
+__all__ = ["SimulationPolicy"]

value_stream/policy/simulation_policy.py

@@ -0,0 +1,20 @@
+from abc import abstractmethod
+from typing import Literal
+
+from value_stream.resources import ResourcePolicy
+from value_stream.task import Task
+from value_stream.workflow import WorkflowPolicy, AssignmentStrategy
+
+
+class SimulationPolicy(ResourcePolicy, WorkflowPolicy):
+    """encapsulates control logic for a simulation"""
+
+    @abstractmethod
+    def task_priority(
+        self, tasks_1: list[Task], tasks_2: list[Task]
+    ) -> Literal[0] | Literal[1] | Literal[-1]:
+        pass
+
+    @abstractmethod
+    def support_assignment_strategy(self, tasks: list[Task]) -> AssignmentStrategy:
+        pass

value_stream/resources/__init__.py

@@ -0,0 +1,23 @@
+from .resource import Resource
+from .resource_metadata import ResourceMetadata
+from .resource_tracker import InMemoryResourceTracker, NoOpResourceTracker, ResourceTracker
+from .resource_policy import ResourcePolicy
+from .resource_pool import ResourcePool
+from .resource_pool import PooledResource
+from .developer import Developer
+from .qa_tester import QATester
+from .toolchain import Toolchain
+
+__all__ = [
+    "Resource",
+    "InMemoryResourceTracker",
+    "Developer",
+    "NoOpResourceTracker",
+    "QATester",
+    "PooledResource",
+    "ResourcePolicy",
+    "ResourcePool",
+    "ResourceTracker",
+    "Toolchain",
+    "ResourceMetadata",
+]

value_stream/resources/developer.py

@@ -0,0 +1,53 @@
+from typing import Any, Generator
+
+from pydantic import Field, FiniteFloat
+from simpy import Environment, Interrupt, Timeout
+
+from value_stream.task import EventStatus, Task
+
+from .resource import Resource
+
+
+class Developer(Resource):
+    """Simulates actions perform on a task by a software developer"""
+
+    efficiency: FiniteFloat = Field(default=1.0, gt=0)
+    name: str = ""
+
+    def effort(self, tasks: list[Task]) -> float:
+        """Return the developer effort for the supplied tasks.
+
+        Args:
+            tasks (list[Task]): Tasks to process.
+
+        Returns:
+            float: The developer effort assigned to the supplied tasks.
+        """
+        return sum([task.remaining_work() / self.efficiency for task in tasks])
+
+    def do_work(self, env: Environment, tasks: list[Task]) -> Generator[Timeout, Any, None]:
+        """Apply developer effort to tasks and yield until the work completes.
+
+        Args:
+            env (Environment): Simulation environment.
+            tasks (list[Task]): Tasks to process.
+
+        Yields:
+            Timeout: Event that completes developer work.
+        """
+        start = env.now
+
+        try:
+            yield env.timeout(self.effort(tasks), value={"result": EventStatus.SUCCESS})
+
+        except Interrupt:
+            applied_story_points = (env.now - start) * self.efficiency
+            for task in tasks:
+                applied_story_points = task.do_work(applied_story_points)
+
+            raise
+
+        applied_story_points = (env.now - start) * self.efficiency
+
+        for task in tasks:
+            applied_story_points = task.do_work(applied_story_points)

value_stream/resources/qa_tester.py

@@ -0,0 +1,51 @@
+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 import Resource
+from .resource_pool import PooledResource
+
+
+class QATester(Resource, PooledResource):
+    """Tests completed development tasks and reports pass or failure."""
+
+    time_cost: FiniteFloat = Field(default=0.1)
+    failure_rate: FiniteFloat = Field(default=0.0, ge=0, le=1)
+    failure_cost: FiniteFloat = Field(default=0.0, ge=0, le=1)
+
+    def do_work(
+        self, env: Environment, tasks: list[Task]
+    ) -> Generator[Timeout, Any, dict[str, EventStatus]]:
+        """Test tasks and yield until the QA work completes.
+
+        Args:
+            env (Environment): Simulation environment.
+            tasks (list[Task]): Tasks to process.
+
+        Yields:
+            Timeout: Event that completes QA work.
+
+        Returns:
+            dict[str, EventStatus]: Work result and completion status.
+        """
+        effort = sum(task.story_points * self.time_cost for task in tasks)
+
+        if random.random() < self.failure_rate:
+            result = EventStatus.FAILURE
+        else:
+            result = EventStatus.SUCCESS
+
+        work = env.timeout(effort, value={"result": result})
+
+        yield work
+
+        # Cost of remediation is a perceentage of original effort
+        if result == EventStatus.FAILURE:
+            for task in tasks:
+                remediation_work = task.story_points * self.failure_cost
+                task.do_work(-remediation_work)
+
+        return work.value

value_stream/resources/resource.py

@@ -0,0 +1,162 @@
+# Parent class for Developer and Toolchain
+from abc import ABC, abstractmethod
+from typing import Any, Generator, Optional, ClassVar
+import uuid
+
+from pydantic import BaseModel, PrivateAttr
+from simpy import Environment, Event, Interrupt, Process, Timeout
+from simpy.events import ProcessGenerator
+
+from value_stream.task import TaskState
+from value_stream.task import EventStatus, Task, TaskRouter
+
+from .resource_policy import ResourcePolicy
+from .resource_tracker import ResourceTracker
+
+
+class Resource(ABC, BaseModel):
+    """Base class for simulation objects that operate on tasks"""
+
+    class ProcessWrapper(Process):
+        """SimPy process that retains the tasks being processed."""
+
+        def __init__(self, env: Environment, tasks: list[Task], generator: ProcessGenerator):
+            super().__init__(env, generator)
+            self.tasks = tasks
+
+    MAX_BACKLOG: ClassVar[int] = 1000
+
+    _idle_t: float = 0
+    _id: uuid.UUID = PrivateAttr(default_factory=uuid.uuid4)
+    _process: Optional[ProcessWrapper] = None
+    _suspended_work: list[Event] = []
+
+    def __hash__(self) -> int:
+        return self._id.__hash__()
+
+    @property
+    def resource_id(self) -> uuid.UUID:
+        return self._id
+
+    @property
+    def idle_t(self):
+        return self._idle_t
+
+    @idle_t.setter
+    def idle_t(self, idle_t: float):
+        self._idle_t = idle_t
+
+    def operate(
+        self,
+        env: Environment,
+        tasks: list[Task],
+        task_router: TaskRouter,
+        policy: ResourcePolicy,
+        workflow_state: TaskState,
+        tracker: ResourceTracker,
+    ) -> Generator[Event, Any, None]:
+        """Simulates an action on a task object.
+
+        Args:
+            env (Environment): Simulation environment.
+            tasks (list[Task]): Tasks to process.
+            task_router (TaskRouter): Router for completed tasks.
+            policy (ResourcePolicy): Policy used to make simulation decisions.
+            workflow_state (TaskState): Workflow state associated with the operation.
+            tracker (ResourceTracker): Tracker for resource activity.
+
+        Yields:
+            Event: SimPy events yielded while processing tasks.
+        """
+
+        for task in tasks:
+            task.start(env.now, workflow_state, resource_id=self._id)
+
+        if (self._process is not None) and (not self._process.processed):
+            if policy.task_priority(tasks, self._process.tasks) == -1:
+                self._process.interrupt()
+            else:
+                # if what's in progress is of higher priority, queue up current work
+                # yield self._process ....
+                yield env.process(self._pause(env))
+
+        while True:
+            status = EventStatus.SUCCESS
+            self._process = self._create_process(env, tasks)
+
+            start_t = env.now
+            try:
+
+                tracker.start_work(workflow_state, env.now - self._idle_t)
+                yield self._process
+
+                if self._process.value is not None:
+                    status = self._process.value["result"]
+
+            except Interrupt:
+
+                # if do_work is interrupted, wait on a signal that will
+                # be triggered once this resource has processed all
+                # subsequent interruptions
+
+                interruption_start_t = env.now
+
+                tracker.complete_work(workflow_state, status, elapsed_t=env.now - start_t)
+
+                yield env.process(self._pause(env))
+
+                tracker.interruption(workflow_state, elapsed_t=env.now - interruption_start_t)
+
+                continue
+
+            tracker.complete_work(workflow_state, status, elapsed_t=env.now - start_t)
+            self._idle_t = env.now
+
+            for task in tasks:
+                task.end(env.now, workflow_state, status=status, resource_id=self._id)
+
+                if status == EventStatus.FAILURE:
+                    yield task_router.route(task=task.as_rework(), status=status)
+                else:
+                    yield task_router.route(task=task.clear_rework(), status=status)
+
+            # once work is complete, check for previously interrupted work
+            # and trigger resumption
+            if self._suspended_work:
+                signal = self._suspended_work[-1]
+                signal.succeed()
+
+            break
+
+    @abstractmethod
+    def do_work(self, env: Environment, tasks: list[Task]) -> Generator[Timeout, Any, None]:
+        pass
+
+    def _pause(self, env: Environment) -> Generator[Event, Any, None]:
+        """Wait until interrupted work can resume.
+
+        Args:
+            env (Environment): Simulation environment.
+
+        Raises:
+            RuntimeError: If the number of suspended work signals exceeds the backlog limit.
+
+        Yields:
+            Event: SimPy events yielded while waiting for work to resume.
+        """
+        while True:
+            signal = env.event()
+            self._suspended_work.append(signal)
+
+            if len(self._suspended_work) > self.MAX_BACKLOG:
+                raise RuntimeError("Runaway simulation detected and aborted")
+
+            yield signal
+
+            self._suspended_work.pop()
+
+            if (self._process is not None) and (self._process.target is None):
+                break
+
+    def _create_process(self, env: Environment, tasks: list[Task]):
+        return Resource.ProcessWrapper(env, tasks, self.do_work(env, tasks))

value_stream/resources/resource_metadata.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, ConfigDict, field_serializer
+from typing import Optional
+from value_stream.task import TaskState
+
+
+class ResourceMetadata(BaseModel):
+    """Stores metadata collected for one simulation resource."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    time: float
+    state: TaskState
+    waiting: int = 0
+    allocated: int = 0
+    active: int = 0
+    success_t: Optional[float] = None
+    failure_t: Optional[float] = None
+    interruption_t: Optional[float] = None
+    waiting_t: Optional[float] = None
+    idle_t: Optional[float] = None
+
+    @field_serializer("state")
+    def serialize_event(self, state: TaskState):
+        return state.value

value_stream/resources/resource_policy.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Literal
+from value_stream.task import Task
+
+
+class ResourcePolicy(ABC):
+    """Defines resource-level decisions during task processing."""
+
+    @abstractmethod
+    def task_priority(
+        self, tasks_1: list[Task], tasks_2: list[Task]
+    ) -> Literal[0] | Literal[1] | Literal[-1]:
+        pass

value_stream/resources/resource_pool.py

@@ -0,0 +1,39 @@
+from typing import Type, Optional, Self
+import uuid
+from pydantic import BaseModel, Field, PrivateAttr, ConfigDict
+
+
+class ResourcePool(BaseModel):
+    """Generates a fixed or unlimited quantity of a homogeneous resource"""
+
+    model_config = ConfigDict(extra="allow")
+    class_name: Type = Field()
+    limit: Optional[int] = Field(default=None, gt=0)
+    _i: int = PrivateAttr(default=0, init=False)
+
+    _pool_id: uuid.UUID = PrivateAttr(default_factory=uuid.uuid4)
+
+    def __next__(self):
+
+        if self.limit is None:
+            kwargs = {} if not self.model_extra else self.model_extra
+            return self.class_name(**kwargs)
+
+        if self._i < self.limit:
+            self._i += 1
+            kwargs = {} if not self.model_extra else self.model_extra
+            return self.class_name(**kwargs)
+
+        raise StopIteration
+
+    def __iter__(self) -> Self:  # pyright: ignore[reportIncompatibleMethodOverride]
+        self._i = 0
+        return self
+
+
+class PooledResource:
+    """Tracks whether a resource is available to the pool."""
+
+    @classmethod
+    def create_pool(cls, limit: Optional[int] = None, **kwargs):
+        return ResourcePool(class_name=cls, limit=limit, **kwargs)