`nexuml.core.discovery`¶

nexuml.core.discovery ¶

Core discovery module with decorator-based registration and scanning.

Provides decorators (@layer, @data_source, @scenario, @eval_algorithm) that attach metadata to objects, and a Scanner that collects decorated objects from imported modules. Supports entry-point and local-root discovery.

DiscoveredItem ¶

Metadata for a decorated discovery item.

DiscoveryError ¶

A failure encountered while importing or registering a discovery item.

Collected instead of raised so that one broken module cannot hide every other scenario/layer/dataset/eval algorithm in the registry.

short ¶

short() -> str

One-line, human-readable summary for tables/log lines.

Returns:

Type	Description
`str`	Compact `module (key): error_type: message` string.

Scanner ¶

Collects decorated objects from imported modules.

errors `property` ¶

errors: list[DiscoveryError]

Import/walk failures collected during scanning.

scan_module ¶

scan_module(module: Any) -> list[DiscoveredItem]

Scan a single already-imported module for decorated objects.

Returns:

Type	Description
`list[DiscoveredItem]`	Newly discovered items found in module.

scan_package ¶

scan_package(package_path: str) -> list[DiscoveredItem]

Import a package (if possible) and recursively scan its modules.

Resilient by design: a module that fails to import (SyntaxError, NameError, validation errors at import time, etc.) is recorded as a :class:DiscoveryError and skipped, so the remaining modules in the package are still discovered. Inspect :attr:errors afterwards to see what was skipped and why.

Returns:

Type	Description
`list[DiscoveredItem]`	Newly discovered items across all modules in the package.

scan_packages ¶

scan_packages(
    package_paths: list[str],
) -> list[DiscoveredItem]

Scan multiple package paths.

Returns:

Type	Description
`list[DiscoveredItem]`	Combined list of discovered items from all packages.

LibraryConfig ¶

User-level configuration for local library roots.

layer ¶

layer(
    key: str, *, version: str = "1"
) -> Callable[[type[DefinitionT]], type[DefinitionT]]

Register a typed layer definition under a stable persisted identity.

Returns:

Type	Description
`Callable[[type[DefinitionT]], type[DefinitionT]]`	Definition class decorator.

data_source ¶

data_source(
    key: str, *, version: str = "1"
) -> Callable[[type[DefinitionT]], type[DefinitionT]]

Register a typed data-source definition.

Returns:

Type	Description
`Callable[[type[DefinitionT]], type[DefinitionT]]`	Definition class decorator.

scenario ¶

scenario(key: str) -> Callable[[Any], Any]

Decorator to register a scenario function.

Returns:

Type	Description
`Callable[[Any], Any]`	Decorator that attaches discovery metadata to fn.

eval_algorithm ¶

eval_algorithm(
    key: str, *, version: str = "1"
) -> Callable[[type[DefinitionT]], type[DefinitionT]]

Register a typed evaluation-algorithm definition.

Returns:

Type	Description
`Callable[[type[DefinitionT]], type[DefinitionT]]`	Definition class decorator.

loader_backend ¶

loader_backend(
    key: str, *, version: str = "1"
) -> Callable[[type[DefinitionT]], type[DefinitionT]]

Register a typed loader-backend definition.

Returns:

Type	Description
`Callable[[type[DefinitionT]], type[DefinitionT]]`	Definition class decorator.

discover_entry_point_packages ¶

discover_entry_point_packages(
    group: str = "nexuml.libraries",
) -> list[str]

Return package names advertised via importlib.metadata entry points.

discover_local_packages ¶

discover_local_packages(
    config: LibraryConfig | None = None,
) -> list[str]

Discover all importable package paths under configured local roots.

Returns:

Type	Description
`list[str]`	Dotted package path strings discovered under all configured roots.

discover_library_packages ¶

discover_library_packages(
    include_entry_points: bool = True,
    include_local_roots: bool = True,
) -> list[str]

Return package paths from installed entry points and configured roots.

register_items ¶

register_items(
    items: list[DiscoveredItem],
    register: Callable[[str, Any], None],
    errors: list[DiscoveryError],
) -> None

Register each discovered item, collecting (not raising) failures.

Mirrors the resilience of :meth:Scanner.scan_package: a single key conflict or bad item must not wipe out every other item in the registry. Appends a :class:DiscoveryError (phase="register") for each failure.

scan_all ¶

scan_all(
    extra_package_paths: list[str] | None = None,
    include_entry_points: bool = True,
    include_local_roots: bool = True,
) -> Scanner

Scan built-in packages, entry points, and local roots for decorated items.

No persistent object cache is used; this always performs fresh imports.

Returns:

Type	Description
`Scanner`	Scanner populated with all discovered items.

nexuml.core.discovery¶