desdeo 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

desdeo/api/models/generic.py

@@ -0,0 +1,104 @@
+"""Generic models for the DESDEO API."""
+
+from pydantic import ConfigDict
+from sqlmodel import JSON, Column, Field, SQLModel
+
+from desdeo.tools.score_bands import SCOREBandsConfig, SCOREBandsResult
+
+from .generic_states import SolutionReferenceResponse
+
+
+class SolutionInfo(SQLModel):
+    """Used when we wish to reference a solution in some `StateDB` stored in the database."""
+
+    state_id: int = Field(description="State of the desired solution.")
+    solution_index: int = Field(description="Index of the desired solution.")
+    name: str | None = Field(description="Name to be given to the solution. Optional.", default=None)
+
+
+class IntermediateSolutionRequest(SQLModel):
+    """Model of the request to solve intermediate solutions between two solutions."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    context: str | None = None  # Method context (nimbus, rpm, etc.)
+    scalarization_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+    solver: str | None = Field(default=None)
+    solver_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+
+    num_desired: int | None = Field(default=1)
+
+    reference_solution_1: SolutionInfo
+    reference_solution_2: SolutionInfo
+
+
+class GenericIntermediateSolutionResponse(SQLModel):
+    """The response from computing intermediate values."""
+
+    state_id: int | None = Field(description="The newly created state id")
+    reference_solution_1: SolutionReferenceResponse = Field(
+        sa_column=Column(JSON),
+        description="The first solution used when computing intermediate solutions.",
+    )
+    reference_solution_2: SolutionReferenceResponse = Field(
+        sa_column=Column(JSON),
+        description="The second solution used when computing intermediate solutions.",
+    )
+    intermediate_solutions: list[SolutionReferenceResponse] = Field(
+        sa_column=Column(JSON), description="The intermediate solutions computed."
+    )
+
+
+class ScoreBandsRequest(SQLModel):
+    """Model of the request to calculate SCORE bands parameters."""
+
+    data: list[list[float]] = Field(description="Matrix of objective values")
+    objs: list[str] = Field(description="Array of objective names for each column")
+
+    # Optional parameters with defaults matching the score_bands.py functions
+    dist_parameter: float = Field(default=0.05, description="Distance parameter for axis positioning")
+    use_absolute_corr: bool = Field(default=False, description="Use absolute correlation values")
+    distance_formula: int = Field(default=1, description="Distance formula (1 or 2)")
+    flip_axes: bool = Field(default=True, description="Whether to flip axes based on correlation signs")
+    clustering_algorithm: str = Field(default="DBSCAN", description="Clustering algorithm (DBSCAN or GMM)")
+    clustering_score: str = Field(default="silhoutte", description="Clustering score metric")
+
+
+class ScoreBandsResponse(SQLModel):
+    """Model of the response containing SCORE bands parameters."""
+
+    groups: list[int] = Field(description="Cluster group assignments for each data point")
+    axis_dist: list[float] = Field(description="Normalized axis positions")
+    axis_signs: list[int] | None = Field(description="Axis direction signs (1 or -1)")
+    obj_order: list[int] = Field(description="Optimal order of objectives")
+
+
+class GroupScoreRequest(SQLModel):
+    """A generic model for requesting SCORE Bands for a state."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    problem_id: int
+    group_id: int
+    """Database ID of the problem to solve."""
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    """State ID of the parent state, if any."""
+
+    config: SCOREBandsConfig | None = Field(default=None)
+    """Configuration for the SCORE bands visualization."""
+
+    solution_ids: list[int] = Field()
+    """List of solution IDs to score."""
+
+
+class GroupScoreResponse(SQLModel):
+    """Model of the response to an EMO score request."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    group_iteration_id: int | None = Field(default=None)
+    """The state ID of the newly created group iteration."""
+
+    result: SCOREBandsResult

desdeo/api/models/generic_states.py

@@ -0,0 +1,401 @@
+"""Defines models for representing the state of various interactive methods."""
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import ConfigDict, computed_field
+from sqlalchemy.orm import object_session
+from sqlmodel import (
+    JSON,
+    Column,
+    Field,
+    Relationship,
+    Session,
+    SQLModel,
+    select,
+)
+
+from desdeo.problem import Tensor, VariableType
+
+from .state import (
+    EMOFetchState,
+    EMOIterateState,
+    EMOSaveState,
+    EMOSCOREState,
+    ENautilusState,
+    GNIMBUSEndState,
+    GNIMBUSOptimizationState,
+    GNIMBUSVotingState,
+    IntermediateSolutionState,
+    NIMBUSClassificationState,
+    NIMBUSFinalState,
+    NIMBUSInitializationState,
+    NIMBUSSaveState,
+    RPMState,
+)
+from .user import User
+
+if TYPE_CHECKING:
+    from .problem import ProblemDB
+    from .session import InteractiveSessionDB
+
+
+class StateKind(str, Enum):
+    """Stores the normalized kinds `{method}.{phase}` of supported states.
+
+    Note:
+        Update this when adding new states. Be sure to update `KIND_TO_STATE`
+        in this file as well.
+    """
+
+    RPM_SOLVE = "reference_point_method.solve_candidates"
+    NIMBUS_SOLVE = "nimbus.solve_candidates"
+    NIMBUS_SAVE = "nimbus.save_solutions"
+    NIMBUS_INIT = "nimbus.initialize"
+    NIMBUS_FINAL = "nimbus.final"
+    GNIMBUS_OPTIMIZE = "gnimbus.optimize"
+    GNIMBUS_VOTE = "gnimbus.vote"
+    GNIMBUS_END = "gnimbus.end"
+    EMO_RUN = "emo.run"
+    EMO_SAVE = "emo.save_solutions"
+    EMO_FETCH = "emo.fetch_solutions"
+    EMO_SCORE = "emo.score_bands"
+    GENERIC_INTERMEDIATE = "generic.solve_intermediate"
+    ENAUTILUS_STEP = "e-nautilus.stepping"
+
+
+class State(SQLModel, table=True):
+    """The 'polymorphic' state to store method information."""
+
+    __tablename__ = "states"
+
+    id: int | None = Field(default=None, primary_key=True)
+
+    # The state is polymorphic on these.
+    # TODO (@gialmisi): once SQLModel supports polymorphic table types, refactor this.
+    method: str = Field(index=True)  # the method name
+    phase: str = Field(index=True)  # the phase of the method
+    kind: StateKind = Field(index=True)  # normalized "{method}.{phase}", lowercase
+
+
+class StateDB(SQLModel, table=True):
+    """State holder with a single relationship to the base State."""
+
+    __tablename__ = "statedb"
+
+    id: int | None = Field(primary_key=True, default=None)
+
+    # Optional cross-links (keep as strings in other modules to avoid circulars)
+    problem_id: int | None = Field(foreign_key="problemdb.id", default=None)
+    session_id: int | None = Field(foreign_key="interactivesessiondb.id", default=None)
+
+    # lineage
+    parent_id: int | None = Field(foreign_key="statedb.id", default=None)
+
+    # one-to-one to base state
+    state_id: int | None = Field(foreign_key="states.id", default=None, index=True)
+    base_state: State | None = Relationship(
+        sa_relationship_kwargs={
+            "uselist": False,
+            "single_parent": True,
+            "cascade": "all, delete-orphan",
+            "foreign_keys": lambda: [StateDB.state_id],
+        }
+    )
+
+    parent: "StateDB" = Relationship(
+        back_populates="children",
+        sa_relationship_kwargs={"remote_side": lambda: StateDB.id},
+    )
+    children: list["StateDB"] = Relationship(
+        back_populates="parent",
+        sa_relationship_kwargs={"cascade": "all, delete-orphan"},
+    )
+
+    session: "InteractiveSessionDB" = Relationship(back_populates="states")
+    problem: "ProblemDB" = Relationship()
+
+    @classmethod
+    def create(
+        cls,
+        database_session: Session,
+        *,
+        problem_id: int | None = None,
+        session_id: int | None = None,
+        parent_id: int | None = None,
+        state: SQLModel | None = None,
+    ) -> "StateDB":
+        """Build a StateDB + base State with a concrete substate."""
+        sub_cls = type(state)
+        kind: StateKind | None = None
+
+        for cls_in_mro in sub_cls.mro():
+            if cls_in_mro in SUBSTATE_TO_KIND:
+                kind = SUBSTATE_TO_KIND[cls_in_mro]
+                break
+
+        if kind is None:
+            raise ValueError(f"No StateKind mapping for substate type {sub_cls!r}")
+
+        method, phase = _method_phase_from_kind(kind)
+        base = State(method=method, phase=phase, kind=kind)
+
+        row = cls(
+            problem_id=problem_id,
+            session_id=session_id,
+            parent_id=parent_id,
+            base_state=base,
+        )
+        database_session.add(row)
+
+        # Persist base and link substate PK=FK
+        _attach_substate(database_session, base, state)
+
+        return row
+
+    @property
+    def state(self) -> SQLModel | None:
+        """Return the concrete substate instance (e.g., NIMBUSSaveState)...
+
+        Return the concrete substate instance (e.g., NIMBUSSaveState)
+        resolved from the stored `base_state`.
+        """
+        if self.base_state is None:
+            return None
+        table: SQLModel | None = KIND_TO_TABLE.get(self.base_state.kind)
+
+        if table is None:
+            return None
+
+        db_session = object_session(self)
+
+        if db_session is None:
+            # No bound state
+            raise RuntimeError("StateDB.state accessed without a bound Session")
+
+        return db_session.exec(select(table).where(table.id == self.base_state.id)).first()
+
+
+KIND_TO_TABLE: dict[StateKind, SQLModel] = {
+    StateKind.RPM_SOLVE: RPMState,
+    StateKind.NIMBUS_SOLVE: NIMBUSClassificationState,
+    StateKind.NIMBUS_SAVE: NIMBUSSaveState,
+    StateKind.NIMBUS_INIT: NIMBUSInitializationState,
+    StateKind.NIMBUS_FINAL: NIMBUSFinalState,
+    StateKind.EMO_RUN: EMOIterateState,
+    StateKind.GNIMBUS_OPTIMIZE: GNIMBUSOptimizationState,
+    StateKind.GNIMBUS_VOTE: GNIMBUSVotingState,
+    StateKind.GNIMBUS_END: GNIMBUSEndState,
+    StateKind.EMO_SAVE: EMOSaveState,
+    StateKind.EMO_FETCH: EMOFetchState,
+    StateKind.EMO_SCORE: EMOSCOREState,
+    StateKind.GENERIC_INTERMEDIATE: IntermediateSolutionState,
+    StateKind.ENAUTILUS_STEP: ENautilusState,
+}
+
+SUBSTATE_TO_KIND: dict[SQLModel, StateKind] = {
+    RPMState: StateKind.RPM_SOLVE,
+    NIMBUSClassificationState: StateKind.NIMBUS_SOLVE,
+    NIMBUSSaveState: StateKind.NIMBUS_SAVE,
+    NIMBUSInitializationState: StateKind.NIMBUS_INIT,
+    NIMBUSFinalState: StateKind.NIMBUS_FINAL,
+    EMOIterateState: StateKind.EMO_RUN,
+    GNIMBUSOptimizationState: StateKind.GNIMBUS_OPTIMIZE,
+    GNIMBUSVotingState: StateKind.GNIMBUS_VOTE,
+    GNIMBUSEndState: StateKind.GNIMBUS_END,
+    EMOSaveState: StateKind.EMO_SAVE,
+    EMOFetchState: StateKind.EMO_FETCH,
+    EMOSCOREState: StateKind.EMO_SCORE,
+    IntermediateSolutionState: StateKind.GENERIC_INTERMEDIATE,
+    ENautilusState: StateKind.ENAUTILUS_STEP,
+}
+
+
+def _method_phase_from_kind(kind: StateKind) -> tuple[str, str]:
+    """Split enum value back to (method, phase)."""
+    method, phase = kind.value.split(".", 1)
+    return method, phase
+
+
+def _attach_substate(session, base: State, sub: SQLModel | None) -> None:
+    """Persist base; link sub.id = base.id; persist sub."""
+    session.add(base)
+    session.flush()  # assigns base.id
+
+    if sub is not None:
+        sub.id = base.id
+        session.add(sub)
+        session.flush()
+
+
+class UserSavedSolutionDB(SQLModel, table=True):
+    """Database model of an archived solution."""
+
+    id: int | None = Field(primary_key=True, default=None)
+
+    name: str | None = Field(default=None, nullable=True)
+    objective_values: dict[str, float] = Field(sa_column=Column(JSON))
+    variable_values: dict[str, VariableType] = Field(sa_column=Column(JSON))
+    solution_index: int | None
+
+    # Links
+    user_id: int | None = Field(foreign_key="user.id", default=None)
+    problem_id: int | None = Field(foreign_key="problemdb.id", default=None)
+    origin_state_id: int | None = Field(
+        foreign_key="states.id", default=None
+    )  # the StateDB where this solution was generated
+    save_state_id: int | None = Field(
+        foreign_key="states.id", default=None
+    )  # the StateDB that explicitly created the save
+
+    # Back populates
+    user: "User" = Relationship(back_populates="archive")
+    problem: "ProblemDB" = Relationship(back_populates="solutions")
+
+    @classmethod
+    def from_state_info(
+        cls,
+        database_session: Session,
+        user_id: int,
+        problem_id: int,
+        state_id: int,
+        solution_index: int,
+        name: str | None,
+    ) -> "UserSavedSolutionDB | None":
+        state = database_session.exec(
+            select(StateDB).where(
+                StateDB.id == state_id,
+                StateDB.problem_id == problem_id,
+            )
+        ).first()
+
+        if state is None:
+            return None
+
+        objective_values = state.state.result_objective_values[solution_index]
+        variable_values = state.state.result_variable_values[solution_index]
+
+        return cls(
+            name=name,
+            objective_values=objective_values,
+            variable_values=variable_values,
+            solution_index=solution_index,
+            user_id=user_id,
+            problem_id=problem_id,
+            origin_state_id=state_id,
+        )
+
+
+class SolutionReferenceBase(SQLModel):
+    """A model that functions as a reference to solutions existing in the database.
+
+    Referenced solutions are not necessarily solutions that the user has saved explicitly. For
+    referencing those, see `SavedSolutionReference`.
+    """
+
+    name: str | None = Field(description="Optional name to help identify the solution if, e.g., saved.", default=None)
+    solution_index: int | None = Field(
+        description="The index of the referenced solution, if multiple solutions exist in the reference state.",
+        default=None,
+    )
+    state: StateDB = Field(description="The reference state with the solution information.")
+
+    @computed_field
+    @property
+    def state_id(self) -> int:
+        return self.state.id
+
+    @computed_field
+    @property
+    def num_solutions(self) -> int:
+        return len(self.state.state.solver_results)
+
+
+class SolutionReference(SolutionReferenceBase):
+    """A full solution reference with objectives and variables."""
+
+    @computed_field
+    @property
+    def objective_values_all(self) -> list[dict[str, float]]:
+        return self.state.state.result_objective_values
+
+    @computed_field
+    @property
+    def variable_values_all(self) -> list[dict[str, VariableType | Tensor]]:
+        return self.state.state.result_variable_values
+
+    @computed_field
+    @property
+    def objective_values(self) -> dict[str, float] | None:
+        if self.solution_index is not None:
+            return self.state.state.result_objective_values[self.solution_index]
+
+        return None
+
+    @computed_field
+    @property
+    def variable_values(self) -> dict[str, VariableType | Tensor] | None:
+        if self.solution_index is not None:
+            return self.state.state.result_variable_values[self.solution_index]
+
+        return None
+
+
+class SolutionReferenceLite(SolutionReferenceBase):
+    """The same as SolutionReference, but without decision variables for more efficient transport over the internet."""
+
+    @computed_field
+    @property
+    def objective_values(self) -> dict[str, float] | None:
+        if self.solution_index is not None:
+            return self.state.state.result_objective_values[self.solution_index]
+
+        return None
+
+
+class SolutionReferenceResponse(SQLModel):
+    """The response information provided when `SolutionReference` object are returned from the client."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    name: str | None = Field(default=None)
+    solution_index: int | None
+    state_id: int
+    objective_values: dict[str, float] | None
+    variable_values: dict[str, "VariableType | Tensor"] | None
+
+
+class SavedSolutionReference(SQLModel):
+    """A model that functions as a reference to solutions that users have chosen to explicitly save in the database."""
+
+    saved_solution: UserSavedSolutionDB = Field(description="The reference object with the solution information.")
+
+    @computed_field
+    @property
+    def name(self) -> str | None:
+        return self.saved_solution.name
+
+    @computed_field
+    @property
+    def objective_values(self) -> dict[str, float]:
+        return self.saved_solution.objective_values
+
+    @computed_field
+    @property
+    def variable_values(self) -> dict[str, VariableType | Tensor]:
+        return self.saved_solution.variable_values
+
+    @computed_field
+    @property
+    def solution_index(self) -> int | None:
+        return self.saved_solution.solution_index
+
+    @computed_field
+    @property
+    def saved_solution_id(self) -> int:
+        return self.saved_solution.id
+
+    @computed_field
+    @property
+    def state_id(self) -> int | None:
+        return self.saved_solution.origin_state_id

