phronesisml 0.3.1

Why · Install · Quick Start · Architecture · SDK · Contributing

Table of Contents

Why PhronesisML

In short: PhronesisML recommends; it does not obscure. Every stage of the pipeline is a discrete, testable, reusable unit of code operating on a shared, typed WorkflowState.

PhronesisML is an SDK-first and CLI-first offline Machine Learning Engineering SDK. The Python SDK — and the CLI built on it — are the canonical interfaces; any future GUI would be a thin client over the same SDK a data scientist would import directly. There is exactly one source of truth for ML logic.

Core Principles

PhronesisML is built around five commitments that shape every design decision in the codebase:

Key Features

Multi-Agent	Orchestration	Auto Engine	Cleaning	Analysis	Engineering
Detection	Selection	Metrics	Explainability	Reporting	Extensible

Architecture Overview

graph TD
    A["Python SDK<br/>Phronesis class"] --> B
    B["LangGraph Workflow<br/>Orchestrates agents"] --> C
    C["Agents<br/>One responsibility each"] --> D
    D["Services<br/>Reusable domain logic"] --> E
    E["Data Engines<br/>Pandas / Polars / PySpark"] --> F
    F["Reports / Storage<br/>Persisted artifacts"]

    style A fill:#6366F1,stroke:#4F46E5,color:#fff,stroke-width:2px
    style B fill:#A855F7,stroke:#9333EA,color:#fff,stroke-width:2px
    style C fill:#EC4899,stroke:#DB2777,color:#fff,stroke-width:2px
    style D fill:#14B8A6,stroke:#0D9488,color:#fff,stroke-width:2px
    style E fill:#F97316,stroke:#EA580C,color:#fff,stroke-width:2px
    style F fill:#06B6D4,stroke:#0891B2,color:#fff,stroke-width:2px

Design Principles

How It Works

graph TD
    A["1. Dataset Upload"] --> B["2. ETL / Cleaning"]
    B --> C["3. Validation"]
    C --> D["4. EDA & Profiling"]
    D --> E["5. Target Detection"]
    E --> F["6. Feature Engineering"]
    F --> G["7. Model Recommendation & Training"]
    G --> H["8. Evaluation"]
    H --> I["9. Explainability"]
    I --> J["10. Reporting"]
    J --> K["11. Storage"]

    style A fill:#6366F1,color:#fff
    style B fill:#0EA5E9,color:#fff
    style C fill:#EF4444,color:#fff
    style D fill:#F97316,color:#fff
    style E fill:#EF4444,color:#fff
    style F fill:#EAB308,color:#000
    style G fill:#8B5CF6,color:#fff
    style H fill:#14B8A6,color:#fff
    style I fill:#EC4899,color:#fff
    style J fill:#06B6D4,color:#fff
    style K fill:#10B981,color:#fff

Each numbered stage is implemented as its own agent — see Project Structure for where each one lives in the codebase.

Engine Selection Logic

PhronesisML supports three interchangeable dataframe backends behind a single DataEngine interface, so pipeline code never imports Pandas, Polars, or PySpark directly.

graph LR
    A["Dataset"] --> B{"Profile size<br/>& shape"}
    B -->|"Small–medium,<br/>fits in memory"| C["Pandas"]
    B -->|"Larger,<br/>single machine"| D["Polars"]
    B -->|"Larger than<br/>memory / distributed"| E["PySpark"]
    C --> F["Same DataEngine<br/>interface downstream"]
    D --> F
    E --> F

    style A fill:#6366F1,color:#fff
    style B fill:#A855F7,color:#fff
    style C fill:#150458,color:#fff
    style D fill:#CD792C,color:#fff
    style E fill:#E25A1C,color:#fff
    style F fill:#06B6D4,color:#fff

Selection is automatic by default but can always be forced explicitly — see Quick Start.

Technology Stack

Performance

PhronesisML's engine abstraction exists specifically so the pipeline can move from Pandas to Polars to PySpark as data size grows, without changing pipeline code. Formal, reproducible benchmarks across dataset sizes and engines are not yet published — this section will be filled in with measured numbers (not estimates) once a benchmark suite lands. Track progress in Roadmap.

Installation

Standard (recommended)

pip install phronesisml

Supported file formats

Optional extras

From source

