API Reference

Phronesis (OOP API)

The main entry point. Wraps the full LangGraph pipeline behind method-chained calls.

phronesisml.sdk.Phronesis(data_path, config=None, agent_overrides=None)

High-level SDK for automated machine learning.

Phronesis provides an intuitive interface over the internal LangGraph pipeline. Every method delegates to existing agents without duplicating business logic.

Parameters:

Name	Type	Description	Default
data_path	str	Path to a dataset (CSV, Excel, JSON, Parquet, etc.).	required
config	Any | None	Optional PhronesisConfig. If None, defaults are used and can be overridden via property setters.	None

Example::

from phronesisml import Phronesis

ml = Phronesis("customers.csv")
ml.run()
print(ml.report())

load()

Load the dataset from disk.

Detects file format automatically. For Excel files with multiple sheets, selects the sheet with the most data.

Returns:

Type	Description
Phronesis	self for method chaining.

summary()

Return a structured summary of the loaded dataset.

Runs load() automatically if not already done.

Returns:

Type	Description
DatasetSummary	A DatasetSummary with rows, columns, dtypes, memory,
DatasetSummary	missing values, duplicates, and a preview DataFrame.

clean(null_strategy=None)

Clean and transform raw data (ETL stage).

Applies null handling, type casting, and categorical encoding.

Parameters:

Name	Type	Description	Default
null_strategy	str | None	"drop", "fill", or "flag". Overrides the constructor default if provided.	None

Returns:

Type	Description
Phronesis	self for method chaining.

validate()

Run data validation checks.

Checks: empty data, zero columns, null analysis, duplicates.

Returns:

Type	Description
ValidationReport	A ValidationReport with pass/fail status and details.

eda()

Run exploratory data analysis.

Computes statistical summaries, distributions, correlations, and column-level insights.

Returns:

Type	Description
EDAReport	An EDAReport with numeric/categorical summaries.

detect_target()

Automatically detect the prediction target and task type.

Returns:

Type	Description
TargetInfo	A TargetInfo with the detected column, task type,
TargetInfo	confidence, and reasoning.

engineer_features()

Engineer features: encode, scale, handle outliers, select.

Returns:

Type	Description
FeatureReport	A FeatureReport with the engineered feature names
FeatureReport	and the resulting DataFrame.

recommend_model(cv=None, model_type=None)

Recommend and train the best model for the dataset.

Evaluates multiple candidate models and selects the best one based on cross-validation performance.

Parameters:

Name	Type	Description	Default
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split. Pass an integer ≥ 2 to enable k-fold cross-validation.	None
model_type	str | None	Optional name of a specific model to train (e.g. "random_forest"). If provided, trains only that model instead of selecting the best from all candidates.	None

Returns:

Type	Description
ModelInfo	A ModelInfo with the selected model, score, candidates,
ModelInfo	training details, and estimated cost.

train(cv=None, model_type=None)

Alias for recommend_model().

Trains the recommended model on the engineered features.

Parameters:

Name	Type	Description	Default
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split.	None
model_type	str | None	Optional name of a specific model to train.	None

Returns:

Type	Description
ModelInfo	A ModelInfo.

evaluate()

Evaluate the trained model.

Computes task-appropriate metrics (accuracy, precision, recall, F1 for classification; RMSE, MAE, R2 for regression).

Returns:

Type	Description
EvaluationMetrics	An EvaluationMetrics with all computed metrics.

explain()

Explain model predictions using SHAP.

Computes feature importance based on SHAP values. SHAP is a core dependency and is always available.

Returns:

Type	Description
ExplanationReport	An ExplanationReport with feature importance scores.

report()

Generate a full Markdown report of the pipeline run.

Runs all stages up to reporting if not already done.

Returns:

Type	Description
str	A Markdown string containing the complete pipeline report.

generate_report(format='markdown')

Generate a pipeline report in the specified format.

Parameters:

