AutoCarver 7.3.2__tar.gz → 7.3.3__tar.gz

{autocarver-7.3.2 → autocarver-7.3.3}/AutoCarver/carvers/multiclass_carver.py

@@ -89,6 +89,9 @@ class MulticlassCarver(BinaryCarver):
         X_dev: pd.DataFrame | None = None,
         y_dev: pd.Series | None = None,
     ) -> Self:
+        # dropping the target column if it leaked into the features (before versioning)
+        self._drop_target_from_features(X, y)
+
         # initiating samples
         samples = Samples(train=Sample(X, y), dev=Sample(X_dev, y_dev))
 

{autocarver-7.3.2 → autocarver-7.3.3}/AutoCarver/carvers/utils/base_carver.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass, field, replace
 from functools import partial
 from multiprocessing import Pool
 from typing import Self
+from warnings import warn
 
 import pandas as pd
 
@@ -293,6 +294,24 @@ class BaseCarver(BaseDiscretizer, ABC):
 
         return samples
 
+    def _drop_target_from_features(self, X: pd.DataFrame, y: pd.Series | None) -> None:
+        """Drops the target column from ``self.features`` if it leaked in.
+
+        ``Features.from_dataframe`` maps every column of the input, target included; the
+        target reaches the carver as the named ``y`` Series, so it is removed here rather
+        than at feature-construction time.
+
+        The guard fires only when ``y`` is genuinely a column of ``X`` (same name *and*
+        values): pandas propagates column names through arithmetic, so a derived target
+        like ``X[col] * 0.5 + noise`` can share a feature's name without being it.
+        """
+        if y is None or y.name is None:
+            return
+        name = str(y.name)
+        if name in self.features and name in X.columns and y.equals(X[name]):
+            warn(f"[{self.__name__}] dropping target column {name!r} from features", UserWarning, stacklevel=2)
+            self.features.remove(name)
+
     def fit(  # type: ignore
         self,
         X: pd.DataFrame,
@@ -332,6 +351,9 @@ class BaseCarver(BaseDiscretizer, ABC):
                 f"[{self.__name__}] features are already fitted or previous fit failed. Please reset your features."
             )
 
+        # dropping the target column if it leaked into the features
+        self._drop_target_from_features(X, y)
+
         # setting is_fitted
         self.features.is_fitted = True
 

{autocarver-7.3.2 → autocarver-7.3.3}/AutoCarver/features/__init__.py

@@ -1,6 +1,12 @@
 """Loads Features tools."""
 
 from AutoCarver.features.features import Features, FeaturesConfig, get_names, get_versions
