Introduction of the input structure for endpoints

Author: GioeleB00

documentation/backend_documentation/requests_generator.md

@@ -40,7 +40,7 @@ class RVConfig(BaseModel):
     distribution: Literal["poisson", "normal", "gaussian"] = "poisson"
     variance: float | None = None  # required only for normal/gaussian
 
-class SimulationInput(BaseModel):
+class RqsGeneratorInput(BaseModel):
     """Define simulation inputs."""
     avg_active_users: RVConfig
     avg_request_per_minute_per_user: RVConfig

src/app/api/simulation.py

@@ -4,13 +4,13 @@
 from fastapi import APIRouter
 
 from app.core.simulation.simulation_run import run_simulation
-from app.schemas.simulation_input import SimulationInput
+from app.schemas.requests_generator_input import RqsGeneratorInput
 from app.schemas.simulation_output import SimulationOutput
 
 router = APIRouter()
 
 @router.post("/simulation")
-async def event_loop_simulation(input_data: SimulationInput) -> SimulationOutput:
+async def event_loop_simulation(input_data: RqsGeneratorInput) -> SimulationOutput:
     """Run the simulation and return aggregate KPIs."""
     rng = np.random.default_rng()
     return run_simulation(input_data, rng=rng)

src/app/config/constants.py

@@ -2,6 +2,9 @@
 
 from enum import IntEnum, StrEnum
 
+# --------------------------------------------------------
+# CONSTANTS FOR THE REQUESTS GENERATOR
+# --------------------------------------------------------
 
 class TimeDefaults(IntEnum):
     """Default time-related constants (all in seconds)."""
@@ -20,4 +23,45 @@ class Distribution(StrEnum):
     POISSON = "poisson"
     NORMAL = "normal"
 
+# --------------------------------------------------------
+# CONSTANTS FOR THE REQUESTS ENDPOINT STRUCTURE IN THE
+# REQUESTS HANDLER
+# --------------------------------------------------------
+
+# Idea here is to create an ordered nested dict with
+# this structure: {endpoint_name: {
+    #                        operation_type:
+    #                           latency (s)/ram (kb): value}}
+# we need Enum to have a better control on the dict keys in the
+# pydantic schema
+
+class EndpointIO(StrEnum):
+    """Name of I/O operations"""
+
+    IO_WITH_CHILD = "io_new_coroutine" #Child task exit
+    IO_LLM_BOUND = "io_llm" # Llm speicif task
+    IO_SLEEP = "i/o_bound"  # No child task
+
+
+class EndpointCPU(StrEnum):
+    """Name of CPU bound operations"""
+
+    INITIAL_PARSING = "initial_parsing"
+    CPU_BOUND_OPERATION = "cpu_bound_operation"
+
+
+class EndpointRAM(StrEnum):
+    """Name of the operation to add ram"""
+
+    RAM = "ram"
+
+
+class MetricKeys(StrEnum):
+    """
+    Name of the key to quantify the operation
+    in terms of Ram or latency
+    """
+
+    LATENCY = "latency"
+    NECESSARY_RAM = "necessary_ram"
 

src/app/core/event_samplers/gaussian_poisson.py

@@ -16,11 +16,11 @@
     truncated_gaussian_generator,
     uniform_variable_generator,
 )
-from app.schemas.requests_generator_input import SimulationInput
+from app.schemas.requests_generator_input import RqsGeneratorInput
 
 
 def gaussian_poisson_sampling(
-    input_data: SimulationInput,
+    input_data: RqsGeneratorInput,
     *,
     rng: np.random.Generator | None = None,
 ) -> Generator[float, None, None]:

src/app/core/event_samplers/poisson_poisson.py

@@ -13,11 +13,11 @@
     poisson_variable_generator,
     uniform_variable_generator,
 )
-from app.schemas.requests_generator_input import SimulationInput
+from app.schemas.requests_generator_input import RqsGeneratorInput
 
 
 def poisson_poisson_sampling(
-    input_data: SimulationInput,
+    input_data: RqsGeneratorInput,
     *,
     rng: np.random.Generator | None = None,
 ) ->  Generator[float, None, None]:

src/app/core/simulation/requests_generator.py

@@ -16,11 +16,11 @@
 
     import numpy as np
 
-    from app.schemas.requests_generator_input import SimulationInput
+    from app.schemas.requests_generator_input import RqsGeneratorInput
 
 
 def requests_generator(
-    input_data: SimulationInput,
+    input_data: RqsGeneratorInput,
     *,
     rng: np.random.Generator | None = None,
 ) -> Generator[float, None, None]:

src/app/core/simulation/simulation_run.py

@@ -14,13 +14,13 @@
 
     import numpy as np
 
-    from app.schemas.simulation_input import SimulationInput
+    from app.schemas.requests_generator_input import RqsGeneratorInput
 
 
 
 
 def run_simulation(
-    input_data: SimulationInput,
+    input_data: RqsGeneratorInput,
     *,
     rng: np.random.Generator,
 ) -> SimulationOutput:

src/app/schemas/full_simulation_input.py

@@ -0,0 +1,13 @@
+"""Definition of the full input for the simulation"""
+
+from pydantic import BaseModel
+
+from app.schemas.requests_generator_input import RqsGeneratorInput
+from app.schemas.requests_handler_input import Endpoint
+
+
+class SimulationPayload(BaseModel):
+    """Full input structure to perform a simulation"""
+
+    rqs_input: RqsGeneratorInput
+    all_endpoints: list[Endpoint]

src/app/schemas/requests_generator_input.py

@@ -31,7 +31,7 @@ def default_variance(cls, model: "RVConfig") -> "RVConfig":  # noqa: N805
             model.variance = model.mean
         return model
 
-class SimulationInput(BaseModel):
+class RqsGeneratorInput(BaseModel):
     """Define the expected variables for the simulation"""
 
     avg_active_users: RVConfig

src/app/schemas/requests_handler_input.py

@@ -0,0 +1,37 @@
+"""Defining the input schema for the requests handler"""
+
+from pydantic import BaseModel, field_validator
+
+from app.config.constants import EndpointCPU, EndpointIO, EndpointRAM, MetricKeys
+
+
+class Step(BaseModel):
+    """Full step structure to be validated with pydantic"""
+
+    kind: EndpointIO | EndpointCPU | EndpointRAM
+    metrics: dict[MetricKeys, float | int]
+
+    @field_validator("metrics", mode="before")
+    def ensure_metric_exist_positive(
+        cls, # noqa: N805
+        v:  dict[MetricKeys, float | int],
+        ) -> dict[MetricKeys, float | int]:
+        """Ensure the measure of an operation exist and is positive"""
+        for key, value in v.items():
+            if not value or value <= 0:
+                msg = f"{key} must be a positive number"
+                raise ValueError(msg)
+        return v
+
+
+class Endpoint(BaseModel):
+    """full endpoint structure to be validated with pydantic"""
+
+    endpoint_name: str
+    steps: list[Step]
+
+    @field_validator("endpoint_name", mode="before")
+    def name_to_lower(cls, v: str) -> str: # noqa: N805
+        """Standardize endpoint name to be lowercase"""
+        return v.lower()
+