Name	Type	Description	Default
format	str	Output format. "markdown" (default) returns a Markdown string. "html" returns a self-contained HTML document. "pdf" raises NotImplementedError.	'markdown'

Returns:

Type	Description
str	A string containing the report in the requested format.

Raises:

Type	Description
NotImplementedError	If format is "pdf".

run(mode='balanced')

Execute the complete ML pipeline end-to-end.

Runs all 11 stages: upload, ETL, validation, EDA, target detection, feature engineering, model selection, evaluation, explainability, reporting, and storage.

Parameters:

Name	Type	Description	Default
mode	str	Execution mode controlling which stages run. - "fast": Skips explainability and storage. Recommended for quick prototyping. - "balanced": Full pipeline (default). - "full": Same as balanced, explicit for clarity.	'balanced'

Returns:

Type	Description
Phronesis	self for method chaining.

Example::

ml = Phronesis("data.csv")
ml.run(mode="fast")  # Quick results
ml.run()             # Full pipeline

get_data()

Return the raw loaded DataFrame.

Runs load() automatically if not yet done.

get_cleaned_data()

Return the cleaned (post-ETL) DataFrame.

Runs clean() automatically if not yet done.

get_features()

Return the engineered feature DataFrame.

Runs engineer_features() automatically if not yet done.

get_model()

Return the trained sklearn model object.

Runs train() automatically if not yet done.

Result Types

phronesisml.sdk.DatasetSummary(rows, columns, column_names, dtypes, memory_bytes, missing_values, duplicate_rows, numeric_columns, categorical_columns, preview) dataclass

Structured summary of a loaded dataset.

memory_mb property

Memory usage in megabytes.

phronesisml.sdk.ValidationReport(passed, rows, columns, null_counts, null_columns, empty_columns, duplicate_rows, raw) dataclass

Result of data validation checks.

phronesisml.sdk.EDAReport(shape, numeric_columns, categorical_columns, numeric_summary, categorical_summary, memory_bytes, raw) dataclass

Exploratory data analysis results.

phronesisml.sdk.TargetInfo(column, task_type, confidence, ambiguity_reason, candidates) dataclass

Result of automatic target detection.

phronesisml.sdk.FeatureReport(feature_names, n_features, n_rows, features) dataclass

Result of feature engineering.

phronesisml.sdk.ModelInfo(model_type, score, candidates, best_params, truncated, trials_used, time_elapsed, estimated_training_cost='unknown') dataclass

Recommended model details.

phronesisml.sdk.EvaluationMetrics(accuracy=None, precision_macro=None, recall_macro=None, f1_macro=None, roc_auc=None, confusion_matrix=None, rmse=None, mae=None, r2=None, ambiguity_caveat=None, raw=dict()) dataclass

Model evaluation results.

phronesisml.sdk.ExplanationReport(feature_importance, explainer_type, sampled, n_samples_used, n_features_used=0, max_samples=0) dataclass

SHAP-based model explanation results.

---

Simple API

Zero-friction one-liner functions. Each runs the relevant pipeline stages and returns a frozen dataclass. Every function has a *_async twin with the same signature.

phronesisml.simple.analyze(path, *, engine=None, null_strategy='drop')

Load, clean, validate, and profile a dataset.

Runs upload, ETL, validation, and EDA stages. Returns a structured dataset profile with shape, dtypes, per-column statistics, and memory usage.

Parameters:

Name	Type	Description	Default
path	str	Path to a CSV, Excel, JSON, or Parquet file.	required
engine	str | None	Force a specific engine ("pandas", "polars", "spark"). None for auto-selection.	None
null_strategy	str	Null handling strategy ("drop", "fill", "flag"). Default "drop".	'drop'

Returns:

Type	Description
DatasetProfile	A DatasetProfile with shape, dtypes, summaries, and
DatasetProfile	memory usage.

Example::

from phronesisml import analyze

profile = analyze("data.csv")
print(f"{profile.shape[0]} rows, {profile.shape[1]} columns")
print(f"Memory: {profile.memory_usage_bytes / 1024:.1f} KB")

