chore: Change class and decorators locations to match new layout

- In general, ai.timefold.solver.core.api.x and its subpackages ->
  timefold.solver.x.

- Exception for ai.timefold.solver.core.api.solver, which it and
  its subpackages -> timefold.solver.

- ai.timefold.solver.core.x and its subpackages -> timefold.solver.x
  (test and config).

- Use dynamic __all__ when not TYPE_CHECKING for score and domain,
  since they have some classes that require the JVM to be started
  When TYPE_CHECKING, there are stub classes that the TYPE_CHECKER
  will see.

- Remove `@incremental_score_calculator` decorator, since it been replaced
  by `IncrementalScoreCalculator` ABC.

- Create an empty Constraint stub so users can reference it in their type
  signatures without importing something from Java.

setup.py

@@ -98,9 +98,9 @@ def find_stub_files(stub_root: str):
         'License :: OSI Approved :: Apache Software License',
         'Operating System :: OS Independent'
     ],
-    packages=['timefold.solver', 'timefold.solver.api', 'timefold.solver.annotation',
-              'timefold.solver.config', 'timefold.solver.constraint', 'timefold.solver.score',
-              'timefold.solver.test', 'timefold.solver.valuerange',
+    packages=['timefold.solver', 'timefold.solver.domain',
+              'timefold.solver.config', 'timefold.solver.score',
+              'timefold.solver.test',
               'jpyinterpreter',
               'java-stubs', 'jpype-stubs', 'ai-stubs'],
     package_dir={

tests/test_collectors.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.score import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 
 from dataclasses import dataclass, field
 from typing import Annotated, List

tests/test_constraint_streams.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.score import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 
 import inspect
 import re

tests/test_constraint_verifier.py

@@ -1,9 +1,8 @@
 import pytest
 
-from timefold.solver.annotation import *
+from timefold.solver.domain import *
 from timefold.solver.score import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.test import *
 
 from typing import Annotated, List

tests/test_custom_shadow_variables.py

@@ -1,10 +1,9 @@
 from typing import Annotated, Optional, List
 from dataclasses import dataclass, field
 
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 

tests/test_domain.py

@@ -1,9 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
-from timefold.solver.valuerange import *
 
 from dataclasses import dataclass, field
 from typing import Annotated, Optional, List

tests/test_easy_score_calculator.py

@@ -1,5 +1,5 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
 from timefold.solver.score import *
 

tests/test_incremental_score_calculator.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
 from timefold.solver.score import *
-from timefold.solver.constraint import *
 
 import pytest
 from dataclasses import dataclass, field
@@ -315,7 +314,6 @@ def get_indictment_map(self):
 
 def test_error_message_for_missing_methods():
     with pytest.raises(TypeError):  # Exact error message from ABC changes between versions
-        @incremental_score_calculator
         class IncrementalScoreCalculatorMissingMethods(IncrementalScoreCalculator):
             def before_entity_added(self, entity):
                 pass

tests/test_inverse_relation.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
 from timefold.solver.score import *
-from timefold.solver.constraint import *
 
 from dataclasses import dataclass, field
 from typing import Annotated, List

tests/test_pinning.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
 from timefold.solver.score import *
-from timefold.solver.constraint import *
 
 from dataclasses import dataclass, field
 from typing import Annotated, List

tests/test_solution_manager.py

@@ -1,8 +1,7 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
 from timefold.solver.score import *
-from timefold.solver.constraint import *
 
 from dataclasses import dataclass, field
 from typing import Annotated, List

tests/test_solver_config.py

@@ -1,6 +1,5 @@
-from timefold.solver.annotation import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 import pathlib

tests/test_solver_configuration.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 from dataclasses import dataclass, field

tests/test_solver_events.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 from dataclasses import dataclass, field

tests/test_solver_factory.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 from dataclasses import dataclass, field

tests/test_solver_manager.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 import pytest

tests/test_solver_problem_change.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 from dataclasses import dataclass, field

tests/test_user_error.py

@@ -1,7 +1,6 @@
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import *
 from timefold.solver.score import *
 
 import pytest

tests/test_vehicle_routing.py

@@ -1,9 +1,8 @@
 from datetime import datetime, timedelta
 
-from timefold.solver.api import *
-from timefold.solver.annotation import *
+from timefold.solver import *
+from timefold.solver.domain import *
 from timefold.solver.config import *
-from timefold.solver.constraint import ConstraintFactory
 from timefold.solver.score import *
 
 from typing import Annotated, List, Optional

timefold-solver-python-core/src/main/python/__init__.py

@@ -7,16 +7,15 @@
 the JVM. If you want to pass custom arguments to the JVM,
 use init before decorators and any timefold.solver.types imports.
 """
-import timefold.solver.api as api
-import timefold.solver.annotation as annotation
+from ._problem_change import *
+from ._solution_manager import *
+from ._solver import *
+from ._solver_factory import *
+from ._solver_manager import *
+
+import timefold.solver.domain as domain
 import timefold.solver.config as config
-import timefold.solver.constraint as constraint
+import timefold.solver.score as score
 import timefold.solver.test as test
-import timefold.solver.valuerange as valuerange
 
 from ._timefold_java_interop import init, set_class_output_directory
-
-__all__ = [# Subpackages
-           'api', 'annotation', 'config', 'constraint', 'test', 'valuerange',
-           # Setup Functions
-           'init', 'set_class_output_directory']

timefold-solver-python-core/src/main/python/api/_future.py → timefold-solver-python-core/src/main/python/_future.py

@@ -1,4 +1,4 @@
-from .._jpype_type_conversions import PythonBiFunction
+from ._jpype_type_conversions import PythonBiFunction
 from typing import Awaitable, TypeVar, TYPE_CHECKING
 from asyncio import Future, get_event_loop, CancelledError
 

timefold-solver-python-core/src/main/python/api/_problem_change.py → timefold-solver-python-core/src/main/python/_problem_change.py

@@ -1,5 +1,3 @@
-from .._timefold_java_interop import get_class
-
 from abc import ABC, abstractmethod
 from typing import TypeVar, Optional, Callable, TYPE_CHECKING, Generic
 from types import FunctionType
@@ -8,13 +6,13 @@
                             update_python_object_from_java,
                             translate_python_bytecode_to_java_bytecode)
 from jpype import JOverride, JImplements
-from traceback import print_exc
 
 if TYPE_CHECKING:
     from ai.timefold.solver.core.api.solver.change import (ProblemChangeDirector as _ProblemChangeDirector)
 
 Solution_ = TypeVar('Solution_')
 
+
 class ProblemChangeDirector:
     _delegate: '_ProblemChangeDirector'
     _java_solution: Solution_

timefold-solver-python-core/src/main/python/_solution_manager.py

@@ -0,0 +1,55 @@
+from ._solver_factory import SolverFactory
+from ._solver_manager import SolverManager
+from .score import ScoreAnalysis, ScoreExplanation
+
+from typing import TypeVar, Generic, TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # These imports require a JVM to be running, so only import if type checking
+    from .score import Score
+    from ai.timefold.solver.core.api.solver import SolutionManager as _JavaSolutionManager
+
+Solution_ = TypeVar('Solution_')
+ProblemId_ = TypeVar('ProblemId_')
+Score_ = TypeVar('Score_', bound='Score')
+Justification_ = TypeVar('Justification_', bound='ConstraintJustification')
+
+
+class SolutionManager(Generic[Solution_]):
+    _delegate: '_JavaSolutionManager'
+
+    def __init__(self, delegate: '_JavaSolutionManager'):
+        self._delegate = delegate
+
+    @staticmethod
+    def create(solver_factory: SolverFactory[Solution_] | SolverManager[Solution_, Any]) -> \
+            'SolutionManager[Solution_]':
+        from ai.timefold.solver.core.api.solver import SolutionManager as JavaSolutionManager
+        return SolutionManager(JavaSolutionManager.create(solver_factory._delegate))
+
+    def update(self, solution: Solution_, solution_update_policy=None) -> 'Score':
+        #  TODO handle solution_update_policy
+        from jpyinterpreter import convert_to_java_python_like_object, update_python_object_from_java
+        java_solution = convert_to_java_python_like_object(solution)
+        out = self._delegate.update(java_solution)
+        update_python_object_from_java(java_solution)
+        return out
+
+    def analyze(self, solution: Solution_, score_analysis_fetch_policy=None, solution_update_policy=None) \
+            -> 'ScoreAnalysis':
+        #  TODO handle policies
+        from jpyinterpreter import convert_to_java_python_like_object
+        return ScoreAnalysis(self._delegate.analyze(convert_to_java_python_like_object(solution)))
+
+    def explain(self, solution: Solution_, solution_update_policy=None) -> 'ScoreExplanation':
+        #  TODO handle policies
+        from jpyinterpreter import convert_to_java_python_like_object
+        return ScoreExplanation(self._delegate.explain(convert_to_java_python_like_object(solution)))
+
+    def recommend_fit(self, solution: Solution_, entity_or_element, proposition_function,
+                      score_analysis_fetch_policy=None):
+        #  TODO
+        raise NotImplementedError
+
+
+__all__ = ['SolutionManager']

timefold-solver-python-core/src/main/python/api/_solver.py → timefold-solver-python-core/src/main/python/_solver.py

@@ -6,7 +6,7 @@
 
 if TYPE_CHECKING:
     # These imports require a JVM to be running, so only import if type checking
-    from ..score import Score
+    from .score import Score
     from ai.timefold.solver.core.api.solver import Solver as _JavaSolver
 
 Solution_ = TypeVar('Solution_')

timefold-solver-python-core/src/main/python/api/_solver_factory.py → timefold-solver-python-core/src/main/python/_solver_factory.py

@@ -1,5 +1,5 @@
 from ._solver import Solver
-from ..config import SolverConfig, SolverConfigOverride
+from .config import SolverConfig, SolverConfigOverride
 
 from typing import TypeVar, Generic, TYPE_CHECKING
 from jpype import JClass

timefold-solver-python-core/src/main/python/api/_solver_manager.py → timefold-solver-python-core/src/main/python/_solver_manager.py

@@ -1,5 +1,5 @@
 from ._problem_change import ProblemChange, ProblemChangeWrapper
-from ..config import SolverConfigOverride
+from .config import SolverConfigOverride
 from ._solver_factory import SolverFactory
 from ._future import wrap_completable_future
 

timefold-solver-python-core/src/main/python/_timefold_java_interop.py

@@ -11,8 +11,6 @@
     from java.lang import ClassLoader
     from ai.timefold.solver.core.api.score.stream import (Constraint as _Constraint,
                                                           ConstraintFactory as _ConstraintFactory)
-    from ai.timefold.solver.core.api.score.calculator import IncrementalScoreCalculator as _IncrementalScoreCalculator
-    from ai.timefold.solver.core.api.domain.variable import VariableListener as _VariableListener
 
 Solution_ = TypeVar('Solution_')
 ProblemId_ = TypeVar('ProblemId_')