deriva-ml 1.17.10__py3-none-any.whl → 1.17.11__py3-none-any.whl

deriva_ml/model/deriva_ml_database.py

@@ -0,0 +1,308 @@
+"""Database-backed implementation of DerivaMLCatalog protocol.
+
+This module provides a DerivaMLDatabase class that implements the DerivaMLCatalog
+protocol using a DatabaseModel (SQLite) instead of a live catalog connection.
+This allows code written against the DerivaMLCatalog protocol to work identically
+with both live catalogs and downloaded bags.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generator, Iterable
+
+import pandas as pd
+from deriva.core.ermrest_model import Table
+
+from deriva_ml.core.definitions import RID, MLVocab, VocabularyTerm
+from deriva_ml.core.exceptions import DerivaMLException, DerivaMLInvalidTerm
+from deriva_ml.dataset.aux_classes import DatasetSpec, DatasetVersion
+from deriva_ml.dataset.dataset_bag import DatasetBag
+from deriva_ml.feature import Feature
+
+if TYPE_CHECKING:
+    from deriva_ml.model.database import DatabaseModel
+
+
+class DerivaMLDatabase:
+    """Database-backed implementation of DerivaMLCatalog protocol.
+
+    Provides the same interface as DerivaML but operates on downloaded
+    bags via SQLite. Read-only operations work; write operations raise
+    DerivaMLException since bags are immutable snapshots.
+
+    This class allows code written against the DerivaMLCatalog protocol
+    to work identically with both live catalogs (DerivaML) and downloaded
+    bags (DerivaMLDatabase).
+
+    Attributes:
+        ml_schema: Name of the ML schema.
+        domain_schemas: Frozenset of domain schema names.
+        default_schema: Default schema for table creation.
+        model: The underlying DatabaseModel.
+        working_dir: Working directory path.
+        cache_dir: Cache directory path.
+    """
+
+    def __init__(self, database_model: "DatabaseModel"):
+        """Create a new DerivaMLDatabase.
+
+        Args:
+            database_model: The DatabaseModel containing the SQLite database.
+        """
+        self._database_model = database_model
+
+    # ==================== Protocol Properties ====================
+
+    @property
+    def ml_schema(self) -> str:
+        """Get the ML schema name."""
+        return self._database_model.ml_schema
+
+    @property
+    def domain_schemas(self) -> frozenset[str]:
+        """Get the domain schema names."""
+        return self._database_model.domain_schemas
+
+    @property
+    def default_schema(self) -> str | None:
+        """Get the default schema name."""
+        return self._database_model.default_schema
+
+    @property
+    def model(self) -> "DatabaseModel":
+        """Get the underlying database model."""
+        return self._database_model
+
+    @property
+    def working_dir(self) -> Path:
+        """Get the working directory path."""
+        return self._database_model.dbase_path
+
+    @property
+    def cache_dir(self) -> Path:
+        """Get the cache directory path (same as working_dir for bags)."""
+        return self._database_model.dbase_path
+
+    @property
+    def catalog_id(self) -> str:
+        """Get the catalog ID (derived from bag path)."""
+        return str(self._database_model.bag_path)
+
+    @property
+    def _dataset_table(self) -> Table:
+        """Get the Dataset table from the model."""
+        return self._database_model.dataset_table
+
+    # ==================== Read Operations (Supported) ====================
+
+    def lookup_dataset(
+        self, dataset: RID | DatasetSpec, deleted: bool = False
+    ) -> DatasetBag:
+        """Look up a dataset by RID or spec.
+
+        Args:
+            dataset: Dataset RID or DatasetSpec to look up.
+            deleted: Whether to include deleted datasets (ignored for bags).
+
+        Returns:
+            DatasetBag for the specified dataset.
+
+        Raises:
+            DerivaMLException: If dataset not found in bag.
+        """
+        if isinstance(dataset, DatasetSpec):
+            rid = dataset.rid
+        else:
+            rid = dataset
+
+        # Validate the dataset exists
+        self._database_model.rid_lookup(rid)
+
+        # Get dataset metadata
+        dataset_record = next(
+            (d for d in self._database_model._get_table_contents("Dataset") if d["RID"] == rid),
+            None
+        )
+        if not dataset_record:
+            raise DerivaMLException(f"Dataset {rid} not found in bag")
+
+        # Get dataset types from association table
+        atable = f"Dataset_{MLVocab.dataset_type.value}"
+        ds_types = [
+            t[MLVocab.dataset_type.value]
+            for t in self._database_model._get_table_contents(atable)
+            if t["Dataset"] == rid
+        ]
+
+        return DatasetBag(
+            catalog=self,
+            dataset_rid=rid,
+            description=dataset_record.get("Description", ""),
+            execution_rid=(self._database_model._get_dataset_execution(rid) or {}).get("Execution"),
+            dataset_types=ds_types,
+        )
+
+    def find_datasets(self, deleted: bool = False) -> Iterable[DatasetBag]:
+        """List all datasets in the bag.
+
+        Args:
+            deleted: Whether to include deleted datasets (ignored for bags).
+
+        Returns:
+            Iterable of DatasetBag objects.
+        """
+        # Get dataset types for all datasets from association table
+        atable = f"Dataset_{MLVocab.dataset_type.value}"
+        ds_types = list(self._database_model._get_table_contents(atable))
+
+        datasets = []
+        for dataset in self._database_model._get_table_contents("Dataset"):
+            my_types = [t[MLVocab.dataset_type.value] for t in ds_types if t["Dataset"] == dataset["RID"]]
+            datasets.append(
+                DatasetBag(
+                    catalog=self,
+                    dataset_rid=dataset["RID"],
+                    description=dataset.get("Description", ""),
+                    execution_rid=(self._database_model._get_dataset_execution(dataset["RID"]) or {}).get("Execution"),
+                    dataset_types=my_types,
+                )
+            )
+        return datasets
+
+    def lookup_term(self, table: str | Table, term_name: str) -> VocabularyTerm:
+        """Look up a vocabulary term by name.
+
+        Args:
+            table: Vocabulary table to search.
+            term_name: Name or synonym of the term.
+
+        Returns:
+            The matching VocabularyTerm.
+
+        Raises:
+            DerivaMLException: If table is not a vocabulary or term not found.
+        """
+        # Get table object if string provided
+        if isinstance(table, str):
+            table_obj = self._database_model.name_to_table(table)
+        else:
+            table_obj = table
+
+        # Validate it's a vocabulary table
+        if not self._database_model.is_vocabulary(table_obj):
+            raise DerivaMLException(f"The table {table} is not a controlled vocabulary")
+
+        # Search for term in SQLite
+        for term in self.get_table_as_dict(table_obj.name):
+            if term_name == term.get("Name") or (
+                term.get("Synonyms") and term_name in term.get("Synonyms", [])
+            ):
+                # Convert synonyms to list if needed
+                synonyms = term.get("Synonyms")
+                if synonyms and not isinstance(synonyms, list):
+                    synonyms = list(synonyms)
+                term["Synonyms"] = synonyms or []
+                return VocabularyTerm.model_validate(term)
+
+        raise DerivaMLInvalidTerm(table, term_name)
+
+    def get_table_as_dataframe(self, table: str) -> pd.DataFrame:
+        """Get table contents as a pandas DataFrame.
+
+        Args:
+            table: Name of the table to retrieve.
+
+        Returns:
+            DataFrame containing all table contents.
+        """
+        return pd.DataFrame(list(self.get_table_as_dict(table)))
+
+    def get_table_as_dict(self, table: str) -> Generator[dict[str, Any], None, None]:
+        """Get table contents as dictionaries.
+
+        Args:
+            table: Name of the table to retrieve.
+
+        Returns:
+            Generator yielding dictionaries for each row.
+        """
+        yield from self._database_model._get_table_contents(table)
+
+    def list_dataset_element_types(self) -> list[Table]:
+        """List the types of elements that can be in datasets.
+
+        Returns:
+            List of Table objects representing element types.
+        """
+        return self._database_model.list_dataset_element_types()
+
+    def find_features(self, table: str | Table) -> Iterable[Feature]:
+        """Find features associated with a table.
+
+        Args:
+            table: Table to find features for.
+
+        Returns:
+            Iterable of Feature objects.
+        """
+        return self._database_model.find_features(table)
+
+    # ==================== Write Operations (Not Supported) ====================
+
+    def create_dataset(
+        self,
+        execution_rid: RID | None = None,
+        version: DatasetVersion | str | None = None,
+        description: str = "",
+        dataset_types: list[str] | None = None,
+    ) -> DatasetBag:
+        """Create a new dataset.
+
+        Raises:
+            DerivaMLException: Always, since bags are read-only.
+        """
+        raise DerivaMLException(
+            "Cannot create datasets in a downloaded bag. "
+            "Bags are immutable snapshots of catalog data."
+        )
+
+    def pathBuilder(self):
+        """Get the catalog path builder.
+
+        Raises:
+            DerivaMLException: Always, since SQLite doesn't use pathBuilder.
+        """
+        raise DerivaMLException(
+            "pathBuilder is not available for database-backed catalogs. "
+            "Use get_table_as_dict() or get_table_as_dataframe() instead."
+        )
+
+    def catalog_snapshot(self, version_snapshot: str):
+        """Create a catalog snapshot.
+
+        Raises:
+            DerivaMLException: Always, since bags are already snapshots.
+        """
+        raise DerivaMLException(
+            "catalog_snapshot is not available for database-backed catalogs. "
+            "Bags are already immutable snapshots."
+        )
+
+    def resolve_rid(self, rid: RID) -> dict[str, Any]:
+        """Resolve a RID to its location.
+
+        For database-backed catalogs, this validates that the RID exists
+        in the bag and returns basic information about it.
+
+        Args:
+            rid: RID to resolve.
+
+        Returns:
+            Dictionary with RID and version information.
+
+        Raises:
+            DerivaMLException: If RID not found in bag.
+        """
+        version = self._database_model.rid_lookup(rid)
+        return {"RID": rid, "version": version}

deriva_ml/model/handles.py

@@ -0,0 +1,14 @@
+"""Handle wrappers for ERMrest model objects.
+
+This module re-exports TableHandle and ColumnHandle from deriva-py
+for backwards compatibility. New code should import directly from
+deriva.core.model_handles.
+
+Classes:
+    ColumnHandle: Wrapper for ERMrest Column with simplified property access.
+    TableHandle: Wrapper for ERMrest Table with simplified operations.
+"""
+
+from deriva.core.model_handles import TableHandle, ColumnHandle
+
+__all__ = ["TableHandle", "ColumnHandle"]

deriva_ml/run_model.py

@@ -0,0 +1,319 @@
+"""Command-line interface for executing ML models with DerivaML tracking.
+
+This module provides a CLI tool for running ML models using hydra-zen configuration
+while automatically tracking the execution in a Deriva catalog. It handles:
+
+- Configuration loading from a user's configs module
+- Hydra-zen configuration composition with command-line overrides
+- Execution tracking with workflow provenance
+- Multirun/sweep support with parent-child execution nesting
+
+Usage:
+    deriva-ml-run --host localhost --catalog 45 model_config=my_model
+    deriva-ml-run +experiment=my_experiment
+    deriva-ml-run --multirun model_config=m1,m2
+    deriva-ml-run --info  # Show available Hydra config options
+
+This parallels `deriva-ml-run-notebook` but for Python model functions instead
+of Jupyter notebooks.
+
+See Also:
+    - run_notebook: CLI for running Jupyter notebooks
+    - runner.run_model: The underlying function that executes models
+"""
+
+import sys
+from pathlib import Path
+
+from deriva.core import BaseCLI
+from hydra_zen import store, zen
+
+from deriva_ml.execution import (
+    run_model,
+    load_configs,
+    get_multirun_config,
+    get_all_multirun_configs,
+)
+
+
+class DerivaMLRunCLI(BaseCLI):
+    """Command-line interface for running ML models with DerivaML execution tracking.
+
+    This CLI extends Deriva's BaseCLI to provide model execution capabilities using
+    hydra-zen. It automatically loads configuration modules from the project's
+    configs directory.
+
+    The CLI supports:
+        - Host and catalog arguments (optional, can use Hydra config defaults)
+        - Hydra configuration overrides as positional arguments
+        - --info flag to display available configuration options
+        - --multirun flag for parameter sweeps
+        - --config-dir to specify custom config location
+
+    Attributes:
+        parser: ArgumentParser instance with configured arguments.
+
+    Example:
+        >>> cli = DerivaMLRunCLI(
+        ...     description="Run ML model",
+        ...     epilog="See documentation for more details"
+        ... )
+        >>> cli.main()  # Parses args and runs model
+    """
+
+    def __init__(self, description: str, epilog: str, **kwargs) -> None:
+        """Initialize the model runner CLI with command-line arguments.
+
+        Sets up argument parsing for model execution, including host/catalog,
+        config directory, and Hydra overrides.
+
+        Args:
+            description: Description text shown in --help output.
+            epilog: Additional text shown after argument help.
+            **kwargs: Additional keyword arguments passed to BaseCLI.
+        """
+        BaseCLI.__init__(self, description, epilog, **kwargs)
+
+        self.parser.add_argument(
+            "--catalog",
+            type=str,
+            default=None,
+            help="Catalog number or identifier (optional if defined in Hydra config)"
+        )
+
+        self.parser.add_argument(
+            "--config-dir",
+            "-c",
+            type=Path,
+            default=Path("src/configs"),
+            help="Path to the configs directory (default: src/configs)",
+        )
+
+        self.parser.add_argument(
+            "--config-name",
+            type=str,
+            default="deriva_model",
+            help="Name of the main hydra-zen config (default: deriva_model)",
+        )
+
+        self.parser.add_argument(
+            "--info",
+            action="store_true",
+            help="Display available Hydra configuration groups and options.",
+        )
+
+        self.parser.add_argument(
+            "--multirun", "-m",
+            action="store_true",
+            help="Run multiple configurations (Hydra multirun mode).",
+        )
+
+        self.parser.add_argument(
+            "hydra_overrides",
+            nargs="*",
+            help="Hydra-zen configuration overrides (e.g., model_config=cifar10_quick)",
+        )
+
+    def main(self) -> int:
+        """Parse command-line arguments and execute the model.
+
+        This is the main entry point that orchestrates:
+        1. Parsing command-line arguments
+        2. Loading configuration modules
+        3. Either showing config info or executing the model
+
+        Returns:
+            Exit code (0 for success, 1 for failure).
+        """
+        args = self.parse_cli()
+
+        # Resolve config directory
+        config_dir = args.config_dir.resolve()
+        if not config_dir.exists():
+            print(f"Error: Config directory not found: {config_dir}")
+            return 1
+
+        # Add the parent of the config directory to sys.path
+        src_dir = config_dir.parent
+        if src_dir.exists() and str(src_dir) not in sys.path:
+            sys.path.insert(0, str(src_dir))
+
+        # Also add project root
+        project_root = src_dir.parent
+        if project_root.exists() and str(project_root) not in sys.path:
+            sys.path.insert(0, str(project_root))
+
+        # Load configurations from the configs module
+        config_module_name = config_dir.name
+        loaded = load_configs(config_module_name)
+        if not loaded:
+            # Try the old way
+            try:
+                exec(f"from {config_module_name} import load_all_configs; load_all_configs()")
+            except ImportError:
+                print(f"Error: Could not load configs from '{config_module_name}'")
+                print("Make sure the config directory contains an __init__.py with load_all_configs()")
+                return 1
+
+        if args.info:
+            self._show_hydra_info()
+            return 0
+
+        # Build Hydra overrides list
+        hydra_overrides = list(args.hydra_overrides) if args.hydra_overrides else []
+
+        # Check for +multirun=<name> and expand it
+        multirun_description = None
+        use_multirun = args.multirun
+        expanded_overrides = []
+
+        for override in hydra_overrides:
+            if override.startswith("+multirun="):
+                # Extract the multirun config name
+                multirun_name = override.split("=", 1)[1]
+                multirun_spec = get_multirun_config(multirun_name)
+
+                if multirun_spec is None:
+                    available = get_all_multirun_configs()
+                    print(f"Error: Unknown multirun config '{multirun_name}'")
+                    if available:
+                        print("Available multirun configs:")
+                        for name in sorted(available.keys()):
+                            print(f"  - {name}")
+                    else:
+                        print("No multirun configs registered. Define them in configs/multiruns.py")
+                    return 1
+
+                # Expand the multirun config's overrides
+                expanded_overrides.extend(multirun_spec.overrides)
+                multirun_description = multirun_spec.description
+                use_multirun = True  # Automatically enable multirun mode
+            else:
+                # Keep non-multirun overrides (they can override multirun config values)
+                expanded_overrides.append(override)
+
+        hydra_overrides = expanded_overrides
+
+        # Add host/catalog overrides if provided on command line
+        if args.host:
+            hydra_overrides.append(f"deriva_ml.hostname={args.host}")
+        if args.catalog:
+            hydra_overrides.append(f"deriva_ml.catalog_id={args.catalog}")
+
+        # If we have a multirun description, add it as an override
+        # This gets passed to run_model which uses it for the parent execution
+        if multirun_description:
+            # Escape the description for Hydra command line
+            # Use single quotes and escape any internal single quotes
+            escaped_desc = multirun_description.replace("'", "\\'")
+            hydra_overrides.append(f"description='{escaped_desc}'")
+
+        # Finalize the hydra-zen store
+        store.add_to_hydra_store()
+
+        # Build argv for Hydra
+        hydra_argv = [sys.argv[0]] + hydra_overrides
+        if use_multirun:
+            hydra_argv.insert(1, "--multirun")
+
+        # Save and replace sys.argv for Hydra
+        original_argv = sys.argv
+        sys.argv = hydra_argv
+
+        try:
+            zen(run_model).hydra_main(
+                config_name=args.config_name,
+                version_base="1.3",
+                config_path=None,
+            )
+        finally:
+            sys.argv = original_argv
+
+        return 0
+
+    @staticmethod
+    def _show_hydra_info() -> None:
+        """Display available Hydra configuration groups and options.
+
+        Inspects the hydra-zen store and prints all registered configuration
+        groups and their available options.
+        """
+        print("Available Hydra Configuration Groups:")
+        print("=" * 50)
+
+        try:
+            groups: dict[str, list[str]] = {}
+
+            for group, name in store._queue:
+                if group:
+                    if group not in groups:
+                        groups[group] = []
+                    if name not in groups[group]:
+                        groups[group].append(name)
+                else:
+                    if "__root__" not in groups:
+                        groups["__root__"] = []
+                    if name not in groups["__root__"]:
+                        groups["__root__"].append(name)
+
+            for group in sorted(groups.keys()):
+                if group == "__root__":
+                    print("\nTop-level configs:")
+                else:
+                    print(f"\n{group}:")
+                for name in sorted(groups[group]):
+                    print(f"  - {name}")
+
+            # Show multirun configs if any are registered
+            multirun_configs = get_all_multirun_configs()
+            if multirun_configs:
+                print("\nmultirun:")
+                for name in sorted(multirun_configs.keys()):
+                    spec = multirun_configs[name]
+                    # Show first line of description or overrides summary
+                    if spec.description:
+                        first_line = spec.description.strip().split('\n')[0]
+                        # Remove markdown formatting for display
+                        first_line = first_line.lstrip('#').strip()
+                        if len(first_line) > 50:
+                            first_line = first_line[:47] + "..."
+                        print(f"  - {name}: {first_line}")
+                    else:
+                        print(f"  - {name}: {', '.join(spec.overrides[:2])}")
+
+            print("\n" + "=" * 50)
+            print("Usage: deriva-ml-run [options] <group>=<option> ...")
+            print("Example: deriva-ml-run --host localhost --catalog 45 model_config=cifar10_quick")
+            print("Example: deriva-ml-run +experiment=cifar10_quick")
+            print("Example: deriva-ml-run +multirun=quick_vs_extended")
+            print("Example: deriva-ml-run --multirun +experiment=cifar10_quick,cifar10_extended")
+
+        except Exception as e:
+            print(f"Error inspecting Hydra store: {e}")
+
+
+def main() -> int:
+    """Main entry point for the model runner CLI.
+
+    Creates and runs the DerivaMLRunCLI instance.
+
+    Returns:
+        Exit code (0 for success, 1 for failure).
+    """
+    cli = DerivaMLRunCLI(
+        description="Run ML models with DerivaML execution tracking",
+        epilog=(
+            "Examples:\n"
+            "  deriva-ml-run model_config=my_model\n"
+            "  deriva-ml-run --host localhost --catalog 45 +experiment=cifar10_quick\n"
+            "  deriva-ml-run +multirun=quick_vs_extended\n"
+            "  deriva-ml-run +multirun=lr_sweep model_config.epochs=5\n"
+            "  deriva-ml-run --multirun +experiment=cifar10_quick,cifar10_extended\n"
+            "  deriva-ml-run --info\n"
+        ),
+    )
+    return cli.main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())