"""Phase 2 stub: AndlakeTracker for lineage-aware experiment tracking.

This module defines the **public API surface** for the tracker that will
be implemented in Phase 2.  All methods log intent and emit a
``FutureWarning`` so early adopters can start coding against the API
without breaking when the real implementation ships.

Usage (Phase 2 target)::

    from andlake import AndlakeTracker

    tracker = AndlakeTracker()
    with tracker.start_run(experiment="fraud-detection"):
        df = tracker.read_table("lake.silver.transactions")
        # ... train model ...
        tracker.log_model(model, "xgboost-fraud-v1")
"""

from __future__ import annotations

import warnings
from typing import Any


_PHASE2_MSG = (
    "AndlakeTracker is a Phase 2 stub. "
    "This method is a no-op and will be implemented in a future release."
)


class AndlakeTracker:
    """Lineage-aware experiment tracker (Phase 2 stub).

    The tracker will combine MLflow experiment tracking with OpenLineage
    lineage events, automatically recording which tables were read/written
    during a training run.
    """

    def __init__(self) -> None:
        warnings.warn(
            "AndlakeTracker is not yet implemented (Phase 2). "
            "You can use this stub to develop against the API surface.",
            FutureWarning,
            stacklevel=2,
        )

    def start_run(self, *, experiment: str, run_name: str | None = None) -> _RunContext:
        """Start a tracked experiment run.

        Parameters
        ----------
        experiment:
            Name of the MLflow experiment.
        run_name:
            Optional human-readable run name.

        Returns
        -------
        _RunContext
            A context manager for the run scope.
        """
        warnings.warn(_PHASE2_MSG, FutureWarning, stacklevel=2)
        return _RunContext(experiment=experiment, run_name=run_name)

    def read_table(self, table: str, **kwargs: Any) -> Any:
        """Read an Iceberg table and record lineage.

        Parameters
        ----------
        table:
            Fully qualified table name (e.g. ``lake.silver.transactions``).

        Returns
        -------
        pandas.DataFrame
            In Phase 2 this will return the table data. Currently returns None.
        """
        warnings.warn(_PHASE2_MSG, FutureWarning, stacklevel=2)
        return None

    def log_model(self, model: Any, name: str, **kwargs: Any) -> None:
        """Log a trained model with lineage metadata.

        Parameters
        ----------
        model:
            The trained model object.
        name:
            Artifact name for the model.
        """
        warnings.warn(_PHASE2_MSG, FutureWarning, stacklevel=2)


class _RunContext:
    """Context manager stub for a tracked run."""

    def __init__(self, *, experiment: str, run_name: str | None) -> None:
        self.experiment = experiment
        self.run_name = run_name

    def __enter__(self) -> _RunContext:
        return self

    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
        pass
