luna-quantum 1.0.0__cp313-cp313-win_amd64.whl → 1.0.1rc9__cp313-cp313-win_amd64.whl

luna_quantum/_core.pyi

@@ -1,15 +1,13 @@
 from datetime import datetime, timedelta
 from enum import Enum
-from typing import Any, overload
-
+from types import TracebackType
+from typing import Literal, Self, overload
 from numpy.typing import NDArray
+from . import errors, translator
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.domain.solve_job import SolveJob
 
-from . import exceptions, translator
-from .client.interfaces.services.luna_solve_i import ILunaSolve
-from .solve import ModelMetadata
-from .solve.domain.solve_job import SolveJob
-
-# _variable.pyi
 class Vtype(Enum):
     """
     Enumeration of variable types supported by the optimization system.
@@ -45,10 +43,12 @@ class Vtype(Enum):
     """Discrete integer-valued variable. Takes integer values within bounds."""
     Binary = ...
     """Binary variable. Can only take values 0 or 1."""
-
     Spin = ...
     """Spin variable. Can only take values -1 or +1."""
 
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
+
 class Unbounded: ...
 
 class Bounds:
@@ -85,33 +85,38 @@ class Bounds:
     """
 
     @overload
-    def __init__(self, /, *, lower: float | Unbounded) -> None: ...
+    def __init__(self, /, *, lower: (float | type[Unbounded])) -> None: ...
     @overload
-    def __init__(self, /, *, upper: float | type[Unbounded]) -> None: ...
+    def __init__(self, /, *, upper: (float | type[Unbounded])) -> None: ...
     @overload
     def __init__(
-        self, /, lower: float | type[Unbounded], upper: float | type[Unbounded]
+        self, /, lower: (float | type[Unbounded]), upper: (float | type[Unbounded])
     ) -> None: ...
-    @overload
     def __init__(
         self,
         /,
-        lower: float | type[Unbounded] | None = ...,
-        upper: float | type[Unbounded] | None = ...,
+        lower: (float | type[Unbounded] | None) = ...,
+        upper: (float | type[Unbounded] | None) = ...,
     ) -> None:
         """
         Create bounds for a variable.
 
         See class-level docstring for full documentation.
         """
+        ...
 
     @property
     def lower(self, /) -> float | Unbounded | None:
-        """Get the lower bound"""
+        """Get the lower bound."""
+        ...
 
     @property
     def upper(self, /) -> float | Unbounded | None:
-        """Get the upper bound"""
+        """Get the upper bound."""
+        ...
+
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
 
 class Variable:
     """
@@ -166,6 +171,8 @@ class Variable:
     @overload
     def __init__(self, /, name: str, *, env: Environment) -> None: ...
     @overload
+    def __init__(self, /, name: str, *, env: Environment, vtype: Vtype) -> None: ...
+    @overload
     def __init__(self, /, name: str, *, vtype: Vtype) -> None: ...
     @overload
     def __init__(self, /, name: str, *, vtype: Vtype, bounds: Bounds) -> None: ...
@@ -178,9 +185,9 @@ class Variable:
         /,
         name: str,
         *,
-        vtype: Vtype | None = ...,
-        bounds: Bounds | None = ...,
-        env: Environment | None = ...,
+        vtype: (Vtype | None) = ...,
+        bounds: (Bounds | None) = ...,
+        env: (Environment | None) = ...,
     ) -> None:
         """
         Initialize a new Variable.
@@ -196,14 +203,22 @@ class Variable:
         VariableCreationError
             If the variable is tried to be created with incompatible bounds.
         """
+        ...
 
     @property
     def name(self, /) -> str:
         """Get the name of the variable."""
+        ...
 
     @property
     def bounds(self, /) -> Bounds:
         """Get the bounds of the variable."""
+        ...
+
+    @property
+    def vtype(self, /) -> Vtype:
+        """Get the vtype of the variable."""
+        ...
 
     @overload
     def __add__(self, other: int, /) -> Expression: ...
@@ -213,7 +228,7 @@ class Variable:
     def __add__(self, other: Variable, /) -> Expression: ...
     @overload
     def __add__(self, other: Expression, /) -> Expression: ...
-    def __add__(self, other: float | Variable | Expression, /) -> Expression:
+    def __add__(self, other: (int | float | Variable | Expression), /) -> Expression:
         """
         Add this variable to another value.
 
@@ -233,6 +248,7 @@ class Variable:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __radd__(self, other: int, /) -> Expression: ...
@@ -242,7 +258,7 @@ class Variable:
     def __radd__(self, other: Variable, /) -> Expression: ...
     @overload
     def __radd__(self, other: Expression, /) -> Expression: ...
-    def __radd__(self, other: float | Variable | Expression, /) -> Expression:
+    def __radd__(self, other: (int | float | Variable | Expression), /) -> Expression:
         """
         Right-hand addition.
 
@@ -260,6 +276,7 @@ class Variable:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __sub__(self, other: int, /) -> Expression: ...
@@ -269,7 +286,7 @@ class Variable:
     def __sub__(self, other: Variable, /) -> Expression: ...
     @overload
     def __sub__(self, other: Expression, /) -> Expression: ...
-    def __sub__(self, other: float | Variable | Expression, /) -> Expression:
+    def __sub__(self, other: (int | float | Variable | Expression), /) -> Expression:
         """
         Subtract a value from this variable.
 
@@ -289,12 +306,13 @@ class Variable:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __rsub__(self, other: int, /) -> Expression: ...
     @overload
     def __rsub__(self, other: float, /) -> Expression: ...
-    def __rsub__(self, other: float, /) -> Expression:
+    def __rsub__(self, other: (int | float), /) -> Expression:
         """
         Subtract this variable from a scalar (right-hand subtraction).
 
@@ -312,6 +330,7 @@ class Variable:
         TypeError
             If `other` is not a scalar.
         """
+        ...
 
     @overload
     def __mul__(self, other: int, /) -> Expression: ...
@@ -321,7 +340,7 @@ class Variable:
     def __mul__(self, other: Variable, /) -> Expression: ...
     @overload
     def __mul__(self, other: Expression, /) -> Expression: ...
-    def __mul__(self, other: float | Variable | Expression, /) -> Expression:
+    def __mul__(self, other: (int | float | Variable | Expression), /) -> Expression:
         """
         Multiply this variable by another value.
 
@@ -341,6 +360,7 @@ class Variable:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __rmul__(self, other: int, /) -> Expression: ...
@@ -350,7 +370,7 @@ class Variable:
     def __rmul__(self, other: Variable, /) -> Expression: ...
     @overload
     def __rmul__(self, other: Expression, /) -> Expression: ...
-    def __rmul__(self, other: float | Variable | Expression, /) -> Expression:
+    def __rmul__(self, other: (int | float | Variable | Expression), /) -> Expression:
         """
         Right-hand multiplication for scalars.
 
@@ -368,6 +388,7 @@ class Variable:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     def __pow__(self, other: int, /) -> Expression:
         """
@@ -386,6 +407,7 @@ class Variable:
         RuntimeError
             If the param `modulo` usually supported for `__pow__` is specified.
         """
+        ...
 
     @overload
     def __eq__(self, rhs: int, /) -> Constraint: ...
@@ -407,7 +429,7 @@ class Variable:
         bool
         """
 
-    def __eq__(self, rhs: float | Expression, /) -> Constraint:  # type: ignore
+    def __eq__(self, rhs: (int | float | Expression), /) -> Constraint:
         """
         Create a constraint: Variable == float | int | Expression.
 
@@ -438,7 +460,7 @@ class Variable:
     def __le__(self, rhs: Variable, /) -> Constraint: ...
     @overload
     def __le__(self, rhs: Expression, /) -> Constraint: ...
-    def __le__(self, rhs: float | Variable | Expression, /) -> Constraint:  # type: ignore
+    def __le__(self, rhs: (int | float | Variable | Expression), /) -> Constraint:
         """
         Create a constraint: Variable <= scalar.
 
@@ -460,6 +482,7 @@ class Variable:
         TypeError
             If the right-hand side is not of type float, int, Variable or Expression.
         """
+        ...
 
     @overload
     def __ge__(self, rhs: int, /) -> Constraint: ...
@@ -469,7 +492,7 @@ class Variable:
     def __ge__(self, rhs: Variable, /) -> Constraint: ...
     @overload
     def __ge__(self, rhs: Expression, /) -> Constraint: ...
-    def __ge__(self, rhs: float | Variable | Expression, /) -> Constraint:
+    def __ge__(self, rhs: (int | float | Variable | Expression), /) -> Constraint:
         """
         Create a constraint: Variable >= scalar.
 
@@ -491,6 +514,7 @@ class Variable:
         TypeError
             If the right-hand side is not of type float, int, Variable or Expression.
         """
+        ...
 
     def __neg__(self, /) -> Expression:
         """
@@ -500,10 +524,122 @@ class Variable:
         -------
         Expression
         """