phronesisml.simple.clean(path, *, null_strategy='drop', engine=None)

Load and clean a dataset (upload + ETL).

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
null_strategy	str	Null handling strategy ("drop", "fill", "flag"). Default "drop".	'drop'
engine	str | None	Force a specific engine. None for auto-selection.	None

Returns:

Type	Description
CleanResult	A CleanResult with row/column counts and transform log.

Example::

from phronesisml import clean

result = clean("data.csv", null_strategy="fill")
print(f"Cleaned {result.n_rows} rows, {result.n_columns} columns")

phronesisml.simple.validate(path, *, engine=None, null_strategy='drop')

Load, clean, and validate a dataset.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'

Returns:

Type	Description
ValidationResult	A ValidationResult with pass/fail status and issues.

Example::

from phronesisml import validate

result = validate("data.csv")
if not result.passed:
    for issue in result.issues:
        print(issue)

phronesisml.simple.detect_target(path, *, engine=None, null_strategy='drop')

Detect the prediction target and task type.

Runs upload through target detection. Returns the detected column, task type (classification/regression), and confidence score.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'

Returns:

Type	Description
TargetResult	A TargetResult with column, task_type, and confidence.

Example::

from phronesisml import detect_target

result = detect_target("data.csv")
print(f"Target: {result.column} ({result.task_type})")

phronesisml.simple.detect_task(path, *, engine=None, null_strategy='drop')

Detect the ML task type for a dataset.

Determines whether the dataset is suited for supervised learning (classification/regression), unsupervised learning (clustering), anomaly detection, or analytics-only exploration.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'

Returns:

Type	Description
TaskDetectionResult	A TaskDetectionResult with task_type, confidence, and
TaskDetectionResult	target_column (if supervised).

Example::

from phronesisml import detect_task

result = detect_task("data.csv")
print(f"Task: {result.task_type} (confidence: {result.confidence:.2f})")

phronesisml.simple.engineer(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1)

Engineer features from a dataset.

Runs upload through feature engineering. Returns the engineered feature names and counts.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1

Returns:

Type	Description
FeatureResult	A FeatureResult with feature names and counts.

Example::

from phronesisml import engineer

result = engineer("data.csv", variance_threshold=0.005)
print(f"{result.n_features} features engineered")

phronesisml.simple.select_model(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None)

Select and evaluate the best model for a dataset.

Runs upload through model selection and evaluation. Returns the best model type, score, and evaluation metrics.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split. Pass an integer ≥ 2 to enable k-fold cross-validation.	None

Returns:

Type	Description
ModelResult	A ModelResult with model type, score, and metrics.

Example::

from phronesisml import select_model

result = select_model("data.csv")
print(f"Best: {result.best_model_type} ({result.best_score:.4f})")

phronesisml.simple.recommend(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None)

Recommend the best model for a dataset (alias of :func:select_model).

Runs model selection and evaluation, returning the recommended model with its score and metrics. Equivalent to select_model with the same arguments and to Phronesis.recommend.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split. Pass an integer ≥ 2 to enable k-fold cross-validation.	None

Returns:

Type	Description
ModelResult	A ModelResult with model type, score, and metrics.

Example::

from phronesisml import recommend

result = recommend("data.csv")
print(f"Recommended: {result.best_model_type} ({result.best_score:.4f})")

phronesisml.simple.evaluate(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None)

Evaluate models on a dataset (alias of :func:select_model).

Runs model selection and evaluation, returning the best model with its metrics. Equivalent to select_model with the same arguments.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split. Pass an integer ≥ 2 to enable k-fold cross-validation.	None

Returns:

Type	Description
ModelResult	A ModelResult with model type, score, and metrics.

phronesisml.simple.explain(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1)

Explain model predictions using SHAP.

Runs upload through explainability. Returns feature importance scores. SHAP is a core dependency and is always available.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1

Returns:

