Phil

Representation-guided imputation for missing tabular data — PyPI package philler (import: phil).

Phil runs a grid of imputation strategies, scores each candidate with an Euler Characteristic Transform (ECT) descriptor via the trailed backend, and selects the most representative result.

Impute → Describe → Select → Transform

Installation

pip install philler          # core library
pip install "philler[mcp]"   # + FastMCP server for agents

Quick start

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)
new_df = phil.transform(new_data)  # reuse fitted pipeline

MCP server — run sweeps from Claude, Cursor, Gemini CLI, etc.

Install the mcp extra and start the server:

pip install "philler[mcp]"
phil-mcp
# or ephemeral: uv tool run --from "philler[mcp]" phil-mcp

Example Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "phil": {
      "command": "uv tool run",
      "args": ["--from", "philler[mcp]", "phil-mcp"]
    }
  }
}

Key tools: ingest_dataset, characterize_dataset, recommend_grid, list_grids, create_config, validate_config, run_imputation_sweep, diagnose_sweep, export_imputed_data.

Agents can read phil://docs/imputation-matrix for grid comparison metadata. Polars users write to Parquet and ingest the file path.

See docs/source/userGuides/mcp.rst for the full tool table and example dialog. Local end-to-end testing: demos/medical.

Configuration — grids and ECT settings

Imputation grids

Named grids 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

Custom grid:

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

from phil import Phil, ECTConfig

phil = Phil(config=ECTConfig(num_thetas=64, radius=1.0, resolution=100, scale=500, normalize=True, seed=42))

scikit-learn pipelines

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)

What's new in v1.1.0

FastMCP server — phil-mcp exposes the imputation sweep pipeline as MCP tools for agents.
Grid recommender — recommend_grid, declarative GridMetadata, and the phil://docs/imputation-matrix resource.
Medical demo — demos/medical with covariate sampling, masked iterative imputation, and MDS visualization of descriptor space.

See CHANGELOG.md for full release notes.

Development

uv sync --all-extras
uv run pytest -v
uvx ruff format phil/ tests/
uvx ruff check phil/ tests/

Contributors: see AGENTS.md for package layout and design notes.

Documentation

Sphinx docs live under docs/source. Build locally:

uv run sphinx-build -M html docs/source docs/build

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

philler-1.1.0.tar.gz (45.9 kB view details)

Uploaded Jul 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

philler-1.1.0-py3-none-any.whl (50.7 kB view details)

Uploaded Jul 30, 2026 Python 3

File details

Details for the file philler-1.1.0.tar.gz.

File metadata

Download URL: philler-1.1.0.tar.gz
Upload date: Jul 30, 2026
Size: 45.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for philler-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`19becf162504f8db1a5196aa507a70f7e0d0246cdb48334a9a29897fd46b8964`
MD5	`abfdbf398682e2359195296158c0d849`
BLAKE2b-256	`b78e19e4438daeb0d9b97715a3a6e1ba213a66ae0cf392e213f4d015d40c124d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for philler-1.1.0.tar.gz:

Publisher: release.yml on Krv-Labs/phil

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: philler-1.1.0.tar.gz
- Subject digest: 19becf162504f8db1a5196aa507a70f7e0d0246cdb48334a9a29897fd46b8964
- Sigstore transparency entry: 2288228520
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Krv-Labs/phil@e8d91241eb0580813916d5d3d3f83d7e027d1688
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/Krv-Labs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e8d91241eb0580813916d5d3d3f83d7e027d1688
- Trigger Event: push

File details

Details for the file philler-1.1.0-py3-none-any.whl.

File metadata

Download URL: philler-1.1.0-py3-none-any.whl
Upload date: Jul 30, 2026
Size: 50.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for philler-1.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`6244cca5f1f2eb8fb08133cb11cbdf2b9d825f60ed46d6beaa60025ef0581442`
MD5	`97b4e90f2450495e6a28b0a94eb4a68c`
BLAKE2b-256	`fd8ed5875d2743aa78421491eea138add574b1b9a305bc0dc132587b1119215a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for philler-1.1.0-py3-none-any.whl:

Publisher: release.yml on Krv-Labs/phil

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: philler-1.1.0-py3-none-any.whl
- Subject digest: 6244cca5f1f2eb8fb08133cb11cbdf2b9d825f60ed46d6beaa60025ef0581442
- Sigstore transparency entry: 2288228579
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: Krv-Labs/phil@e8d91241eb0580813916d5d3d3f83d7e027d1688
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/Krv-Labs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e8d91241eb0580813916d5d3d3f83d7e027d1688
- Trigger Event: push

Release history Release notifications | RSS feed

This release

1.1.0 This release

Jul 30, 2026 2 files

1.0.1

Apr 1, 2026 2 files

1.0.0

Mar 27, 2026 2 files

philler 1.1.0

Phil

Installation

Quick start

Imputation grids

ECT descriptor

Key dates

Owner

Credits

Requires

Provides Extra

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed