Canonical Imports

Cross-layer

saealib is still pre-1.0, so public APIs may evolve before the first stable release. Within that constraint, use these four layers when choosing an import path:

1. Root convenience API

Use the root package for common, user-facing entry points and convenience examples:

from saealib import minimize, Problem, GA

Root exports are intended to make the common path easy. An existing root import is preserved as part of the root compatibility surface, but a name being available elsewhere does not automatically make it a root export.

2. Domain namespaces

Use public namespaces when an object belongs to a particular domain. Examples include saealib.surrogate, saealib.acquisition, and saealib.operators:

from saealib.surrogate import RBFSurrogate
from saealib.acquisition import MeanPrediction
from saealib.operators import MutationPolynomial

Import SearchSpace, execution, and Feedback names from the public namespaces saealib.space, saealib.execution, and saealib.policies, respectively.

Other public domain namespaces follow the same rule. Prefer the namespace export over a deeper module path when both are available.

3. Framework and runtime extension APIs

Use saealib.core as the framework extension facade for contracts and composition primitives:

from saealib.core import (
    AssumptionSet,
    Component,
    ComponentContract,
    ComponentGraph,
    DataSpec,
    ExecutionContract,
    LifecycleContract,
    PartSpec,
    PortContract,
    PortSpec,
    StateContract,
)

The facade contains the contract vocabulary needed for an ordinary custom component. More specialized contract descriptors remain under saealib.core.contracts. saealib.core.contracts is a public specialized submodule, not a compatibility-only path; treat it as an advanced API when the saealib.core facade does not expose the descriptor you need.

Use saealib.execution for runtime extension points. The canonical provider-author surface consists of RuntimeRegistry, RuntimeRegistration, and create_runtime:

from saealib.execution import (
    RuntimeRegistration,
    RuntimeRegistry,
    create_runtime,
)

RuntimeFactory and default_runtime_registry remain beta compatibility and advanced customization hooks. They are available from saealib.execution, but are distinct from the canonical three-name provider-author surface. The deeper saealib.execution.runtime module is an implementation path, not a canonical import path.

Asynchronous provider boundaries report nonblocking poll progress explicitly:

from saealib.execution import PollResult

return PollResult(state=state, progressed=False)

These facades are the supported starting points for framework and runtime extensions. Their detailed behavior may still change while saealib remains pre-1.0.

4. Deep implementation paths

Paths below the public facades, such as saealib.core.compiler.compiler, are deep implementation paths. They are non-canonical and have no compatibility guarantee; do not use them as the basis for application imports or extension documentation.