+        ...
+
+    @property
+    def _environment(self, /) -> Environment:
+        """Get this variables's environment."""
+        ...
 
     def __hash__(self, /) -> int: ...
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
+
+class Constant:
+    """A constant expression.
+
+    Convenience class to indicate the empty set of variables of an expression's
+    constant term when iterating over the expression's components.
+
+    Note that the bias corresponding to the constant part is not part of this class.
+
+    Examples
+    --------
+    >>> from luna_quantum import Constant, Expression, HigherOrder, Linear, Quadratic
+    >>> expr: Expression = ...
+    >>> vars: Constant | Linear | Quadratic | HigherOrder
+    >>> bias: float
+    >>> for vars, bias in expr.items():
+    >>> match vars:
+    >>>     case Constant(): do_something_with_constant(bias)
+    >>>     case Linear(x): do_something_with_linear_var(x, bias)
+    >>>     case Quadratic(x, y): do_something_with_quadratic_vars(x, y, bias)
+    >>>     case HigherOrder(ho): do_something_with_higher_order_vars(ho, bias)
+    """
+
+class Linear:
+    """A linear expression.
+
+    Convenience class to indicate the variable of an expression's linear term when
+    iterating over the expression's components.
+
+    Note that the bias corresponding to this variable is not part of this class.
+
+    Examples
+    --------
+    >>> from luna_quantum import Constant, Expression, HigherOrder, Linear, Quadratic
+    >>> expr: Expression = ...
+    >>> vars: Constant | Linear | Quadratic | HigherOrder
+    >>> bias: float
+    >>> for vars, bias in expr.items():
+    >>> match vars:
+    >>>     case Constant(): do_something_with_constant(bias)
+    >>>     case Linear(x): do_something_with_linear_var(x, bias)
+    >>>     case Quadratic(x, y): do_something_with_quadratic_vars(x, y, bias)
+    >>>     case HigherOrder(ho): do_something_with_higher_order_vars(ho, bias)
+    """
+
+    __match_args__ = ("var",)
+
+    @property
+    def var(self) -> Variable: ...
+
+class Quadratic:
+    """A quadratic expression.
+
+    Convenience class to indicate the variables of an expression's quadratic term when
+    iterating over the expression's components.
+
+    Note that the bias corresponding to these two variables is not part of this class.
+
+    Examples
+    --------
+    >>> from luna_quantum import Constant, Expression, HigherOrder, Linear, Quadratic
+    >>> expr: Expression = ...
+    >>> vars: Constant | Linear | Quadratic | HigherOrder
+    >>> bias: float
+    >>> for vars, bias in expr.items():
+    >>> match vars:
+    >>>     case Constant(): do_something_with_constant(bias)
+    >>>     case Linear(x): do_something_with_linear_var(x, bias)
+    >>>     case Quadratic(x, y): do_something_with_quadratic_vars(x, y, bias)
+    >>>     case HigherOrder(ho): do_something_with_higher_order_vars(ho, bias)
+    """
+
+    __match_args__ = "var_a", "var_b"
+
+    @property
+    def var_a(self) -> Variable: ...
+    @property
+    def var_b(self) -> Variable: ...
+
+class HigherOrder:
+    """A higher-order expression.
+
+    Convenience class to indicate the set of variables of an expression's higher-order
+    term when iterating over the expression's components.
+
+    Note that the bias corresponding to these variables is not part of this class.
+
+    Examples
+    --------
+    >>> from luna_quantum import Constant, Expression, HigherOrder, Linear, Quadratic
+    >>> expr: Expression = ...
+    >>> vars: Constant | Linear | Quadratic | HigherOrder
+    >>> bias: float
+    >>> for vars, bias in expr.items():
+    >>> match vars:
+    >>>     case Constant(): do_something_with_constant(bias)
+    >>>     case Linear(x): do_something_with_linear_var(x, bias)
+    >>>     case Quadratic(x, y): do_something_with_quadratic_vars(x, y, bias)
+    >>>     case HigherOrder(ho): do_something_with_higher_order_vars(ho, bias)
+    """
+
+    __match_args__ = ("vars",)
+
+    @property
+    def vars(self) -> list[Variable]: ...
 
-# _timing.pyi
 class Timing:
     """
     The object that holds information about an algorithm's runtime.
@@ -532,10 +668,12 @@ class Timing:
     @property
     def start(self, /) -> datetime:
         """The starting time of the algorithm."""
+        ...
 
     @property
     def end(self, /) -> datetime:
         """The end, or finishing, time of the algorithm."""
+        ...
 
     @property
     def total(self, /) -> timedelta:
@@ -547,25 +685,30 @@ class Timing:
         RuntimeError
             If total cannot be computed due to an inconsistent start or end time.
         """
+        ...
 
     @property
     def total_seconds(self, /) -> float:
         """
-        The total time in seconds an algorithm needed to run. Computed as the
-        difference of end and start time.
+        The total time in seconds an algorithm needed to run.
+
+        Computed as the difference of end and start time.
 
         Raises
         ------
         RuntimeError
-            If total_seconds cannot be computed due to an inconsistent start or end time.
+            If `total_seconds` cannot be computed due to an inconsistent start or
+            end time.
         """
+        ...
 
     @property
     def qpu(self, /) -> float | None:
         """The qpu usage time of the algorithm this timing object was created for."""
+        ...
 
     @qpu.setter
-    def qpu(self, /, value: float | None):
+    def qpu(self, /, value: (float | None)) -> None:
         """
         Set the qpu usage time.
 
@@ -574,11 +717,13 @@ class Timing:
         ValueError
             If `value` is negative.
         """
+        ...
 
-    def add_qpu(self, /, value: float):
+    def add_qpu(self, /, value: float) -> None:
         """
-        Add qpu usage time to the qpu usage time already present. If the current value
-        is None, this method acts like a setter.
+        Add qpu usage time to the qpu usage time already present.
+
+        If the current value is None, this method acts like a setter.
 
         Parameters
         ----------
@@ -590,6 +735,7 @@ class Timing:
         ValueError
             If `value` is negative.
         """
+        ...
 
 class Timer:
     """
@@ -618,6 +764,7 @@ class Timer:
         Timer
             The timer.
         """
+        ...
 
     def stop(self, /) -> Timing:
         """
@@ -628,8 +775,8 @@ class Timer:
         Timing
             The timing object that holds the start and end time.
         """
+        ...
 
-# _solution.pyi
 class Solution:
     """
     The solution object that is obtained by running an algorihtm.
@@ -639,9 +786,10 @@ class Solution:
     returned by the algorithm, metadata about the solution quality, e.g., the objective
     value, and the runtime of the algorithm.
 
-    A `Solution` can be constructed explicitly using `from_dict` or by obtaining a solution
-    from an algorithm or by converting a different solution format with one of the available
-    translators. Note that the latter requires the environment the model was created in.
+    A `Solution` can be constructed explicitly using `from_dict` or by obtaining a
+    solution from an algorithm or by converting a different solution format with one of
+    the available translators. Note that the latter requires the environment the model
+    was created in.
 
     Examples
     --------
@@ -675,10 +823,13 @@ class Solution:
 
     Notes
     -----
-    - To ensure metadata like objective values or feasibility, use `model.evaluate(solution)`.
+    - To ensure metadata like objective values or feasibility, use
+      `model.evaluate(solution)`.
     - Use `encode()` and `decode()` to serialize and recover solutions.
     """
 
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
     def __len__(self, /) -> int: ...
     def __iter__(self, /) -> ResultIterator:
         """
@@ -695,6 +846,7 @@ class Solution:
         IndexError
             If the row index is out of bounds for the variable environment.
         """
+        ...
 
     def __getitem__(self, item: int, /) -> ResultView:
         """
@@ -711,8 +863,9 @@ class Solution:
         IndexError
             If the row index is out of bounds for the variable environment.
         """
+        ...
 
-    def __eq__(self, other: Solution, /) -> bool:  # type: ignore
+    def __eq__(self, other: Solution, /) -> bool:
         """
         Check whether this solution is equal to `other`.
 
@@ -724,6 +877,7 @@ class Solution:
         -------
         bool
         """
+        ...
 
     def best(self, /) -> ResultView | None:
         """
@@ -737,44 +891,60 @@ class Solution:
         ResultView
             The best result of the solution as a view.
         """
+        ...
 
     @property
     def results(self, /) -> ResultIterator:
         """Get an iterator over the single results of the solution."""
+        ...
 
     @property
     def samples(self, /) -> Samples:
         """Get a view into the samples of the solution."""
+        ...
 
     @property
     def obj_values(self, /) -> NDArray:
         """
-        Get the objective values of the single samples as a ndarray. A value will be
-        None if the sample hasn't yet been evaluated.
+        Get the objective values of the single samples as a ndarray.
+
+        A value will be None if the sample hasn't yet been evaluated.
         """
+        ...
 
     @property
     def raw_energies(self, /) -> NDArray:
-        """
+        """Get the raw energies.
+
         Get the raw energy values of the single samples as returned by the solver /
         algorithm. Will be None if the solver / algorithm did not provide a value.
         """
+        ...
 
     @property
     def counts(self, /) -> NDArray:
         """Return how often each sample occurred in the solution."""
+        ...
 
     @property
     def runtime(self, /) -> Timing | None:
         """Get the solver / algorithm runtime."""
+        ...
+
+    @property
+    def sense(self, /) -> Sense:
+        """Get the optimization sense."""
+        ...
 
     @property
     def best_sample_idx(self, /) -> int | None:
         """Get the index of the sample with the best objective value."""
+        ...
 
     @property
     def variable_names(self, /) -> list[str]:
         """Get the names of all variables in the solution."""
+        ...
 
     def expectation_value(self, /) -> float:
         """
@@ -790,6 +960,55 @@ class Solution:
         ComputationError
             If the computation fails for any reason.
         """
+        ...
+
+    def feasibility_ratio(self, /) -> float:
+        """
+        Compute the feasibility ratio of the solution.
+
+        Returns
+        -------
+        float
+            The feasibility ratio.
+
+        Raises
+        ------
+        ComputationError
+            If the computation fails for any reason.
+        """
+        ...
+
+    def filter_feasible(self, /) -> Solution:
+        """
+        Get a new solution with all infeasible samples removed.
+
+        Returns
+        -------
+            The new solution with only feasible samples.
+
+        Raises
+        ------
+        ComputationError
+            If the computation fails for any reason.
+        """
+        ...
+
+    def highest_constraint_violation(self, /) -> int | None:
+        """
+        Get the index of the constraint with the highest number of violations.
+
+        Returns
+        -------
+        int | None
+            The index of the constraint with the most violations. None, if the solution
+            was created for an unconstrained model.
+
+        Raises
+        ------
+        ComputationError
+            If the computation fails for any reason.
+        """
+        ...
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -798,7 +1017,8 @@ class Solution:
     @overload
     def encode(self, /, *, level: int) -> bytes: ...
     @overload
-    def encode(self, /, *, compress: bool, level: int) -> bytes:
+    def encode(self, /, *, compress: bool, level: int) -> bytes: ...
+    def encode(self, /, *, compress: bool = True, level: int = 3) -> bytes:
         """
         Serialize the solution into a compact binary format.
 
