philler 1.0.0__tar.gz

philler-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Krv Analytics
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

philler-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: philler
+Version: 1.0.0
+Summary: Phil: representation-guided multiverse imputation with Rust-backed ECT.
+Author-email: Krv Labs <team@krv.ai>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: trailed>=0.1.0
+Dynamic: license-file
+
+# Phil
+
+`Phil` is a representation-guided imputation library for missing tabular data.
+
+It generates multiple imputations using a configurable strategy grid, computes
+Euler Characteristic Transform (ECT) descriptors over each imputed dataset, and
+selects the most representative imputation from the candidate set.
+
+## Installation
+
+```bash
+pip install phil
+```
+
+`phil` requires the `trailed` backend for ECT computation. Install it from the
+KRV research index or provide a compatible local build.
+
+## What Phil Does
+
+1. **Impute** — runs a grid of imputation strategies (sklearn estimators or custom) over the input dataframe, producing a set of candidate datasets
+2. **Describe** — computes an ECT descriptor for each candidate via the `trailed` backend
+3. **Select** — picks the candidate closest to the mean descriptor (most representative imputation)
+4. **Transform** — exposes the fitted pipeline for inference on new data
+
+## Quick Start
+
+```python
+import pandas as pd
+from phil import Phil
+
+df = pd.read_csv("data_with_missing.csv")
+
+phil = Phil(samples=30, random_state=42)
+imputed_df = phil.fit(df)
+
+# Apply the same fitted pipeline to new data
+new_df = phil.transform(new_data)
+```
+
+### scikit-learn Pipeline Integration
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from phil import PhilTransformer
+
+pipe = Pipeline([
+    ("imputer", PhilTransformer(samples=20, random_state=0)),
+    ("model", RandomForestClassifier()),
+])
+pipe.fit(X_train, y_train)
+```
+
+## Configuration
+
+### Imputation grids
+
+`Phil` ships with named grids accessible via `GridGallery`:
+
+| Name          | Methods                                                     |
+| ------------- | ----------------------------------------------------------- |
+| `default`     | BayesianRidge, DecisionTree, RandomForest, GradientBoosting |
+| `sampling`    | DistributionImputer (empirical sampling)                    |
+| `finance`     | IterativeImputer, KNNImputer, SimpleImputer                 |
+| `healthcare`  | KNNImputer, SimpleImputer, IterativeImputer                 |
+| `marketing`   | SimpleImputer, KNNImputer, IterativeImputer                 |
+| `engineering` | SimpleImputer, KNNImputer, IterativeImputer                 |
+
+Pass a grid name or an `ImputationConfig` directly:
+
+```python
+from phil import Phil, ImputationConfig
+from sklearn.model_selection import ParameterGrid
+
+config = ImputationConfig(
+    methods=["KNNImputer"],
+    modules=["sklearn.impute"],
+    grids=[ParameterGrid({"n_neighbors": [3, 5, 7]})],
+)
+phil = Phil(param_grid=config)
+```
+
+### ECT descriptor
+
+ECT is configured via `ECTConfig`:
+
+```python
+from phil import Phil, ECTConfig
+
+ect_config = ECTConfig(
+    num_thetas=64,
+    radius=1.0,
+    resolution=100,
+    scale=500,
+    normalize=True,
+    seed=42,
+)
+phil = Phil(config=ect_config)
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -v
+uv run black phil/ tests/
+```

philler-1.0.0/README.md

@@ -0,0 +1,107 @@
+# Phil
+
+`Phil` is a representation-guided imputation library for missing tabular data.
+
+It generates multiple imputations using a configurable strategy grid, computes
+Euler Characteristic Transform (ECT) descriptors over each imputed dataset, and
+selects the most representative imputation from the candidate set.
+
+## Installation
+
+```bash
+pip install phil
+```
+
+`phil` requires the `trailed` backend for ECT computation. Install it from the
+KRV research index or provide a compatible local build.
+
+## What Phil Does
+
+1. **Impute** — runs a grid of imputation strategies (sklearn estimators or custom) over the input dataframe, producing a set of candidate datasets
+2. **Describe** — computes an ECT descriptor for each candidate via the `trailed` backend
+3. **Select** — picks the candidate closest to the mean descriptor (most representative imputation)
+4. **Transform** — exposes the fitted pipeline for inference on new data
+
+## Quick Start
+
+```python
+import pandas as pd
+from phil import Phil
+
+df = pd.read_csv("data_with_missing.csv")
+
+phil = Phil(samples=30, random_state=42)
+imputed_df = phil.fit(df)
+
+# Apply the same fitted pipeline to new data
+new_df = phil.transform(new_data)
+```
+
+### scikit-learn Pipeline Integration
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from phil import PhilTransformer
+
+pipe = Pipeline([
+    ("imputer", PhilTransformer(samples=20, random_state=0)),
+    ("model", RandomForestClassifier()),
+])
+pipe.fit(X_train, y_train)
+```
+
+## Configuration
+
+### Imputation grids
+
+`Phil` ships with named grids accessible via `GridGallery`:
+
+| Name          | Methods                                                     |
+| ------------- | ----------------------------------------------------------- |
+| `default`     | BayesianRidge, DecisionTree, RandomForest, GradientBoosting |
+| `sampling`    | DistributionImputer (empirical sampling)                    |
+| `finance`     | IterativeImputer, KNNImputer, SimpleImputer                 |
+| `healthcare`  | KNNImputer, SimpleImputer, IterativeImputer                 |
+| `marketing`   | SimpleImputer, KNNImputer, IterativeImputer                 |
+| `engineering` | SimpleImputer, KNNImputer, IterativeImputer                 |
+
+Pass a grid name or an `ImputationConfig` directly:
+
+```python
+from phil import Phil, ImputationConfig
+from sklearn.model_selection import ParameterGrid
+
+config = ImputationConfig(
+    methods=["KNNImputer"],
+    modules=["sklearn.impute"],
+    grids=[ParameterGrid({"n_neighbors": [3, 5, 7]})],
+)
+phil = Phil(param_grid=config)
+```
+
+### ECT descriptor
+
+ECT is configured via `ECTConfig`:
+
+```python
+from phil import Phil, ECTConfig
+
+ect_config = ECTConfig(
+    num_thetas=64,
+    radius=1.0,
+    resolution=100,
+    scale=500,
+    normalize=True,
+    seed=42,
+)
+phil = Phil(config=ect_config)
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -v
+uv run black phil/ tests/
+```

