Simple API¶

Zero-friction one-liner functions. Each runs the relevant pipeline stages and returns a frozen dataclass. No setup, no configuration — just call a function.

Available Functions¶

Function	Stages Run	Returns	Use Case
`analyze(path)`	Upload → ETL → Validation → EDA	`DatasetProfile`	Quick data profiling
`clean(path)`	Upload → ETL	`CleanResult`	Data cleaning only
`validate(path)`	Upload → ETL → Validation	`ValidationResult`	Quality checks
`detect_target(path)`	Upload → ... → Target Detection	`TargetResult`	Find prediction target
`detect_task(path)`	Upload → ... → Task Detection	`TaskDetectionResult`	Detect task type
`engineer(path)`	Upload → ... → Feature Engineering	`FeatureResult`	Feature pipeline
`select_model(path)`	Upload → ... → Model Selection + Evaluation	`ModelResult`	Model comparison
`recommend(path)`	Upload → ... → Model Selection + Evaluation	`ModelResult`	Model recommendation (alias of `select_model`)
`evaluate(path)`	Upload → ... → Model Selection + Evaluation	`ModelResult`	Evaluation (alias of `select_model`)
`explain(path)`	Upload → ... → Explainability	`ExplainResult`	Feature importance
`report(path)`	Upload → ... → Reporting	`str` (Markdown)	Full report
`train(path)`	All 11 stages	`TrainResult`	Complete pipeline
`profile(path)`	Upload → ETL → Validation → EDA	`DatasetProfile`	Alias of `analyze`
`predict(path, data)`	Train, then predict	`list`	Train + predict on new rows
`compare(path, models)`	Train several models	`ModelComparison`	Rank model families
`cluster(path)`	Unsupervised clustering	`ClusteringResult`	Cluster analysis
`detect_anomalies(path)`	Unsupervised anomaly detection	`AnomalyResult`	Outlier detection
`save(path, dir)`	All stages + persist	`dict`	Persist artifacts + model
`restore(dir)`	Load saved run	`SavedRun`	Offline prediction
`load(dir)`	Load saved run	`SavedRun`	Alias of `restore`
`version()`	—	`str`	Installed version
`capabilities()`	—	`dict`	SDK capability report
`health()`	—	`dict`	Offline self-check

Basic Usage¶

Profile a Dataset¶

from phronesisml import analyze

profile = analyze("data.csv")
print(f"Shape: {profile.shape}")
print(f"Memory: {profile.memory_usage_bytes / 1024:.1f} KB")
print(f"Columns: {profile.column_names}")
print(f"Numeric summary: {profile.numeric_summary}")

Train a Model¶

from phronesisml import train

result = train("data.csv")
print(f"Best model: {result.best_model_type}")
print(f"Score: {result.best_score:.4f}")
print(result.report[:500])  # First 500 chars of the report

Clean Data¶

from phronesisml import clean

result = clean("messy_data.csv", null_strategy="fill")
print(f"Rows after cleaning: {result.n_rows}")

Engine Selection¶

Force a specific engine with the engine parameter:

# Use Polars for faster processing
profile = analyze("data.csv", engine="polars")

# Use Pandas for compatibility
result = train("data.csv", engine="pandas")

# Use Spark for large datasets
profile = analyze("huge_data.csv", engine="spark")

Auto-selection (default):

Data Size	Engine
< 2 MB	Pandas
2–500 MB	Polars
> 500 MB	Spark

Null Handling¶

Control how nulls are handled during the ETL stage:

# Drop rows with nulls (default)
result = clean("data.csv", null_strategy="drop")

# Fill nulls (strategy-level; value handling is config-driven)
result = clean("data.csv", null_strategy="fill")

# Flag nulls as separate columns
result = clean("data.csv", null_strategy="flag")

Strategy Comparison¶

Strategy	Row Count	Columns	Best For
`"drop"`	Decreases	Same	Clean datasets
`"fill"`	Preserves	Same	When you need all rows
`"flag"`	Preserves	Increases	When nullity is informative

Result Types¶

Each function returns a specific frozen dataclass:

DatasetProfile (from `analyze`)¶

profile = analyze("data.csv")

profile.shape              # (rows, columns)
profile.memory_usage_bytes # int
profile.column_names       # list[str]
profile.missing_counts     # dict[str, int]
profile.validation_passed  # bool

TrainResult (from `train`)¶

result = train("data.csv")

result.best_model_type     # str (e.g. "random_forest")
result.best_score          # float
result.report              # str (full Markdown report)

ModelResult (from `select_model`)¶

result = select_model("data.csv")

result.best_model_type     # str
result.best_score          # float
result.candidates          # list[dict] (all evaluated models)

Async Variants¶

Every function has an _async variant for use inside a running async context (e.g. Jupyter async cells, your own asyncio app):

from phronesisml import analyze_async, train_async

# In an async context
profile = await analyze_async("data.csv")
result = await train_async("data.csv")

Warning

The sync functions use asyncio.run() internally. Do not call them from inside a running event loop (Jupyter async cells). Use the _async variants instead.

Error Handling¶

All functions raise PhronesisError subclasses on failure:

from phronesisml import analyze
from phronesisml.exceptions import DataLoadError, DataValidationError

try:
    profile = analyze("data.csv")
except DataLoadError as e:
    print(f"Failed to load data: {e}")
except DataValidationError as e:
    print(f"Data validation failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Complete Example¶

from phronesisml import analyze, clean, train, detect_target

# Step 1: Profile
profile = analyze("customers.csv", engine="polars")
print(f"Dataset: {profile.shape[0]} rows, {profile.shape[1]} columns")

# Step 2: Clean
result = clean("customers.csv", null_strategy="fill")
print(f"Cleaned: {result.n_rows} rows")

# Step 3: Detect target
target = detect_target("customers.csv")
print(f"Target: {target.column} ({target.task_type})")

# Step 4: Train
result = train("customers.csv")
print(f"Best model: {result.best_model_type} (score: {result.best_score:.4f})")