git clone https://github.com/kartik00052/PhronesisML.git
cd PhronesisML
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Using uv? uv sync --all-extras creates the environment from the committed uv.lock (reproducible install), and uv build produces the wheel + sdist. Both pip and uv are first-class, CI-validated workflows.

Quick Start

SDK (Python)

from phronesisml import Phronesis

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

CLI

phronesisml run data/customers.csv
phronesisml run data/customers.csv --engine polars
phronesisml info

Examples

from phronesisml import Phronesis

ml = Phronesis("data/customers.csv")
ml.load()
print(ml.summary())

ml.clean(null_strategy="fill")
ml.validate()
ml.eda()

ml.detect_target()
result = ml.train()
print(f"Best model: {result.model_type} ({result.score:.4f})")

print(ml.evaluate())
print(ml.explain())

from phronesisml import analyze, train

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

result = train("data/customers.csv")
print(f"Best model: {result.best_model_type} ({result.best_score:.4f})")

from phronesisml import cluster, detect_anomalies

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

anomalies = detect_anomalies("data/customers.csv", contamination=0.1)
print(f"Anomalies: {anomalies.n_anomalies} of {anomalies.n_total}")

from phronesisml import analyze_async, train_async
import asyncio

async def main():
    profile = await analyze_async("data/customers.csv")
    result = await train_async("data/customers.csv")

asyncio.run(main())

from phronesisml import train
from phronesisml.exceptions import DataValidationError, EngineSelectionError, WorkflowError

try:
    result = train("data/customers.csv")
except DataValidationError as e:
    print(f"Dataset failed validation: {e}")
except EngineSelectionError as e:
    print(f"Could not select a data engine: {e}")
except WorkflowError as e:
    print(f"Pipeline failed: {e}")

import asyncio
from phronesisml import run_pipeline

async def main():
    result = await run_pipeline(data_path="data/customers.csv")
    print(result)

asyncio.run(main())

SDK Interfaces

PhronesisML is SDK-first and CLI-first: the CLI is a thin client that calls the same SDK you import directly.

Project Structure

phronesisml/
  __init__.py          # Public SDK surface
  exceptions.py        # Exception hierarchy
  agents/              # Pipeline agents (11 total)
  configs/             # Pydantic configuration
  data/                # Data loading, validation, profiling
  engines/             # Pandas/Polars/Spark abstraction
  interfaces/           # CLI (Typer)
  ml/                   # Model definitions, training, metrics
  rag/                   # RAG infrastructure
  workflow/             # LangGraph workflow orchestration

Offline-First Philosophy

PhronesisML's core pipeline — validation, profiling, ETL, EDA, feature engineering, target detection, model recommendation, training, evaluation, explainability, and reporting — runs entirely on your machine, with no network dependency and no requirement to send data to a hosted service. Optional extras (mlflow for remote experiment tracking, future cloud storage backends) are opt-in additions on top of an offline-capable core, not a requirement for it.

Security

• No data leaves your machine unless you explicitly configure a remote storage or tracking backend.
• No hidden network calls in the core pipeline — installation extras that do require network access (e.g. mlflow) are opt-in.
• Dependency-pinned releases to reduce supply-chain surface area.
• Found a security issue? Please open a private security advisory on GitHub rather than a public issue.

Roadmap

Completed

• Core WorkflowState + LangGraph orchestration
• All 11 pipeline agents
• Pandas, Polars, PySpark engines with auto-selection
• Local filesystem storage
• CLI interface
• HTML report generation
• Clustering and anomaly detection flows (unsupervised)
• Full test suites

Planned

• Plugin system with entry-points discovery
• S3, GCS, Azure Blob storage backends
• DuckDB engine
• PDF report rendering
• Parallel/branching agent execution
• Reproducible benchmark suite (see Performance)
• Desktop GUI client
• Human-in-the-loop checkpoints

Contributing

make check       # lint + typecheck + test
make format      # auto-fix formatting
make build        # build wheel + sdist

New to the project? Look for issues labeled good first issue. Please open an issue before starting on a large change, so the design can be discussed first.

Community

• GitHub Discussions — design questions, ideas, and general Q&A
• Issues — bug reports and feature requests
• Pull Requests — see what's currently in progress

FAQ

License

Licensed under the MIT License — see LICENSE for the full text.

Acknowledgements

PhronesisML's design draws inspiration from the architectural patterns and developer experience established by these projects, without any affiliation with or endorsement from them.