philler-1.0.0/phil/__init__.py

@@ -0,0 +1,21 @@
+"""
+Phil package.
+"""
+
+from phil.gallery import GridGallery
+from phil.imputation import DistributionImputer, ImputationConfig, PreprocessingConfig
+from phil.magic import ECT, ECTConfig
+from phil.phil import Phil
+from phil.transformers import PhilTransformer
+
+__version__ = "0.1.0"
+__all__ = [
+    "Phil",
+    "PhilTransformer",
+    "GridGallery",
+    "ECT",
+    "ECTConfig",
+    "ImputationConfig",
+    "PreprocessingConfig",
+    "DistributionImputer",
+]

philler-1.0.0/phil/gallery.py

@@ -0,0 +1,149 @@
+"""Collection of predefined configurations for Phil."""
+
+from typing import Dict
+
+import numpy as np
+from pydantic import BaseModel
+from sklearn.model_selection import ParameterGrid
+
+from phil.imputation import ImputationConfig, PreprocessingConfig
+from phil.magic import ECTConfig
+
+
+class GridGallery:
+    _grids = {
+        "default": ImputationConfig(
+            methods=[
+                "BayesianRidge",
+                "DecisionTreeRegressor",
+                "RandomForestRegressor",
+                "GradientBoostingRegressor",
+            ],
+            modules=[
+                "sklearn.linear_model",
+                "sklearn.tree",
+                "sklearn.ensemble",
+                "sklearn.ensemble",
+            ],
+            grids=[
+                ParameterGrid({"alpha": [1.0, 0.1, 0.01]}),
+                ParameterGrid(
+                    {"max_depth": [None, 5, 10], "min_samples_split": [2, 5]}
+                ),
+                ParameterGrid({"n_estimators": [10, 50], "max_depth": [None, 5]}),
+                ParameterGrid(
+                    {"learning_rate": [0.1, 0.01], "n_estimators": [50, 100]}
+                ),
+            ],
+        ),
+        "sampling": ImputationConfig(
+            methods=["DistributionImputer"],
+            modules=["phil.imputation"],
+            grids=[ParameterGrid({"random_state": np.arange(0, 100, 1)})],
+        ),
+        "finance": ImputationConfig(
+            methods=["IterativeImputer", "KNNImputer", "SimpleImputer"],
+            modules=["sklearn.impute"] * 3,
+            grids=[
+                ParameterGrid({"estimator": ["BayesianRidge"], "max_iter": [10, 50]}),
+                ParameterGrid(
+                    {"n_neighbors": [3, 5, 10], "weights": ["uniform", "distance"]}
+                ),
+                ParameterGrid({"strategy": ["mean", "median"]}),
+            ],
+        ),
+        "healthcare": ImputationConfig(
+            methods=["KNNImputer", "SimpleImputer", "IterativeImputer"],
+            modules=["sklearn.impute"] * 3,
+            grids=[
+                ParameterGrid({"n_neighbors": [5, 10], "weights": ["distance"]}),
+                ParameterGrid({"strategy": ["median", "most_frequent"]}),
+                ParameterGrid(
+                    {"estimator": ["RandomForestRegressor"], "max_iter": [10, 20]}
+                ),
+            ],
+        ),
+        "marketing": ImputationConfig(
+            methods=["SimpleImputer", "KNNImputer", "IterativeImputer"],
+            modules=["sklearn.impute"] * 3,
+            grids=[
+                ParameterGrid(
+                    {
+                        "strategy": ["most_frequent", "constant"],
+                        "fill_value": ["unknown"],
+                    }
+                ),
+                ParameterGrid({"n_neighbors": [3, 5], "weights": ["uniform"]}),
+                ParameterGrid(
+                    {"estimator": ["GradientBoostingRegressor"], "max_iter": [10, 30]}
+                ),
+            ],
+        ),
+        "engineering": ImputationConfig(
+            methods=["SimpleImputer", "KNNImputer", "IterativeImputer"],
+            modules=["sklearn.impute"] * 3,
+            grids=[
+                ParameterGrid({"strategy": ["mean", "median"]}),
+                ParameterGrid({"n_neighbors": [3, 5, 7], "weights": ["distance"]}),
+                ParameterGrid(
+                    {"estimator": ["DecisionTreeRegressor"], "max_iter": [10, 20]}
+                ),
+            ],
+        ),
+    }
+
+    @classmethod
+    def get(cls, name: str) -> ImputationConfig:
+        return cls._grids.get(name, cls._grids["default"])
+
+
+class ProcessingGallery:
+    _numeric_methods = {
+        "default": PreprocessingConfig(method="StandardScaler"),
+        "finance": PreprocessingConfig(
+            method="MinMaxScaler", params={"feature_range": [(0, 1)]}
+        ),
+        "healthcare": PreprocessingConfig(method="RobustScaler"),
+        "marketing": PreprocessingConfig(
+            method="PowerTransformer", params={"method": ["yeo-johnson"]}
+        ),
+        "engineering": PreprocessingConfig(method="StandardScaler"),
+    }
+
+    _categorical_methods = {
+        "default": PreprocessingConfig(method="OneHotEncoder"),
+        "finance": PreprocessingConfig(
+            method="OneHotEncoder", params={"handle_unknown": ["ignore"]}
+        ),
+        "healthcare": PreprocessingConfig(
+            method="OrdinalEncoder",
+            params={"handle_unknown": ["use_encoded_value"]},
+        ),
+        "marketing": PreprocessingConfig(
+            method="OneHotEncoder",
+            params={"sparse": [False], "handle_unknown": ["ignore"]},
+        ),
+    }
+
+    @classmethod
+    def get(cls, name: str = "default") -> Dict[str, PreprocessingConfig]:
+        return {
+            "num": cls._numeric_methods.get(name, cls._numeric_methods["default"]),
+            "cat": cls._categorical_methods.get(
+                name, cls._categorical_methods["default"]
+            ),
+        }
+
+
+class MagicGallery:
+    @staticmethod
+    def get(method: str) -> BaseModel:
+        if method == "ECT":
+            return ECTConfig(
+                num_thetas=64,
+                radius=1.0,
+                resolution=100,
+                scale=500,
+                seed=42,
+            )
+        raise ValueError(f"Unknown magic method: {method}")

