phronesisml 0.2.0

Open-source Python SDK that automates the complete ML lifecycle using a modular multi-agent architecture orchestrated by LangGraph.

---

Table of Contents

Navigation

1. Why PhronesisML
2. Key Features
3. Architecture Overview
4. How It Works
5. Technology Stack
6. Installation
7. Quick Start
8. Examples
9. SDK Interfaces
10. Project Structure
11. Roadmap
12. Contributing
13. FAQ
14. License

---

Why PhronesisML

	Notebooks	AutoML Tools	PhronesisML
Structure	Ad hoc, cell-by-cell	Fixed, opaque	Modular agents on typed WorkflowState
Transparency	High, unorganized	Low -- black box	High -- every decision is inspectable
Overridable	N/A	Rarely	Yes -- imputation, encoding, model
Reusable	Low	Low	High -- same pipeline, swap the data
Production	No	Partially	Yes -- versioned artifacts

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 SDK-first -- the CLI, the FastAPI service, and any future GUI are thin clients built on the same SDK a data scientist would import directly. There is exactly one source of truth for ML logic.

---

Key Features

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

Feature	Description	Status
Multi-Agent Workflow	Each pipeline stage is an independent agent with a single responsibility	✅
LangGraph Orchestration	Agents are nodes in a directed graph; state passing, retries	✅
Automatic Engine Selection	Dataset size determines Pandas, Polars, or PySpark	✅
ETL	Declarative extraction, cleaning, and transformation	✅
Validation	Schema, type, and quality validation before downstream processing	✅
EDA	Automated statistical profiling and structured dataset summaries	✅
Feature Engineering	Automated and configurable transformation, encoding, derivation	✅
Target Detection	Heuristic, overridable identification of prediction target	✅
Model Recommendation	Rule- and metric-driven suggestion of candidate model families	✅
Explainability	Post-training feature importance and model-behavior summaries	✅
Reporting	Structured, versionable output artifacts for every stage	✅
FastAPI Interface	REST API with file upload, background jobs, OpenAPI docs	✅
Offline-First	Core pipeline stages run without network access	✅
SDK-First	Every interface is a client of the SDK	✅
Plugin System	Extension points for custom agents, models, engines, storage	🔸

---

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

Layer	Responsibility	Depends On
Python SDK	Single public entry point (Phronesis class)	--
LangGraph Workflow	Pipeline as graph; owns WorkflowState	Called by SDK
Agents	One pipeline responsibility each; read/write state	Graph nodes
Services	Stateless, reusable domain logic	Called by agents
Data Engines	Pandas, Polars, PySpark implementations	Called by services
Reports / Storage	Persists run artifacts	Written to by agents

Design Principles

Principle	What It Means
SDK-first	One source of truth for ML logic
Offline-first	Core pipeline runs without network
Deterministic ML	Same input + config = same output
DI	Agents receive dependencies
Clean Architecture	Layers depend inward
SRP	One agent, one job
Strategy Pattern	Interchangeable engine selection

Data Engine Abstraction

Engine	Best For	Why
Pandas	Small-to-medium, in-memory	Ubiquitous, well understood
Polars	Larger single-machine	Rust-based, multi-threaded
PySpark	Distributed / larger-than-memory	Industry standard at scale

---

How It Works

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

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

---

Technology Stack

---

Installation

Standard (recommended)

pip install phronesisml

What's included

Format	Supported	Dependency
CSV / TSV	✅	pandas (core)
Excel (.xlsx)	✅	openpyxl (core)
Parquet	✅	pyarrow (core)
JSON / JSONL	✅	pandas (core)
Feather / Arrow	✅	pyarrow (core)

With optional extras

Extra	Install	What it adds
all	pip install phronesisml[all]	Everything below
api	pip install phronesisml[api]	FastAPI REST endpoints
cli	pip install phronesisml[cli]	CLI commands
explain	pip install phronesisml[explain]	SHAP explanations
boost	pip install phronesisml[boost]	XGBoost models
mlflow	pip install phronesisml[mlflow]	MLflow tracking
spark	pip install phronesisml[spark]	PySpark engine
parquet	pip install phronesisml[parquet]	Parquet support
dev	pip install phronesisml[dev]	pytest, ruff, mypy

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]"

---

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

FastAPI

pip install phronesisml[api]
uvicorn phronesisml.interfaces.api.app:app --reload

---

Examples

Incremental Usage

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())

Simple API (One-Liner Functions)

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})")

Async Variants

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())

Error Handling

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}")

Advanced -- Low-Level Workflow API

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: the CLI and FastAPI service are thin clients that call the same SDK you import directly.

Interface	Install	Description
Python SDK	pip install phronesisml	from phronesisml import Phronesis
CLI	pip install phronesisml[cli]	phronesisml run data.csv
FastAPI	pip install phronesisml[api]	uvicorn phronesisml.interfaces.api.app:app

---

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) + FastAPI
  ml/                  # Model definitions, training, metrics
  rag/                 # RAG infrastructure
  workflow/            # LangGraph workflow orchestration

---

Roadmap

Completed

• Core WorkflowState + LangGraph orchestration
• All 11 pipeline agents
• Pandas, Polars, PySpark engines with auto-selection
• Local filesystem storage
• CLI and FastAPI interfaces
• HTML report generation
• 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
• Desktop GUI client
• Human-in-the-loop checkpoints

---

Contributing

make check       # lint + typecheck + test
make format      # auto-fix formatting
make build       # build wheel + sdist
make docker      # build and run Docker image

---

FAQ

Why not just use AutoML?

AutoML tools optimize for a leaderboard metric and hide their reasoning. PhronesisML makes every decision inspectable and overridable.

Why LangGraph?

LangGraph models workflows as a graph of stateful nodes with conditional edges -- a direct map onto PhronesisML's pipeline shape.

Why Polars in addition to Pandas?

Polars' Rust-based, multi-threaded engine handles larger workloads significantly faster. PhronesisML upgrades automatically when warranted.

Can I run only part of the pipeline?

Yes -- run() and run_pipeline() accept a stages parameter.

---

License

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

---

Acknowledgements

---

Built with a commitment to transparent, inspectable machine learning pipelines.