furu 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

furu/__init__.py

@@ -36,15 +36,7 @@ from .runtime import (
     log,
     write_separator,
 )
-from .migrate import migrate
-from .migration import (
-    NamespacePair,
-    MigrationCandidate,
-    MigrationSkip,
-    apply_migration,
-    find_migration_candidates,
-    find_migration_candidates_initialized_target,
-)
+from .migration import FuruRef, MigrationReport, MigrationSkip
 from .serialization import FuruSerializer
 from .storage import MetadataManager, StateManager
 
@@ -67,13 +59,9 @@ __all__ = [
     "DependencyChzSpec",
     "DependencySpec",
     "MISSING",
-    "migrate",
-    "NamespacePair",
-    "MigrationCandidate",
+    "FuruRef",
+    "MigrationReport",
     "MigrationSkip",
-    "apply_migration",
-    "find_migration_candidates",
-    "find_migration_candidates_initialized_target",
     "MetadataManager",
     "StateManager",
     "SubmititAdapter",

furu/aliases.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterator
+from pathlib import Path
+
+from .config import FURU_CONFIG
+from .storage import MigrationManager, MigrationRecord
+from .storage.migration import RootKind
+from .storage.state import StateManager
+
+AliasKey = tuple[str, str, RootKind]
+
+
+def iter_roots() -> Iterator[Path]:
+    """Iterate over all existing Furu storage roots."""
+    for version_controlled in (False, True):
+        root = FURU_CONFIG.get_root(version_controlled)
+        if root.exists():
+            yield root
+
+
+def find_experiment_dirs(root: Path) -> list[Path]:
+    """Find all directories containing .furu/state.json files."""
+    experiments: list[Path] = []
+
+    for furu_dir in root.rglob(StateManager.INTERNAL_DIR):
+        if not furu_dir.is_dir():
+            continue
+        state_file = furu_dir / StateManager.STATE_FILE
+        if state_file.is_file():
+            experiments.append(furu_dir.parent)
+
+    return experiments
+
+
+def alias_key(migration: MigrationRecord) -> AliasKey:
+    return (migration.from_namespace, migration.from_hash, migration.from_root)
+
+
+def collect_aliases(
+    *, include_inactive: bool = True
+) -> dict[AliasKey, list[MigrationRecord]]:
+    aliases: dict[AliasKey, list[MigrationRecord]] = defaultdict(list)
+    for root in iter_roots():
+        for experiment_dir in find_experiment_dirs(root):
+            migration = MigrationManager.read_migration(experiment_dir)
+            if migration is None or migration.kind != "alias":
+                continue
+            if not include_inactive and migration.overwritten_at is not None:
+                continue
+            aliases[alias_key(migration)].append(migration)
+    return aliases

furu/core/furu.py

@@ -18,13 +18,14 @@ from typing import (
     Callable,
     ClassVar,
     Hashable,
+    Iterable,
+    Literal,
     Mapping,
     Protocol,
     Self,
     Sequence,
     TypeAlias,
     TypedDict,
-    TypeVar,
     cast,
 )
 
@@ -47,8 +48,19 @@ from ..runtime import current_holder
 from ..runtime.logging import enter_holder, get_logger, log, write_separator
 from ..runtime.tracebacks import format_traceback
 from ..runtime.overrides import has_override, lookup_override
+from ..schema import schema_key_from_cls
 from ..serialization import FuruSerializer
 from ..serialization.serializer import JsonValue
+from ..aliases import AliasKey, collect_aliases
+from ..migration import (
+    FuruRef,
+    MigrationReport,
+    current as _current_refs,
+    migrate as _migrate,
+    migrate_one as _migrate_one,
+    resolve_original_ref,
+    stale as _stale_refs,
+)
 from ..storage import (
     FuruMetadata,
     MetadataManager,
@@ -312,8 +324,108 @@ class Furu[T](ABC):
         """Convert to Python code."""
         return FuruSerializer.to_python(self, multiline=multiline)
 
+    @classmethod
+    def schema_key(cls) -> tuple[str, ...]:
+        """
+        Return the stable schema key for this class.
+
+        Returns:
+            tuple[str, ...]: Sorted field names for the class schema.
+        """
+        return schema_key_from_cls(cls)
+
+    @classmethod
+    def migrate(
+        cls,
+        *,
+        from_schema: Iterable[str] | None = None,
+        from_drop: Iterable[str] | None = None,
+        from_add: Iterable[str] | None = None,
+        from_hash: str | None = None,
+        from_furu_obj: dict[str, JsonValue] | None = None,
+        from_namespace: str | None = None,
+        default_field: Iterable[str] | None = None,
+        set_field: Mapping[str, JsonValue] | None = None,
+        drop_field: Iterable[str] | None = None,
+        rename_field: Mapping[str, str] | None = None,
+        include_alias_sources: bool = False,
+        conflict: Literal["throw", "skip"] = "throw",
+        origin: str | None = None,
+        note: str | None = None,
+    ) -> MigrationReport:
+        """
+        Create alias-only migrations for stored objects matching the selector.
+
+        Notes:
+            set_field only adds fields that are not already present. To replace
+            a field, drop it first and then set it.
+        """
+        return _migrate(
+            cls,
+            from_schema=from_schema,
+            from_drop=from_drop,
+            from_add=from_add,
+            from_hash=from_hash,
+            from_furu_obj=from_furu_obj,
+            from_namespace=from_namespace,
+            default_field=default_field,
+            set_field=set_field,
+            drop_field=drop_field,
+            rename_field=rename_field,
+            include_alias_sources=include_alias_sources,
+            conflict=conflict,
+            origin=origin,
+            note=note,
+        )
+
+    @classmethod
+    def migrate_one(
+        cls,
+        *,
+        from_hash: str,
+        from_namespace: str | None = None,
+        default_field: Iterable[str] | None = None,
+        set_field: Mapping[str, JsonValue] | None = None,
+        drop_field: Iterable[str] | None = None,
+        rename_field: Mapping[str, str] | None = None,
+        include_alias_sources: bool = False,
+        conflict: Literal["throw", "skip"] = "throw",
+        origin: str | None = None,
+        note: str | None = None,
+    ) -> MigrationRecord | None:
+        return _migrate_one(
+            cls,
+            from_hash=from_hash,
+            from_namespace=from_namespace,
+            default_field=default_field,
+            set_field=set_field,
+            drop_field=drop_field,
+            rename_field=rename_field,
+            include_alias_sources=include_alias_sources,
+            conflict=conflict,
+            origin=origin,
+            note=note,
+        )
+
+    @classmethod
+    def stale(cls, *, namespace: str | None = None) -> list[FuruRef]:
+        return _stale_refs(cls, namespace=namespace)
+
+    @classmethod
+    def current(cls, *, namespace: str | None = None) -> list[FuruRef]:
+        return _current_refs(cls, namespace=namespace)
+
     def log(self: Self, message: str, *, level: str = "INFO") -> Path:
-        """Log a message to the current holder's `furu.log`."""
+        """
+        Log a message to the current holder's `furu.log`.
+
+        Parameters:
+            message (str): The message to log.
+            level (str): Logging level name (e.g., "INFO", "ERROR").
+
+        Returns:
+            Path: Path to the log file where the message was written.
+        """
         return log(message, level=level)
 
     def _exists_quiet(self: Self) -> bool:
@@ -369,6 +481,45 @@ class Furu[T](ABC):
         """Get migration record for this object."""
         return MigrationManager.read_migration(self._base_furu_dir())
 
+    def is_alias(self: Self) -> bool:
+        record = self._alias_record(self._base_furu_dir())
+        return record is not None
+
+    def original(self: Self) -> FuruRef:
+        base_dir = self._base_furu_dir()
+        ref = FuruRef(
+            namespace=".".join(self.__class__._namespace().parts),
+            furu_hash=self.furu_hash,
+            root=MigrationManager.root_kind_for_dir(base_dir),
+            directory=base_dir,
+        )
+        return resolve_original_ref(ref)
+
+    def aliases(
+        self: Self,
+        *,
+        include_inactive: bool = True,
+        alias_index: dict[AliasKey, list[MigrationRecord]] | None = None,
+    ) -> list[FuruRef]:
+        original_ref = self.original()
+        if alias_index is None:
+            alias_index = collect_aliases(include_inactive=include_inactive)
+        records = alias_index.get(
+            (original_ref.namespace, original_ref.furu_hash, original_ref.root),
+            [],
+        )
+        refs = [
+            FuruRef(
+                namespace=record.to_namespace,
+                furu_hash=record.to_hash,
+                root=record.to_root,
+                directory=MigrationManager.resolve_dir(record, target="to"),
+            )
+            for record in records
+        ]
+        refs.sort(key=lambda item: item.furu_hash)
+        return refs
+
     def get(self: Self, *, force: bool = False) -> T:
         """
         Load result if it exists, computing if necessary.
@@ -1593,6 +1744,3 @@ def _dependency_type_error(
         f"{path} must be a Furu instance or a collection of Furu instances; "
         f"got {type(value).__name__}"
     )
-
-
-_H = TypeVar("_H", bound=Furu, covariant=True)

furu/dashboard/api/models.py

@@ -19,6 +19,17 @@ class HealthCheck(BaseModel):
     version: str
 
 
+class AliasInfo(BaseModel):
+    """Alias reference information for an experiment."""
+
+    namespace: str
+    furu_hash: str
+    migrated_at: str | None = None
+    overwritten_at: str | None = None
+    origin: str | None = None
+    note: str | None = None
+
+
 class ExperimentSummary(BaseModel):
     """Summary of an experiment for list views."""
 
@@ -46,6 +57,13 @@ class ExperimentSummary(BaseModel):
     to_namespace: str | None = None
     to_hash: str | None = None
     original_result_status: str | None = None
+    original_namespace: str | None = None
+    original_hash: str | None = None
+    schema_key: list[str] | None = None
+    current_schema_key: list[str] | None = None
+    is_stale: bool | None = None
+    is_alias: bool | None = None
+    aliases: list[AliasInfo] | None = None
 
 
 class ExperimentDetail(ExperimentSummary):
@@ -55,10 +73,6 @@ class ExperimentDetail(ExperimentSummary):
     state: JsonDict
     metadata: JsonDict | None = None
     attempt: StateAttempt | None = None
-    original_namespace: str | None = None
-    original_hash: str | None = None
-    alias_namespaces: list[str] | None = None
-    alias_hashes: list[str] | None = None
 
 
 class ExperimentList(BaseModel):

furu/dashboard/api/routes.py

@@ -1,5 +1,7 @@
 """API route definitions for the Furu Dashboard."""
 
+from typing import Literal
+
 from fastapi import APIRouter, HTTPException, Query
 
 from .. import __version__
@@ -21,6 +23,8 @@ from .models import (
 
 router = APIRouter(prefix="/api", tags=["api"])
 
+SchemaFilter = Literal["current", "stale", "any"]
+
 
 @router.get("/health", response_model=HealthCheck)
 async def health_check() -> HealthCheck:
@@ -57,6 +61,9 @@ async def list_experiments(
     migration_policy: str | None = Query(
         None, description="Filter by migration policy"
     ),
+    schema: SchemaFilter = Query(
+        "current", description="Filter by schema status (current, stale, any)"
+    ),
     view: str = Query("resolved", description="View mode: resolved or original"),
     limit: int = Query(100, ge=1, le=1000, description="Maximum number of results"),
     offset: int = Query(0, ge=0, description="Offset for pagination"),
@@ -76,6 +83,7 @@ async def list_experiments(
         config_filter=config_filter,
         migration_kind=migration_kind,
         migration_policy=migration_policy,
+        schema=schema,
         view=view,
     )