philler-1.0.0/phil/imputation/__init__.py

@@ -0,0 +1,8 @@
+"""
+Phil imputation module.
+"""
+
+from .config import ImputationConfig, PreprocessingConfig
+from .distribution import DistributionImputer
+
+__all__ = ["DistributionImputer", "ImputationConfig", "PreprocessingConfig"]

philler-1.0.0/phil/imputation/config.py

@@ -0,0 +1,26 @@
+"""
+Configuration models for Phil's imputation strategies.
+"""
+
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, Field
+from sklearn.model_selection import ParameterGrid
+
+
+class ImputationConfig(BaseModel):
+    """Configuration for imputation methods and parameter grids."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    methods: List[str] = Field(..., description="Names of imputation methods")
+    modules: List[str] = Field(..., description="Python modules containing methods")
+    grids: List[ParameterGrid] = Field(..., description="Parameter grids for methods")
+
+
+class PreprocessingConfig(BaseModel):
+    """Configuration for data preprocessing steps."""
+
+    method: str
+    module: str = "sklearn.preprocessing"
+    params: Dict[str, Any] = Field(default_factory=dict)

philler-1.0.0/phil/imputation/distribution.py

@@ -0,0 +1,67 @@
+"""
+Distribution-preserving imputation strategies.
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator
+
+
+class DistributionImputer(BaseEstimator):
+    """Imputer that samples from empirical observed values."""
+
+    def __init__(self, missing_values=np.nan, random_state=None, threshold=1.0):
+        if not 0 <= threshold <= 1:
+            raise ValueError("threshold must be between 0 and 1")
+        self.missing_values = missing_values
+        self.random_state = random_state
+        self.threshold = threshold
+
+    def fit(self, X, y):
+        if not isinstance(y, (np.ndarray, pd.Series)):
+            y = np.asarray(y)
+
+        if y.ndim != 1:
+            raise ValueError("DistributionImputer only supports 1D y.")
+
+        self.dtype_ = y.dtype
+        self.is_categorical_ = y.dtype.kind in "OSU"
+
+        if not self.is_categorical_:
+            y = y.astype(float, copy=True)
+        else:
+            y = y.astype(object, copy=True)
+
+        missing_mask = (y == self.missing_values) | pd.isnull(y)
+        fraction_missing = missing_mask.sum() / y.size
+
+        if fraction_missing == 1.0:
+            self.skip_imputation_ = True
+            self.distribution_ = np.array([], dtype=self.dtype_)
+        else:
+            self.skip_imputation_ = fraction_missing > self.threshold
+            if not self.skip_imputation_:
+                self.distribution_ = y[~missing_mask]
+            else:
+                self.distribution_ = np.array([], dtype=self.dtype_)
+
+        if isinstance(self.random_state, np.random.RandomState):
+            self.rng_ = self.random_state
+        else:
+            self.rng_ = np.random.RandomState(self.random_state)
+
+        return self
+
+    def predict(self, X):
+        if not hasattr(self, "distribution_"):
+            raise RuntimeError("Call fit before predict")
+
+        n_samples = X.shape[0]
+
+        if self.skip_imputation_ or self.distribution_.size == 0:
+            if self.is_categorical_:
+                return np.full(n_samples, None, dtype=object)
+            return np.full(n_samples, np.nan, dtype=float)
+
+        predictions = self.rng_.choice(self.distribution_, size=n_samples, replace=True)
+        return predictions.astype(self.dtype_)