+from AutoCarver.features.llm_qualifier import (
+    build_qualification_prompt,
+    parse_qualification_response,
+    qualify_with_llm,
+    specs_to_features_kwargs,
+)
 from AutoCarver.features.qualitatives import (
     CategoricalFeature,
     NestedFeature,
@@ -41,4 +47,8 @@ __all__ = [
     "NumericalFeature",
     "DatetimeFeature",
     "QualitativeFeature",
+    "build_qualification_prompt",
+    "parse_qualification_response",
+    "qualify_with_llm",
+    "specs_to_features_kwargs",
 ]

{autocarver-7.3.2 → autocarver-7.3.3}/AutoCarver/features/features.py

@@ -3,6 +3,7 @@
 from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import TypeVar, overload
+from warnings import warn
 
 import numpy as np
 import pandas as pd
@@ -48,39 +49,49 @@ class FeaturesConfig:
     dropna: bool = False
 
 
-# class AutoFeatures(Features):
-#     """TODO"""
-
-#     __name__ = "AutoFeatures"
-
-#     def __init__(self):
-#         raise EnvironmentError(
-#             f"[{self.__name__}] Should be instantiated with AutoFeatures.from_dataframe()"
-#         )
-
-#     def from_dataframe(self, X: pd.DataFrame) -> None:
-#         """Automatically generates Features from an input DataFrame based on there data types"""
-#         # initiating features
-#         categoricals, ordinals, quantitatives, datetimes = ([],) * 4
-
-#         # getting data types
-#         for feature, dtype in X.dtypes:
-#             str_dtype = str(dtype).lower()
-#             # categorical feature
-#             if dtype == "object":
-#                 categoricals += [feature]
-#             # quantitative feature
-#             elif str_dtype.startswith("int") or str_dtype.startswith("float"):
-#                 quantitatives += [feature]
-#             # datetime feature
-#             elif "date" in str_dtype or "time" in str_dtype:
-#                 datetimes += [feature]
-#             # unknown data type
-#             else:
-#                 warn(
-#                     f"[{self.__name__}] Ommited column {feature}, unknown data type {dtype}",
-#                     UserWarning,
-#                 )
+def infer_feature_kind(dtype) -> str | None:
+    """Maps a pandas dtype to a feature kind, or ``None`` when unsupported.
+
+    Single source of truth for the dtype-based mapping used by both
+    :meth:`Features.from_dataframe` and the MCP inspection layer. Returns one of
+    ``"ordinal"`` / ``"datetime"`` / ``"numerical"`` / ``"categorical"``.
+    """
+    if isinstance(dtype, pd.CategoricalDtype) and dtype.ordered:
+        return "ordinal"
+    if pd.api.types.is_datetime64_any_dtype(dtype):
+        return "datetime"
+    if pd.api.types.is_bool_dtype(dtype):
+        return "categorical"
+    if pd.api.types.is_numeric_dtype(dtype):
+        return "numerical"
+    if isinstance(dtype, pd.CategoricalDtype) or dtype == "object" or pd.api.types.is_string_dtype(dtype):
+        return "categorical"
+    return None
+
+
+def _resolve_datetime_references(X: pd.DataFrame, datetime_cols: list[str]) -> dict[str, str]:
+    """Picks a ``reference_date`` for each auto-detected datetime column.
+
+    Every datetime column is measured (row-wise) against the most recent datetime column —
+    the ``anchor``, chosen as the column with the latest observation. The anchor can't
+    reference itself, so it falls back to a fixed literal (its own earliest date); the same
+    fallback applies when there is a single datetime column.
+    """
+    # most recent observation per column (NaT for all-NaT columns, which can't be anchors)
+    representatives = {col: X[col].max() for col in datetime_cols}
+    anchor_candidates = [col for col in datetime_cols if pd.notna(representatives[col])]
+
+    anchor = max(anchor_candidates, key=lambda col: representatives[col]) if anchor_candidates else None
+
+    references: dict[str, str] = {}
+    for col in datetime_cols:
+        if anchor is not None and col != anchor:
+            references[col] = anchor  # row-wise reference against the most recent column
+        else:
+            # anchor (or single/all-NaT column): fixed literal = its earliest date
+            earliest = X[col].min()
+            references[col] = str(earliest.date()) if pd.notna(earliest) else str(earliest)
+    return references
 
 
 def _check_names_only(names: list[str] | None, kind: str) -> None:
@@ -230,6 +241,58 @@ class Features:
         instance._build(_dedupe_by_version(feature_list), config)
         return instance
 
+    @classmethod
+    def from_dataframe(cls, X: pd.DataFrame, config: FeaturesConfig | None = None) -> "Features":
+        """Build a :class:`Features` by mapping each column of ``X`` to a feature type.
+
+        Mapping rules (deterministic, from each column's dtype):
+
+        - ordered ``category`` → :class:`OrdinalFeature` (order lifted from ``.cat.categories``)
+        - numeric (non-bool) → :class:`NumericalFeature`
+        - ``datetime64`` → :class:`DatetimeFeature` (``reference_date`` resolved against the
+          most recent datetime column, see :func:`_resolve_datetime_references`)
+        - ``bool`` / ``object`` / ``string`` / unordered ``category`` → :class:`CategoricalFeature`
+        - any other dtype → skipped with a warning
+
+        Nested features can't be inferred from a single column's dtype and are not produced;
+        declare them explicitly or use :func:`qualify_with_llm`. The target column, if present
+        in ``X``, is mapped like any other column and dropped later by the carver (see
+        ``BaseCarver._drop_target_from_features``).
+
+        Parameters
+        ----------
+        X : pd.DataFrame
+            DataFrame whose columns are mapped to typed features.
+
+        config : FeaturesConfig, optional
+            Collection-level config propagated to each feature, by default ``None``.
+        """
+        datetime_cols = [col for col in X.columns if pd.api.types.is_datetime64_any_dtype(X[col])]
+        references = _resolve_datetime_references(X, datetime_cols)
+
+        features: list[BaseFeature] = []
+        for col, dtype in X.dtypes.items():
+            name = str(col)
+            kind = infer_feature_kind(dtype)
+            if kind == "ordinal":
+                features.append(OrdinalFeature(name, values=[str(c) for c in dtype.categories]))
+            elif kind == "datetime":
+                features.append(DatetimeFeature(name, reference_date=references[col]))
+            elif kind == "numerical":
+                features.append(NumericalFeature(name))
+            elif kind == "categorical":
+                features.append(CategoricalFeature(name))
+            else:
+                warn(
+                    f"[{cls.__name__}] Omitted column {name!r}, unsupported data type {dtype}.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        instance = cls.__new__(cls)
+        instance._build(features, config)
+        return instance
+
     def _build(self, features: list[BaseFeature], config: FeaturesConfig | None) -> None:
         """Shared construction body: apply config and group by type."""
 

autocarver-7.3.3/AutoCarver/features/llm_qualifier.py

@@ -0,0 +1,185 @@
+"""Provider-agnostic helpers to qualify a DataFrame's columns into :class:`Features` via an LLM.
+
+These helpers never import any provider SDK. The caller supplies ``llm_fn``, a callable taking
+the prompt string and returning the model's raw text answer, so any backend can be plugged in.
+
+Anthropic example (latest model id ``claude-opus-4-8``)::
+
+    from anthropic import Anthropic
+
+    client = Anthropic()
+
+    def llm_fn(prompt: str) -> str:
+        msg = client.messages.create(
+            model="claude-opus-4-8",
+            max_tokens=2000,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return msg.content[0].text
+
+    features = qualify_with_llm(X, llm_fn)
+
+OpenAI example::
+
+    from openai import OpenAI
+
+    client = OpenAI()
+
+    def llm_fn(prompt: str) -> str:
+        resp = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return resp.choices[0].message.content
+
+    features = qualify_with_llm(X, llm_fn)
+"""
+
+import json
+from collections.abc import Callable
+
+import pandas as pd
+
+from AutoCarver.features.features import Features, FeaturesConfig
+
+# the JSON contract the model must follow, embedded in the prompt and used to parse the answer
+_SCHEMA_INSTRUCTIONS = """\
+Return ONLY a JSON object (no prose, no markdown fences) mapping every column name to an object
+describing its feature type. Each value must have a "type" field, one of:
+
+- "numerical": a quantitative column.
+- "categorical": an unordered qualitative column.
+- "ordinal": an ordered qualitative column. Add "values": the full list of categories from
+  smallest/lowest to largest/highest (strings).
+- "datetime": a date/time column. Add "reference": either the name of another datetime column
+  to measure elapsed time against, or a fixed date literal like "2020-01-01".
+- "nested": a fine-grained qualitative column that rolls up into coarser columns. Add "parents":
+  the list of coarser-ward parent column names, from nearest to farthest.
+- "ignore": a column that should not become a feature (ids, free text, leakage, etc.).
+
+Example:
+{"age": {"type": "numerical"},
+ "city": {"type": "categorical"},
+ "grade": {"type": "ordinal", "values": ["low", "medium", "high"]},
+ "signed_at": {"type": "datetime", "reference": "observed_at"},
+ "product": {"type": "nested", "parents": ["category", "division"]},
+ "user_id": {"type": "ignore"}}
+"""
+
+
+def build_qualification_prompt(X: pd.DataFrame, *, sample_size: int = 20) -> str:
+    """Builds the qualification prompt describing every column of ``X`` for the LLM.
+
+    Each column is summarised by its name, dtype, number of unique values and a small sample of
+    values so the model can infer its feature type and any ordering / hierarchy.
+
+    Parameters
+    ----------
+    X : pd.DataFrame
+        DataFrame whose columns are described.
+    sample_size : int, optional
+        Maximum number of sample values shown per column, by default ``20``.
+    """
+    lines = ["You are qualifying the columns of a tabular dataset for the AutoCarver library.", ""]
+    for col in X.columns:
+        series = X[col]
+        sample = series.dropna().unique()[:sample_size]
+        sample_repr = ", ".join(map(str, sample))
+        lines.append(f"- {col!r} (dtype={series.dtype}, n_unique={series.nunique()}): {sample_repr}")
+    lines += ["", _SCHEMA_INSTRUCTIONS]
+    return "\n".join(lines)
+
+
+def _require(spec: dict, key: str, col: str, kind: str):
+    """Returns ``spec[key]`` or raises a clear error naming the column and its kind."""
+    if key not in spec:
+        raise ValueError(f"[qualify] {kind} column {col!r} is missing its {key!r}.")
+    return spec[key]
+
+
+def specs_to_features_kwargs(mapping: dict) -> dict:
+    """Routes a ``{column: {"type": ..., ...}}`` mapping into :class:`Features` kwargs.
+
+    Returns a dict with the ``categoricals``, ``numericals``, ``ordinals``, ``datetimes`` and
+    ``nested`` keys expected by ``Features(**kwargs)``. ``ignore`` columns are dropped. Shared
+    by the LLM qualifier and the MCP session so the type-routing has a single source of truth.
+
+    Raises
+    ------
+    ValueError
+        If a column declares an unknown / incomplete type.
+    """
+    categoricals: list[str] = []
+    numericals: list[str] = []
+    ordinals: dict[str, list[str]] = {}
+    datetimes: list[tuple[str, str]] = []
+    nested: dict[str, list[str]] = {}
+
+    for col, spec in mapping.items():
+        kind = spec.get("type")
+        if kind == "numerical":
+            numericals.append(col)
+        elif kind == "categorical":
+            categoricals.append(col)
+        elif kind == "ordinal":
+            ordinals[col] = [str(value) for value in _require(spec, "values", col, kind)]
+        elif kind == "datetime":
+            datetimes.append((col, str(_require(spec, "reference", col, kind))))
+        elif kind == "nested":
+            nested[col] = [str(parent) for parent in _require(spec, "parents", col, kind)]
+        elif kind != "ignore":
+            raise ValueError(f"[qualify] column {col!r} has unknown type {kind!r}.")
+
+    return {
+        "categoricals": categoricals,
+        "numericals": numericals,
+        "ordinals": ordinals,
+        "datetimes": datetimes,
+        "nested": nested,
+    }
+
+
+def parse_qualification_response(response: str) -> dict:
+    """Parses the LLM's JSON answer into keyword arguments for :class:`Features`.
+
+    Extracts the JSON object from ``response`` and routes it through
+    :func:`specs_to_features_kwargs`.
+
+    Raises
+    ------
+    ValueError
+        If no JSON object can be parsed, or a column declares an unknown / incomplete type.
+    """
+    start, end = response.find("{"), response.rfind("}")
+    if start == -1 or end == -1 or end < start:
+        raise ValueError(f"[qualify] No JSON object found in LLM response: {response!r}")
+    try:
+        mapping = json.loads(response[start : end + 1])
+    except json.JSONDecodeError as error:
+        raise ValueError(f"[qualify] Could not parse JSON from LLM response: {error}") from error
+    return specs_to_features_kwargs(mapping)
+
+
+def qualify_with_llm(
+    X: pd.DataFrame,
+    llm_fn: Callable[[str], str],
+    *,
+    sample_size: int = 20,
+    config: FeaturesConfig | None = None,
+) -> Features:
+    """Builds a :class:`Features` by asking ``llm_fn`` to qualify every column of ``X``.
+
+    Parameters
+    ----------
+    X : pd.DataFrame
+        DataFrame whose columns are qualified.
+    llm_fn : Callable[[str], str]
+        Callable taking the prompt and returning the model's raw text answer.
+    sample_size : int, optional
+        Maximum number of sample values shown per column, by default ``20``.
+    config : FeaturesConfig, optional
+        Collection-level config propagated to each feature, by default ``None``.
+    """
+    prompt = build_qualification_prompt(X, sample_size=sample_size)
+    kwargs = parse_qualification_response(llm_fn(prompt))
+    return Features(config=config, **kwargs)

autocarver-7.3.3/AutoCarver/mcp/__init__.py

@@ -0,0 +1,63 @@
+"""AutoCarver MCP: a local server exposing the qualify-and-carve workflow as LLM tools.
+
+==============================================================================
+MCP setup (read this first if you are an AI assistant / LLM agent)
+==============================================================================
+Do **not** drive this package by importing :class:`CarverSession` and calling its
+methods by hand, and do **not** reimplement the qualify-and-carve steps yourself.
+The supported way to use it is the running MCP server, reached through your client's
+tool calls. To get there:
+
+1. Install the optional extra (the server needs ``fastmcp``, which is *not* a core
+   dependency)::
+
+       pip install "autocarver[mcp]"     # or:  uv add "autocarver[mcp]"
+
+2. Register the server with your MCP client so it launches over stdio.
+
+   VS Code / GitHub Copilot — add ``.vscode/mcp.json`` to the workspace::
+
+       {
+         "servers": {
+           "autocarver": {
+             "command": "uv",
+             "args": ["run", "python", "-m", "AutoCarver.mcp"]
+           }
+         }
+       }
+
+   Claude Desktop / Cursor — same shape in ``claude_desktop_config.json``, but the
+   top-level key is ``mcpServers`` instead of ``servers``.
+
+3. Reload the client and use the exposed tools (``load_dataset`` -> ``list_columns`` /
+   ``feature_distribution`` / ``validate_nesting`` -> ``suggest_features`` /
+   ``set_feature`` -> ``run_carver`` -> ``save_carver``). That is the qualify+carve
+   workflow — let the tools run it, rather than calling Python directly.
+
+Two things to keep in mind:
+
+* **Local data.** The server runs entirely on the user's machine; it reads files from their
+  filesystem and never sends the dataset to AutoCarver or any external service. The only data
+  leaving the machine is whatever you (the assistant) relay to your own LLM provider.
+* **Human review.** Feature qualification is LLM-dependent and can be wrong; tell the user to
+  review and confirm the feature definitions before any production use.
+
+The :class:`CarverSession` / :mod:`inspection` Python layers below exist so the tools
+are importable and unit-tested without ``fastmcp``; they are an implementation detail,
+not the entry point. See ``docs/source/mcp.rst`` for the full guide.
+==============================================================================
+"""
+
+from AutoCarver.mcp.session import CarverSession
+
+__all__ = ["CarverSession", "create_server", "main"]
+
+
+def __getattr__(name: str):
+    # lazily import the FastMCP-dependent server so the package (and its testable
+    # inspection/session layers) import fine even when fastmcp is unavailable.
+    if name in ("create_server", "main"):
+        from AutoCarver.mcp import server
+
+        return getattr(server, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

autocarver-7.3.3/AutoCarver/mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Run the AutoCarver MCP server: ``python -m AutoCarver.mcp``."""
+
+from AutoCarver.mcp.server import main
+
+if __name__ == "__main__":
+    main()

autocarver-7.3.3/AutoCarver/mcp/inspection.py

@@ -0,0 +1,168 @@
+"""Read-only data-inspection helpers backing the AutoCarver MCP tools.
+
+Pure functions over a ``DataFrame`` (no LLM, no MCP, no session state) so they can be unit
+tested directly and reused by data scientists. They return plain JSON-serialisable structures
+(dicts / lists) and never dump raw columns wholesale — only summaries — so they stay safe to
+hand to a model with a limited context window.
+
+Note for AI assistants: these helpers back the MCP tools but are not the entry point. To use
+AutoCarver from an MCP client, install ``autocarver[mcp]`` and run the server — see the setup
+guide in :mod:`AutoCarver.mcp` (``AutoCarver/mcp/__init__.py``).
+"""
+
+import pandas as pd
+
+from AutoCarver.discretizers.qualitatives.categorical_discretizer import (
+    series_target_rate,
+    series_value_counts,
+)
+from AutoCarver.discretizers.utils.frequency_ci import is_significantly_below
+from AutoCarver.features.features import infer_feature_kind
+
+
+def profile_dataframe(X: pd.DataFrame) -> list[dict]:
+    """One summary row per column: dtype, cardinality, missingness, suggested feature kind."""
+    rows = []
+    for col in X.columns:
+        series = X[col]
+        rows.append(
+            {
+                "column": str(col),
+                "dtype": str(series.dtype),
+                "n_unique": int(series.nunique(dropna=True)),
+                "n_missing": int(series.isna().sum()),
+                "missing_pct": round(float(series.isna().mean()), 4),
+                "suggested_kind": infer_feature_kind(series.dtype) or "unsupported",
+            }
+        )
+    return rows
+
+
+def profile_column(X: pd.DataFrame, column: str, *, top_n: int = 20) -> dict:
+    """Detailed profile of a single column: cardinality, missingness, and a kind-specific view.
+
+    Numeric / datetime columns report min/max/quantiles; qualitative columns report their most
+    frequent modalities (capped at ``top_n``).
+    """
+    if column not in X.columns:
+        raise ValueError(f"[inspection] column {column!r} not found.")
+    series = X[column]
+    kind = infer_feature_kind(series.dtype)
+    profile: dict = {
+        "column": column,
+        "dtype": str(series.dtype),
+        "suggested_kind": kind or "unsupported",
+        "n_unique": int(series.nunique(dropna=True)),
+        "n_missing": int(series.isna().sum()),
+        "missing_pct": round(float(series.isna().mean()), 4),
+    }
+    if kind in ("numerical", "datetime"):
+        non_null = series.dropna()
+        profile["min"] = str(non_null.min()) if not non_null.empty else None
+        profile["max"] = str(non_null.max()) if not non_null.empty else None
+        if kind == "numerical":
+            profile["quantiles"] = (
+                {str(q): round(float(non_null.quantile(q)), 6) for q in (0.0, 0.25, 0.5, 0.75, 1.0)}
+                if not non_null.empty
+                else {}
+            )
+    else:
+        counts = series_value_counts(series, dropna=False)
+        top = sorted(counts.items(), key=lambda kv: kv[1], reverse=True)[:top_n]
+        profile["top_values"] = [{"value": _key(k), "count": int(v)} for k, v in top]
+    return profile
+
+
+def feature_distribution(
+    X: pd.DataFrame,
+    column: str,
+    y: pd.Series | None = None,
+    *,
+    min_freq: float | None = None,
+    alpha: float = 0.05,
+    top_n: int = 50,
+) -> dict:
+    """Distribution of a qualitative column's modalities, optionally against the target.
+
+    Reports per-modality count and frequency, the target rate when ``y`` is given, and — when
+    ``min_freq`` is provided — flags modalities whose frequency is *significantly* below it
+    (Wilson upper bound, matching how the carvers decide rarity).
+    """
+    if column not in X.columns:
+        raise ValueError(f"[inspection] column {column!r} not found.")
+    series = X[column]
+    counts = series_value_counts(series, dropna=False)
+    nobs = int(series.notna().sum())
+    rates = series_target_rate(series, y, dropna=True) if y is not None else {}
+
+    modalities = []
+    for value, count in sorted(counts.items(), key=lambda kv: kv[1], reverse=True)[:top_n]:
+        entry = {
+            "value": _key(value),
+            "count": int(count),
+            "frequency": round(count / nobs, 6) if nobs else 0.0,
+        }
+        if y is not None and value in rates:
+            entry["target_rate"] = round(float(rates[value]), 6)
+        if min_freq is not None and value is not None:
+            entry["rare"] = bool(is_significantly_below(count, nobs, min_freq, alpha))
+        modalities.append(entry)
+
+    return {"column": column, "n_observations": nobs, "n_modalities": len(counts), "modalities": modalities}
+
+
+def validate_nesting(X: pd.DataFrame, child: str, parents: list[str]) -> dict:
+    """Checks that ``child`` rolls cleanly into ``parents`` (a many-to-one hierarchy).
+
+    For each consecutive (finer, coarser) level pair, verifies that every finer modality maps
+    to exactly one coarser modality. Returns whether the hierarchy is valid, the cardinality of
+    each level, and any violations (a finer modality spread across several coarser ones).
+    """
+    levels = [child] + list(parents)
+    missing = [c for c in levels if c not in X.columns]
+    if missing:
+        raise ValueError(f"[inspection] columns not found: {missing}")
+
+    cardinalities = {col: int(X[col].nunique(dropna=True)) for col in levels}
+    violations = []
+    for finer, coarser in zip(levels[:-1], levels[1:]):
+        pairs = X[[finer, coarser]].dropna()
+        spread = pairs.groupby(finer)[coarser].nunique()
+        for value in spread[spread > 1].index:
+            parent_values = sorted(map(str, pairs.loc[pairs[finer] == value, coarser].unique()))
+            violations.append({"level": finer, "value": _key(value), "parent": coarser, "maps_to": parent_values})
+
+    return {
+        "child": child,
+        "parents": list(parents),
+        "valid": len(violations) == 0,
+        "cardinalities": cardinalities,
+        "violations": violations,
+    }
+
+
+def datetime_reference_candidates(X: pd.DataFrame) -> list[dict]:
+    """Summarises each datetime column (span + coverage) to help pick a reference.
+
+    A good fixed reference / anchor is typically the column with the widest, most-complete
+    coverage; another datetime column can also be referenced row-wise.
+    """
+    candidates = []
+    for col in X.columns:
+        if not pd.api.types.is_datetime64_any_dtype(X[col]):
+            continue
+        non_null = X[col].dropna()
+        candidates.append(
+            {
+                "column": str(col),
+                "min": str(non_null.min()) if not non_null.empty else None,
+                "max": str(non_null.max()) if not non_null.empty else None,
+                "coverage_pct": round(float(X[col].notna().mean()), 4),
+            }
+        )
+    return candidates
+
+
+def _key(value):
+    """JSON-safe representation of a modality key (``None`` stays null, else stringified)."""
+    return None if value is None or pd.isna(value) else str(value)