Type	Description
ExplainResult	An ExplainResult with feature importance scores.

Example::

from phronesisml import explain

result = explain("data.csv")
for feature, importance in result.feature_importance.items():
    print(f"  {feature}: {importance:.4f}")

phronesisml.simple.report(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1)

Generate a Markdown report of the full pipeline.

Runs upload through reporting. Returns a Markdown string summarizing all pipeline stages.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1

Returns:

Type	Description
str	A Markdown string with the pipeline report.

Example::

from phronesisml import report

print(report("data.csv"))

phronesisml.simple.train(path, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None, model_type=None)

Run the full ML pipeline and return trained model details.

Runs all 11 stages: upload, ETL, validation, EDA, target detection, feature engineering, model selection, evaluation, explainability, reporting, and storage.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. If None (default), uses a single train/test split. Pass an integer ≥ 2 to enable k-fold cross-validation.	None
model_type	str | None	Optional name of a specific model to train (e.g. "random_forest").	None

Returns:

Type	Description
TrainResult	A TrainResult with model, explanation, report, and
TrainResult	artifact location.

Example::

from phronesisml import train

result = train("data.csv")
print(f"Model: {result.best_model_type}")
print(f"Report length: {len(result.report)} chars")

phronesisml.simple.profile(path, *, engine=None, null_strategy='drop')

Profile a dataset (alias of :func:analyze).

Loads, cleans, validates, and summarizes a dataset. Provided as a descriptive entry point mirroring the SDK's profile() method.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'

Returns:

Type	Description
DatasetProfile	A DatasetProfile with shape, dtypes, summaries, and
DatasetProfile	memory usage.

Example::

from phronesisml import profile

summary = profile("data.csv")
print(f"{summary.shape[0]} rows, {summary.shape[1]} columns")

phronesisml.simple.predict(path, data, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None, model_type=None, already_engineered=False)

Train a model on a dataset and predict on new rows.

Runs upload through model selection, then applies the saved feature transform recipe to data and returns one prediction per row. The target column, if present in data, is ignored.

Parameters:

Name	Type	Description	Default
path	str	Path to the training data file.	required
data	Any	A pandas DataFrame (or array-like) shaped like the training data.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. None uses a single train/test split.	None
model_type	str | None	Optional name of a specific model to train.	None
already_engineered	bool	True if data already contains the engineered feature columns.	False

Returns:

Type	Description
list[Any]	A list of model predictions, one per input row.

Example::

from phronesisml import predict

predictions = predict("data.csv", new_rows)
print(f"{len(predictions)} predictions")

phronesisml.simple.compare(path, model_types=None, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None)

Train several models on a dataset and rank them.

The recommended baseline model is included automatically. Each additional model is trained through the same resource-bounded HPO, then all models are ranked by the task's primary metric.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
model_types	list[str] | None	Names of models to compare. None compares every model in the recommended candidate pool.	None
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. None uses a single train/test split.	None

Returns:

Type	Description
ModelComparison	A ModelComparison with a best-first ranking.

Example::

from phronesisml import compare

result = compare("data.csv", ["random_forest", "logistic_regression"])
print(result.best_model)

phronesisml.simple.cluster(path, *, engine=None, null_strategy='drop')

Run clustering analysis on a dataset.

Executes upload through clustering evaluation. Automatically selects the best clustering algorithm (KMeans, DBSCAN, Agglomerative) based on silhouette score.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'

Returns:

Type	Description
ClusteringResult	A ClusteringResult with algorithm, scores, and labels.

Example::

from phronesisml import cluster

result = cluster("data.csv")
print(f"Algorithm: {result.algorithm}, Clusters: {result.n_clusters}")

phronesisml.simple.detect_anomalies(path, *, engine=None, null_strategy='drop', contamination=0.1)

Run anomaly detection on a dataset.

Executes upload through anomaly evaluation. Automatically selects the best algorithm (Isolation Forest, LOF).

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
contamination	float	Expected fraction of anomalies.	0.1