philler-1.0.0/phil/magic/__init__.py

@@ -0,0 +1,9 @@
+"""
+Phil magic module.
+"""
+
+from phil.magic.base import Magic
+from phil.magic.config import ECTConfig
+from phil.magic.ect import ECT
+
+__all__ = ["Magic", "ECT", "ECTConfig"]

philler-1.0.0/phil/magic/base.py

@@ -0,0 +1,18 @@
+"""
+Base interfaces for descriptor generation methods.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+import numpy as np
+from pydantic import BaseModel
+
+
+class Magic(ABC):
+    def __init__(self, config: BaseModel):
+        self.config = config
+
+    @abstractmethod
+    def generate(self, data: List[np.ndarray]) -> List[np.ndarray]:
+        pass

philler-1.0.0/phil/magic/config.py

@@ -0,0 +1,14 @@
+"""
+Euler Characteristic Transform (ECT) configuration.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ECTConfig(BaseModel):
+    num_thetas: int = Field(..., description="Number of angles to sample")
+    radius: float = Field(..., description="Maximum radius for filtration")
+    resolution: int = Field(..., description="Number of points per direction")
+    scale: int = Field(..., description="Scaling factor for point cloud")
+    normalize: bool = Field(True, description="Whether to normalize the ECT output")
+    seed: int = Field(0, description="Random seed for reproducibility")

philler-1.0.0/phil/magic/ect.py