desdeo/api/models/nimbus.py

@@ -0,0 +1,158 @@
+"""Models specific to the nimbus method."""
+
+from typing import Literal
+
+from sqlmodel import JSON, Column, Field, SQLModel
+
+from .generic import SolutionInfo
+from .generic_states import SolutionReferenceResponse
+from .preference import ReferencePoint
+
+
+class NIMBUSClassificationRequest(SQLModel):
+    """Model of the request to the nimbus method."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+
+    scalarization_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+    solver: str | None = Field(default=None)
+    solver_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+    preference: ReferencePoint = Field(Column(JSON))
+
+    current_objectives: dict[str, float] = Field(
+        sa_column=Column(JSON), description="The objectives used for iteration."
+    )
+    num_desired: int | None = Field(default=1)
+
+
+class NIMBUSSaveRequest(SQLModel):
+    """Request model for saving solutions from any method's state."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+
+    solution_info: list[SolutionInfo]
+
+class NIMBUSDeleteSaveRequest(SQLModel):
+    """Request model for deletion of a saved solution."""
+
+    state_id : int = Field(description="The ID of the save state.")
+    solution_index: int = Field(description="The ID of the solution within the above state.")
+
+
+class NIMBUSFinalizeRequest(SQLModel):
+    """Request model for finalizing the NIMBUS procedure."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+
+    solution_info: SolutionInfo # the final solution
+
+
+class NIMBUSClassificationResponse(SQLModel):
+    """The response from NIMBUS classification endpoint."""
+
+    response_type: Literal["nimbus.classification"] = "nimbus.classification"
+
+    state_id: int | None = Field(description="The newly created state id")
+    previous_preference: ReferencePoint = Field(description="The previous preference used.")
+    previous_objectives: dict[str, float] = Field(
+        sa_column=Column(JSON), description="The previous solutions objectives used for iteration."
+    )
+    current_solutions: list[SolutionReferenceResponse] = Field(
+        description="The solutions from the current iteration of nimbus."
+    )
+    saved_solutions: list[SolutionReferenceResponse] = Field(
+        description="The best candidate solutions saved by the decision maker."
+    )
+    all_solutions: list[SolutionReferenceResponse] = Field(
+        description="All solutions generated by NIMBUS in all iterations."
+    )
+
+
+class NIMBUSInitializationResponse(SQLModel):
+    """The response from NIMBUS classification endpoint."""
+
+    response_type: Literal["nimbus.initialization"] = "nimbus.initialization"
+
+    state_id: int | None = Field(description="The newly created state id")
+    current_solutions: list[SolutionReferenceResponse] = Field(
+        description="The solutions from the current interation of nimbus."
+    )
+    saved_solutions: list[SolutionReferenceResponse] = Field(
+        description="The best candidate solutions saved by the decision maker."
+    )
+    all_solutions: list[SolutionReferenceResponse] = Field(
+        description="All solutions generated by NIMBUS in all iterations."
+    )
+
+
+class NIMBUSSaveResponse(SQLModel):
+    """The response from NIMBUS save endpoint."""
+
+    response_type: Literal["nimbus.save"] = "nimbus.save"
+
+    state_id: int | None = Field(description="The id of the newest state")
+
+class NIMBUSDeleteSaveResponse(SQLModel):
+    """Response of NIMBUS save deletion."""
+
+    response_type: str = "nimbus.delete_save"
+
+    message: str | None
+
+class NIMBUSFinalizeResponse(SQLModel):
+    """The response from NIMBUS finish endpoint."""
+
+    response_type: Literal["nimbus.finalize"] = "nimbus.finalize"
+
+    state_id: int | None = Field(description="The newly created state id")
+    final_solution: SolutionReferenceResponse = Field(
+        description="The final solution. We do not need the other current solutions."
+    )
+    saved_solutions: list[SolutionReferenceResponse] = Field(
+        description="The best candidate solutions saved by the decision maker."
+    )
+    all_solutions: list[SolutionReferenceResponse] = Field(
+        description="All solutions generated by NIMBUS in all iterations."
+    )
+
+
+class NIMBUSInitializationRequest(SQLModel):
+    """Model of the request to the nimbus method."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+
+    starting_point: ReferencePoint | SolutionInfo | None = Field(sa_column=Column(JSON), default=None)
+    scalarization_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+    solver: str | None = Field(default=None)
+    solver_options: dict[str, float | str | bool] | None = Field(sa_column=Column(JSON), default=None)
+
+
+class NIMBUSIntermediateSolutionResponse(SQLModel):
+    """The response from NIMBUS classification endpoint."""
+
+    response_type: Literal["nimbus.intermediate"] = "nimbus.intermediate"
+
+    state_id: int | None = Field(description="The newly created state id")
+    reference_solution_1: dict[str, float] = Field(
+        sa_column=Column(JSON), description="The first solution used when computing intermediate points."
+    )
+    reference_solution_2: dict[str, float]= Field(
+        sa_column=Column(JSON), description="The second solution used when computing intermediate points."
+    )
+    current_solutions: list[SolutionReferenceResponse] = Field(
+        description="The solutions from the current iteration of NIMBUS."
+    )
+    saved_solutions: list[SolutionReferenceResponse] = Field(
+        description="The best candidate solutions saved by the decision maker."
+    )
+    all_solutions: list[SolutionReferenceResponse] = Field(
+        description="All solutions generated by NIMBUS in all iterations."
+    )