vamos-optimization 1.0.0__py3-none-any.whl

vamos/__init__.py

@@ -0,0 +1,99 @@
+"""
+VAMOS package facade.
+
+Import most features from the dedicated facades:
+- `vamos.api` for core optimization entrypoints.
+- `vamos.algorithms` for algorithm configs and registry helpers.
+- `vamos.problems` for curated benchmark/real-world problem classes.
+- `vamos.ux.api` for analysis/visualization helpers.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from vamos.api import (
+    CompatibilityReport,
+    EnvironmentalSelectionResult,
+    IncompleteRunMetadataError,
+    LoadLimits,
+    OptimizationResult,
+    Problem,
+    ReplayReport,
+    RunManifest,
+    StoredRun,
+    Study,
+    StudyLoadLimits,
+    StudyPlanReport,
+    StudyReport,
+    StudyResult,
+    StudySpec,
+    StudySummary,
+    VerificationReport,
+    available_problem_names,
+    configure_logging,
+    create_study,
+    load_result,
+    load_run,
+    load_study,
+    make_problem,
+    make_problem_selection,
+    optimize,
+    plan_study,
+    reproduce,
+    run_self_check,
+    save_result,
+    select_survivors,
+    verify_run,
+)
+from vamos.foundation.version import get_version as _get_version
+
+__all__ = [
+    "__version__",
+    # Optimization
+    "optimize",
+    "select_survivors",
+    "EnvironmentalSelectionResult",
+    "Problem",
+    "make_problem",
+    "OptimizationResult",
+    "StudyResult",
+    "configure_logging",
+    "available_problem_names",
+    "make_problem_selection",
+    "run_self_check",
+    "save_result",
+    "load_run",
+    "load_result",
+    "StoredRun",
+    "RunManifest",
+    "LoadLimits",
+    "IncompleteRunMetadataError",
+    "CompatibilityReport",
+    "ReplayReport",
+    "VerificationReport",
+    "verify_run",
+    "reproduce",
+    "StudySpec",
+    "Study",
+    "StudyLoadLimits",
+    "StudyPlanReport",
+    "StudyReport",
+    "StudySummary",
+    "create_study",
+    "load_study",
+    "plan_study",
+    "problems",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name == "__version__":
+        return _get_version()
+    if name == "problems":
+        return importlib.import_module(".problems", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(__all__) | set(globals()))

vamos/algorithms.py

@@ -0,0 +1,145 @@
+"""
+Algorithm facade: configuration builders and registry helpers.
+
+Use this module for algorithm config objects and discovery helpers.
+For running optimizations, use `vamos.api` or `vamos.optimize`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from vamos.engine.algorithm.config import (
+    AGEMOEAConfig,
+    GenericAlgorithmConfig,
+    IBEAConfig,
+    MOEADConfig,
+    NSGAIIConfig,
+    NSGAIIIConfig,
+    ProbabilityExpression,
+    ProbabilityValue,
+    RVEAConfig,
+    SMPSOConfig,
+    SMSEMOAConfig,
+    SPEA2Config,
+)
+from vamos.engine.variation.helpers import (
+    BINARY_CROSSOVER,
+    BINARY_MUTATION,
+    INT_CROSSOVER,
+    INT_MUTATION,
+    MIXED_CROSSOVER,
+    MIXED_MUTATION,
+    PERM_CROSSOVER,
+    PERM_MUTATION,
+    REAL_CROSSOVER,
+    REAL_MUTATION,
+)
+from vamos.foundation.encoding import normalize_encoding
+
+if TYPE_CHECKING:
+    from vamos.engine.algorithm.registry import AlgorithmBuilder
+
+
+def available_algorithms() -> tuple[str, ...]:
+    """Return the canonical algorithm identifiers supported by the engine."""
+    from vamos.engine.algorithm.registry import get_algorithms_registry
+
+    return tuple(sorted(get_algorithms_registry().keys()))
+
+
+def discover_algorithm_plugins(*, force: bool = False) -> tuple[str, ...]:
+    """Load algorithm builders exposed via the ``vamos.algorithms`` entry point group."""
+    from vamos.engine.algorithm.registry import discover_algorithm_plugins as _discover_algorithm_plugins
+
+    return _discover_algorithm_plugins(force=force)
+
+
+def available_crossover_methods(encoding: str = "real") -> tuple[str, ...]:
+    """
+    Return the available crossover method identifiers for a given encoding.
+
+    Parameters
+    ----------
+    encoding : str, default ``"real"``
+        Variable encoding type.
+
+    Returns
+    -------
+    tuple[str, ...]
+        Supported crossover method identifiers for the encoding.
+    """
+    try:
+        normalized = normalize_encoding(encoding)
+    except ValueError:
+        return ()
+    if normalized == "real":
+        return tuple(sorted(REAL_CROSSOVER.keys()))
+    if normalized == "binary":
+        return tuple(sorted(BINARY_CROSSOVER.keys()))
+    if normalized == "permutation":
+        return tuple(sorted(PERM_CROSSOVER.keys()))
+    if normalized == "integer":
+        return tuple(sorted(INT_CROSSOVER.keys()))
+    if normalized == "mixed":
+        return tuple(sorted(MIXED_CROSSOVER.keys()))
+    return ()
+
+
+def available_mutation_methods(encoding: str = "real") -> tuple[str, ...]:
+    """
+    Return the available mutation method identifiers for a given encoding.
+
+    Parameters
+    ----------
+    encoding : str, default ``"real"``
+        Variable encoding type.
+
+    Returns
+    -------
+    tuple[str, ...]
+        Supported mutation method identifiers for the encoding.
+    """
+    try:
+        normalized = normalize_encoding(encoding)
+    except ValueError:
+        return ()
+    if normalized == "real":
+        return tuple(sorted(REAL_MUTATION.keys()))
+    if normalized == "binary":
+        return tuple(sorted(BINARY_MUTATION.keys()))
+    if normalized == "permutation":
+        return tuple(sorted(PERM_MUTATION.keys()))
+    if normalized == "integer":
+        return tuple(sorted(INT_MUTATION.keys()))
+    if normalized == "mixed":
+        return tuple(sorted(MIXED_MUTATION.keys()))
+    return ()
+
+
+def resolve_algorithm(name: str) -> AlgorithmBuilder:
+    """Return the registered builder for a named algorithm."""
+    from vamos.engine.algorithm.registry import resolve_algorithm as _resolve_algorithm
+
+    return _resolve_algorithm(name)
+
+
+__all__ = [
+    "NSGAIIConfig",
+    "NSGAIIIConfig",
+    "MOEADConfig",
+    "SMSEMOAConfig",
+    "SMPSOConfig",
+    "SPEA2Config",
+    "IBEAConfig",
+    "AGEMOEAConfig",
+    "RVEAConfig",
+    "GenericAlgorithmConfig",
+    "ProbabilityExpression",
+    "ProbabilityValue",
+    "available_algorithms",
+    "discover_algorithm_plugins",
+    "available_crossover_methods",
+    "available_mutation_methods",
+    "resolve_algorithm",
+]