@@ -0,0 +1,58 @@
+"""
+Euler Characteristic Transform implementation backed by Rust.
+"""
+
+from typing import List
+
+import numpy as np
+
+from . import rust_backend
+from .base import Magic
+from .config import ECTConfig
+
+
+class ECT(Magic):
+    def __init__(self, config: ECTConfig):
+        self.config = config
+        self.configure(**config.model_dump())
+
+    def configure(self, **kwargs):
+        for key, value in kwargs.items():
+            if hasattr(self.config, key):
+                setattr(self, key, value)
+            else:
+                raise ValueError(f"Invalid configuration key: {key}")
+
+    def generate(self, X: List[np.ndarray]) -> List[np.ndarray]:
+        if not isinstance(X, list):
+            raise ValueError("Input must be a list of numpy arrays")
+        if not X or any(x.size == 0 for x in X):
+            raise ValueError("Input cannot be empty")
+
+        scale = float(self.scale)
+        descriptors: List[np.ndarray] = []
+        for sample in X:
+            if np.ndim(sample) != 2:
+                raise ValueError("Each sample must be a 2D numpy array")
+            cloud = np.asarray(sample, dtype=np.float32)
+            descriptor = rust_backend.compute_ect_descriptor(
+                points=cloud,
+                num_thetas=self.num_thetas,
+                radius=self.radius,
+                resolution=self.resolution,
+                scale=scale,
+                seed=self.seed,
+            )
+            if self.normalize:
+                descriptor = self._normalize(descriptor)
+            descriptors.append(descriptor)
+
+        return descriptors
+
+    @staticmethod
+    def _normalize(arr: np.ndarray) -> np.ndarray:
+        lo = np.min(arr)
+        hi = np.max(arr)
+        if hi <= lo:
+            return np.zeros_like(arr)
+        return (arr - lo) / (hi - lo)

philler-1.0.0/phil/magic/rust_backend.py

@@ -0,0 +1,48 @@
+"""ECT backend adapter backed by the `trailed` package."""
+
+from __future__ import annotations
+
+import importlib
+
+import numpy as np
+
+
+def _load_backend():
+    try:
+        return importlib.import_module("trailed")
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError("No ECT backend found. Install `trailed`.") from exc
+
+
+_BACKEND = _load_backend()
+
+
+def compute_ect_descriptor(
+    points: np.ndarray,
+    num_thetas: int,
+    radius: float,
+    resolution: int,
+    scale: float,
+    seed: int,
+) -> np.ndarray:
+    """Compute a single-sample ECT descriptor with stable output shape.
+
+    Returns an array shaped [num_thetas, resolution].
+    """
+    points = np.asarray(points, dtype=np.float32)
+    ect = _BACKEND.compute_ect_from_numpy(
+        points=points,
+        num_thetas=num_thetas,
+        resolution=resolution,
+        radius=radius,
+        scale=scale,
+        seed=seed,
+        normalized=False,
+        parallel=True,
+    )
+    ect = np.asarray(ect, dtype=np.float32)
+    if ect.shape == (resolution, num_thetas):
+        return ect.T
+    if ect.shape == (num_thetas, resolution):
+        return ect
+    raise ValueError(f"Unexpected ECT shape from trailed backend: {ect.shape}")

philler-1.0.0/phil/phil.py