@@ -807,7 +1027,7 @@ class Solution:
         compress : bool, optional
             Whether to compress the binary output. Default is True.
         level : int, optional
-            Compression level (0–9). Default is 3.
+            Compression level (0-9). Default is 3.
 
         Returns
         -------
@@ -819,6 +1039,7 @@ class Solution:
         IOError
             If serialization fails.
         """
+        ...
 
     @overload
     def serialize(self, /) -> bytes: ...
@@ -829,13 +1050,14 @@ class Solution:
     @overload
     def serialize(self, /, compress: bool, level: int) -> bytes: ...
     def serialize(
-        self, /, compress: bool | None = ..., level: int | None = ...
+        self, /, compress: (bool | None) = ..., level: (int | None) = ...
     ) -> bytes:
         """
         Alias for `encode()`.
 
         See `encode()` for details.
         """
+        ...
 
     @classmethod
     def decode(cls, data: bytes) -> Solution:
@@ -857,184 +1079,124 @@ class Solution:
         DecodeError
             If decoding fails due to corruption or incompatibility.
         """
+        ...
 
     @classmethod
     def deserialize(cls, data: bytes) -> Solution:
         """Alias for `decode()`."""
-
-    @staticmethod
-    def build(
-        component_types: list[Vtype],
-        *,
-        variable_names: list[str] | None = ...,
-        binary_cols: list[list[int]] | None = ...,
-        spin_cols: list[list[int]] | None = ...,
-        int_cols: list[list[int]] | None = ...,
-        real_cols: list[list[float]] | None = ...,
-        raw_energies: list[float | None] | None = ...,
-        timing: Timing | None = ...,
-        counts: list[int] | None = ...,
-    ) -> Solution:
-        """
-        Build a `Solution` based on the provided input data. The solution is constructed
-        based on a column layout of the solution. Let's take the following sample-set with three
-        samples as an example:
-
-        [ 0  1  -1  3  2.2  1 ]
-        [ 1  0  -1  6  3.8  0 ]
-        [ 1  1  +1  2  2.4  0 ]
-
-        Each row encodes a single sample. However, the variable types vary, the first, second, and
-        last columns all represent a Binary variable (index 0, 1, 5). The third column represents a
-        variable of type Spin (index 2). The fourth column (index 3), a variable of type Integer and
-        the fifth column (index 4), a real-valued variable.
-
-        Thus, the `component_types` list is:
-
-        >>> component_types = [Vtype.Binary, Vtype.Binary, Vtype.Spin, Vtype.Integer, Vtype.Real, Vtype.Binary]
-
-        Now we can extract all columns for a binary-valued variable and append them to a new list:
-
-        >>> binary_cols = [[0, 1, 1], [1, 0, 1], [1, 0, 0]]
-
-        where the first element in the list represents the first column, the second element the\
-        second column and the third element the fifth column.
-        We do the same for the remaining variable types:
-
-        >>> spin_cols = [[-1, -1, +1]]
-        >>> int_cols = [[3, 6, 2]]
-        >>> real_cols = [[2.2, 3.8, 2.4]]
-
-        If we know the raw energies, we can construct them as well:
-
-        >>> raw_energies = [-200, -100, +300]
-
-        And finally call the `build` function:
-
-        >>> sol = Solution.build(
-        ...     component_types,
-        ...     binary_cols,
-        ...     spin_cols,
-        ...     int_cols,
-        ...     real_cols,
-        ...     raw_energies,
-        ...     timing,
-        ...     counts=[1, 1, 1]
-        ... )
-        >>> sol
-
-        In this example, we could also neglect the `counts` as it defaults to `1`
-        for all samples if not set:
-
-        >>> sol = Solution.build(
-        ...     component_types,
-        ...     binary_cols,
-        ...     spin_cols,
-        ...     int_cols,
-        ...     real_cols,
-        ...     raw_energies,
-        ...     timing
-        ... )
-        >>> sol
-
-
-        Parameters
-        ----------
-        component_types : list[Vtype]
-            The variable type each element in a sample encodes.
-        variable_names : list[Vtype], optional
-            The name of each variable in the solution.
-        binary_cols : list[list[int]], optional
-            The data of all binary valued columns. Each inner list encodes a single binary-valued
-            column. Required if any element in the `component_types` is `Vtype.Binary`.
-        spin_cols : list[list[int]], optional
-            The data of all spin-valued columns. Each inner list encodes a single spin-valued
-            column. Required if any element in the `component_types` is `Vtype.Spin`.
-        int_cols : list[list[int]], optional
-            The data of all integer-valued columns. Each inner list encodes a single integer valued
-            column. Required if any element in the `component_types` is `Vtype.Integer`.
-        real_cols : list[list[float]], optional
-            The data of all real-valued columns. Each inner list encodes a single real-valued
-            column. Required if any element in the `component_types` is `Vtype.Real`.
-        raw_energies : list[float, optional], optional
-            The data of all real valued columns. Each inner list encodes a single real-valued
-            column.
-        timing : Timing, optional
-            The timing data.
-        counts : list[int], optional
-            The number how often each sample in the solution has occurred. By default, 1 for all
-            samples.
-
-        Returns
-        -------
-        Solution
-            The constructed solution
-
-        Raises
-        ------
-        RuntimeError
-            If a sample column has an incorrect number of samples or if `counts` has
-            a length different from the number of samples given.
-        """
+        ...
 
     @overload
     @staticmethod