Returns:

Type	Description
AnomalyResult	An AnomalyResult with labels, scores, and metadata.

Example::

from phronesisml import detect_anomalies

result = detect_anomalies("data.csv")
print(f"Anomalies: {result.n_anomalies} of {result.n_total}")

phronesisml.simple.save(path, directory=None, *, engine=None, null_strategy='drop', variance_threshold=0.01, correlation_threshold=0.05, min_features=1, cv=None, model_type=None)

Run the full pipeline and persist the artifact suite.

Runs every stage through storage, then writes the standard artifact set (including the trained model) to <directory>/<run_id>/.

Parameters:

Name	Type	Description	Default
path	str	Path to a data file.	required
directory	str | None	Base directory for artifacts. None uses the pipeline default (./Phronesis_artifacts/<run_id>/).	None
engine	str | None	Force a specific engine. None for auto-selection.	None
null_strategy	str	Null handling strategy. Default "drop".	'drop'
variance_threshold	float	Drop features with variance below this.	0.01
correlation_threshold	float	Drop features with target correlation below this.	0.05
min_features	int	Minimum number of features to retain.	1
cv	int | None	Number of cross-validation folds. None uses a single train/test split.	None
model_type	str | None	Optional name of a specific model to train.	None

Returns:

Type	Description
dict[str, Any]	A dict with artifact_uri, saved_files, and warnings.

Example::

from phronesisml import save, restore

info = save("data.csv", "saved_runs")
restored = restore(info["artifact_uri"])
print(restored.predict(new_rows))

phronesisml.simple.restore(directory)

Restore a saved run for offline prediction.

Parameters:

Name	Type	Description	Default
directory	str	The artifact directory produced by :func:save or Phronesis.save.	required

Returns:

Type	Description
SavedRun	A SavedRun with a predict() method and run metadata.

Example::

from phronesisml import restore

run = restore("saved_runs/run_abc")
predictions = run.predict(new_rows)

phronesisml.simple.load(directory)

Load a saved run for offline prediction (alias of :func:restore).

Parameters:

Name	Type	Description	Default
directory	str	The artifact directory produced by :func:save or Phronesis.save.	required

Returns:

Type	Description
SavedRun	A SavedRun with a predict() method and run metadata.

Example::

from phronesisml import load

run = load("saved_runs/run_abc")
predictions = run.predict(new_rows)

phronesisml.simple.version()

Return the installed phronesisml version.

Example::

from phronesisml import version

print(version())

phronesisml.simple.capabilities()

Report the SDK's capabilities: engines, tasks, stages, APIs.

Deterministic and offline — the same information surfaced by phronesisml capabilities.

Example::

from phronesisml import capabilities

info = capabilities()
print(info["version"])

phronesisml.simple.health()

Run offline dependency and self checks.

Example::

from phronesisml import health

report = health()
print(report["status"])

Simple API Result Types

phronesisml.simple.DatasetProfile(shape, dtypes, numeric_summary, categorical_summary, missing_counts, memory_usage_bytes, column_names, validation_passed) dataclass

Structured profile of a dataset after upload + ETL + validation + EDA.

Example::

profile = analyze("data.csv")
print(f"{profile.shape[0]} rows, {profile.shape[1]} columns")
for col, count in profile.missing_counts.items():
    print(f"  {col}: {count} missing")

phronesisml.simple.CleanResult(n_rows, n_columns, transform_log, column_names) dataclass

Result of running upload + ETL on a dataset.

Example::

result = clean("data.csv", null_strategy="fill")
print(f"Cleaned {result.n_rows} rows")

phronesisml.simple.ValidationResult(passed, n_rows, n_columns, null_columns, empty_columns, duplicate_rows, issues) dataclass

Result of running upload + ETL + validation on a dataset.

Example::

result = validate("data.csv")
if result.passed:
    print("All checks passed")
else:
    print(f"Issues: {result.issues}")