@@ -0,0 +1,221 @@
+import importlib
+import warnings
+from typing import Any, List, Tuple
+
+import numpy as np
+import pandas as pd
+from pydantic import BaseModel
+from sklearn.compose import ColumnTransformer
+from sklearn.exceptions import ConvergenceWarning
+from sklearn.impute import IterativeImputer
+from sklearn.pipeline import Pipeline
+
+from phil.gallery import GridGallery, MagicGallery, ProcessingGallery
+from phil.imputation import ImputationConfig
+from phil.magic import Magic
+import phil.magic as METHODS
+
+
+class Phil:
+    def __init__(
+        self,
+        samples: int = 30,
+        param_grid: str = "default",
+        magic: str = "ECT",
+        config=None,
+        random_state=None,
+    ):
+        self.config, self.magic = self._configure_magic_method(
+            magic=magic, config=config
+        )
+        self.samples = samples
+        self.param_grid = self._configure_param_grid(param_grid)
+        self.random_state = random_state
+        self.representations = []
+        self.magic_descriptors = []
+
+    def impute(self, df: pd.DataFrame, max_iter: int = 10) -> List[np.ndarray]:
+        if df.isnull().sum().sum() == 0:
+            raise ValueError("No missing values found in the input DataFrame.")
+        categorical_columns, numerical_columns = self._identify_column_types(df)
+        preprocessor = self._configure_preprocessor(
+            "default", categorical_columns, numerical_columns
+        )
+        imputers = self._create_imputers(preprocessor, max_iter)
+        self.selected_imputers = self._select_imputations(imputers)
+        return self._apply_imputations(df, self.selected_imputers)
+
+    @staticmethod
+    def _identify_column_types(df: pd.DataFrame) -> Tuple[List[str], List[str]]:
+        categorical_columns = df.select_dtypes(
+            include=["object", "category"]
+        ).columns.tolist()
+        numerical_columns = df.select_dtypes(
+            include=["number", "bool"]
+        ).columns.tolist()
+        return categorical_columns, numerical_columns
+
+    def _create_imputers(
+        self, preprocessor: ColumnTransformer, max_iter: int
+    ) -> List[Pipeline]:
+        imputers = []
+        for method, module, params in zip(
+            self.param_grid.methods,
+            self.param_grid.modules,
+            self.param_grid.grids,
+        ):
+            model = self._import_model(module, method)
+            for param_vals in params:
+                compatible_params = {
+                    k: v
+                    for k, v in param_vals.items()
+                    if k in model.__init__.__code__.co_varnames
+                }
+                estimator = model(**compatible_params)
+                imputers.append(self._build_pipeline(preprocessor, estimator, max_iter))
+        return imputers
+
+    @staticmethod
+    def _import_model(module: str, method: str):
+        imported_module = importlib.import_module(module)
+        return getattr(imported_module, method)
+
+    def _build_pipeline(
+        self, preprocessor: ColumnTransformer, estimator, max_iter: int
+    ) -> Pipeline:
+        return Pipeline(
+            [
+                ("preprocessor", preprocessor),
+                (
+                    "imputer",
+                    IterativeImputer(
+                        estimator=estimator,
+                        random_state=self.random_state,
+                        max_iter=max_iter,
+                    ),
+                ),
+            ]
+        )
+
+    def _select_imputations(self, imputers: List[Pipeline]) -> List[Pipeline]:
+        np.random.seed(self.random_state)
+        selected_idxs = np.random.choice(
+            range(len(imputers)),
+            min(self.samples, len(imputers)),
+            replace=False,
+        )
+        return [imputers[idx] for idx in selected_idxs]
+
+    def _apply_imputations(
+        self, df: pd.DataFrame, imputers: List[Pipeline]
+    ) -> List[np.ndarray]:
+        imputations = []
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=ConvergenceWarning)
+            for imputer in imputers:
+                imputer.fit(df)
+                imputations.append(imputer.transform(df))
+            return imputations
+
+    def generate_descriptors(self) -> List[np.ndarray]:
+        return self.magic.generate(self.representations)
+
+    def fit(self, df: pd.DataFrame, max_iter: int = 5) -> pd.DataFrame:
+        self.representations = self.impute(df, max_iter)
+        self.magic_descriptors = self.generate_descriptors()
+
+        assert len(self.representations) == len(self.magic_descriptors)
+        self.closest_index = self._select_representative(self.magic_descriptors)
+        X = self.representations[self.closest_index]
+        self.pipeline = self.selected_imputers[self.closest_index]
+        imputed_columns = self._get_imputed_columns(
+            transformer=self.pipeline["preprocessor"]
+        )
+        return pd.DataFrame(X, columns=imputed_columns)
+
+    def transform(self, df: pd.DataFrame, max_iter: int = 5) -> pd.DataFrame:
+        if not hasattr(self, "pipeline"):
+            raise RuntimeError("Pipeline not fitted. Call `fit` first.")
+
+        imputed_columns = self._get_imputed_columns(
+            transformer=self.pipeline["preprocessor"]
+        )
+        return pd.DataFrame(self.pipeline.transform(df), columns=imputed_columns)
+
+    @staticmethod
+    def _get_imputed_columns(transformer: ColumnTransformer) -> List[str]:
+        return transformer.get_feature_names_out()
+
+    @staticmethod
+    def _select_representative(descriptors: List[np.ndarray]) -> int:
+        stacked = np.stack(descriptors)
+        avg_descriptor = stacked.mean(axis=0)
+        norms = np.linalg.norm(
+            (stacked - avg_descriptor).reshape(len(descriptors), -1), axis=1
+        )
+        return int(np.argmin(norms))
+
+    @staticmethod
+    def _configure_magic_method(magic: str, config) -> Tuple[BaseModel, Magic]:
+        magic_method = getattr(METHODS, magic, None)
+        if magic_method is None:
+            raise ValueError(f"Magic method '{magic}' not found.")
+        if not isinstance(config, BaseModel):
+            config = MagicGallery.get(magic)
+        return config, magic_method(config=config)
+
+    @staticmethod
+    def _configure_param_grid(param_grid) -> ImputationConfig:
+        if isinstance(param_grid, str):
+            return GridGallery.get(param_grid)
+        if isinstance(param_grid, ImputationConfig):
+            return param_grid
+        if isinstance(param_grid, BaseModel):
+            if (
+                not hasattr(param_grid, "methods")
+                or not hasattr(param_grid, "modules")
+                or not hasattr(param_grid, "grids")
+            ):
+                raise ValueError("Invalid parameter grid configuration.")
+            return ImputationConfig(
+                methods=param_grid.methods,
+                modules=param_grid.modules,
+                grids=param_grid.grids,
+            )
+        if isinstance(param_grid, dict):
+            if not all(key in param_grid for key in ["methods", "modules", "grids"]):
+                raise ValueError("Invalid parameter grid configuration.")
+            return ImputationConfig(
+                methods=param_grid["methods"],
+                modules=param_grid["modules"],
+                grids=param_grid["grids"],
+            )
+        raise ValueError("Invalid parameter grid type.")
+
+    @staticmethod
+    def _configure_preprocessor(
+        strategy: str,
+        categorical_columns: List[str],
+        numerical_columns: List[str],
+    ) -> ColumnTransformer:
+        strategy = ProcessingGallery.get(strategy)
+        transformers: List[Tuple[str, Any, List[str]]] = []
+
+        for key, preprocessing_config in strategy.items():
+            try:
+                model = Phil._import_model(
+                    preprocessing_config.module, preprocessing_config.method
+                )
+            except (ImportError, AttributeError) as e:
+                raise RuntimeError(
+                    f"Failed to import model {preprocessing_config.method} from module {preprocessing_config.module}: {e}"
+                )
+
+            transformer = model(**preprocessing_config.params)
+
+            if key == "num" and len(numerical_columns) > 0:
+                transformers.append((key, transformer, numerical_columns))
+            elif key == "cat" and len(categorical_columns) > 0:
+                transformers.append((key, transformer, categorical_columns))
+
+        return ColumnTransformer(transformers, verbose_feature_names_out=True)