vamos/api.py

@@ -0,0 +1,106 @@
+"""
+User-facing API surface for VAMOS.
+
+This module exposes the small set of stable entrypoints most users need:
+- Programmatic optimization via `optimize`.
+- Problem selection helpers.
+- Basic diagnostics helpers.
+
+For lower-level control, import from the layered packages:
+`vamos.foundation.*`, `vamos.engine.*`, `vamos.experiment.*`, `vamos.ux.*`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from vamos.experiment.diagnostics.self_check import run_self_check
+from vamos.experiment.optimization_result import OptimizationResult, StudyResult
+
+# Unified API - the primary entry point
+from vamos.experiment.unified import optimize
+from vamos.foundation.logging import configure_vamos_logging
+from vamos.foundation.problem.base import Problem
+from vamos.foundation.problem.builder import make_problem
+from vamos.foundation.problem.registry import (
+    available_problem_names,
+    make_problem_selection,
+)
+from vamos.run_artifacts import (
+    CompatibilityReport,
+    IncompleteRunMetadataError,
+    LoadLimits,
+    ReplayReport,
+    RunManifest,
+    StoredRun,
+    VerificationReport,
+    load_result,
+    load_run,
+    reproduce,
+    save_result,
+    verify_run,
+)
+from vamos.selection import EnvironmentalSelectionResult, select_survivors
+from vamos.study_artifacts import (
+    Study,
+    StudyLoadLimits,
+    StudyPlanReport,
+    StudyReport,
+    StudySpec,
+    StudySummary,
+    create_study,
+    load_study,
+    plan_study,
+)
+
+
+def configure_logging(*, level: int = logging.INFO) -> None:
+    """Configure a minimal console logger for VAMOS.
+
+    Attaches a ``StreamHandler`` to the ``"vamos"`` logger if no handlers
+    are already present.  This is intentionally opt-in: library code
+    must never call ``logging.basicConfig()``.
+
+    Parameters
+    ----------
+    level : int, default ``logging.INFO``
+        Logging level for the ``"vamos"`` logger.
+    """
+    configure_vamos_logging(level=level)
+
+
+__all__ = [
+    # Primary API
+    "optimize",
+    "select_survivors",
+    "EnvironmentalSelectionResult",
+    "Problem",
+    "make_problem",
+    "OptimizationResult",
+    "StudyResult",
+    "available_problem_names",
+    "make_problem_selection",
+    "run_self_check",
+    "configure_logging",
+    "save_result",
+    "load_run",
+    "load_result",
+    "StoredRun",
+    "RunManifest",
+    "LoadLimits",
+    "IncompleteRunMetadataError",
+    "CompatibilityReport",
+    "ReplayReport",
+    "VerificationReport",
+    "verify_run",
+    "reproduce",
+    "StudySpec",
+    "Study",
+    "StudyLoadLimits",
+    "StudyPlanReport",
+    "StudyReport",
+    "StudySummary",
+    "create_study",
+    "load_study",
+    "plan_study",
+]

vamos/assist/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from .apply import apply_plan
+from .catalog import build_catalog
+from .cli import run_assist
+from .doctor import collect_doctor_report
+from .explain import summarize_plan
+from .go import go
+from .plan import create_plan
+from .providers import MockPlanProvider, OpenAIPlanProvider, PlanProvider, QuestionsMockProvider
+from .run import run_plan, select_config_path
+
+__all__ = [
+    "apply_plan",
+    "build_catalog",
+    "collect_doctor_report",
+    "create_plan",
+    "go",
+    "MockPlanProvider",
+    "OpenAIPlanProvider",
+    "PlanProvider",
+    "QuestionsMockProvider",
+    "run_assist",
+    "run_plan",
+    "select_config_path",
+    "summarize_plan",
+]

vamos/assist/apply.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import shutil
+from functools import lru_cache
+from pathlib import Path
+
+from vamos.engine.config.spec import validate_experiment_spec
+from vamos.experiment.cli.args import build_parser, build_pre_parser
+from vamos.experiment.cli.loaders import load_spec_defaults
+from vamos.experiment.cli.spec_args import parser_spec_keys
+from vamos.foundation.core.experiment_config import ExperimentConfig
+
+_REQUIRED_PLAN_FILES: tuple[str, ...] = ("config.json", "plan.json")
+_OPTIONAL_PLAN_FILES: tuple[str, ...] = ("prompt.txt", "catalog.json")
+
+_README_CONTENT = """# Run VAMOS
+
+This directory was generated by `vamos assist apply`.
+
+## How To Run
+
+```bash
+vamos --config config.json
+python -m vamos.experiment.cli.main --config config.json
+```
+
+Results/output location is controlled by fields in `config.json` (for example `defaults.output_root`).
+"""
+
+
+@lru_cache(maxsize=1)
+def _spec_allowed_overrides() -> tuple[str, ...]:
+    default_config = ExperimentConfig()
+    pre_parser = build_pre_parser()
+    spec_defaults = load_spec_defaults(None)
+    parser = build_parser(default_config=default_config, pre_parser=pre_parser, spec_defaults=spec_defaults)
+    return tuple(sorted(parser_spec_keys(parser)))
+
+
+def _read_json(path: Path) -> object:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise ValueError(f"Invalid JSON file: {path.name}") from exc
+
+
+def _validate_plan_dir(plan_dir: Path) -> None:
+    if not plan_dir.exists() or not plan_dir.is_dir():
+        raise ValueError(f"Plan directory not found: {plan_dir}")
+    for name in _REQUIRED_PLAN_FILES:
+        if not (plan_dir / name).is_file():
+            raise ValueError(f"Missing required plan file: {name}")
+
+
+def _validate_config(config_data: object) -> None:
+    try:
+        validate_experiment_spec(config_data, allowed_overrides=_spec_allowed_overrides())
+    except Exception as exc:
+        raise ValueError(f"Invalid plan config: {exc}") from exc
+
+
+def _prepare_project_dir(project_dir: Path, *, overwrite: bool) -> None:
+    if project_dir.exists():
+        if not overwrite:
+            raise ValueError(f"Project directory already exists: {project_dir}")
+        shutil.rmtree(project_dir)
+    project_dir.mkdir(parents=True, exist_ok=False)
+
+
+def _copy_plan_files(plan_dir: Path, project_dir: Path) -> None:
+    for name in (*_REQUIRED_PLAN_FILES, *_OPTIONAL_PLAN_FILES):
+        src = plan_dir / name
+        if src.is_file():
+            shutil.copy2(src, project_dir / name)
+
+
+def apply_plan(plan_dir: Path, out_dir: Path | None = None, overwrite: bool = False) -> Path:
+    resolved_plan_dir = Path(plan_dir)
+    _validate_plan_dir(resolved_plan_dir)
+
+    config_data = _read_json(resolved_plan_dir / "config.json")
+    _validate_config(config_data)
+
+    project_dir = Path(out_dir) if out_dir is not None else resolved_plan_dir / "project"
+    _prepare_project_dir(project_dir, overwrite=overwrite)
+    _copy_plan_files(resolved_plan_dir, project_dir)
+    (project_dir / "README_run.md").write_text(_README_CONTENT, encoding="utf-8")
+    return project_dir
+
+
+__all__ = ["apply_plan"]

vamos/assist/catalog.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from vamos.algorithms import available_algorithms, available_crossover_methods, available_mutation_methods
+from vamos.experiment.cli.quickstart import available_templates
+from vamos.foundation.kernel.registry import KERNELS
+
+
+def build_catalog(problem_type: str = "real") -> dict[str, list[str]]:
+    """Build a deterministic catalog of available optimization building blocks."""
+    return {
+        "algorithms": sorted(available_algorithms()),
+        "kernels": sorted(KERNELS.keys()),
+        "crossover_methods": sorted(available_crossover_methods(problem_type)),
+        "mutation_methods": sorted(available_mutation_methods(problem_type)),
+        "templates": sorted(available_templates()),
+    }
+
+
+__all__ = ["build_catalog"]