phronesisml.simple.TargetResult(column, task_type, confidence, ambiguity_reason) dataclass

Result of automatic target detection.

Example::

result = detect_target("data.csv")
print(f"Target: {result.column} ({result.task_type})")

phronesisml.simple.TaskDetectionResult(task_type, target_column, confidence, ambiguity_reason) dataclass

Result of unified task detection.

Example::

result = detect_task("data.csv")
print(f"Task: {result.task_type} (confidence: {result.confidence:.2f})")

phronesisml.simple.FeatureResult(feature_names, n_features, n_rows) dataclass

Result of feature engineering.

Example::

result = engineer("data.csv")
print(f"{result.n_features} features from {result.n_rows} rows")

phronesisml.simple.ModelResult(best_model_type, best_score, candidates, best_params, truncated, trials_used, task_type, evaluation_metrics, ambiguity_caveat, estimated_training_cost='unknown') dataclass

Result of model selection and evaluation.

Example::

result = select_model("data.csv")
print(f"Best: {result.best_model_type} (score={result.best_score:.4f})")

phronesisml.simple.ExplainResult(feature_importance, explainer_type, sampled, n_samples_used, n_features_used=0, max_samples=0) dataclass

Result of SHAP-based model explanation.

Example::

result = explain("data.csv")
for feature, importance in result.feature_importance.items():
    print(f"  {feature}: {importance:.4f}")

phronesisml.simple.TrainResult(best_model_type, best_score, candidates, best_params, task_type, feature_importance, explainer_type, report, artifact_uri, estimated_training_cost='unknown') dataclass

Full pipeline result with model, explanation, and report.

Example::

result = train("data.csv")
print(f"Model: {result.best_model_type}")
print(result.report)

phronesisml.simple.ClusteringResult(algorithm, n_clusters, silhouette_score, davies_bouldin_score, calinski_harabasz_score, cluster_labels, params, report) dataclass

Result of clustering analysis.

Example::

result = cluster("data.csv")
print(f"Algorithm: {result.algorithm}, Clusters: {result.n_clusters}")

phronesisml.simple.AnomalyResult(algorithm, n_anomalies, n_total, contamination, anomaly_labels, anomaly_scores, params, report) dataclass

Result of anomaly detection.

Example::

result = detect_anomalies("data.csv")
print(f"Anomalies: {result.n_anomalies} of {result.n_total}")

---

Advanced API

Low-level entry point for full control over pipeline stages and configuration.

phronesisml.run_pipeline(data_path, engine_preference=None, null_strategy='drop', stages=None, config=None, sampling_config=None) async

Run the Phronesis pipeline on a dataset.

This is the primary public API. It: 1. Builds configuration (from config or defaults). 2. Composes agents via manual DI. 3. Constructs the LangGraph workflow with the requested stages. 4. Executes the graph with the initial state.

Parameters:

Name	Type	Description	Default
data_path	str	Path to the input dataset.	required
engine_preference	str | None	Force a specific engine ("pandas", "polars", "spark"). None for auto-selection.	None
null_strategy	str	Null handling strategy ("drop", "fill", "flag").	'drop'
stages	list[str] | None	Ordered list of pipeline stages to execute. If None, runs the full pipeline (all 11 stages).	None
config	PhronesisConfig | None	Optional pre-built configuration. If None, a config is constructed from the other arguments.	None
sampling_config	Any | None	Optional SamplingConfig for pre-flight sampling. If None, uses the config's sampling settings or disables sampling.	None

Returns:

Type	Description
dict[str, Any]	A dict summarising the pipeline results.

Raises:

Type	Description
WorkflowError	If the workflow graph execution fails.

phronesisml.PhronesisConfig

Bases: BaseModel

Top-level SDK configuration.

phronesisml.WorkflowState

Bases: BaseModel

Mutable shared state passed through the LangGraph workflow.

Every field defaults to None so that partial pipelines work correctly — only the fields populated by the agents that actually run will have values.