philler-1.0.0/phil/transformers.py

@@ -0,0 +1,52 @@
+"""
+Scikit-learn compatible transformers for Phil.
+"""
+
+from typing import Any, Optional, Union
+
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+
+from phil.imputation import ImputationConfig
+from phil.phil import Phil
+
+
+class PhilTransformer(BaseEstimator, TransformerMixin):
+    def __init__(
+        self,
+        samples: int = 30,
+        param_grid: Union[str, ImputationConfig] = "default",
+        magic: str = "ECT",
+        config: Optional[dict] = None,
+        random_state: Optional[int] = None,
+        max_iter: int = 5,
+    ):
+        self.samples = samples
+        self.param_grid = param_grid
+        self.magic = magic
+        self.config = config
+        self.random_state = random_state
+        self.max_iter = max_iter
+        self.phil = None
+
+    def fit(self, X: pd.DataFrame, y: Any = None) -> "PhilTransformer":
+        self.feature_names_in_ = X.columns.tolist()
+        self.n_features_in_ = len(self.feature_names_in_)
+
+        self.phil = Phil(
+            samples=self.samples,
+            param_grid=self.param_grid,
+            magic=self.magic,
+            config=self.config,
+            random_state=self.random_state,
+        )
+        self.phil.fit(X, max_iter=self.max_iter)
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        if self.phil is None:
+            raise RuntimeError(
+                "This PhilTransformer instance is not fitted yet. "
+                "Call 'fit' before using this estimator."
+            )
+        return self.phil.transform(X, max_iter=self.max_iter)