-    def from_dict(data: dict[Variable, int]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[Variable, float]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[str, int]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[str, float]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[Variable | str, int | float]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[Variable, int], *, env: Environment) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(data: dict[Variable, float], *, env: Environment) -> Solution: ...
+    def from_dict(
+        data: dict[Variable, int],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[str, int], *, env: Environment) -> Solution: ...
+    def from_dict(
+        data: dict[Variable, float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[str, float], *, env: Environment) -> Solution: ...
+    def from_dict(
+        data: dict[str, int],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
     def from_dict(
-        data: dict[Variable | str, int | float], *, env: Environment
+        data: dict[str, float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[Variable, int], *, model: Model) -> Solution: ...
+    def from_dict(
+        data: dict[Variable | str, int],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[Variable, float], *, model: Model) -> Solution: ...
+    def from_dict(
+        data: dict[Variable | str, float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[str, int], *, model: Model) -> Solution: ...
+    def from_dict(
+        data: dict[Variable, int | float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dict(data: dict[str, float], *, model: Model) -> Solution: ...
+    def from_dict(
+        data: dict[str, int | float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
     def from_dict(
-        data: dict[Variable | str, int | float], *, model: Model
+        data: dict[Variable | str, int | float],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: int = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @staticmethod
     def from_dict(
         data: dict[Variable | str, int | float],
         *,
-        env: Environment | None = ...,
-        model: Model | None = ...,
-        timing: Timing | None = ...,
+        env: (Environment | None) = ...,
+        model: (Model | None) = ...,
+        timing: (Timing | None) = ...,
+        counts: (int | None) = ...,
+        sense: (Sense | None) = ...,
     ) -> Solution:
-        """
+        """Create a `Solution` from a dict.
+
         Create a `Solution` from a dict that maps variables or variable names to their
         assigned values.
 
@@ -1049,6 +1211,8 @@ class Solution:
             The environment the variable types shall be determined from.
         model : Model, optional
             A model to evaluate the sample with.
+        counts : int, optional
+            The number of occurrences of this sample.
 
         Returns
         -------
@@ -1063,6 +1227,7 @@ class Solution:
         ValueError
             If `env` and `model` are both present. When this is the case, the user's
             intention is unclear as the model itself already contains an environment.
+            Or if `sense` and `model` are both present as the sense is then ambiguous.
         SolutionTranslationError
             Generally if the sample translation fails. Might be specified by one of the
             three following errors.
@@ -1074,72 +1239,122 @@ class Solution:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[Variable, int]]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[Variable, float]]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[str, int]]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[str, float]]) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[Variable | str, int | float]]) -> Solution: ...
     @overload
     @staticmethod
     def from_dicts(
-        data: list[dict[Variable, int]], *, env: Environment
+        data: list[dict[Variable, int]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @overload
     @staticmethod
     def from_dicts(
-        data: list[dict[Variable, float]], *, env: Environment
+        data: list[dict[Variable, float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dicts(data: list[dict[str, int]], *, env: Environment) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(data: list[dict[str, float]], *, env: Environment) -> Solution: ...
+    def from_dicts(
+        data: list[dict[str, int]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
     def from_dicts(
-        data: list[dict[Variable | str, int | float]], *, env: Environment
+        data: list[dict[str, float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dicts(data: list[dict[Variable, int]], *, model: Model) -> Solution: ...
+    def from_dicts(
+        data: list[dict[Variable | str, int]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dicts(data: list[dict[Variable, float]], *, model: Model) -> Solution: ...
+    def from_dicts(
+        data: list[dict[Variable | str, float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dicts(data: list[dict[str, int]], *, model: Model) -> Solution: ...
+    def from_dicts(
+        data: list[dict[Variable, int | float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
-    def from_dicts(data: list[dict[str, float]], *, model: Model) -> Solution: ...
+    def from_dicts(
+        data: list[dict[str, int | float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
+    ) -> Solution: ...
     @overload
     @staticmethod
     def from_dicts(
-        data: list[dict[Variable | str, int | float]], *, model: Model
+        data: list[dict[Variable | str, int | float]],
+        *,
+        env: Environment = ...,
+        model: Model = ...,
+        timing: Timing = ...,
+        counts: list[int] = ...,
+        sense: Sense = ...,
     ) -> Solution: ...
     @staticmethod
     def from_dicts(
         data: list[dict[Variable | str, int | float]],
         *,
-        env: Environment | None = ...,
-        model: Model | None = ...,
-        timing: Timing | None = ...,
+        env: (Environment | None) = ...,
+        model: (Model | None) = ...,
+        timing: (Timing | None) = ...,
+        counts: (list[int] | None) = ...,
+        sense: (Sense | None) = ...,
     ) -> Solution:
-        """
-        Create a `Solution` from multiple dicts that map variables or variable names to their
-        assigned values. Duplicate samples contained in the `data` list are aggregated to a single
-        sample.
+        """Create a `Solution` from multiple dicts.
+
+        Create a `Solution` from multiple dicts that map variables or variable names to
+        their assigned values. Duplicate samples contained in the `data` list are
+        aggregated to a single sample.
 
         If a Model is passed, the solution will be evaluated immediately. Otherwise,
         there has to be an environment present to determine the correct variable types.
@@ -1152,6 +1367,10 @@ class Solution:
             The environment the variable types shall be determined from.
         model : Model, optional
             A model to evaluate the sample with.
+        counts : int, optional
+            The number of occurrences for each sample.
+        sense: Sense, optional
+            The sense of the optimization problem.
 
         Returns
         -------
@@ -1166,6 +1385,8 @@ class Solution:
         ValueError
             If `env` and `model` are both present. When this is the case, the user's
             intention is unclear as the model itself already contains an environment.
+            Or if `sense` and `model` are both present as the sense is then ambiguous.
+            Or if the the number of samples and the number of counts do not match.
         SolutionTranslationError
             Generally if the sample translation fails. Might be specified by one of the
             three following errors.
@@ -1177,8 +1398,130 @@ class Solution:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
+
+    @staticmethod
+    def from_counts(
+        data: dict[str, int],
+        *,
+        env: (Environment | None) = ...,
+        model: (Model | None) = ...,
+        timing: (Timing | None) = ...,
+        sense: (Sense | None) = ...,
+        bit_order: Literal["LTR", "RTL"] = "RTL",
+    ) -> Solution:
+        """
+        Create a `Solution` from a dict that maps measured bitstrings to counts.
+
+        If a Model is passed, the solution will be evaluated immediately. Otherwise,
+        there has to be an environment present to determine the correct variable types.
+        Only applicable to binary or spin models.
+
+        Parameters
+        ----------
+        data : dict[str, int]
+            The counts that shall be part of the solution.
+        env : Environment, optional
+            The environment the variable types shall be determined from.
+        model : Model, optional
+            A model to evaluate the sample with.
+        timing : Timing, optional
+            The timing for acquiring the solution.
+        sense : Sense, optional
+            The sense the model the solution belongs to. Default: Sense.Min
+        bit_order : Literal["LTR", "RTL"]
+            The order of the bits in the bitstring. Default "RTL".
+
+        Returns
+        -------
+        Solution
+            The solution object created from the sample dict.
+
+        Raises
+        ------
+        NoActiveEnvironmentFoundError
+            If no environment or model is passed to the method or available from the
+            context.
+        ValueError
+            If `env` and `model` are both present. When this is the case, the user's
+            intention is unclear as the model itself already contains an environment.
+            Or if `sense` and `model` are both present as the sense is then ambiguous.
+            Or if the the environment contains non-(binary or spin) variables.
+            Or if a bitstring contains chars other than '0' and '1'.
+        SolutionTranslationError
+            Generally if the sample translation fails. Might be specified by one of the
+            three following errors.
+        SampleIncorrectLengthErr
+            If a sample has a different number of variables than the environment.
+        """
+        ...
+
+    def print(
+        self,
+        /,
+        layout: Literal["row", "column"] = "column",
+        max_line_length: int = 80,
+        max_column_length: int = 5,
+        max_lines: int = 10,
+        max_var_name_length: int = 10,
+        show_metadata: Literal["before", "after", "hide"] = "after",
+    ) -> None:
+        """
+        Show a solution object as a human-readable string.
+
+        This method provides various ways to customize the way the solution is
+        represented as a string.
+
+        Parameters
+        ----------
+        layout : Literal["row", "column"]
+            With `"row"` layout, all assignments to one variable across different
+            samples are shown in the same *row*, and each sample is shown in one
+            column.
+            With `"column"` layout, all assignments to one variable across different
+            samples are shown in the same *column*, and each sample is shown in one row.
+        max_line_length : int
+            The max number of chars shown in one line or, in other words, the max width
+            of a row.
+        max_column_length : int
+            The maximal number of chars in one column. For both the row and column
+            layout, this controls the max number of chars a single variable assignment
+            may be shown with. For the column layout, this also controls the max number
+            of chars that a variable name is shown with.
+            Note: the max column length cannot always be adhered to. This is
+            specifically the case when a variable assignment is so high that the max
+            column length is not sufficient to show the number correctly.
+        max_lines : int
+            The max number of lines used for showing the samples. Note that this
+             parameter does not influence how metadata are shown, s.t. the total number
+             of lines may be higher than `max_lines`.
+        max_var_name_length : int
+            The max number of chars that a variable is shown with in row layout. This
+            parameter is ignored in column layout.
+        show_metadata : Literal["before", "after", "hide"]
+            Whether and where to show sample-specific metadata such as feasibility and
+            objective value. Note that this parameter only controls how sample-specific
+            metadata are shown. Other metadata, like the solution timing will be shown
+            after the samples regardless of the value of this parameter.
+
+            - `"before"`: show metadata before the actual sample, i.e., above the
+                sample in row layout, and left of the sample in column layout.
+            - `"after"`: show metadata after the actual sample, i.e., below the
+                sample in row layout, and right of the sample in column layout.
+            - "hide": do not show sample-specific metadata.
+
+        Returns
+        -------
+        str
+            The solution represented as a string.
+
+        Raises
+        ------
+        ValueError
+            If at least one of the params has an invalid value.
+        """
+        ...
 
-# _sample.pyi
 class SamplesIterator:
     """
     An iterator over a solution's samples.
@@ -1222,12 +1565,11 @@ class SampleIterator:
     def __next__(self, /) -> int | float: ...
 
 class Samples:
-    """
-    A samples object is simply a set-like object that contains every different sample
-    of a solution.
+    """A set-like object containing every different sample of a solution.
 
-    The ``Samples`` class is readonly as it's merely a helper class for looking into a
-    solution's different samples.
+    A samples object is simply a set-like object that contains every different sample
+    of a solution. The ``Samples`` class is readonly as it's merely a helper class for
+    looking into a solution's different samples.
 
     Examples
     --------
@@ -1240,12 +1582,14 @@ class Samples:
     [1, -4, -0.42]
     """
 
+    def __str__(self, /) -> str: ...
     @overload
     def __getitem__(self, item: int, /) -> Sample: ...
     @overload
-    def __getitem__(self, item: tuple[int, int], /) -> int | float:
-        """
-        Extract a sample or variable assignment from the ``Samples`` object.
+    def __getitem__(self, item: tuple[int, int], /) -> int | float: ...
+    def __getitem__(self, item: (int | tuple[int, int]), /) -> int | float:
+        """Extract a sample or variable assignment from the ``Samples`` object.
+
         If ``item`` is an int, returns the sample in this row. If ``item`` is a tuple
         of ints `(i, j)`, returns the variable assignment in row `i` and column `j`.
 
@@ -1260,6 +1604,7 @@ class Samples:
         IndexError
             If the row or column index is out of bounds for the variable environment.
         """
+        ...
 
     def __len__(self, /) -> int:
         """
@@ -1269,6 +1614,7 @@ class Samples:
         -------
         int
         """
+        ...
 
     def __iter__(self, /) -> SamplesIterator:
         """
@@ -1278,9 +1624,11 @@ class Samples:
         -------
         SamplesIterator
         """
+        ...
 
     def tolist(self, /) -> list[list[int | float]]:
-        """
+        """Convert sample into a 2-dimensional list.
+
         Convert the sample into a 2-dimensional list where a row constitutes a single
         sample, and a column constitutes all assignments for a single variable.
 
@@ -1289,10 +1637,12 @@ class Samples:
         list[list[int | float]]
             The samples object as a 2-dimensional list.
         """
+        ...
 
 class Sample:
-    """
-    A sample object is an assignment of an actual value to each of the models'
+    """Assignment of actual values to the model's variables.
+
+    A sample object is an assignment of an actual value to each of the model's
     variables.
 
     The ``Sample`` class is readonly as it's merely a helper class for looking into a
@@ -1311,17 +1661,20 @@ class Sample:
     [0, -5, 0.28]
     """
 
+    def __str__(self, /) -> str: ...
     @overload
     def __getitem__(self, item: int, /) -> int | float: ...
     @overload
     def __getitem__(self, item: Variable, /) -> int | float: ...
-    def __getitem__(self, item: int | Variable, /) -> int | float:
+    @overload
+    def __getitem__(self, item: str, /) -> int | float: ...
+    def __getitem__(self, item: (int | Variable | str), /) -> int | float:
         """
         Extract a variable assignment from the ``Sample`` object.
 
         Returns
         -------
-        Sample or int or float
+        int or float
 
         Raises
         ------
@@ -1330,6 +1683,7 @@ class Sample:
         IndexError
             If the row or column index is out of bounds for the variable environment.
         """
+        ...
 
     def __len__(self, /) -> int:
         """
@@ -1339,6 +1693,7 @@ class Sample:
         -------
         int
         """
+        ...
 
     def __iter__(self, /) -> SampleIterator:
         """
@@ -1348,8 +1703,18 @@ class Sample:
         -------
         SampleIterator
         """
+        ...
+
+    def to_dict(self, /) -> dict[str, int | float]:
+        """Convert the sample to a dictionary.
+
+        Returns
+        -------
+        dict
+            A dictionary representation of the sample, where the keys are the
+            variable names and the values are the variables' assignments.
+        """
 
-# _result.pyi
 class ResultIterator:
     """
     An iterator over a solution's results.
@@ -1398,28 +1763,35 @@ class Result:
     @property
     def sample(self, /) -> Sample:
         """Get the sample of the result."""
+        ...
 
     @property
     def obj_value(self, /) -> float | None:
         """Get the objective value of the result."""
+        ...
 
     @property
     def constraints(self, /) -> NDArray | None:
-        """
+        """The result's feasibility of all constraints.
+
         Get this result's feasibility values of all constraints. Note that
         `results.constraints[i]` iff. `model.constraints[i]` is feasible for
         this result.
         """
+        ...
 
     @property
     def variable_bounds(self, /) -> NDArray | None:
-        """
-        Get this result's feasibility values of all variable bounds.
-        """
+        """Get this result's feasibility values of all variable bounds."""
+        ...
 
     @property
     def feasible(self, /) -> bool | None:
         """Return whether all constraint results are feasible for this result."""
+        ...
+
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
 
 class ResultView:
     """
@@ -1450,46 +1822,56 @@ class ResultView:
     @property
     def sample(self, /) -> Sample:
         """Get the sample of the result."""
+        ...
 
     @property
     def counts(self, /) -> int:
         """Return how often this result appears in the solution."""
+        ...
 
     @property
     def obj_value(self, /) -> float | None:
         """
-        Get the objective value of this sample if present. This is the value computed
-        by the corresponding AqModel.
+        Get the objective value of this sample if present.
+
+        This is the value computed by the corresponding AqModel.
         """
+        ...
 
     @property
     def raw_energy(self, /) -> float | None:
         """
-        Get the raw energy returned by the algorithm if present. This value is not
-        guaranteed to be accurate under consideration of the corresponding AqModel.
+        Get the raw energy returned by the algorithm if present.
+
+        This value is not guaranteed to be accurate under consideration of the
+        corresponding AqModel.
         """
+        ...
 
     @property
     def constraints(self, /) -> NDArray | None:
         """
-        Get this result's feasibility values of all constraints. Note that
-        `results.constraints[i]` iff. `model.constraints[i]` is feasible for
+        Get this result's feasibility values of all constraints.
+
+        Note that `results.constraints[i]` iff. `model.constraints[i]` is feasible for
         this result.
         """
+        ...
 
     @property
     def variable_bounds(self, /) -> NDArray | None:
-        """
-        Get this result's feasibility values of all variable bounds.
-        """
+        """Get this result's feasibility values of all variable bounds."""
+        ...
 
     @property
     def feasible(self, /) -> bool | None:
         """Return whether all constraint results are feasible for this result."""
+        ...
 
-    def __eq__(self, other: ResultView, /) -> bool: ...  # type: ignore
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
+    def __eq__(self, other: ResultView, /) -> bool: ...
 
-# _model.pyi
 class Sense(Enum):
     """
     Enumeration of optimization senses supported by the optimization system.
@@ -1500,7 +1882,6 @@ class Sense(Enum):
 
     Min = ...
     """Indicate the objective function to be minimized."""
-
     Max = ...
     """Indicate the objective function to be maximized."""
 
@@ -1558,22 +1939,11 @@ class Model:
     Notes
     -----
     - The `Model` class does not solve the optimization problem.
-    - Use `.objective`, `.constraints`, and `.environment` to access the symbolic content.
+    - Use `.objective`, `.constraints`, and `.environment` to access the symbolic
+      content.
     - Use `encode()` and `decode()` to serialize and recover models.
     """
 
-    metadata: ModelMetadata | None = ...
-
-    @staticmethod
-    def load_luna(model_id: str, client: ILunaSolve | str | None = None) -> Model: ...
-    def save_luna(self, client: ILunaSolve | str | None = None) -> None: ...
-    def delete_luna(self, client: ILunaSolve | str | None = None) -> None: ...
-    def load_solutions(
-        self, client: ILunaSolve | str | None = None
-    ) -> list[Solution]: ...
-    def load_solve_jobs(
-        self, client: ILunaSolve | str | None = None
-    ) -> list[SolveJob]: ...
     @overload
     def __init__(self, /) -> None: ...
     @overload
@@ -1593,10 +1963,10 @@ class Model:
     def __init__(
         self,
         /,
-        name: str | None = ...,
+        name: (str | None) = ...,
         *,
-        sense: Sense | None = ...,
-        env: Environment | None = ...,
+        sense: (Sense | None) = ...,
+        env: (Environment | None) = ...,
     ) -> None:
         """
         Initialize a new symbolic model.
@@ -1609,6 +1979,7 @@ class Model:
             The environment in which the model operates. If not provided, a new
             environment will be created or inferred from context.
         """
+        ...
 
     def set_sense(self, /, sense: Sense) -> None:
         """
@@ -1619,47 +1990,130 @@ class Model:
         sense : Sense
             The sense of the model (minimization, maximization)
         """
+        ...
+
+    @overload
+    def add_variable(self, name: str, /) -> Variable: ...
+    @overload
+    def add_variable(self, name: str, /, vtype: (Vtype | None) = ...) -> Variable: ...
+    @overload
+    def add_variable(
+        self, name: str, /, vtype: Vtype, *, lower: (float | type[Unbounded])
+    ) -> Variable: ...
+    @overload
+    def add_variable(
+        self, name: str, /, vtype: Vtype, *, upper: (float | type[Unbounded])
+    ) -> Variable: ...
+    @overload
+    def add_variable(
+        self,
+        name: str,
+        /,
+        vtype: Vtype,
+        *,
+        lower: (float | type[Unbounded]),
+        upper: (float | type[Unbounded]),
+    ) -> Variable: ...
+    def add_variable(
+        self,
+        name: str,
+        /,
+        vtype: (Vtype | None) = ...,
+        *,
+        lower: (float | type[Unbounded] | None) = ...,
+        upper: (float | type[Unbounded] | None) = ...,
+    ) -> Variable:
+        """
+        Add a new variable to the model.
+
+        Parameters
+        ----------
+        name : str
+            The name of the variable.
+        vtype : Vtype, optional
+            The variable type (e.g., `Vtype.Real`, `Vtype.Integer`, etc.).
+            Defaults to `Vtype.Binary`.
+        lower: float, optional
+            The lower bound restricts the range of the variable. Only applicable for
+            `Real` and `Integer` variables.
+        upper: float, optional
+            The upper bound restricts the range of the variable. Only applicable for
+            `Real` and `Integer` variables.
+
+        Returns
+        -------
+        Variable
+            The variable added to the model.
+        """
+        ...
+
+    def get_variable(self, name: str, /) -> Variable:
+        """Get a variable by its label (name).
+
+        Parameters
+        ----------
+        label : str
+            The name/label of the variable
+
+        Returns
+        -------
+        Variable
+            The variable with the specified label/name.
+
+        Raises
+        ------
+        VariableNotExistingError
+            If no variable with the specified name is registered.
+        """
+        ...
 
     @property
     def name(self, /) -> str:
         """Return the name of the model."""
+        ...
 
     @property
     def sense(self, /) -> Sense:
         """
-        Get the sense of the model
+        Get the sense of the model.
 
         Returns
         -------
         Sense
             The sense of the model (Min or Max).
         """
+        ...
 
     @property
     def objective(self, /) -> Expression:
         """Get the objective expression of the model."""
+        ...
 
     @objective.setter
-    def objective(self, value: Expression, /):
+    def objective(self, value: Expression, /) -> None:
         """Set the objective expression of the model."""
+        ...
 
     @property
     def constraints(self, /) -> Constraints:
         """Access the set of constraints associated with the model."""
+        ...
 
     @constraints.setter
-    def constraints(self, value: Constraints, /):
+    def constraints(self, value: Constraints, /) -> None:
         """Replace the model's constraints with a new set."""
+        ...
 
     @property
     def environment(self, /) -> Environment:
         """Get the environment in which this model is defined."""
+        ...
 
     @overload
     def variables(self, /) -> list[Variable]: ...
     @overload
     def variables(self, /, *, active: bool) -> list[Variable]: ...
-    def variables(self, /, active: bool | None = ...) -> list[Variable]:
+    def variables(self, /, active: (bool | None) = ...) -> list[Variable]:
         """
         Get all variables that are part of this model.
 
@@ -1673,12 +2127,15 @@ class Model:
         -------
         The model's variables as a list.
         """
+        ...
 
     @overload
-    def add_constraint(self, /, constraint: Constraint): ...
+    def add_constraint(self, /, constraint: Constraint) -> None: ...
     @overload
-    def add_constraint(self, /, constraint: Constraint, name: str): ...
-    def add_constraint(self, /, constraint: Constraint, name: str | None = ...):
+    def add_constraint(self, /, constraint: Constraint, name: str) -> None: ...
+    def add_constraint(
+        self, /, constraint: Constraint, name: (str | None) = ...
+    ) -> None:
         """
         Add a constraint to the model's constraint collection.
 
@@ -1689,12 +2146,15 @@ class Model:
         name : str, optional
             The name of the constraint to be added.
         """
+        ...
 
     @overload
-    def set_objective(self, /, expression: Expression): ...
+    def set_objective(self, /, expression: Expression) -> None: ...
     @overload
-    def set_objective(self, /, expression: Expression, *, sense: Sense): ...
-    def set_objective(self, /, expression: Expression, *, sense: Sense | None = ...):
+    def set_objective(self, /, expression: Expression, *, sense: Sense) -> None: ...
+    def set_objective(
+        self, /, expression: Expression, *, sense: (Sense | None) = ...
+    ) -> None:
         """
         Set the model's objective to this expression.
 
@@ -1705,6 +2165,7 @@ class Model:
         sense : Sense, optional
             The sense of the model for this objective, by default Sense.Min.
         """
+        ...
 
     @property
     def num_constraints(self, /) -> int:
@@ -1716,6 +2177,7 @@ class Model:
         int
             Total number of constraints.
         """
+        ...
 
     def evaluate(self, /, solution: Solution) -> Solution:
         """
@@ -1731,6 +2193,7 @@ class Model:
         Solution
             A new solution object with filled-out information.
         """
+        ...
 
     def evaluate_sample(self, /, sample: Sample) -> Result:
         """
@@ -1746,6 +2209,55 @@ class Model:
         Result
             A result object containing the information from the evaluation process.
         """
+        ...
+
+    def violated_constraints(self, /, sample: Sample) -> Constraints:
+        """
+        Get all model constraints that are violated by the given sample.
+
+        Parameters
+        ----------
+        sample : Sample
+            The sample to check constraint feasibility for.
+
+        Returns
+        -------
+        Constraints
+            The constraints violated by the given sample.
+        """
+        ...
+
+    def substitute(
+        self, /, target: Variable, replacement: (Expression | Variable)
+    ) -> None:
+        """Substitute every occurrence of variable.
+
+        Substitute every occurrence of a variable in the model's objective and
+        constraint expressions with another expression.
+
+        Given a `Model` instance `self`, this method replaces all occurrences of
+        `target` with `replacement` for the objective and each constraint.
+        If any substitution would cross differing environments (e.g. captures from two
+        different scopes), it raises a `DifferentEnvsError`.
+
+        Parameters
+        ----------
+        target : VarRef
+            The variable reference to replace.
+        replacement : Expression
+            The expression to insert in place of `target`.
+
+        Returns
+        -------
+        None
+            Performs substitution in place; no return value.
+
+        Raises
+        ------
+        DifferentEnvsError
+            If the environments of `self`, `target`, and `replacement`
+            are not compatible.
+        """
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -1755,7 +2267,9 @@ class Model:
     def encode(self, /, *, level: int) -> bytes: ...
     @overload
     def encode(self, /, compress: bool, level: int) -> bytes: ...
-    def encode(self, /, compress: bool | None = ..., level: int | None = ...) -> bytes:
+    def encode(
+        self, /, compress: (bool | None) = True, level: (int | None) = 3
+    ) -> bytes:
         """
         Serialize the model into a compact binary format.
 
@@ -1764,7 +2278,7 @@ class Model:
         compress : bool, optional
             Whether to compress the binary output. Default is True.
         level : int, optional
-            Compression level (0–9). Default is 3.
+            Compression level (0-9). Default is 3.
 
         Returns
         -------
@@ -1776,6 +2290,7 @@ class Model:
         IOError
             If serialization fails.
         """
+        ...
 
     @overload
     def serialize(self, /) -> bytes: ...
@@ -1786,13 +2301,14 @@ class Model:
     @overload
     def serialize(self, /, compress: bool, level: int) -> bytes: ...
     def serialize(
-        self, /, compress: bool | None = ..., level: int | None = ...
+        self, /, compress: (bool | None) = ..., level: (int | None) = ...
     ) -> bytes:
         """
         Alias for `encode()`.
 
         See `encode()` for full documentation.
         """
+        ...
 
     @classmethod
     def decode(cls, data: bytes) -> Model:
@@ -1814,6 +2330,7 @@ class Model:
         DecodeError
             If decoding fails due to corruption or incompatibility.
         """
+        ...
 
     @classmethod
     def deserialize(cls, data: bytes) -> Model:
@@ -1822,8 +2339,9 @@ class Model:
 
         See `decode()` for full documentation.
         """
+        ...
 
-    def __eq__(self, other: Model, /) -> bool:  # type: ignore
+    def __eq__(self, other: Model, /) -> bool:
         """
         Check whether this model is equal to `other`.
 
@@ -1835,18 +2353,32 @@ class Model:
         -------
         bool
         """
+        ...
 
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
     def __hash__(self, /) -> int: ...
+    metadata: ModelMetadata | None = ...
+
+    @staticmethod
+    def load_luna(model_id: str, client: (ILunaSolve | str | None) = None) -> Model: ...
+    def save_luna(self, client: (ILunaSolve | str | None) = None) -> None: ...
+    def delete_luna(self, client: (ILunaSolve | str | None) = None) -> None: ...
+    def load_solutions(
+        self, client: (ILunaSolve | str | None) = None
+    ) -> list[Solution]: ...
+    def load_solve_jobs(
+        self, client: (ILunaSolve | str | None) = None
+    ) -> list[SolveJob]: ...
 
-# _expression.pyi
 class Expression:
     """
-    Polynomial expression supporting symbolic arithmetic, constraint creation, and encoding.
+    Polynomial expression supporting symbolic arithmetic, constraint creation.
 
-    An `Expression` represents a real-valued mathematical function composed of variables,
-    scalars, and coefficients. Expressions may include constant, linear, quadratic, and
-    higher-order terms (cubic and beyond). They are used to build objective functions
-    and constraints in symbolic optimization models.
+    An `Expression` represents a real-valued mathematical function composed of
+    variables, scalars, and coefficients. Expressions may include constant, linear,
+    quadratic, and higher-order terms (cubic and beyond). They are used to build
+    objective functions and constraints in symbolic optimization models.
 
     Expressions support both regular and in-place arithmetic, including addition and
     multiplication with integers, floats, `Variable` instances, and other `Expression`s.
@@ -1936,20 +2468,21 @@ class Expression:
     def __init__(self, /) -> None: ...
     @overload
     def __init__(self, /, env: Environment) -> None: ...
-    def __init__(self, /, env: Environment | None = ...) -> None:
+    def __init__(self, /, env: (Environment | None) = ...) -> None:
         """
-         Create a new empty expression scoped to an environment.
+        Create a new empty expression scoped to an environment.
 
         Parameters
         ----------
-         env : Environment
-             The environment to which this expression is bound.
+        env : Environment
+            The environment to which this expression is bound.
 
         Raises
         ------
-         NoActiveEnvironmentFoundError
-             If no environment is provided and none is active in the context.
+        NoActiveEnvironmentFoundError
+            If no environment is provided and none is active in the context.
         """
+        ...
 
     def get_offset(self, /) -> float:
         """
@@ -1960,6 +2493,7 @@ class Expression:
         float
             The constant term.
         """
+        ...
 
     def get_linear(self, /, variable: Variable) -> float:
         """
@@ -1980,6 +2514,7 @@ class Expression:
         VariableOutOfRangeError
             If the variable index is not valid in this expression's environment.
         """
+        ...
 
     def get_quadratic(self, /, u: Variable, v: Variable) -> float:
         """
@@ -2000,6 +2535,7 @@ class Expression:
         VariableOutOfRangeError
             If either variable is out of bounds for the expression's environment.
         """
+        ...
 
     def get_higher_order(self, /, variables: tuple[Variable, ...]) -> float:
         """
@@ -2020,6 +2556,21 @@ class Expression:
         VariableOutOfRangeError
             If any variable is out of bounds for the environment.
         """
+        ...
+
+    def items(self, /) -> ExpressionIterator:
+        """
+        Iterate over the single components of an expression.
+
+        An *component* refers to
+        a single constant, linear, quadratic, or higher-order term of an expression.
+
+        Returns
+        -------
+        ExpressionIterator
+            The iterator over the expression's components.
+        """
+        ...
 
     @property
     def num_variables(self, /) -> int:
@@ -2031,6 +2582,7 @@ class Expression:
         int
             Number of variables with non-zero coefficients.
         """
+        ...
 
     def is_equal(self, /, other: Expression) -> bool:
         """
@@ -2046,6 +2598,37 @@ class Expression:
         bool
             If the two expressions are equal.
         """
+        ...
+
+    def substitute(
+        self, /, target: Variable, replacement: (Expression | Variable)
+    ) -> Expression:
+        """
+        Substitute every occurrence of a variable with another expression.
+
+        Given an expression `self`, this method replaces all occurrences of `target`
+        with `replacement`. If the substitution would cross differing environments
+        (e.g. captures from two different scopes), it returns a `DifferentEnvsErr`.
+
+        Parameters
+        ----------
+        target : VarRef
+            The variable reference to replace.
+        replacement : Expression
+            The expression to insert in place of `target`.
+
+        Returns
+        -------
+        Expression
+            The resulting expression after substitution.
+
+        Raises
+        ------
+        DifferentEnvsErr
+            If the environments of `self`, `target` and `replacement`
+            are not compatible.
+        """
+        ...
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -2055,7 +2638,9 @@ class Expression:
     def encode(self, /, *, level: int) -> bytes: ...
     @overload
     def encode(self, /, compress: bool, level: int) -> bytes: ...
-    def encode(self, /, compress: bool | None = ..., level: int | None = ...) -> bytes:
+    def encode(
+        self, /, compress: (bool | None) = True, level: (int | None) = 3
+    ) -> bytes:
         """
         Serialize the expression into a compact binary format.
 
@@ -2064,7 +2649,7 @@ class Expression:
         compress : bool, optional
             Whether to compress the data. Default is True.
         level : int, optional
-            Compression level (0–9). Default is 3.
+            Compression level (0-9). Default is 3.
 
         Returns
         -------
@@ -2076,6 +2661,7 @@ class Expression:
         IOError
             If serialization fails.
         """
+        ...
 
     @overload
     def serialize(self, /) -> bytes: ...
@@ -2086,13 +2672,14 @@ class Expression:
     @overload
     def serialize(self, /, compress: bool, level: int) -> bytes: ...
     def serialize(
-        self, /, compress: bool | None = ..., level: int | None = ...
+        self, /, compress: (bool | None) = ..., level: (int | None) = ...
     ) -> bytes:
         """
         Alias for `encode()`.
 
         See `encode()` for full documentation.
         """
+        ...
 
     @classmethod
     def decode(cls, data: bytes) -> Expression:
@@ -2114,6 +2701,7 @@ class Expression:
         DecodeError
             If decoding fails due to corruption or incompatibility.
         """
+        ...
 
     @classmethod
     def deserialize(cls, data: bytes) -> Expression:
@@ -2122,6 +2710,7 @@ class Expression:
 
         See `decode()` for full documentation.
         """
+        ...
 
     @overload
     def __add__(self, other: Expression, /) -> Expression: ...
@@ -2131,7 +2720,7 @@ class Expression:
     def __add__(self, other: int, /) -> Expression: ...
     @overload
     def __add__(self, other: float, /) -> Expression: ...
-    def __add__(self, other: Expression | Variable | float, /) -> Expression:
+    def __add__(self, other: (Expression | Variable | int | float), /) -> Expression:
         """
         Add another expression, variable, or scalar.
 
@@ -2150,6 +2739,7 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __radd__(self, other: Expression, /) -> Expression: ...
@@ -2159,7 +2749,7 @@ class Expression:
     def __radd__(self, other: int, /) -> Expression: ...
     @overload
     def __radd__(self, other: float, /) -> Expression: ...
-    def __radd__(self, other: Expression | Variable | float, /) -> Expression:
+    def __radd__(self, other: (Expression | Variable | int | float), /) -> Expression:
         """
         Add this expression to a scalar or variable.
 
@@ -2176,16 +2766,17 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
-    def __iadd__(self, other: Expression, /): ...
+    def __iadd__(self, other: Expression, /) -> Self: ...
     @overload
-    def __iadd__(self, other: Variable, /): ...
+    def __iadd__(self, other: Variable, /) -> Self: ...
     @overload
-    def __iadd__(self, other: int, /): ...
+    def __iadd__(self, other: int, /) -> Self: ...
     @overload
-    def __iadd__(self, other: float, /): ...
-    def __iadd__(self, other: Expression | Variable | float, /) -> Expression:
+    def __iadd__(self, other: float, /) -> Self: ...
+    def __iadd__(self, other: (Expression | Variable | int | float), /) -> Self:
         """
         In-place addition.
 
@@ -2195,7 +2786,7 @@ class Expression:
 
         Returns
         -------
-        Expression
+        Self
 
         Raises
         ------
@@ -2204,16 +2795,17 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
-    def __isub__(self, other: Expression, /): ...
+    def __isub__(self, other: Expression, /) -> Self: ...
     @overload
-    def __isub__(self, other: Variable, /): ...
+    def __isub__(self, other: Variable, /) -> Self: ...
     @overload
-    def __isub__(self, other: int, /): ...
+    def __isub__(self, other: int, /) -> Self: ...
     @overload
-    def __isub__(self, other: float, /): ...
-    def __isub__(self, other: Expression | Variable | float, /):
+    def __isub__(self, other: float, /) -> Self: ...
+    def __isub__(self, other: (Expression | Variable | int | float), /) -> Self:
         """
         In-place subtraction.
 
@@ -2223,7 +2815,7 @@ class Expression:
 
         Returns
         -------
-        Expression
+        Self
 
         Raises
         ------
@@ -2232,6 +2824,7 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __sub__(self, other: Expression, /) -> Expression: ...
@@ -2241,7 +2834,7 @@ class Expression:
     def __sub__(self, other: int, /) -> Expression: ...
     @overload
     def __sub__(self, other: float, /) -> Expression: ...
-    def __sub__(self, other: Expression | Variable | float, /) -> Expression:
+    def __sub__(self, other: (Expression | Variable | int | float), /) -> Expression:
         """
         Subtract another expression, variable, or scalar.
 
@@ -2260,6 +2853,7 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __mul__(self, other: Expression, /) -> Expression: ...
@@ -2269,7 +2863,7 @@ class Expression:
     def __mul__(self, other: int, /) -> Expression: ...
     @overload
     def __mul__(self, other: float, /) -> Expression: ...
-    def __mul__(self, other: Expression | Variable | float, /) -> Expression:
+    def __mul__(self, other: (Expression | Variable | int | float), /) -> Expression:
         """
         Multiply this expression by another value.
 
@@ -2288,12 +2882,13 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
     def __rmul__(self, other: int, /) -> Expression: ...
     @overload
     def __rmul__(self, other: float, /) -> Expression: ...
-    def __rmul__(self, other: float, /) -> Expression:
+    def __rmul__(self, other: (int | float), /) -> Expression:
         """
         Right-hand multiplication.
 
@@ -2310,16 +2905,17 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     @overload
-    def __imul__(self, other: Expression, /): ...
+    def __imul__(self, other: Expression, /) -> Self: ...
     @overload
-    def __imul__(self, other: Variable, /): ...
+    def __imul__(self, other: Variable, /) -> Self: ...
     @overload
-    def __imul__(self, other: int, /): ...
+    def __imul__(self, other: int, /) -> Self: ...
     @overload
-    def __imul__(self, other: float, /): ...
-    def __imul__(self, other: Expression | Variable | float, /):
+    def __imul__(self, other: float, /) -> Self: ...
+    def __imul__(self, other: (Expression | Variable | int | float), /) -> Self:
         """
         In-place multiplication.
 
@@ -2329,7 +2925,7 @@ class Expression:
 
         Returns
         -------
-        Expression
+        Self
 
         Raises
         ------
@@ -2338,6 +2934,7 @@ class Expression:
         TypeError
             If the operand type is unsupported.
         """
+        ...
 
     def __pow__(self, other: int, /) -> Expression:
         """
@@ -2356,18 +2953,19 @@ class Expression:
         RuntimeError
             If the param `modulo` usually supported for `__pow__` is specified.
         """
+        ...
 
     @overload
     def __eq__(self, rhs: Expression, /) -> Constraint: ...
     @overload
     def __eq__(self, rhs: Variable, /) -> Constraint: ...
     @overload
-    def __eq__(self, rhs: int, /) -> Constraint: ...  # type: ignore
+    def __eq__(self, rhs: int, /) -> Constraint: ...
     @overload
-    def __eq__(self, rhs: float, /) -> Constraint: ...  # type: ignore
-    def __eq__(self, rhs: Expression | Variable | float, /) -> Constraint:  # type: ignore
+    def __eq__(self, rhs: float, /) -> Constraint: ...
+    def __eq__(self, rhs: (Expression | Variable | int | float), /) -> Constraint:
         """
-        Compare to a different expression or create a constraint `expression == scalar`
+        Compare to a different expression or create a constraint `expression == scalar`.
 
         If `rhs` is of type `Variable` or `Expression` it is moved to the `lhs` in the
         constraint, resulting in the following constraint:
@@ -2387,6 +2985,7 @@ class Expression:
         TypeError
             If the right-hand side is not an Expression or scalar.
         """
+        ...
 
     @overload
     def __le__(self, rhs: Expression, /) -> Constraint: ...
@@ -2396,7 +2995,7 @@ class Expression:
     def __le__(self, rhs: int, /) -> Constraint: ...
     @overload
     def __le__(self, rhs: float, /) -> Constraint: ...
-    def __le__(self, rhs: Expression | Variable | float, /) -> Constraint:
+    def __le__(self, rhs: (Expression | Variable | int | float), /) -> Constraint:
         """
         Create a constraint `expression <= scalar`.
 
@@ -2418,6 +3017,7 @@ class Expression:
         TypeError
             If the right-hand side is not of type float, int, Variable or Expression.
         """
+        ...
 
     @overload
     def __ge__(self, rhs: Expression, /) -> Constraint: ...
@@ -2427,7 +3027,7 @@ class Expression:
     def __ge__(self, rhs: int, /) -> Constraint: ...
     @overload
     def __ge__(self, rhs: float, /) -> Constraint: ...
-    def __ge__(self, rhs: Expression | Variable | float, /) -> Constraint:
+    def __ge__(self, rhs: (Expression | Variable | int | float), /) -> Constraint:
         """
         Create a constraint: expression >= scalar.
 
@@ -2449,6 +3049,7 @@ class Expression:
         TypeError
             If the right-hand side is not of type float, int, Variable or Expression.
         """
+        ...
 
     def __neg__(self, /) -> Expression:
         """
@@ -2458,14 +3059,43 @@ class Expression:
         -------
         Expression
         """
+        ...
+
+    @property
+    def _environment(self, /) -> Environment:
+        """Get this expression's environment."""
+        ...
+
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
+
+class ExpressionIterator:
+    """
+    Iterate over the single components of an expression.
+
+    Examples
+    --------
+    >>> from luna_quantum import Constant, Expression, HigherOrder, Linear, Quadratic
+    >>> expr: Expression = ...
+    >>> vars: Constant | Linear | Quadratic | HigherOrder
+    >>> bias: float
+    >>> for vars, bias in expr.items():
+    >>> match vars:
+    >>>     case Constant(): do_something_with_constant(bias)
+    >>>     case Linear(x): do_something_with_linear_var(x, bias)
+    >>>     case Quadratic(x, y): do_something_with_quadratic_vars(x, y, bias)
+    >>>     case HigherOrder(ho): do_something_with_higher_order_vars(ho, bias)
+    """
+
+    def __next__(self) -> tuple[Constant | Linear | Quadratic | HigherOrder, float]: ...
+    def __iter__(self) -> ExpressionIterator: ...
 
-# _environment.pyi
 class Environment:
     """
     Execution context for variable creation and expression scoping.
 
-    An `Environment` provides the symbolic scope in which `Variable` objects are defined.
-    It is required for variable construction, and ensures consistency across expressions.
+    An `Environment` provides the symbolic scope in which `Variable`s are defined.
+    It is required for constructing variables ensuring consistency across expressions.
     The environment does **not** store constraints or expressions — it only facilitates
     their creation by acting as a context manager and anchor for `Variable` instances.
 
@@ -2489,7 +3119,8 @@ class Environment:
     Notes
     -----
     - The environment is required to create `Variable` instances.
-    - It does **not** own constraints or expressions — they merely reference variables tied to an environment.
+    - It does **not** own constraints or expressions — they merely reference variables
+      tied to an environment.
     - Environments **cannot be nested**. Only one can be active at a time.
     - Use `encode()` / `decode()` to persist and recover expression trees.
     """
@@ -2500,8 +3131,9 @@ class Environment:
 
         It is recommended to use this in a `with` statement to ensure proper scoping.
         """
+        ...
 
-    def __enter__(self, /) -> Any:
+    def __enter__(self, /) -> Self:
         """
         Activate this environment for variable creation.
 
@@ -2515,13 +3147,21 @@ class Environment:
         MultipleActiveEnvironmentsError
             If another environment is already active.
         """
+        ...
 
-    def __exit__(self, /, exc_type, exc_value, exc_traceback) -> None:
+    def __exit__(
+        self,
+        /,
+        exc_type: (type[BaseException] | None) = ...,
+        exc_value: (BaseException | None) = ...,
+        exc_traceback: (TracebackType | None) = ...,
+    ) -> None:
         """
         Deactivate this environment.
 
         Called automatically at the end of a `with` block.
         """
+        ...
 
     def get_variable(self, /, name: str) -> Variable:
         """
@@ -2542,6 +3182,7 @@ class Environment:
         VariableNotExistingError
             If no variable with the specified name is registered.
         """
+        ...
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -2551,7 +3192,9 @@ class Environment:
     def encode(self, /, *, level: int) -> bytes: ...
     @overload
     def encode(self, /, compress: bool, level: int) -> bytes: ...
-    def encode(self, /, compress: bool | None = ..., level: int | None = ...) -> bytes:
+    def encode(
+        self, /, compress: (bool | None) = True, level: (int | None) = 3
+    ) -> bytes:
         """
         Serialize the environment into a compact binary format.
 
@@ -2574,6 +3217,7 @@ class Environment:
         IOError
             If serialization fails.
         """
+        ...
 
     @overload
     def serialize(self, /) -> bytes: ...
@@ -2584,13 +3228,14 @@ class Environment:
     @overload
     def serialize(self, /, compress: bool, level: int) -> bytes: ...
     def serialize(
-        self, /, compress: bool | None = ..., level: int | None = ...
+        self, /, compress: (bool | None) = ..., level: (int | None) = ...
     ) -> bytes:
         """
         Alias for `encode()`.
 
         See `encode()` for full usage details.
         """
+        ...
 
     @classmethod
     def decode(cls, data: bytes) -> Environment:
@@ -2612,6 +3257,7 @@ class Environment:
         DecodeError
             If decoding fails due to corruption or incompatibility.
         """
+        ...
 
     @classmethod
     def deserialize(cls, data: bytes) -> Environment:
@@ -2620,10 +3266,12 @@ class Environment:
 
         See `decode()` for full usage details.
         """
+        ...
 
-    def __eq__(self, other: Environment, /) -> bool: ...  # type: ignore
+    def __eq__(self, other: Environment, /) -> bool: ...
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
 
-# _constraints.pyi
 class Comparator(Enum):
     """
     Comparison operators used to define constraints.
@@ -2649,13 +3297,14 @@ class Comparator(Enum):
 
     Eq = ...
     """Equality (==)"""
-
     Le = ...
     """Less-than or equal (<=)"""
-
     Ge = ...
     """Greater-than or equal (>=)"""
 
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
+
 class Constraint:
     """
     A symbolic constraint formed by comparing an expression to a constant.
@@ -2754,8 +3403,8 @@ class Constraint:
     def __init__(
         self,
         /,
-        lhs: Variable | Expression,
-        rhs: float | Expression | Variable,
+        lhs: (Variable | Expression),
+        rhs: (int | float | Expression | Variable),
         comparator: Comparator,
         name: str,
     ) -> None:
@@ -2780,6 +3429,7 @@ class Constraint:
         IllegalConstraintNameError
             If the constraint is tried to be created with an illegal name.
         """
+        ...
 
     @property
     def name(self, /) -> str | None:
@@ -2791,41 +3441,47 @@ class Constraint:
         str, optional
             Returns the name of the constraint as a string or None if it is unnamed.
         """
+        ...
 
     @property
     def lhs(self, /) -> Expression:
         """
-        Get the left-hand side of the constraint
+        Get the left-hand side of the constraint.
 
         Returns
         -------
         Expression
             The left-hand side expression.
         """
+        ...
 
     @property
     def rhs(self, /) -> float:
         """
-        Get the right-hand side of the constraint
+        Get the right-hand side of the constraint.
 
         Returns
         -------
         float
             The right-hand side expression.
         """
+        ...
 
     @property
     def comparator(self, /) -> Comparator:
         """
-        Get the comparator of the constraint
+        Get the comparator of the constraint.
 
         Returns
         -------
         Comparator
             The comparator of the constraint.
         """
+        ...
 
-    def __eq__(self, other: Constraint, /) -> bool: ...  # type: ignore
+    def __eq__(self, other: Constraint, /) -> bool: ...
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
 
 class Constraints:
     """
@@ -2845,8 +3501,6 @@ class Constraints:
     ...     c = Constraint(x + 1, 0.0, Comparator.Le)
 
     >>> cs = Constraints()
-    >>> cs.add_constraint(c)
-
     >>> cs += x >= 1.0
 
     Serialization:
@@ -2862,21 +3516,12 @@ class Constraints:
 
     def __init__(self, /) -> None: ...
     @overload
-    def add_constraint(self, /, constraint: Constraint):
-        """
-        Add a constraint to the collection.
-
-        Parameters
-        ----------
-        constraint : Constraint
-            The constraint to be added.
-        name : str, optional
-            The name of the constraint to be added.
-        """
-
+    def add_constraint(self, /, constraint: Constraint) -> None: ...
     @overload
-    def add_constraint(self, /, constraint: Constraint, name: str): ...
-    def add_constraint(self, /, constraint: Constraint, name: str | None = ...):
+    def add_constraint(self, /, constraint: Constraint, name: str) -> None: ...
+    def add_constraint(
+        self, /, constraint: Constraint, name: (str | None) = ...
+    ) -> None:
         """
         Add a constraint to the collection.
 
@@ -2887,6 +3532,7 @@ class Constraints:
         name : str, optional
             The name of the constraint to be added.
         """
+        ...
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -2896,7 +3542,9 @@ class Constraints:
     def encode(self, /, *, level: int) -> bytes: ...
     @overload
     def encode(self, /, compress: bool, level: int) -> bytes: ...
-    def encode(self, /, compress: bool | None = ..., level: int | None = ...) -> bytes:
+    def encode(
+        self, /, compress: (bool | None) = True, level: (int | None) = 3
+    ) -> bytes:
         """
         Serialize the constraint collection to a binary blob.
 
@@ -2905,7 +3553,7 @@ class Constraints:
         compress : bool, optional
             Whether to compress the result. Default is True.
         level : int, optional
-            Compression level (0–9). Default is 3.
+            Compression level (0-9). Default is 3.
 
         Returns
         -------
@@ -2917,6 +3565,7 @@ class Constraints:
         IOError
             If serialization fails.
         """
+        ...
 
     @overload
     def serialize(self, /) -> bytes: ...
@@ -2927,13 +3576,14 @@ class Constraints:
     @overload
     def serialize(self, /, compress: bool, level: int) -> bytes: ...
     def serialize(
-        self, /, compress: bool | None = ..., level: int | None = ...
+        self, /, compress: (bool | None) = ..., level: (int | None) = ...
     ) -> bytes:
         """
         Alias for `encode()`.
 
         See `encode()` for details.
         """
+        ...
 
     @classmethod
     def decode(cls, data: bytes, env: Environment) -> Expression:
@@ -2955,6 +3605,7 @@ class Constraints:
         DecodeError
             If decoding fails due to corruption or incompatibility.
         """
+        ...
 
     @classmethod
     def deserialize(cls, data: bytes, env: Environment) -> Expression:
@@ -2963,12 +3614,13 @@ class Constraints:
 
         See `decode()` for usage.
         """
+        ...
 
     @overload
-    def __iadd__(self, constraint: Constraint, /): ...
+    def __iadd__(self, constraint: Constraint, /) -> Self: ...
     @overload
-    def __iadd__(self, constraint: tuple[Constraint, str], /): ...
-    def __iadd__(self, constraint: Constraint | tuple[Constraint, str], /):
+    def __iadd__(self, constraint: tuple[Constraint, str], /) -> Self: ...
+    def __iadd__(self, constraint: (Constraint | tuple[Constraint, str]), /) -> Self:
         """
         In-place constraint addition using `+=`.
 
@@ -2987,9 +3639,22 @@ class Constraints:
         TypeError
             If the value is not a `Constraint` or valid symbolic comparison.
         """
+        ...
 
-    def __eq__(self, other: Constraints, /) -> bool: ...  # type: ignore
+    def __eq__(self, other: Constraints, /) -> bool: ...
+    def __str__(self, /) -> str: ...
+    def __repr__(self, /) -> str: ...
     def __getitem__(self, item: int, /) -> Constraint: ...
+    def __len__(self, /) -> int:
+        """
+        Get the number of constraints.
+
+        Returns
+        -------
+        int
+            The number of constraints associated with this `Constraints` object.
+        """
+        ...
 
 __all__ = [
     "Bounds",