philler-1.0.0/philler.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: philler
+Version: 1.0.0
+Summary: Phil: representation-guided multiverse imputation with Rust-backed ECT.
+Author-email: Krv Labs <team@krv.ai>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: trailed>=0.1.0
+Dynamic: license-file
+
+# Phil
+
+`Phil` is a representation-guided imputation library for missing tabular data.
+
+It generates multiple imputations using a configurable strategy grid, computes
+Euler Characteristic Transform (ECT) descriptors over each imputed dataset, and
+selects the most representative imputation from the candidate set.
+
+## Installation
+
+```bash
+pip install phil
+```
+
+`phil` requires the `trailed` backend for ECT computation. Install it from the
+KRV research index or provide a compatible local build.
+
+## What Phil Does
+
+1. **Impute** — runs a grid of imputation strategies (sklearn estimators or custom) over the input dataframe, producing a set of candidate datasets
+2. **Describe** — computes an ECT descriptor for each candidate via the `trailed` backend
+3. **Select** — picks the candidate closest to the mean descriptor (most representative imputation)
+4. **Transform** — exposes the fitted pipeline for inference on new data
+
+## Quick Start
+
+```python
+import pandas as pd
+from phil import Phil
+
+df = pd.read_csv("data_with_missing.csv")
+
+phil = Phil(samples=30, random_state=42)
+imputed_df = phil.fit(df)
+
+# Apply the same fitted pipeline to new data
+new_df = phil.transform(new_data)
+```
+
+### scikit-learn Pipeline Integration
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import RandomForestClassifier
+from phil import PhilTransformer
+
+pipe = Pipeline([
+    ("imputer", PhilTransformer(samples=20, random_state=0)),
+    ("model", RandomForestClassifier()),
+])
+pipe.fit(X_train, y_train)
+```
+
+## Configuration
+
+### Imputation grids
+
+`Phil` ships with named grids accessible via `GridGallery`:
+
+| Name          | Methods                                                     |
+| ------------- | ----------------------------------------------------------- |
+| `default`     | BayesianRidge, DecisionTree, RandomForest, GradientBoosting |
+| `sampling`    | DistributionImputer (empirical sampling)                    |
+| `finance`     | IterativeImputer, KNNImputer, SimpleImputer                 |
+| `healthcare`  | KNNImputer, SimpleImputer, IterativeImputer                 |
+| `marketing`   | SimpleImputer, KNNImputer, IterativeImputer                 |
+| `engineering` | SimpleImputer, KNNImputer, IterativeImputer                 |
+
+Pass a grid name or an `ImputationConfig` directly:
+
+```python
+from phil import Phil, ImputationConfig
+from sklearn.model_selection import ParameterGrid
+
+config = ImputationConfig(
+    methods=["KNNImputer"],
+    modules=["sklearn.impute"],
+    grids=[ParameterGrid({"n_neighbors": [3, 5, 7]})],
+)
+phil = Phil(param_grid=config)
+```
+
+### ECT descriptor
+
+ECT is configured via `ECTConfig`:
+
+```python
+from phil import Phil, ECTConfig
+
+ect_config = ECTConfig(
+    num_thetas=64,
+    radius=1.0,
+    resolution=100,
+    scale=500,
+    normalize=True,
+    seed=42,
+)
+phil = Phil(config=ect_config)
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -v
+uv run black phil/ tests/
+```

philler-1.0.0/philler.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+phil/__init__.py
+phil/gallery.py
+phil/phil.py
+phil/transformers.py
+phil/imputation/__init__.py
+phil/imputation/config.py
+phil/imputation/distribution.py
+phil/magic/__init__.py
+phil/magic/base.py
+phil/magic/config.py
+phil/magic/ect.py
+phil/magic/rust_backend.py
+philler.egg-info/PKG-INFO
+philler.egg-info/SOURCES.txt
+philler.egg-info/dependency_links.txt
+philler.egg-info/requires.txt
+philler.egg-info/top_level.txt

philler-1.0.0/philler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

philler-1.0.0/philler.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pandas>=2.2.3
+pydantic>=2.10.6
+scikit-learn>=1.6.1
+scipy>=1.15.2
+trailed>=0.1.0

philler-1.0.0/philler.egg-info/top_level.txt

@@ -0,0 +1 @@
+phil

philler-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "philler"
+version = "1.0.0"
+authors = [
+    {name = "Krv Labs", email = "team@krv.ai"}
+]
+description = "Phil: representation-guided multiverse imputation with Rust-backed ECT."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.2.3",
+    "pydantic>=2.10.6",
+    "scikit-learn>=1.6.1",
+    "scipy>=1.15.2",
+    "trailed>=0.1.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages]
+find = {include = ["phil", "phil.*"]}
+
+[tool.uv.sources]
+trailed = { index = "krv-research" }
+
+[[tool.uv.index]]
+name = "krv-research"
+url = "https://api.pyx.dev/simple/krv/research"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "ipykernel>=6.29.5",
+    "pdoc>=15.0.1",
+    "pytest>=8.3.5",
+    "pytest-cov>=6.1.1",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.15.8",
+]

philler-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+